# WddSuperAgent DDS（现代化改造草案）

## 背景与总体目标
- WddSuperAgent 由多个 Go 模块组成：`agent-wdd`（通用 CLI 工具）、`agent-common`（工具库/常量/镜像命名转换等）、`agent-deploy`（K8s 部署模板生成）、`agent-operator`（运维中枢：镜像同步、K8s 操作、Harbor/MinIO 交互）。目前模块耦合度高、流程以脚本式函数为主，缺少统一 API 与测试保障。
- 目标：以“运维服务化”为方向，引入 Gin 提供标准接口，按领域拆分服务层/适配层，完善配置、安全与测试体系，并为后续 UI/自动化编排提供稳定基础。

## 现状梳理（按模块）
- `agent-common`：提供 logger、断言、文件/字符串等工具，镜像命名转换（`image` 包）、项目镜像列表（`real_project/*`），缺少接口抽象和错误语义。
- `agent-deploy`（依赖 agent-common）：生成/应用 CMII 相关的 K8s 资源模板（Dashboard、NFS、Middlewares、App、Ingress、Env Config），通过 `CommonEnvironmentConfig` 拼装 YAML/Apply 文件；存在大量硬编码路径与全局变量。
- `agent-operator`（依赖 agent-common、agent-deploy）：运维中枢，职责包含：
  - 镜像同步 DCU/DLTU 流程（`CmiiImageSyncOperator`）：Download → Compress → Upload/Push；支持从 Demo/RKE/Middle/版本号拉取，MinIO 上传，Harbor 直推（tag + push）。
  - Docker/Harbor/MinIO 适配（`image`、`minio` 包），K8s 适配（`CmiiK8sOperator`，Deployment/Pod/Node 的查询、缩容、重启、打 tag 等），部分函数含硬编码认证信息。
  - main 以交互式模式运行（mode=image/operator），无 HTTP API，流程控制与状态管理零散。
- `agent-wdd`（独立）：Cobra CLI 瑞士军刀（zsh、proxy、acme、Cloudflare、host info 等），与 CMII 运维解耦。

## 关键现有流程
- 镜像同步（DCU/DLTU）：`ImageSyncEntity` 描述 Download/Compress/Upload 条件，`A_DownloadCompressUpload` 执行拉取→压缩→上传，`A_DownloadLoadTagUpload` 负责离线包加载+重 tag + 推送；大量文件系统操作与全局路径（`OfflineImageGzipFolderPrefix`）。
- K8s 操作：`CmiiK8sOperator` 封装 client-go，基于 namespace 切换进行 Deployment/StatefulSet/Pod/Node 的查询、扩缩容、重启、删 pod/evict 等。
- 部署生成：`OctopusDeploy` 依靠模板包组合环境，按镜像 map 生成并 apply。

## 主要痛点
- 架构层次不足：领域逻辑、基础设施操作、流程编排混杂在同一包内；全局变量与硬编码路径/凭据多。
- 可测试性弱：测试多为打印/人工验证，`SaveImageListToGzipFile` 等函数甚至返回 stub；缺少接口注入、mock 与集成回归。
- 接口形态单一：仅 CLI/交互模式，缺少 HTTP API/任务编排，不利于自动化或 UI 集成。
- 配置与安全：凭据明文/硬编码（Harbor RegistryAuth、kubeconfig 路径等），无统一配置加载与密钥管理。
- 可靠性/可观察性：缺少健康探针、审计日志、指标/追踪；IO/网络无超时控制，错误语义不清晰。

## 目标架构（分层与模块化）
- **项目结构（示例）**
  ```
  /cmd/operator (HTTP + CLI 入口)
  /cmd/wdd      (保留独立 CLI)
  /pkg/domain   (实体与用例协议：ImageSyncSpec、DeployPlan、ClusterTarget 等)
  /pkg/service  (应用层：ImageSyncService、DeployService、K8sService、RegistryService、StorageService)
  /pkg/infra    (适配层：Docker/Harbor client、MinIO client、K8s client、Template renderer、Config)
  /pkg/transport/http (Gin handler，DTO 校验，统一响应)
  /pkg/transport/cli  (Cobra 命令适配，复用同一 service)
  /pkg/obs      (日志/指标/追踪/审计)
  /configs      (环境化配置，区分 dev/test/prod)
  ```
- **依赖关系**：`transport -> service -> infra`，`domain` 为纯模型；`agent-wdd` 继续独立，但可共用 `pkg/infra` 的下载/文件工具。
- **并发/任务模型**：对长耗时的镜像同步/压缩/上传采用异步任务（队列或 goroutine + work pool），任务状态持久化（可选 Bolt/SQLite/Redis），Gin 提供查询/取消接口。

## 组件设计与接口草案
- **Domain 模型**
  - `ImageSyncSpec`：源列表（cmiiNameTags/fullNames/projectVersion/sourceAuth）、压缩策略（split/monolithic、目标目录）、上传策略（minio bucket/oss prefix）、推送策略（target harbor/cred）、更新策略（是否更新集群 tag）。
  - `DeployPlan`：目标集群/namespace、镜像 map、模板参数（NFS/Ingress/SRS 等）。
  - `ClusterTarget`：kubeconfig/上下文/namespace，执行策略（超时、并发度）。
- **Service 层**
  - `ImageSyncService`：封装 Download→Compress→Upload→Push，用接口注入 `RegistryClient`、`StorageClient`、`Compressor`、`ImageNamer`；支持幂等与断点续跑（跳过已存在 gzip）。
  - `DeployService`：生成/渲染/Apply K8s 清单；可选 dry-run；依赖 `K8sApplier`（kubectl/go-client）。
  - `K8sService`：Deployment/StatefulSet/Pod/Node 读写操作，暴露给 HTTP/CLI；支持批量重启/cordon/evict。
  - `ConfigService`：集中配置加载（Viper），支持 env 覆盖与 secret 挂载。
  - `ObsService`：日志封装（zap sugared logger）、Prometheus 指标（请求量/耗时/失败率/队列长度）、OpenTelemetry trace。
- **Transport（Gin）**
  - `/api/v1/images/sync` `POST`：提交 `ImageSyncSpec`，返回任务 id。
  - `/api/v1/images/tasks/:id` `GET`：查询任务状态/日志片段。
  - `/api/v1/registry/push` `POST`：源→目标 Harbor 的 tag/push。
  - `/api/v1/deploy/apply` `POST`：提交 `DeployPlan`，可选择 `dryRun`。
  - `/api/v1/k8s/deployments/:ns/:name/tag` `PUT`：更新镜像 tag。
  - `/api/v1/healthz`、`/metrics`：健康检查与指标暴露。
- **CLI（Cobra）**
  - 复用同一 service：`wdd image sync ...`，`wdd deploy apply ...`，与 HTTP 行为保持一致。

## 关键改造点与落地方案
- **解耦与接口化**：为 Docker/Harbor/MinIO/K8s 定义接口（`RegistryClient`, `StorageClient`, `K8sClient`），在服务层通过依赖注入；现有实现迁移至 `infra`，便于 mock。
- **配置/密钥**：移除硬编码（RegistryAuth、kubeconfig 路径等），采用 `configs/*.yaml` + 环境变量覆盖；敏感信息通过文件挂载或 Secret 管理，Gin 层仅传递引用。
- **路径与存储**：统一离线镜像根路径（可配置），将 txt/gzip 列表输出迁移到任务上下文目录；为分片压缩/单包压缩提供策略接口。
- **错误与重试**：下载/上传/推送增加上下文超时与可配置重试；对局部失败的镜像保留失败列表与诊断信息。
- **并发与资源控制**：镜像拉取/压缩采用 worker pool（并发上限可配置），避免当前全局 goroutine + 共享 slice 可能的竞态。
- **可观察性**：统一日志格式；Gin middleware 注入 request-id；暴露 Prometheus 指标与 pprof；长任务输出阶段进度。
- **安全**：移除代码中的 base64 凭据；K8s 操作增加 RBAC 范围与 kubeconfig 选择；上传/下载校验 hash（md5/sha256）。
- **兼容性**：保留现有 DCU/DLTU 能力，通过 CLI 子命令封装新的 service，实现“新 API + 旧脚本可用”。

## 测试与质量保障
- **单元测试**：引入 `testify`/`gomock`，对核心服务（ImageSyncService/K8sService/DeployService）做 mock 测试；覆盖命名转换、列表生成、失败分支。
- **集成测试**：使用 kind + 本地 registry（或 test Harbor mock）、本地 MinIO 容器，跑镜像下载→压缩→推送→K8s apply 的端到端流程；提供 `make test-integration`。
- **契约测试**：Gin API 使用 `httptest` 覆盖请求校验/错误码；CLI 使用 golden 测试。
- **静态检查**：启用 `golangci-lint`（vet, ineffassign, errcheck, revive），`go test ./...` 作为最小门槛。

## 迁移路线（建议三步）
1) **基础设施抽象**：提炼 Registry/K8s/Storage/Compressor 接口，将现有实现迁入 `pkg/infra`，补齐 `SaveImageListToGzipFile` 等 stub，清理硬编码凭据/路径。
2) **服务化与测试**: 新建 `pkg/service`，重写 DCU/DLTU 流程为可注入的 `ImageSyncService`；构建 Gin 入口与 API DTO，补足单元/集成测试与 CI 流水线。
3) **运维增强**: 引入任务队列/状态持久化、指标/日志/trace，完善 K8s 操作 API，逐步替换旧 CLI 逻辑为 service 调用，并整理配置与文档。

## 成功度量
- 关键流程 API 化：镜像同步/推送、部署 apply、K8s tag 更新均有 Gin 接口与 CLI 对应子命令。
- 质量门槛：`go test ./...` 绿色，集成测试可在本地 one-command 运行；lint 无高危告警。
- 运维可用性：无硬编码密钥，配置可按环境切换；指标可在 Prometheus 抓取，健康检查可被 K8s 探针消费。