docs: 添加项目评估、开发路线图、TDD开发计划三份核心文档

- PROJECT_EVALUATION.md: 综合评分72/100，15模块全量审计，工程质量(零测试)为最大风险 - ROADMAP.md: v0.3.0质量加固(当前)→v0.4.0企业级→v1.0.0智能化，含技术债务清单 - TDD_PLAN.md: 后端3阶段测试计划(覆盖率0%→50%)，含K8s/Auth/Pipeline具体测试函数
2026-06-21 21:20:04 +08:00
1 parent 9dbb7e9fc4
commit 3b112ee813
@@ -0,0 +1,200 @@
+# AIOps 智能运维平台 — 项目评估报告
+
+> 审计日期: 2026-06-21
+> 审计方式: 全量代码扫描 + 模块逐项评估
+> 当前版本: v0.2.0 (Phase 2 — AI 能力增强)
+> 综合评分: **72 / 100**
+
+---
+
+## 一、项目概况
+
+| 项目 | 说明 |
+|------|------|
+| **名称** | AIOps 智能运维平台 |
+| **定位** | 企业级云原生智能运维解决方案 |
+| **仓库** | gitee.com/attacker/aiops (master 分支) |
+| **开发机** | 10.10.10.75 (Ubuntu 24.04, Go 1.22.2) |
+| **生产机** | 10.10.10.150 (docker-compose 部署) |
+| **部署方式** | 3 种: embed 单容器 / 二进制 / K8s |
+| **近 7 天提交** | 171 次 (极度活跃) |
+
+### 三大核心能力
+
+1. **资产管理** — 服务器/云资源(云账号·域名·账单)/K8s 集群
+2. **监控告警** — Agent 指标采集 / 告警引擎 / 告警中心 / 日志 / 链路追踪 / 监控大屏
+3. **自动化运维 + AIOps** — CronJob/Script/Ansible / 资源审批 / AI 告警分析·故障诊断·脚本生成
+
+---
+
+## 二、技术架构评估
+
+### 技术栈
+
+| 层 | 技术 | 版本 | 端口 |
+|----|------|------|------|
+| 后端 | Go + Gin + GORM + SQLite(CGO) + JWT + Zap | Go 1.24 | 8080 |
+| 前端 | React + TypeScript + Vite + Tailwind + shadcn/ui + Zustand + TanStack Query | React 19 | 5173 |
+| Agent | Go (CGO_ENABLED=0 静态二进制, amd64+arm64) | Go 1.24 | — |
+| 数据库 | SQLite (CGO) | — | — |
+| 缓存 | Redis | — | 6379 |
+
+### 代码规模
+
+| 模块 | 行数 | 文件数 | 说明 |
+|------|------|--------|------|
+| 后端 Go | 28,633 | 60+ handler, 25 model | 含 K8s 2583 行 + client 1486 行 |
+| 前端 TS/TSX | 50,287 | 15 组件目录 + 6 页面 | K8s 组件 22 个 |
+| Agent Go | 1,701 | 13 文件 | 双通道: 指标采集 + 远程任务 |
+| **合计** | **~80,621** | — | 中大型项目 |
+
+### 架构亮点
+
+- ✅ **Agent 双通道设计** — 指标采集 (10s 上报 `/proc`) + 远程任务 (5s 轮询),解耦清晰
+- ✅ **5 套主题** — CSS 变量驱动,暗色/亮色/紫色/绿色/玫红一键切换
+- ✅ **WebShell / PTY 终端** — WebSocket 实现,K8s exec + kubectl 双终端
+- ✅ **3 种部署方式** — embed 单容器 / 二进制 / K8s,灵活适配
+- ✅ **RBAC + Item-Role** — 细粒度数据级权限控制
+- ✅ **WebSocket 实时能力** — 终端 / 指标流 / Pipeline 日志 / K8s exec
+
+### 架构风险
+
+- ⚠️ **SQLite + CGO** — 单文件数据库,并发写入受限,不适合多实例横向扩展
+- ⚠️ **kubernetes.go 巨型文件** — 96KB / 2583 行 / 99 函数,严重违反单一职责
+- ⚠️ **Go module 名仍为 `ezops`** — 与项目名 `aiops` 不一致 (历史遗留)
+- ⚠️ **无消息队列** — 告警/任务全同步处理,高并发下可能阻塞
+
+---
+
+## 三、功能完成度评估
+
+### 后端逐模块 (15 个功能模块)
+
+| # | 模块 | Handler 文件 | 路由数 | 完成度 | 状态 |
+|---|------|-------------|--------|--------|------|
+| 1 | 认证/用户/角色 (JWT+RBAC) | user.go, user_admin.go, role.go, item_role.go | ~25 | 100% | ✅ 生产可用 |
+| 2 | LDAP 集成 | ldap.go, ldap_ou.go, ldap_users.go | ~12 | 100% | ✅ 生产可用 |
+| 3 | 仪表盘 | dashboard.go | ~4 | 100% | ✅ |
+| 4 | 服务器管理 | server.go, server_batch.go, webshell.go | ~10 | 100% | ✅ 生产可用 |
+| 5 | 云资源管理 | cloud_accounts/domain/platform/region/billing/sync | ~25 | 100% | ✅ 生产可用 |
+| 6 | 监控告警 | prometheus/zabbix/snmp/site/alert* | ~40 | 95% | ✅ 告警渠道待完善 |
+| 7 | **Kubernetes** | kubernetes.go (99 函数!) | 74 | 95% | ✅ 核心功能完备 |
+| 8 | CI/CD 部署 | pipeline*.go, credential*.go, deploy*.go | ~30 | 90% | ✅ 执行器完备 |
+| 9 | 自动化运维 | automation_cron/script, ansible.go | ~20 | 100% | ✅ 15 个 Ansible 模板 |
+| 10 | 资源审批 | approval.go, approval_process.go | ~8 | 100% | ✅ 动态表单 |
+| 11 | AI/LLM | llm*.go (chat/config/history) | ~10 | 90% | ✅ 多模型支持 |
+| 12 | 操作审计 | audit.go | ~5 | 90% | ⚠️ CSV 导出 TODO |
+| 13 | 导航/菜单 | navigation*.go | ~6 | 100% | ✅ |
+| 14 | Agent 管理 | agent.go, agent_install.go, agent_task.go | ~15 | 100% | ✅ 含一键安装 |
+| 15 | 监控数据源 | prometheus/zabbix_datasource + proxy | ~15 | 100% | ✅ |
+
+### 前端逐模块
+
+| 模块 | 组件数 | 代表组件 | 完成度 |
+|------|--------|---------|--------|
+| K8s 管理 | 22 | DeploymentDetail (719行), TopologyView (586行), PodFileBrowser (552行) | 95% |
+| CI/CD 部署 | 8 | PipelineManager, PipelineEditor, CredentialManager | 90% |
+| 监控告警 | 12 | AlertCenter, GrafanaDashboard, TraceManager | 90% |
+| 服务器管理 | 6 | ServerManager, CloudServerImport, WebShell | 100% |
+| 云资源 | 4 | CloudAccountManager, CloudBilling, DomainManager | 100% |
+| 自动化 | 3 | AnsibleWorkflow (886行) | 100% |
+| AI 助手 | 2 | AIOpsAssistant (686行) | 90% |
+| 系统管理 | 4 | LdapManagementSection | 100% |
+| 审批流程 | 3 | ApprovalFlow, ApprovalCreateDialog | 100% |
+| 布局/UI | — | sidebar (689行) + shadcn/ui 全家桶 | 100% |
+
+### Mock / TODO 清单
+
+| 位置 | 类型 | 严重度 | 说明 |
+|------|------|--------|------|
+| `audit.go:223` | TODO | 低 | CSV/Excel 导出未实现 |
+| `scripts/mock.go` | 种子数据 | 无 | 开发用 mock 数据生成器,非生产代码 |
+| `scripts/seed*.go` | 种子数据 | 无 | K8s 资源种子数据 |
+
+> **结论:** 生产代码中 Mock 极少,仅 1 个 TODO。功能真实度高。
+
+---
+
+## 四、多维度评分
+
+| 维度 | 权重 | 得分 | 加权 | 说明 |
+|------|------|------|------|------|
+| 功能完整度 | 25% | **90** | 22.5 | 15 模块全部可用,K8s 99 函数覆盖极广 |
+| 前后端对接 | 20% | **85** | 17.0 | 367 路由全连通,WebSocket 实时通道完备 |
+| 工程质量 | 20% | **30** | 6.0 | ⚠️ **零测试!** 无 CI/CD,技术债集中在测试 |
+| UI/UX | 15% | **85** | 12.75 | 5 主题,shadcn/ui,响应式,交互流畅 |
+| 后端架构 | 20% | **70** | 14.0 | 模块清晰但 kubernetes.go 巨型,SQLite 限扩展 |
+| **综合** | **100%** | — | **72.25** | **72 / 100** |
+
+### 评分雷达图 (ASCII)
+
+```
+        功能完整度 90
+           ★★★★★
+          /       \
+         /         \
+架构 70 ★           ★ 85 对接
+        \         /
+         \       /
+工程质量  ★★★☆☆   ★★★★★  UI/UX
+   30         85
+```
+
+---
+
+## 五、关键风险 (按严重度排序)
+
+### 🔴 P0 — 必须立即处理
+
+| # | 风险 | 影响 | 建议 |
+|---|------|------|------|
+| 1 | **零测试覆盖** | 任何改动无回归保护,171 次/周提交量下极其危险 | 立即建立后端单元测试,优先覆盖 K8s/CI-CD/认证模块 |
+| 2 | **无 CI/CD 流水线** | 代码质量无门禁,构建/部署全手动 | 搭建 GitHub Actions/Gitea CI,PR 必须过测试+lint |
+
+### 🟡 P1 — 本版本内处理
+
+| # | 风险 | 影响 | 建议 |
+|---|------|------|------|
+| 3 | **SQLite 并发瓶颈** | 高并发写入锁竞争,无法多实例部署 | 评估迁移 MySQL/PostgreSQL (已有多数据库抽象层) |
+| 4 | **kubernetes.go 巨型文件** | 96KB 维护困难,合并冲突高发 | 拆分为 cluster/deployment/pod/hpa/cronjob 等子文件 |
+| 5 | **Go module 名 `ezops`** | 与项目名不一致,导入路径混乱 | 全局重命名 `ezops` → `aiops` |
+| 6 | **无 API 文档自动生成** | 367 路由无 Swagger/OpenAPI | 引入 swaggo 自动生成 API 文档 |
+
+### 🟢 P2 — 下个版本规划
+
+| # | 风险 | 影响 | 建议 |
+|---|------|------|------|
+| 7 | **无消息队列** | 告警/任务同步处理 | 引入 Redis Stream / NATS 异步化 |
+| 8 | **前端无 E2E 测试** | UI 回归靠人工 | 引入 Playwright 覆盖核心流程 |
+| 9 | **审计日志 CSV 导出缺失** | 用户无法导出审计报表 | 实现 audit.go:223 TODO |
+
+---
+
+## 六、下一步行动 (优先级排序)
+
+### 立即行动 (本周)
+
+1. **搭建测试框架** — 后端 `testing` + `testify` + `httptest`,前端 `Vitest` + `React Testing Library`
+2. **建立 CI 流水线** — `.gitea/workflows/ci.yml`:lint → test → build → docker push
+3. **拆分 kubernetes.go** — 按资源类型拆为 6-8 个文件
+
+### 短期 (2-4 周)
+
+4. **编写核心模块测试** — K8s handler / Pipeline executor / Auth / Alert engine (覆盖率 > 50%)
+5. **引入 Swagger** — `swag init` 生成 API 文档,367 路由全覆盖
+6. **module 重命名** — `ezops` → `aiops` 全局替换
+7. **前端测试基建** — Vitest + Playwright E2E 冒烟测试
+
+### 中期 (1-2 月)
+
+8. **数据库迁移评估** — SQLite → MySQL (利用现有 GORM 抽象层)
+9. **告警异步化** — 引入 Redis Stream 解耦告警引擎
+10. **可观测性** — 后端引入 Prometheus metrics + 结构化日志增强
+
+---
+
+## 七、总结
+
+AIOps 平台在 **功能广度** 上已达到企业级水准 — 15 个功能模块、367 条路由、80K+ 行代码,K8s 管理能力尤其突出(99 个函数覆盖集群全生命周期)。前后端对接完整,UI/UX 打磨到位,部署方式灵活。
+
+**最大短板是工程质量(30/100)**: 零测试、无 CI、巨型文件。在 171 次/周的高频提交节奏下,缺乏测试保护是最高风险。**当前阶段的战略重心应从"功能开发"转向"质量加固"** — 建立 TDD 流程、搭建 CI/CD、拆分巨型文件,为后续的多云管理和智能化升级打下坚实工程基础。
@@ -0,0 +1,172 @@
+# AIOps 智能运维平台 — 开发路线图
+
+> 版本: v2.0
+> 更新日期: 2026-06-21
+> 当前阶段: **v0.3.0 — 质量加固** (从功能驱动转向质量驱动)
+> 关联文档: [PROJECT_EVALUATION.md](./PROJECT_EVALUATION.md) | [TDD_PLAN.md](./TDD_PLAN.md)
+
+---
+
+## 版本规划总览
+
+```
+已完成                                        当前聚焦
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━►
+  v0.1.0          v0.2.0          v0.3.0          v0.4.0          v1.0.0
+  MVP核心    →    AI能力增强  →   质量加固    →   企业级特性  →   智能化升级
+  [完成]          [完成]          [进行中]        [计划]          [计划]
+                                      
+                  ┌─────────────────────────────────────────────┐
+                  │  v0.3.0 重点: 测试 + CI + 重构 + API 文档    │
+                  │  目标: 工程质量 30 → 75, 综合评分 72 → 82    │
+                  └─────────────────────────────────────────────┘
+```
+
+| 版本 | 主题 | 状态 | 目标周期 | 核心交付 |
+|------|------|------|---------|---------|
+| v0.1.0 | MVP 核心功能 | ✅ 完成 | — | 资产/监控/发布/自动化 |
+| v0.2.0 | AI 能力增强 | ✅ 完成 | — | AI 告警分析/脚本生成/故障诊断 |
+| **v0.3.0** | **质量加固** | **🔄 进行中** | **2-4 周** | **测试 + CI/CD + 重构 + API 文档** |
+| v0.4.0 | 企业级特性 | 📋 计划 | Q3 2026 | MySQL 迁移 / 多云增强 / 安全合规 |
+| v1.0.0 | 智能化升级 | 📋 计划 | Q4 2026 | 智能自愈 / 知识图谱 / 开放 API |
+
+---
+
+## v0.3.0 — 质量加固 (当前版本)
+
+> **战略转折点**: 从"功能开发"转向"质量加固"
+> **验收标准**: 工程质量 ≥ 75, 后端测试覆盖率 ≥ 50%, CI 流水线全绿
+
+### Sprint 1: 测试基建 (第 1 周)
+
+| # | 任务 | 类型 | 优先级 | 验收标准 | 状态 |
+|---|------|------|--------|---------|------|
+| 1 | 后端测试框架搭建 | 后端 | P0 | `testify` + `httptest` 引入, `make test` 可运行 | ☐ |
+| 2 | K8s handler 单元测试 (第一批) | 后端 | P0 | 覆盖 cluster CRUD + sync, ≥ 15 个测试函数 | ☐ |
+| 3 | 认证模块测试 | 后端 | P0 | login/register/JWT 验证全覆盖 | ☐ |
+| 4 | 前端测试框架搭建 | 前端 | P1 | Vitest + Testing Library 引入, `npm test` 可运行 | ☐ |
+| 5 | CI 流水线搭建 | DevOps | P0 | `.gitea/workflows/ci.yml`: lint → test → build | ☐ |
+
+### Sprint 2: 核心重构 (第 2 周)
+
+| # | 任务 | 类型 | 优先级 | 验收标准 | 状态 |
+|---|------|------|--------|---------|------|
+| 6 | 拆分 kubernetes.go (96KB → 8 文件) | 后端 | P0 | cluster/deployment/pod/service/hpa/cronjob/config/node 各自独立 | ☐ |
+| 7 | Go module 重命名 ezops → aiops | 后端 | P1 | `go.mod` module 名 + 全量 import 路径替换 | ☐ |
+| 8 | K8s handler 测试 (第二批) | 后端 | P0 | 覆盖 deployment/scale/restart/HPA, ≥ 20 个测试函数 | ☐ |
+| 9 | Pipeline executor 测试 | 后端 | P1 | 覆盖 pipeline 创建/执行/日志流 | ☐ |
+| 10 | golangci-lint 集成 | DevOps | P1 | `.golangci.yml` 配置, CI 中 lint 零 error | ☐ |
+
+### Sprint 3: API 文档 + 前端测试 (第 3 周)
+
+| # | 任务 | 类型 | 优先级 | 验收标准 | 状态 |
+|---|------|------|--------|---------|------|
+| 11 | 引入 Swagger/swaggo | 后端 | P1 | `swag init` 生成 API 文档, 核心路由注解覆盖 | ☐ |
+| 12 | 告警引擎测试 | 后端 | P1 | 覆盖告警规则评估/通知触发/静默逻辑 | ☐ |
+| 13 | 前端核心组件测试 | 前端 | P2 | K8s/Login/Dashboard 组件 ≥ 10 个测试用例 | ☐ |
+| 14 | Playwright E2E 冒烟测试 | 前端 | P2 | 登录/服务器列表/K8s 集群 3 条核心流程 | ☐ |
+| 15 | 审计 CSV 导出 TODO | 后端 | P2 | `audit.go:223` 实现 CSV/Excel 导出 | ☐ |
+
+### Sprint 4: 质量收尾 (第 4 周)
+
+| # | 任务 | 类型 | 优先级 | 验收标准 | 状态 |
+|---|------|------|--------|---------|------|
+| 16 | 全量回归测试 | QA | P0 | 15 模块手动回归 + 自动化测试全绿 | ☐ |
+| 17 | 覆盖率报告 | DevOps | P1 | 后端 ≥ 50%, 生成覆盖率徽章 | ☐ |
+| 18 | 代码规范文档 | 文档 | P2 | 更新 CLAUDE.md + 新增 CONTRIBUTING.md | ☐ |
+| 19 | v0.3.0 Release Notes | 文档 | P2 | CHANGELOG.md 更新 | ☐ |
+| 20 | v0.3.0 发布部署 | DevOps | P0 | 3 种部署方式全部验证通过 | ☐ |
+
+### v0.3.0 验收检查点
+
+- [ ] 后端测试覆盖率 ≥ 50%
+- [ ] CI 流水线: push → lint → test → build → 全绿
+- [ ] kubernetes.go 拆分完成, 单文件不超过 500 行
+- [ ] API 文档可访问 (Swagger UI)
+- [ ] 前端冒烟 E2E 3 条流程通过
+- [ ] golangci-lint 零 error
+- [ ] 3 种部署方式全部验证通过
+
+---
+
+## v0.4.0 — 企业级特性 (计划 Q3 2026)
+
+> **目标**: 提升可扩展性和安全性,支撑生产级多租户部署
+
+### 后端任务
+
+| # | 任务 | 优先级 | 验收标准 |
+|---|------|--------|---------|
+| 1 | SQLite → MySQL 迁移 | P0 | 利用 GORM 抽象层,数据迁移脚本,双写过渡 |
+| 2 | 告警异步化 (Redis Stream) | P1 | 告警引擎解耦, 告警队列消费器 |
+| 3 | 多租户支持 (数据隔离) | P1 | tenant_id 全表注入, 查询自动过滤 |
+| 4 | 安全基线检查模块 | P2 | CIS Benchmark 基础检查 |
+| 5 | 漏洞扫描集成 | P2 | 对接 Trivy / Clair |
+
+### 前端任务
+
+| # | 任务 | 优先级 | 验收标准 |
+|---|------|--------|---------|
+| 6 | 自定义仪表盘 (拖拽) | P1 | 用户自定义监控面板组件 |
+| 7 | 告警降噪和聚合视图 | P2 | 告警分组/抑制/聚合展示 |
+| 8 | 多渠道告警通知配置 UI | P2 | 钉钉/飞书/企微/邮件/短信 |
+
+### DevOps 任务
+
+| # | 任务 | 优先级 | 验收标准 |
+|---|------|--------|---------|
+| 9 | Helm Chart 仓库 | P1 | 官方 Helm Chart + 版本管理 |
+| 10 | 蓝绿/金丝雀发布支持 | P2 | Pipeline 增加发布策略 |
+| 11 | 自动回滚机制 | P2 | 健康检查失败自动回滚 |
+
+---
+
+## v1.0.0 — 智能化升级 (计划 Q4 2026)
+
+> **目标**: 全栈智能化, 降低人工干预
+
+### 智能化
+
+| # | 任务 | 优先级 | 验收标准 |
+|---|------|--------|---------|
+| 1 | 智能自愈引擎 | P0 | 故障检测 → 自动修复 → 效果验证闭环 |
+| 2 | 运维知识图谱 | P1 | 故障知识沉淀 + 智能问答增强 |
+| 3 | 容量预测与扩缩容 | P1 | 基于历史数据的资源预测 |
+| 4 | AIOps 工作台 | P2 | 个性化运维视图 + 任务推荐 |
+
+### 生态
+
+| # | 任务 | 优先级 | 验收标准 |
+|---|------|--------|---------|
+| 5 | 开放 API 平台 (REST + GraphQL) | P1 | 完整 API 覆盖 + SDK |
+| 6 | 插件市场框架 | P2 | 插件 SDK + 官方插件 |
+| 7 | Webhook 体系完善 | P2 | 全事件 Webhook 通知 |
+
+---
+
+## 进度追踪表
+
+| 版本 | 状态 | 开始日期 | 完成日期 | 备注 |
+|------|------|---------|---------|------|
+| v0.1.0 MVP | ✅ 完成 | — | 2026-06 | 15 模块核心功能 |
+| v0.2.0 AI增强 | ✅ 完成 | — | 2026-06 | AI 告警/脚本/诊断 |
+| v0.3.0 质量加固 | 🔄 进行中 | 2026-06-21 | — | 当前聚焦 |
+| v0.4.0 企业级 | 📋 计划 | — | — | MySQL/多租户/安全 |
+| v1.0.0 智能化 | 📋 计划 | — | — | 自愈/知识图谱 |
+
+---
+
+## 技术债务清单 (持续追踪)
+
+| # | 债务 | 严重度 | 引入版本 | 计划清除版本 | 状态 |
+|---|------|--------|---------|------------|------|
+| 1 | 零测试覆盖 | 🔴 P0 | v0.1.0 | v0.3.0 | ☐ |
+| 2 | kubernetes.go 巨型文件 (96KB) | 🟡 P1 | v0.1.0 | v0.3.0 | ☐ |
+| 3 | Go module 名 `ezops` | 🟡 P1 | v0.1.0 | v0.3.0 | ☐ |
+| 4 | SQLite 并发瓶颈 | 🟡 P1 | v0.1.0 | v0.4.0 | ☐ |
+| 5 | 无 API 自动文档 | 🟡 P1 | v0.1.0 | v0.3.0 | ☐ |
+| 6 | 无 CI/CD 流水线 | 🔴 P0 | v0.1.0 | v0.3.0 | ☐ |
+| 7 | 审计 CSV 导出缺失 | 🟢 P2 | v0.1.0 | v0.3.0 | ☐ |
+| 8 | 无消息队列 | 🟢 P2 | v0.2.0 | v0.4.0 | ☐ |
+| 9 | 前端无 E2E 测试 | 🟢 P2 | v0.1.0 | v0.3.0 | ☐ |
+| 10 | 无多租户隔离 | 🟢 P2 | — | v0.4.0 | ☐ |
@@ -0,0 +1,385 @@
+# AIOps 智能运维平台 — TDD 开发计划
+
+> 版本: v1.0
+> 创建日期: 2026-06-21
+> 当前覆盖率: **0%** → 目标覆盖率: **≥ 50%** (v0.3.0)
+> 关联文档: [PROJECT_EVALUATION.md](./PROJECT_EVALUATION.md) | [ROADMAP.md](./ROADMAP.md)
+
+---
+
+## 一、TDD 原则
+
+### Red-Green-Refactor 循环
+
+```
+    ┌──────────┐     ┌──────────┐     ┌──────────┐
+    │  🔴 RED  │ ──► │ 🟢 GREEN │ ──► │ 🔵 REFACT│
+    │ 写失败测试 │     │ 最快实现  │     │ 消除重复  │
+    └──────────┘     └──────────┘     └──────────┘
+         ▲                                    │
+         └────────────────────────────────────┘
+                       循环
+```
+
+**三条核心规则:**
+
+1. **没有测试就不写产品代码** — 先写一个失败的测试,再写实现
+2. **每次只写刚好能通过的最少代码** — 不过度设计
+3. **测试通过后立即重构** — 消除重复,提升可读性
+
+### 测试金字塔
+
+```
+                    ╱╲
+                   ╱E2E╲           ← 少量 (Playwright, ~5%)
+                  ╱──────╲
+                 ╱ 集成测试 ╲       ← 适量 (httptest + DB, ~25%)
+                ╱────────────╲
+               ╱   单元测试    ╲    ← 大量 (纯函数/逻辑, ~70%)
+              ╱──────────────────╲
+```
+
+---
+
+## 二、测试框架选型
+
+### 后端 (Go)
+
+| 工具 | 用途 | 引入方式 |
+|------|------|---------|
+| `testing` (标准库) | 测试运行器 | 内置 |
+| `testify/assert` | 断言库 | `go get github.com/stretchr/testify/assert` |
+| `testify/require` | 致命断言 | 同上 |
+| `testify/mock` | Mock 框架 | 同上 |
+| `net/http/httptest` | HTTP handler 测试 | 内置 |
+| `gorm.io/driver/sqlite` :memory: | 内存数据库测试 | 已有依赖 |
+| `swaggo/swag` (可选) | API 文档 | `go get github.com/swaggo/swag/cmd/swag` |
+
+### 前端 (React)
+
+| 工具 | 用途 | 引入方式 |
+|------|------|---------|
+| `vitest` | 测试运行器 | `npm i -D vitest` |
+| `@testing-library/react` | 组件测试 | `npm i -D @testing-library/react` |
+| `@testing-library/jest-dom` | DOM 断言 | `npm i -D @testing-library/jest-dom` |
+| `@testing-library/user-event` | 用户交互模拟 | `npm i -D @testing-library/user-event` |
+| `msw` | API Mock | `npm i -D msw` |
+| `@playwright/test` | E2E 测试 | `npm i -D @playwright/test` |
+
+---
+
+## 三、后端逐模块测试计划
+
+### 阶段 1: 核心模块 (第 1-2 周) — 目标覆盖率 40%
+
+#### 1.1 认证模块 (`user.go`, `user_admin.go`)
+
+| 测试文件 | 测试函数 | 覆盖场景 | 优先级 |
+|---------|---------|---------|--------|
+| `user_test.go` | `TestLogin_Success` | 正确用户名密码 → 200 + JWT | P0 |
+| | `TestLogin_WrongPassword` | 错误密码 → 401 | P0 |
+| | `TestLogin_UserNotFound` | 不存在用户 → 401 | P0 |
+| | `TestRegister_Success` | 正常注册 → 201 | P0 |
+| | `TestRegister_DuplicateUsername` | 重复用户名 → 409 | P0 |
+| | `TestGetProfile_Authenticated` | 带 JWT → 200 + 用户信息 | P0 |
+| | `TestGetProfile_NoAuth` | 无 JWT → 401 | P0 |
+| | `TestChangePassword_Success` | 正确旧密码 → 200 | P1 |
+| | `TestChangePassword_WrongOld` | 错误旧密码 → 400 | P1 |
+| | `TestJWTAuth_ValidToken` | 有效 JWT → 放行 | P0 |
+| | `TestJWTAuth_ExpiredToken` | 过期 JWT → 401 | P0 |
+| | `TestJWTAuth_MalformedToken` | 畸形 JWT → 401 | P1 |
+
+#### 1.2 Kubernetes 模块 (`kubernetes.go`) — 最高优先级
+
+| 测试文件 | 测试函数 | 覆盖场景 | 优先级 |
+|---------|---------|---------|--------|
+| `kubernetes_cluster_test.go` | `TestListClusters_Empty` | 空列表 → 200 + [] | P0 |
+| | `TestListClusters_With3Records` | 3 条记录 → 200 + 3 items | P0 |
+| | `TestCreateCluster_ValidInput` | 合法 Name/Code → 201 | P0 |
+| | `TestCreateCluster_InvalidName` | Name 含中文/空格 → 400 | P0 |
+| | `TestCreateCluster_DuplicateCode` | 重复 Code → 409 | P0 |
+| | `TestGetCluster_Found` | 存在的 ID → 200 | P0 |
+| | `TestGetCluster_NotFound` | 不存在的 ID → 404 | P0 |
+| | `TestUpdateCluster_Success` | 更新名称 → 200 | P1 |
+| | `TestDeleteCluster_Success` | 删除 → 200 | P1 |
+| | `TestDeleteCluster_NotFound` | 删除不存在 → 404 | P1 |
+| | `TestSyncCluster_Success` | 同步集群资源 → 200 + 统计 | P0 |
+| | `TestResolveClusterCode_Valid` | code 解析 → cluster ID | P0 |
+| | `TestResolveClusterCode_NotFound` | 无效 code → 错误 | P0 |
+| `kubernetes_workload_test.go` | `TestListDeployments_NS` | 按命名空间过滤 → 200 | P0 |
+| | `TestScaleDeployment_Up` | 扩容 1→3 → 200 + replicas=3 | P0 |
+| | `TestScaleDeployment_Down` | 缩容 3→1 → 200 | P1 |
+| | `TestRestartDeployment_Success` | 滚动重启 → 200 | P0 |
+| | `TestUpdateDeploymentImage_Success` | 更新镜像 → 200 | P1 |
+| | `TestListHPAs_NS` | HPA 列表 → 200 | P1 |
+| | `TestCreateHPA_Valid` | 创建 HPA → 201 | P1 |
+| | `TestDeleteHPA_Success` | 删除 HPA → 200 | P2 |
+| | `TestListCronJobs_NS` | CronJob 列表 → 200 | P1 |
+| | `TestCreateCronJob_Valid` | 创建 CronJob → 201 | P1 |
+| | `TestSuspendCronJob_Success` | 挂起 → 200 | P2 |
+| | `TestTriggerCronJob_Success` | 手动触发 → 200 | P2 |
+
+> **注意:** K8s 测试需要 Mock `kubernetesclient.Client` 接口,不依赖真实集群。使用 `testify/mock` 或接口抽象。
+
+#### 1.3 CI/CD Pipeline 模块 (`pipeline.go`, `pipeline_executor.go`)
+
+| 测试文件 | 测试函数 | 覆盖场景 | 优先级 |
+|---------|---------|---------|--------|
+| `pipeline_test.go` | `TestCreatePipeline_Valid` | 合法配置 → 201 | P0 |
+| | `TestCreatePipeline_DuplicateCode` | 重复 code → 409 | P0 |
+| | `TestListPipelines_Pagination` | 分页 → 正确总数+页 | P1 |
+| | `TestGetPipeline_Found` | 查询 → 200 | P0 |
+| | `TestUpdatePipeline_Success` | 更新 → 200 | P1 |
+| | `TestDeletePipeline_Success` | 删除 → 200 | P1 |
+| | `TestWebhookTrigger_Valid` | Webhook 触发 → 200 + run | P0 |
+| `pipeline_executor_test.go` | `TestExecutePipeline_AllStepsPass` | 全步骤通过 → success | P0 |
+| | `TestExecutePipeline_StepFail` | 步骤失败 → failed | P0 |
+| | `TestExecutePipeline_Conditional` | 条件步骤 → skip/execute | P1 |
+
+### 阶段 2: 监控/告警模块 (第 3 周) — 目标覆盖率 50%
+
+#### 2.1 告警引擎 (`alert_engine.go`, `alert_rules.go`)
+
+| 测试文件 | 测试函数 | 覆盖场景 | 优先级 |
+|---------|---------|---------|--------|
+| `alert_engine_test.go` | `TestEvaluateRule_ThresholdExceeded` | CPU > 90% → 触发 | P0 |
+| | `TestEvaluateRule_ThresholdNormal` | CPU < 90% → 不触发 | P0 |
+| | `TestEvaluateRule_OfflineDetection` | Agent 离线 → 触发 | P0 |
+| | `TestEvaluateRule_SilencedPeriod` | 静默期内 → 不触发 | P1 |
+| | `TestSendAlert_AllChannels` | 通知全渠道 → 计数正确 | P1 |
+| `alert_rules_test.go` | `TestCreateAlertRule_Valid` | 创建规则 → 201 | P1 |
+| | `TestListAlertRules_BySeverity` | 按级别过滤 → 200 | P1 |
+| | `TestUpdateAlertRule_Toggle` | 启用/禁用 → 200 | P2 |
+
+#### 2.2 服务器管理 (`server.go`)
+
+| 测试文件 | 测试函数 | 覆盖场景 | 优先级 |
+|---------|---------|---------|--------|
+| `server_test.go` | `TestListServers_Pagination` | 分页 → 正确 | P1 |
+| | `TestCreateServer_Valid` | 合法 → 201 | P1 |
+| | `TestBatchCreateServers_3Items` | 批量创建 3 条 → 201 | P1 |
+| | `TestBatchDeleteServers_3IDs` | 批量删除 → 200 | P2 |
+| | `TestGetServerStats_Aggregation` | 统计聚合 → 正确数字 | P2 |
+
+#### 2.3 云资源 (`cloud_accounts.go`, `cloud_sync.go`)
+
+| 测试文件 | 测试函数 | 覆盖场景 | 优先级 |
+|---------|---------|---------|--------|
+| `cloud_accounts_test.go` | `TestCreateCloudAccount_Valid` | 合法 → 201 | P1 |
+| | `TestCreateCloudAccount_InvalidAK` | 空 AK → 400 | P2 |
+| | `TestListCloudAccounts_ByPlatform` | 按平台过滤 → 200 | P2 |
+| `cloud_sync_test.go` | `TestDiscoverInstances_MockProvider` | Mock 云 API → 正确实例 | P2 |
+
+### 阶段 3: 补全覆盖 (第 4 周) — 目标覆盖率 50%+
+
+#### 3.1 Agent / 自动化 / 审批
+
+| 测试文件 | 测试函数 | 覆盖场景 | 优先级 |
+|---------|---------|---------|--------|
+| `agent_test.go` | `TestRegisterAgent_New` | 新注册 → 201 | P1 |
+| | `TestAgentHeartbeat_Update` | 心跳 → 更新时间 | P1 |
+| | `TestAssignTask_AvailableAgent` | 分配任务 → 200 | P2 |
+| `automation_cron_test.go` | `TestCreateCronJob_Valid` | 创建定时任务 → 201 | P1 |
+| | `TestListCronJobs_FilterByStatus` | 按状态过滤 → 200 | P2 |
+| `approval_test.go` | `TestCreateApprovalRequest_Valid` | 创建审批 → 201 | P1 |
+| | `TestApproveRequest_Success` | 审批通过 → 200 | P1 |
+| | `TestRejectRequest_WithReason` | 审批拒绝 → 200 | P2 |
+| `audit_test.go` | `TestListAuditLogs_Pagination` | 审计日志分页 → 200 | P2 |
+| | `TestExportAuditLogs_CSV` | CSV 导出 → 200 + text/csv | P2 |
+
+---
+
+## 四、前端测试计划
+
+### 阶段 1: 基建 + 核心组件 (第 2-3 周)
+
+#### 4.1 单元测试 (Vitest)
+
+| 测试文件 | 覆盖场景 | 优先级 |
+|---------|---------|--------|
+| `api.test.ts` | API 函数参数构造/响应解析 Mock | P1 |
+| `auth/LoginForm.test.tsx` | 表单验证/提交/错误展示 | P0 |
+| `kubernetes/KubernetesClusters.test.tsx` | 集群列表渲染/创建对话框 | P0 |
+| `kubernetes/DeploymentDetail.test.tsx` | Deployment 详情渲染/操作按钮 | P1 |
+| `server/ServerManager.test.tsx` | 服务器列表/搜索/分页 | P1 |
+| `dashboard/StatsCard.test.tsx` | 统计卡片数据渲染 | P2 |
+
+#### 4.2 E2E 测试 (Playwright) — 冒烟流程
+
+| 测试文件 | 覆盖流程 | 优先级 |
+|---------|---------|--------|
+| `e2e/login.spec.ts` | 登录 → 跳转仪表盘 → 验证菜单 | P0 |
+| `e2e/server-list.spec.ts` | 服务器列表 → 搜索 → 查看详情 → WebShell | P1 |
+| `e2e/k8s-cluster.spec.ts` | K8s 集群 → 工作负载 → Deployment 详情 → 日志 | P1 |
+
+---
+
+## 五、测试执行策略
+
+### 三级执行体系
+
+| 级别 | 触发时机 | 执行内容 | 耗时目标 |
+|------|---------|---------|---------|
+| **日常开发** | `git commit` (pre-push hook) | 后端单元测试 + lint | < 30s |
+| **PR 检查** | PR 创建/更新 (CI) | 全量测试 + lint + build + 覆盖率 | < 5min |
+| **发布门禁** | tag/release (CI) | 全量 + E2E + 安全扫描 + 3 种部署验证 | < 15min |
+
+### Makefile 集成
+
+```makefile
+# 后端测试
+test:
+	cd backend && go test ./... -v -count=1
+
+test-cover:
+	cd backend && go test ./... -coverprofile=coverage.out -covermode=atomic
+	go tool cover -html=coverage.out -o coverage.html
+
+test-short:
+	cd backend && go test ./... -v -short -count=1
+
+# 前端测试
+test-fe:
+	cd frontend && npx vitest run
+
+test-fe-watch:
+	cd frontend && npx vitest
+
+test-e2e:
+	cd frontend && npx playwright test
+
+# 全量测试
+test-all: test-cover test-fe test-e2e
+	@echo "✅ All tests passed"
+
+# lint
+lint:
+	cd backend && golangci-lint run
+	cd frontend && npx eslint src --max-warnings 0
+```
+
+### CI 流水线 (`.gitea/workflows/ci.yml`)
+
+```yaml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  backend-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+      - run: cd backend && go vet ./...
+      - run: cd backend && golangci-lint run
+      - run: cd backend && go test ./... -coverprofile=coverage.out -race
+      - run: cd backend && go tool cover -func=coverage.out
+
+  frontend-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: cd frontend && npm ci
+      - run: cd frontend && npx vitest run --coverage
+      - run: cd frontend && npx tsc --noEmit
+
+  build:
+    needs: [backend-test, frontend-test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: make build
+```
+
+---
+
+## 六、覆盖率里程碑
+
+| 版本 | 后端覆盖率 | 前端覆盖率 | E2E 覆盖 | 说明 |
+|------|-----------|-----------|---------|------|
+| **当前** | **0%** | **0%** | **0%** | 零起点 |
+| v0.3.0 Sprint 1 | 15% | 5% | 0% | 核心模块首批测试 |
+| v0.3.0 Sprint 2 | 30% | 10% | 0% | K8s 全覆盖 + 重构 |
+| v0.3.0 Sprint 3 | 45% | 15% | 3 条 | 监控/告警 + E2E 冒烟 |
+| **v0.3.0 发布** | **≥ 50%** | **≥ 15%** | **3 条** | 质量加固验收 |
+| v0.4.0 | ≥ 65% | ≥ 30% | 8 条 | 企业级特性 + 测试增强 |
+| v1.0.0 | ≥ 75% | ≥ 50% | 20 条 | 智能化 + 全量覆盖 |
+
+### 覆盖率豁免规则
+
+以下代码允许低覆盖率:
+- `main.go` / `cmd/` — 入口文件,由 E2E 覆盖
+- `scripts/` — 种子数据/Mock 脚本
+- WebSocket handler — 由集成测试覆盖
+- `pkg/crypto` — 安全敏感,由专项安全测试覆盖
+
+---
+
+## 七、Mock 策略
+
+### 后端 Mock 层次
+
+```
+┌─────────────────────────────────────┐
+│         HTTP Handler Test           │  ← httptest.NewServer
+├─────────────────────────────────────┤
+│         Service / Business          │  ← 接口注入 Mock
+├─────────────────────────────────────┤
+│         Data Access (GORM)          │  ← SQLite :memory: 真实 DB
+├─────────────────────────────────────┤
+│    External (K8s/Prometheus/SSH)    │  ← Interface Mock
+└─────────────────────────────────────┘
+```
+
+**原则:**
+- **数据库层**: 使用 SQLite `:memory:` 真实测试,不用 Mock (GORM 兼容)
+- **外部服务** (K8s/Prometheus/Zabbix): 抽象为 interface,用 `testify/mock` 替换
+- **HTTP handler**: 使用 `httptest` 发起真实 HTTP 请求测试
+
+### K8s Client Mock 示例
+
+```go
+// 定义 interface (如果没有的话)
+type K8sClientInterface interface {
+    ListDeployments(namespace string) ([]appsv1.Deployment, error)
+    ScaleDeployment(name, namespace string, replicas int32) error
+    // ...
+}
+
+// Mock 实现
+type MockK8sClient struct {
+    mock.Mock
+}
+
+func (m *MockK8sClient) ListDeployments(ns string) ([]appsv1.Deployment, error) {
+    args := m.Called(ns)
+    return args.Get(0).([]appsv1.Deployment), args.Error(1)
+}
+
+// 测试中使用
+func TestListDeployments_NS(t *testing.T) {
+    mockClient := new(MockK8sClient)
+    mockClient.On("ListDeployments", "default").Return([]appsv1.Deployment{...}, nil)
+    
+    handler := &KubernetesHandler{k8sClient: mockClient, db: testDB}
+    // ... HTTP 测试
+}
+```
+
+---
+
+## 八、常见陷阱
+
+1. **不要 Mock 数据库** — 用 SQLite `:memory:` 真实测试 GORM 逻辑,Mock DB 会漏掉 SQL 错误
+2. **测试必须独立** — 每个测试用例使用独立 DB 实例或事务回滚,避免数据污染
+3. **K8s 测试不连真实集群** — 通过 interface Mock,CI 环境没有 K8s
+4. **WebSocket 测试用 dialer** — 不依赖浏览器,用 `gorilla/websocket` dialer 模拟
+5. **前端测试不依赖网络** — 用 MSW 拦截所有 API 请求
+6. **测试命名清晰** — `Test<函数>_<场景>` 格式,如 `TestLogin_WrongPassword`
+7. **覆盖率不是目的** — 50% 覆盖核心逻辑 > 90% 覆盖 getter/setter
+8. **先写最难的测试** — K8s handler 99 个函数,从 cluster CRUD 开始(逻辑最核心)