chore: initial import

docs/CHANGELOG.md

@@ -0,0 +1,20 @@
+# AI-Ops 更新日志
+
+## 2026-05-11 — Review 修复
+
+### 已完成
+- [x] 统一回滚错误码：PRD / HLD / INTERFACE 三处不一致，统一为 `OPS_AUD_4101` / `OPS_AUD_4102`
+- [x] 修复笔误："游戏化事务" → "编程式事务"，"预畈" → "预留"
+- [x] 填充 docs/ 目录：新增 README.md、CHANGELOG.md
+- [x] 补齐数据库 migration SQL：`tech/migrations/000001_init_schema.up.sql` / `.down.sql`
+  - 覆盖核心 6 张表：ai_ops_rules / ai_ops_alerts / ai_ops_healings / ai_ops_channels / ai_ops_audits / ai_ops_metrics
+  - 审计日志防篡改触发器（append-only）
+  - 时序表分区策略（按天分区，自动清理 > 7 天）
+- [x] 功能清单裁剪：删除 66 条 PM 越界按钮级任务，添加 PM/Engineer 范围边界说明
+- [x] HLD 门控结论更新为具体行动项：
+  - 威胁建模验证要求转化为 CI 阻断测试
+  - `BuildServer` / `BuildRuntime` 显式挂载约束落实为 QA 阻断检查项
+  - 高风险变更 fail-closed 规则明确化
+
+### 待完成
+- [ ] 项目骨架（go.mod、Makefile、Dockerfile — 待开发阶段启动）

docs/EXECUTION_BOARD.md

@@ -0,0 +1,91 @@
+# AI-Ops Phase 1 代码开发执行板
+
+> 状态：开发中  
+> 最后更新：2026-05-11  
+> 负责人：小龙（统筹）
+
+---
+
+## 一、Phase 1 范围
+
+| 模块 | 功能点 | 工期 | 状态 |
+|------|--------|------|------|
+| 1.1 监控首页 | 首页布局 + 实时指标 + 供应商数 + 告警数 + 指标下钻 | 5 人天 | 骨架完成 |
+| 1.2 日志查询 | 查询页 + 表格展示 + 分页 + CSV 导出 + 超时 + Redis 缓存 | 3 人天 | 骨架完成 |
+
+**总计：8 人天**
+
+---
+
+## 二、任务清单
+
+### 模块 1.1：监控首页
+
+| 任务 ID | 任务 | 产出物 | 状态 | 备注 |
+|---------|------|--------|------|------|
+| C1-01 | 项目初始化（go mod + 目录结构） | go.mod + 目录树 | 完成 | 21 个 Go 文件 |
+| C1-02 | 基础设施（config、database、redis、errors、response） | internal/{config,database,redis}/ + pkg/ | 完成 | 待 go mod tidy 下载依赖 |
+| C1-03 | Domain 层（models + repository 接口） | internal/domain/{model,repository}/ | 完成 | 3 model + 3 interface |
+| C1-04 | Infra 层（PostgreSQL 实现） | internal/infra/repository/pg_*.go | 完成 | 3 个 repository |
+| C1-05 | Service 层（metrics + log 业务逻辑） | internal/service/*.go | 完成 | 含 CSV 导出、Redis 缓存 |
+| C1-06 | Handler 层（HTTP API） | internal/handler/*.go | 完成 | 7 个 API 端点 |
+| C1-07 | Middleware（auth、logging、recovery） | internal/middleware/*.go | 完成 | JWT + API Key 双鉴权 |
+| C1-08 | 首页路由 /ops/dashboard | dashboard_handler.go | 完成 | 内联模板，待优化为文件模板 |
+| C1-09 | 实时指标 API /api/v1/ai-ops/metrics/realtime | metric_handler.go | 完成 | 查询 ai_ops_metrics 表 |
+| C1-10 | 供应商数量 API /api/v1/ai-ops/metrics/suppliers/count | metric_handler.go | 完成 | 基于 supplier_health 指标 |
+| C1-11 | 告警数量 API /api/v1/ai-ops/alerts/open/count | metric_handler.go | 完成 | 查询 ai_ops_alerts 表 |
+| C1-12 | 指标下钻 API /api/v1/ai-ops/metrics/query | metric_handler.go | 完成 | 支持时间范围过滤 |
+| C1-13 | 前端模板优化 | web/templates/*.html | 待办 | 当前为内联模板 |
+
+### 模块 1.2：日志查询
+
+| 任务 ID | 任务 | 产出物 | 状态 | 备注 |
+|---------|------|--------|------|------|
+| C2-01 | 日志查询页路由 /ops/dashboard/logs | dashboard_handler.go | 完成 | 内联模板 |
+| C2-02 | 日志查询 API /api/v1/ai-ops/logs | log_handler.go | 完成 | 支持分页 + 多维度筛选 |
+| C2-03 | CSV 导出 /api/v1/ai-ops/logs/export | log_handler.go | 完成 | 上限 10000 条 |
+| C2-04 | 查询超时逻辑 | log_service.go | 完成 | 3 秒超时 |
+| C2-05 | Redis 缓存（5 分钟 TTL） | log_service.go | 完成 | 基于筛选条件构建缓存键 |
+| C2-06 | 日志表 migration | tech/migrations/000002_create_request_logs.up.sql | 完成 | 7 个索引 |
+
+### 通用任务
+
+| 任务 ID | 任务 | 产出物 | 状态 | 备注 |
+|---------|------|--------|------|------|
+| C0-01 | 基础测试（service + handler mock 测试） | *_test.go | 完成 | 2 个测试文件 |
+| C0-02 | 编译验证 | go build | 阻塞 | 缺少 go.sum，需运行 go mod tidy |
+| C0-03 | 性能测试脚本（k6） | test/perf/ | 待办 | Phase 1 功能清单未要求，可延后 |
+| C0-04 | 配置示例 | config.yaml | 完成 | 支持环境变量覆盖 |
+
+---
+
+## 三、API 端点清单
+
+| 方法 | 路径 | 说明 | 状态 |
+|------|------|------|------|
+| GET | /ops/dashboard | 监控首页 | 完成 |
+| GET | /ops/dashboard/logs | 日志查询页 | 完成 |
+| GET | /api/v1/ai-ops/metrics/realtime | 实时指标（QPS/延迟/P99/错误率） | 完成 |
+| GET | /api/v1/ai-ops/metrics/suppliers/count | 活跃供应商数量 | 完成 |
+| GET | /api/v1/ai-ops/alerts/open/count | 未关闭告警数量 | 完成 |
+| GET | /api/v1/ai-ops/metrics/query | 指标下钻查询 | 完成 |
+| GET | /api/v1/ai-ops/logs | 日志查询（分页） | 完成 |
+| GET | /api/v1/ai-ops/logs/export | 日志导出 CSV | 完成 |
+| GET | /health | 健康检查 | 完成 |
+
+---
+
+## 四、阻塞项
+
+| 阻塞项 | 影响 | 解决方案 | 负责人 |
+|--------|------|----------|--------|
+| go.sum 缺失 | 无法编译运行 | 运行 `go mod tidy` 下载依赖并生成 go.sum | 用户/运维 |
+
+---
+
+## 五、下一步行动
+
+1. **编译验证**：运行 `go mod tidy` + `go build ./...` 解决依赖和编译错误
+2. **模板分离**：将内联 HTML 模板提取到 `web/templates/` 目录
+3. **集成测试**：补充数据库集成测试（使用 testcontainers 或内存 PostgreSQL）
+4. **Phase 1 验收**：所有 API 可访问，日志查询响应 <1s，CSV 导出正常

docs/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,199 @@
+# AI-Ops 智能运维系统 — 详细实施计划
+
+> 版本：v1.0
+> 生成日期：2026-05-11
+> 编制：小龙（统筹）
+> 基准：汇总审核报告与改进任务清单
+
+---
+
+## 一、实施总览
+
+| 项目 | 内容 |
+|------|------|
+| 总任务数 | 48 项（P0: 16, P1: 18, P2: 14） |
+| 总预估工时 | 24 人天（含 20% 联调缓冲） |
+| 建议人员配置 | PM 0.5F + TechLead 0.5F + QA 0.3F + Security 0.2F |
+| 总周期 | 2~3 周（并行执行时） |
+| 进入开发门禁 | 所有 P0 闭环 + PM/TechLead/QA 三方复审通过 |
+
+---
+
+## 二、时间线
+
+```
+Week 1          Week 2          Week 3
+|---------------|---------------|---------------|
+Phase 0 文档修复  Phase 1+需求   Phase 2+技术   Phase 3+测试   Phase 4+安全
+(所有 P0)      (所有 P1)     (所有 P1)    (所有 P1)    (P1+P2)
+|=======|       |=======|       |=======|       |=======|       |=====|
+        ↓复审            ↓复审            ↓复审            ↓复审            ↓复审
+```
+
+---
+
+## 三、Phase 0 — 文档修复与对齐（Week 1，16 项，8 人天）
+
+**目标：消除所有 P0 问题，确保文档间一致性。本 Phase 是进入开发的绝对前提。**
+
+### 3.1 接口对齐（TechLead 主导）
+
+| 任务 ID | 任务名称 | 责任人 | 工时 | 产出物 | 依赖 | 验收标准 |
+|----------|----------|--------|------|--------|------|----------|
+| D0-01 | 召开接口对齐会 | TechLead | 0.5d | `docs/INTEGRATION_CONTRACT.md` | 无 | HLD/INTERFACE/DEPLOYMENT 三份文档无接口冲突 |
+| D0-02 | 补齐或删除 ER 图中 4 张缺失表 | TechLead | 0.5d | HLD §4.2 更新 + `migrations/000001_init_schema.up.sql` 更新 | D0-01 | migration 与 ER 图一致，CI `go test` 通过 |
+| D0-03 | 统一自愈动作命名 | TechLead | 0.5d | HLD §3.3 + INTERFACE §1.3 + 功能清单 3.1.2 同步更新 | D0-01 | 全文档自愈动作命名一致，搜索无冲突 |
+| D0-04 | 定义 IntegrationPlugin Go interface | TechLead | 0.5d | INTERFACE.md 新增 §X | D0-01 | interface 含 Name/Init/RegisterRoutes/HealthChecks/Shutdown 方法，有注释和示例 |
+
+### 3.2 需求修正（PM 主导）
+
+| 任务 ID | 任务名称 | 责任人 | 工时 | 产出物 | 依赖 | 验收标准 |
+|----------|----------|--------|------|--------|------|----------|
+| R0-01 | 解决范围冲突：明确供应商智能切换定位 | PM | 0.5d | PRD §3 更新 + 功能清单 相关章节 | 无 | PRD In/Out of Scope 与功能清单一致，无范围模糊区 |
+| R0-02 | 重新估算工期 | PM | 0.5d | 功能清单 “任务估算汇总” 更新 | 无 | 138 任务总估算在 30~40 人天，含缓冲 |
+| R0-03 | 补充自愈动作“重启实例”实现任务 | PM | 0.5d | 功能清单 3.1.2 更新 | R0-01 | 功能清单包含重启实例任务，与 AC-6 对应 |
+
+### 3.3 安全基线（Security 主导）
+
+| 任务 ID | 任务名称 | 责任人 | 工时 | 产出物 | 依赖 | 验收标准 |
+|----------|----------|--------|------|--------|------|----------|
+| S0-01 | 在威胁建模中增加 LLM 特有风险 | Security | 0.5d | HLD §10.1 更新 | 无 | 威胁建模覆盖 LLM Top 5 风险，每个有缓解策略 |
+| S0-02 | 补充审计表防篡改触发器 | Security | 0.5d | `migrations/000001_init_schema.up.sql` 新增触发器 | D0-02 | 审计表执行 UPDATE/DELETE 时报错，单测验证 |
+| S0-03 | 明确审计写入与业务执行的事务顺序 | Security | 0.5d | HLD §3.3 更新 | 无 | 文档明确"先写审计再执行业务"，含回滚机制 |
+| S0-04 | 补充 WebSocket JWT 鉴权说明 | Security | 0.5d | INTERFACE §3.4 更新 | 无 | WebSocket 接口含连接建立时的 token 校验流程 |
+| S0-05 | 在 HLD 中增加参数化查询强制要求 | Security | 0.5d | HLD §4 更新 | 无 | 所有数据库交互层必须使用参数化/预编译查询 |
+| S0-06 | 限制 /metrics 端点访问 | Security | 0.5d | INTERFACE §3.2 更新 | 无 | /metrics 含内网 IP 限制或 API Key 鉴权说明 |
+
+### 3.4 测试资产（QA 主导）
+
+| 任务 ID | 任务名称 | 责任人 | 工时 | 产出物 | 依赖 | 验收标准 |
+|----------|----------|--------|------|--------|------|----------|
+| T0-01 | 为 8 个缺失负向用例的 AC 补充负向用例 | QA | 1d | TEST_DESIGN.md + CASES.md 更新 | 无 | 每个 AC 至少 1 正向 + 1 负向，PRD AC 覆盖率 100% |
+| T0-02 | 补充 F-05~F-08 异常流程用例 | QA | 0.5d | CASES.md 新增 TC-E5~E8 | 无 | 8 条异常流程全部有对应用例 |
+| T0-03 | 创建 CI 配置文件 | QA | 0.5d | `.github/workflows/ci.yml` | 无 | PR 提交时自动触发，覆盖率不达标时 exit 1 |
+| T0-04 | 创建性能压测目录 | QA | 0.5d | `test/perf/dashboard_k6.js` + `test/perf/drilldown_k6.js` + `test/perf/PERF_ENV.md` | 无 | k6 脚本可执行，含环境规格和 P99 计算方法 |
+
+---
+
+## 四、Phase 1 — 需求与产品级 P1 闭环（Week 1~2，9 项，4.5 人天）
+
+**目标：PRD 完善，AC 可测试，权限明确。**
+
+| 任务 ID | 任务名称 | 责任人 | 工时 | 产出物 | 依赖 | 验收标准 |
+|----------|----------|--------|------|--------|------|----------|
+| R1-01 | 统一失败判定线 | PM | 0.5d | PRD §2 + §8.3 更新 | R0-01 | 只有一条失败判定线，时间窗口、阈值统一 |
+| R1-02 | 删除“不仅仅包括于” | PM | 0.5d | PRD §3 更新 | 无 | In Scope 为封闭列表，无"等”和"包括不仅仅于" |
+| R1-03 | 统一通知渠道列表 | PM | 0.5d | PRD AC-4 + 功能清单 更新 | R0-01 | 通知渠道列表在所有文档中一致 |
+| R1-04 | AC-7 补充不可篡改技术实现定义 | PM | 0.5d | PRD AC-7 更新 | S0-02 | 明确实现方式（触发器 + 只追加） |
+| R1-05 | AC-8 补充“有效”判定标准 | PM | 0.5d | PRD AC-8 更新 | 无 | 明确"有效"的定义（非空、JSON 可解析、Schema 匹配） |
+| R1-06 | AC-6 补充级联故障回退验收点 | PM | 0.5d | PRD AC-6 更新 | D0-03 | AC-6 含级联故障回退的验收条件 |
+| R1-07 | 容量预测（AC-9）补充可测试标准 | PM | 0.5d | PRD AC-9 更新 | 无 | 含量化指标（如 MAPE<30%） |
+| R1-08 | 补充 UI 最低兼容性要求 | PM | 0.5d | PRD 新增章节 | 无 | 明确浏览器、分辨率、移动端策略 |
+| R1-09 | 细化角色权限矩阵到 API 级别 | PM | 0.5d | PRD AC-12 + 功能清单 G1 更新 | D1-07 | 以表格形式列出各角色对关键 API 的 CRUD 权限 |
+
+---
+
+## 五、Phase 2 — 技术设计级 P1 闭环（Week 2，9 项，4.5 人天）
+
+**目标：HLD/DEPLOYMENT 完善，部署可执行，规则评估有扩展方案。**
+
+| 任务 ID | 任务名称 | 责任人 | 工时 | 产出物 | 依赖 | 验收标准 |
+|----------|----------|--------|------|--------|------|----------|
+| D1-05 | 修正 DEPLOYMENT “主备”为 active-active | TechLead | 0.5d | DEPLOYMENT §1.1 更新 | 无 | 描述为多实例多活 + 负载均衡 |
+| D1-06 | 分离 migration 执行从 Worker | TechLead | 0.5d | DEPLOYMENT §3.2 更新 | D0-02 | migration 由 init container 或 K8s Job 执行 |
+| D1-07 | 补充 `ai_ops_roles` 表结构 | TechLead | 0.5d | HLD §8.1 + migration 更新 | D0-02 | 表含 id/role_name/permissions/created_at，CI 通过 |
+| D1-08 | 补充 `ai_ops_snapshots` 表结构 | TechLead | 0.5d | HLD §3.3 + migration 更新 | D0-02 | 表含 id/healing_id/state_json/config_version/created_at |
+| D1-09 | 完善告警聚合状态机 | TechLead | 0.5d | HLD §5.2 更新 | 无 | 含解除规则、子告警与父告警状态同步策略 |
+| D1-10 | 补充规则评估分片策略 | TechLead | 0.5d | HLD §9.1/9.2 更新 | 无 | 含分片键、负载均衡方案、水平扩展策略 |
+| D2-12 | 完善 metrics 分区表管理策略 | TechLead | 0.5d | migration + HLD 更新 | D0-02 | 含按天分区或应用层定时任务说明 |
+| D2-14 | 补充 Graceful Shutdown WebSocket 关闭策略 | TechLead | 0.5d | DEPLOYMENT §3.2 更新 | S0-04 | 含 close frame + 5s ack 等待机制 |
+| D2-15 | 重新校准时序存储容量估算 | TechLead | 0.5d | HLD §9.3 更新 | 无 | 参考 Prometheus 官方公式，给出保守估算 |
+
+---
+
+## 六、Phase 3 — 测试资产完善（Week 2~3，8 项，4 人天）
+
+**目标：测试用例完整，CI 可运行，混沌测试有设计，E2E 有场景。**
+
+| 任务 ID | 任务名称 | 责任人 | 工时 | 产出物 | 依赖 | 验收标准 |
+|----------|----------|--------|------|--------|------|----------|
+| T1-01 | 建立覆盖率验证机制 | QA | 0.5d | `scripts/check_coverage.sh` + STRATEGY.md 更新 | T0-03 | CI 中自动解析 coverprofile，按模块阻断 |
+| T1-02 | 设计 3 条混沌测试用例 | QA | 0.5d | TEST_DESIGN.md 新增混沌测试章节 | T0-02 | 含 Given-When-Then，覆盖 Pod 杀死/Redis 分区/PG 切换 |
+| T1-03 | 完善测试数据管理规范 | QA | 0.5d | STRATEGY.md 更新 + `test/fixtures/` 目录结构文档 | T0-03 | 含 SQL/JSON/Go seed 三种方式，含大数据生成脚本说明 |
+| T1-04 | 为灰度门禁增加自动化判定脚本 | QA | 0.5d | `scripts/gate_check.sh` + TEST_DESIGN.md §5.2 更新 | T0-03 | 脚本可自动采集覆盖率/沙盒验证/安全扫描结果 |
+| T1-05 | 明确安全扫描工具与阈值 | QA | 0.5d | STRATEGY.md 更新 | S0-01 | 明确工具（Trivy/Gosec）、漏洞等级定义、扫描时机 |
+| T1-06 | 补充 E2E 详细场景设计 | QA | 0.5d | TEST_DESIGN.md + CASES.md 新增 E2E 章节 | T0-01 | 含完整链路：指标异常→告警触发→通知发送→自愈执行→事件记录 |
+| T2-01 | 统一用例编号风格 | QA | 0.5d | TEST_DESIGN.md + CASES.md 全文更新 | T0-01 | 全部统一为 TC-{AC}-{seq} |
+| T2-02 | 补充 Webhook 5xx 测试场景 | QA | 0.5d | CASES.md TC-E2 更新 | T0-02 | TC-E2 含 5xx 和 8xx 两种场景 |
+
+---
+
+## 七、Phase 4 — 安全与运营工具（Week 3，6 项，3 人天）
+
+**目标：威胁建模完善，安全门禁可执行，商业化闭环有 ROI。**
+
+| 任务 ID | 任务名称 | 责任人 | 工时 | 产出物 | 依赖 | 验收标准 |
+|----------|----------|--------|------|--------|------|----------|
+| S1-01 | 补充敏感字段脱敏具体实现 | Security | 0.5d | HLD §8 更新 | S0-05 | 含密码替换策略、加密算法、脱敏测试用例 |
+| S1-02 | 明确自愈引擎权限边界 | Security | 0.5d | PRD AC-6 + HLD §3.3 更新 | D0-03 | 含重启关键服务的白名单/黑名单机制 |
+| R2-01 | 补充 ROI 量化模型 | PM | 0.5d | PRD 新增章节 | R0-02 | 含当前运维成本、目标节省金额、回收周期 |
+| R2-02 | 补充发布策略量化门控标准 | PM | 0.5d | PRD §8 更新 | R1-01 | 含噪声率<10%、通知成功率>95% 等可量化条件 |
+| R2-03 | 补充审计日志存储成本评估 | PM | 0.5d | PRD + HLD §9.3 更新 | D2-15 | 含压缩率、归档策略、存储成本上限 |
+| D2-11 | 优化错误码排版 | TechLead | 0.5d | INTERFACE §3.3 更新 | D0-01 | 错误码分段排版，每个含注释说明 |
+
+---
+
+## 八、关键路径与产出物清单
+
+### 文档级产出物
+
+| 文件路径 | 说明 | 贡献者 |
+|----------|------|--------|
+| `docs/INTEGRATION_CONTRACT.md` | 外部集成契约唯一信源源 | TechLead |
+| `prd/PRD.md` | 主需求文档（更新后） | PM |
+| `specs/功能清单.md` | 功能清单（更新后） | PM |
+| `tech/HLD.md` | 高层设计（更新后） | TechLead |
+| `tech/INTERFACE.md` | 接口设计（更新后） | TechLead |
+| `tech/DEPLOYMENT.md` | 部署设计（更新后） | TechLead |
+| `tech/TEST_DESIGN.md` | 测试设计（更新后） | QA |
+| `test/CASES.md` | 测试用例（更新后） | QA |
+| `test/STRATEGY.md` | 测试策略（更新后） | QA |
+
+### 代码级产出物
+
+| 文件路径 | 说明 | 贡献者 |
+|----------|------|--------|
+| `.github/workflows/ci.yml` | CI Pipeline（覆盖率阻断、测试执行、失败通知） | QA |
+| `scripts/check_coverage.sh` | 覆盖率解析脚本 | QA |
+| `scripts/gate_check.sh` | 灰度门禁自动化判定脚本 | QA |
+| `test/perf/dashboard_k6.js` | 看板首页性能压测脚本 | QA |
+| `test/perf/drilldown_k6.js` | 下钻性能压测脚本 | QA |
+| `test/perf/PERF_ENV.md` | 性能压测环境规格 | QA |
+| `test/fixtures/` 目录结构文档 | 测试数据管理规范 | QA |
+| `tech/migrations/000001_init_schema.up.sql` | 数据库 schema（更新后） | TechLead |
+| `docs/汇总审核报告与改进任务清单.md` | 汇总审核报告 | 小龙 |
+| `docs/IMPLEMENTATION_PLAN.md` | 本文档 | 小龙 |
+
+---
+
+## 九、门禁与复审机制
+
+| 门禁点 | 条件 | 复审者 |
+|------|------|--------|
+| Phase 0 完成 | 所有 16 项 P0 任务完成，文档间一致性通过自动化检查 | 小龙 + TechLead |
+| Phase 1 完成 | 所有 9 项需求 P1 任务完成，PRD 可转测试用例 | PM + QA |
+| Phase 2 完成 | 所有 9 项技术 P1 任务完成，migration 可执行 | TechLead |
+| Phase 3 完成 | 所有 8 项测试任务完成，CI 可运行 | QA |
+| Phase 4 完成 | 所有 6 项安全/运营任务完成 | Security + PM |
+| 进入开发门禁 | 所有 Phase 完成，四方（PM/TechLead/QA/Security）复审通过 | 小龙 |
+
+---
+
+## 十、风险与应对
+
+| 风险 | 概率 | 影响 | 应对策略 |
+|------|------|------|----------|
+| 接口对齐会迟到或不能达成一致 | 中 | 高 | 由小龙主持，PM/TechLead 双方必须参与，不达成一致不开会 |
+| 工期估算仍被认为过高 | 低 | 中 | 预留 20% 联调缓冲 + 15% 风险缓冲，每周回顾 |
+| QA 资产补齐耗时超预期 | 中 | 中 | 优先完成 T0-01~T0-04（P0），P1/P2 可延后到开发期补充 |
+| Security 审查引发范围变更 | 低 | 高 | S0-01 限于威胁建模文档更新，不扩展为新功能需求 |

docs/INTEGRATION_CONTRACT.md

@@ -0,0 +1,127 @@
+# AI-Ops 集成接口契约（Integration Contract）
+
+> 版本：v1.0 | 状态：正式版
+> 本文档是 AI-Ops 与立交桥主项目（gateway/supply-api/token-runtime）集成时的唯一信源源。
+> 所有集成接口的路径、命名、字段、错误码均以本文档为准。
+
+---
+
+## 1. 集成原则
+
+1. **唯一信源源**：本文档覆盖的所有接口，以 INTERFACE.md 为技术基准，以本文档为集成契约准。
+2. **路径统一**：集成接口路径使用 `/internal/` 前缀，表明为内部服务间通信，不对外暴露。
+3. **命名统一**：所有自愈动作类型使用 snake_case，统一为：`switch_route`、`throttle`、`restart_instance`、`invoke_script`、`isolate_node`。
+4. **错误码统一**：所有错误码使用 `{SOURCE}_{CATEGORY}_{CODE}` 格式。
+5. **审计覆盖**：任何修改类操作（POST/PUT/DELETE/PATCH）必须记录审计日志。
+
+---
+
+## 2. 与 Bridge Gateway 集成
+
+### 2.1 接口清单
+
+| 方法 | 路径 | 请求 | 响应 | 说明 | 审计 |
+|------|------|------|------|------|------|
+| 查询服务状态 | `GET /internal/gateway/health` | - | `{"status":"up","services":{}}` | 诊断时查询各服务健康状态 | 否 |
+| 获取路由策略 | `GET /internal/gateway/routes` | - | `{"routes":[]}` | 读取当前路由配置，用于影响面分析 | 否 |
+| 修改路由策略 | `POST /internal/gateway/routes` | `{"action":"switch_route","target":"","config":{}}` | `{"success":true}` | 自愈动作调用 | 是 |
+| 获取请求量统计 | `GET /internal/gateway/metrics` | `?metric=qps&duration=5m` | `{"value":1234.5}` | 采集指标数据 | 否 |
+
+### 2.2 安全约束
+
+- `/internal/gateway/metrics` 仅限内网 IP 访问（10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16）或需携带有效的服务间 API Key。
+- 公网直接访问返回 403 Forbidden。
+- 修改路由策略必须经过 AI-Ops 审计流程，由 HLD §3.3 审计设计章节规范。
+
+### 2.3 字段规范
+
+**`POST /internal/gateway/routes` 请求体**:
+```json
+{
+  "action": "switch_route",      // 必填，枚举: switch_route/throttle/restart_instance/invoke_script/isolate_node
+  "target": "service_a",         // 必填，目标资源 ID
+  "config": {                    // 可选，动作特定参数
+    "fallback_provider": "p_b",  // switch_route 时指定备用供应商
+    "rate_limit_rps": 1000       // throttle 时指定限流值
+  },
+  "dry_run": false               // 可选，默认 false，true 时仅验证不执行
+}
+```
+
+**`修改路由策略` 错误码**:
+| 错误码 | HTTP 状态 | 说明 |
+|---------|-----------|------|
+| `OPS_GWY_4001` | 400 | 请求参数验证失败 |
+| `OPS_GWY_4002` | 404 | 目标资源不存在 |
+| `OPS_GWY_4003` | 409 | 目标资源正在被其他操作修改 |
+| `OPS_GWY_5001` | 500 | gateway 内部错误 |
+
+---
+
+## 3. 与 supply-api 集成
+
+### 3.1 接口清单
+
+| 方法 | 路径 | 请求 | 响应 | 说明 | 审计 |
+|------|------|------|------|------|------|
+| 查询供应商状态 | `GET /internal/supply/accounts/health` | - | `{"accounts":[]}` | 诊断供应商健康状态 | 否 |
+| 获取审计日志格式 | `GET /internal/supply/audit/schema` | - | `{"schema":{}}` | 确保审计事件格式一致 | 否 |
+
+### 3.2 安全约束
+
+- 供应商健康接口仅限内网访问。
+- 审计日志格式接口用于初始化时校验 schema 一致性，不对外暴露。
+
+---
+
+## 4. 与 platform-token-runtime 集成
+
+### 4.1 接口清单
+
+| 方法 | 路径 | 请求 | 响应 | 说明 | 审计 |
+|------|------|------|------|------|------|
+| 获取 Token 消耗 | `GET /internal/runtime/token-usage` | `?window=1h` | `{"total":12345,"by_model":{}}` | 采集 Token 消耗指标 | 否 |
+| 获取容量使用率 | `GET /internal/runtime/capacity` | - | `{"utilization":0.75}` | 采集容量指标 | 否 |
+
+### 4.2 安全约束
+
+- Token 消耗接口可能包含敏感信息，仅限内网访问。
+- 返回的 Token 数量应为汇总值，不得暴露用户级别的明细。
+
+---
+
+## 5. 错误码映射总表
+
+| 错误码 | HTTP 状态 | 来源 | 说明 |
+|---------|-----------|-------|------|
+| `OPS_GEN_4001` | 400 | 通用 | 请求参数错误 |
+| `OPS_GEN_4002` | 401 | 通用 | 未授权 |
+| `OPS_GEN_4003` | 403 | 通用 | 权限不足 |
+| `OPS_GEN_4004` | 404 | 通用 | 资源不存在 |
+| `OPS_GEN_4005` | 409 | 通用 | 资源冲突 |
+| `OPS_GEN_4006` | 413 | 通用 | 请求体过大 |
+| `OPS_GEN_5001` | 500 | 通用 | 内部服务错误 |
+| `OPS_MET_4001` | 400 | metric | 指标名称无效 |
+| `OPS_MET_4002` | 400 | metric | 时间范围不合法 |
+| `OPS_ALT_4001` | 400 | alert | 规则名称已存在 |
+| `OPS_ALT_4002` | 400 | alert | 规则参数验证失败 |
+| `OPS_ALT_4003` | 409 | alert | 版本冲突 |
+| `OPS_HEAL_4001` | 400 | healing | 自愈动作参数无效 |
+| `OPS_HEAL_4002` | 409 | healing | 自愈动作正在执行中 |
+| `OPS_HEAL_4003` | 400 | healing | 回滚目标执行不存在 |
+| `OPS_AUD_4001` | 403 | audit | 无权进行审计操作 |
+| `OPS_AUD_4101` | 400 | audit | 回滚目标资源不存在 |
+| `OPS_AUD_4102` | 409 | audit | 回滚目标已被后续修改覆盖 |
+| `OPS_CAP_4001` | 400 | capacity | 容量指标不存在 |
+| `OPS_GWY_4001` | 400 | gateway | 请求参数验证失败 |
+| `OPS_GWY_4002` | 404 | gateway | 目标资源不存在 |
+| `OPS_GWY_4003` | 409 | gateway | 目标资源正在被其他操作修改 |
+| `OPS_GWY_5001` | 500 | gateway | gateway 内部错误 |
+
+---
+
+## 6. 变更日志
+
+| 版本 | 日期 | 修改人 | 内容 |
+|------|------|---------|------|
+| v1.0 | 2026-05-11 | TechLead | 初稿：统一集成接口路径、自愈动作命名、错误码、安全约束 |

docs/README.md

@@ -0,0 +1,59 @@
+# AI-Ops 智能运维系统
+
+> 立连桥（立交桥）平台的智能运维子系统，把从人工排查转为机器主导的实时保障。
+
+---
+
+## 快速导航
+
+| 文档 | 路径 | 说明 |
+|---|---|---|
+| 产品需求 | `prd/PRD.md` | 需求范围、AC、用户场景、上线策略 |
+| 竞品分析 | `prd/competitor-analysis.md` | 14 个竞品全景矩阵与差距分析 |
+| 高层设计 | `tech/HLD.md` | 架构总览、模块设计、数据模型、安全与性能 |
+| 接口设计 | `tech/INTERFACE.md` | 内部接口、REST API、WebSocket、错误码 |
+| 部署设计 | `tech/DEPLOYMENT.md` | 容器化部署、资源需求、灾备方案 |
+| 测试设计 | `tech/TEST_DESIGN.md` | 测试策略、用例矩阵、灰度门禁 |
+| 功能清单 | `specs/功能清单.md` | 按 Phase 划分的模块级功能清单 |
+| 竞品分析 | `specs/竞品分析.md` | 竞品差异化与市场定位 |
+| 测试用例 | `test/CASES.md` | 按 AC 编号的测试用例 |
+| 测试策略 | `test/STRATEGY.md` | 分层测试模型与工具链 |
+
+---
+
+## 技术栈
+
+| 组件 | 选型 |
+|---|---|
+| 语言 | Go 1.22+ |
+| HTTP | 标准库 `net/http` + 自定义中间件 |
+| 数据库 | PostgreSQL 15+ (`jackc/pgx/v5`) |
+| 缓存 | Redis (`redis/go-redis/v9`) |
+| 配置 | YAML + Viper |
+| 时序库 | Prometheus / VictoriaMetrics |
+| 前端 | React 18+ + ECharts 5.x |
+| 测试 | Go testing + testify + miniredis + sqlmock |
+
+---
+
+## 当前状态
+
+- **门控结论**：HLD 与 TEST_DESIGN 均为 `REQUEST_CHANGES`，尚未达到进入开发的标准。
+- **待补齐项**：
+  1. 错误码统一（已完成）
+  2. 低级笔误修复（已完成）
+  3. 数据库 migration SQL
+  4. 项目骨架（go.mod、Makefile、Dockerfile）
+  5. 功能清单裁剪（PM 越界细节）
+  6. 门控行动项转化为可执行任务
+
+---
+
+## 与桥项目的关系
+
+本系统是桥项目的延伸，技术体系保持一致：
+- 同样的分层架构（Repository + Service + Handler）
+- 同样的 Store 接口（含乐观锁版本控制）
+- 同样的独立运行 + 集成运行双模式
+- 同样的审计事件模型（与 supply-api/ 一致）
+- 数据库表前缀 `ai_ops_`，避免 schema 冲突

docs/SINGLE_NODE_RUNBOOK.md

@@ -0,0 +1,193 @@
+# AI-Ops 单机运行 Runbook
+
+> 适用范围：开发机、单台线上服务器。目标是稳定可重复启动、可健康检查、可备份、可回滚、可故障恢复。不是多节点高可用方案。
+
+## 0. 前置条件
+
+任选一种容器运行时：
+
+- Docker + docker compose
+- Podman + podman-compose
+
+本机还需要：
+
+- go 1.22+
+- curl
+- python3
+- gzip / zcat
+
+## 1. 一键启动
+
+```bash
+cd /home/long/project/ai-ops
+scripts/aiops-single-node.sh start
+```
+
+脚本会自动完成：
+
+1. 生成 `.runtime/single-node.env`，包含随机 JWT secret 和 metrics auth。
+2. 生成 `.runtime/config.single.yaml`，使用 production mode。
+3. 编译静态二进制 `.runtime/ai-ops`。
+4. 启动 PostgreSQL、Redis、AI-Ops App。
+5. 等待 `/actuator/health/ready` 变绿。
+6. 执行 smoke：health、login、alerts、rules、channels、dashboard、openapi。
+
+默认监听地址和端口：
+
+| 服务 | 默认监听 | 说明 |
+|------|----------|------|
+| App | 127.0.0.1:18080 | 默认只允许本机访问，生产机不要直接公网暴露 |
+| PostgreSQL | 127.0.0.1:15432 | 默认只允许本机访问 |
+| Redis | 127.0.0.1:16379 | 默认只允许本机访问 |
+
+可通过环境变量覆盖：
+
+```bash
+AI_OPS_APP_PORT=28080 AI_OPS_DB_PORT=25432 AI_OPS_REDIS_PORT=26379 scripts/aiops-single-node.sh start
+```
+
+## 2. 日常检查
+
+```bash
+scripts/aiops-single-node.sh status
+scripts/aiops-single-node.sh smoke
+scripts/aiops-single-node.sh logs
+```
+
+直接访问：
+
+```bash
+curl -fsS http://127.0.0.1:18080/health
+curl -fsS http://127.0.0.1:18080/actuator/health/ready
+curl -fsS http://127.0.0.1:18080/ops/dashboard
+```
+
+## 3. 告警能力边界
+
+当前单机版支持：
+
+- 告警规则 CRUD
+- 规则引擎定时评估
+- P2 持续 2 小时升级 P1
+- 同资源 1 分钟聚合告警
+- webhook 通知发送
+- 通知日志落库
+- 失败后尝试备用渠道
+
+当前占位，不能作为正式值班渠道承诺：
+
+- email
+- Feishu
+- Wechat
+
+因此单机稳定版建议先用 webhook 接入现有告警网关、企业机器人转发器或自建 relay。
+
+## 4. 备份
+
+```bash
+scripts/aiops-single-node.sh backup
+```
+
+备份文件输出到：
+
+```text
+backups/ai_ops_YYYYMMDD-HHMMSS.sql.gz
+```
+
+建议线上服务器至少每天执行一次，可用 crontab：
+
+```cron
+30 2 * * * cd /home/long/project/ai-ops && scripts/aiops-single-node.sh backup >> backups/backup.log 2>&1
+```
+
+## 5. 回滚 / 恢复数据库
+
+从某个备份恢复：
+
+```bash
+scripts/aiops-single-node.sh restore backups/ai_ops_YYYYMMDD-HHMMSS.sql.gz
+```
+
+脚本会：
+
+1. 停止 app 容器，避免恢复期间写入。
+2. 清空 PostgreSQL `public` schema，避免表/函数/触发器已存在导致恢复失败。
+3. 用 psql 导入备份。
+4. 启动 app。
+5. 等待 ready。
+6. 自动 smoke。
+
+注意：restore 是有副作用操作，执行前应先确认备份文件正确，必要时先复制一份当前备份。
+
+## 6. 故障恢复
+
+容器异常退出、服务器重启后：
+
+```bash
+scripts/aiops-single-node.sh recover
+```
+
+脚本会基于现有 volume 重新拉起 PostgreSQL、Redis、App，并执行 ready + smoke。
+
+如果 app 异常但 DB/Redis 正常：
+
+```bash
+scripts/aiops-single-node.sh restart
+scripts/aiops-single-node.sh smoke
+```
+
+## 7. 停止服务
+
+```bash
+scripts/aiops-single-node.sh stop
+```
+
+该命令保留 volume，不删除数据。
+
+## 8. 安全配置
+
+`.runtime/single-node.env` 默认权限由脚本以 `umask 077` 创建，包含：
+
+- `AI_OPS_JWT_SECRET`
+- `AI_OPS_METRICS_AUTH`
+- 数据库密码
+
+不要提交 `.runtime/` 和 `backups/`。仓库 `.gitignore` 已屏蔽这些目录。
+
+production mode 下应用会强制校验：
+
+- JWT secret 至少 32 字符
+- metrics auth 至少 16 字符
+- DB host/user/password/dbname 必填
+- port/pool/retention 必须合法
+
+## 9. 单机版 Gate
+
+上线前至少执行：
+
+```bash
+go vet ./...
+go test -race -buildvcs=false ./...
+scripts/aiops-single-node.sh doctor
+scripts/aiops-single-node.sh start
+scripts/aiops-single-node.sh backup
+scripts/aiops-single-node.sh recover
+```
+
+如果有回滚演练窗口，再执行：
+
+```bash
+scripts/aiops-single-node.sh restore backups/<latest>.sql.gz
+```
+
+## 10. 仍然不是多节点生产级
+
+单机版不提供：
+
+- 多副本高可用
+- PostgreSQL 主从切换
+- Redis 高可用
+- 多节点任务互斥
+- 完整 Feishu/Wechat/email 生产通知实现
+
+但它满足开发机和单台线上服务器的稳定运行、备份、回滚和恢复闭环。

docs/汇总审核报告与改进任务清单.md

@@ -0,0 +1,223 @@
+# AI-Ops 智能运维系统 — 汇总审核报告与改进任务清单
+
+> 审核日期：2026-05-11
+> 审核角色：PM + TechLead + QA + Security（小龙统筹）
+> 审核范围：PRD、HLD、INTERFACE、DEPLOYMENT、TEST_DESIGN、CASES、STRATEGY、功能清单、竞品分析、migration SQL
+
+---
+
+## 一、各角色审核结论
+
+| 角色 | 总体评级 | 审核文档 | 核心判断 |
+|------|----------|----------|----------|
+| PM | B | PRD.md, 功能清单.md, competitor-analysis.md | 用户旅程完整，AC 量化程度高，但存在范围冲突、工期估算失真、功能遗漏 |
+| TechLead | B | HLD.md, INTERFACE.md, DEPLOYMENT.md, migration | 架构方向正确，但文档间接口严重不一致，ER 图与 migration 表缺失，IntegrationPlugin 未定义 |
+| QA | C | TEST_DESIGN.md, CASES.md, STRATEGY.md | 测试策略框架较好，但负向用例大面积缺失、异常流程漏了 4 条、CI 零配置、性能压测无载体 |
+| Security | C+ | HLD.md, INTERFACE.md, PRD.md, migration | 基础 RBAC 和脱敏有设计，但 LLM 特有风险未覆盖、审计防篡改触发器缺失、WebSocket/指标端点无鉴权 |
+
+**综合判断：当前设计不足以支撑进入开发，必须先修复 P0 问题，同步闭环 P1 问题，才能达到生产级交付标准。**
+
+---
+
+## 二、P0 阻塞级问题（合计 16 项，已去重）
+
+### 2.1 文档一致性（4 项）
+
+| 编号 | 问题 | 影响 | 责任文档 | 修复方案 |
+|------|------|------|----------|----------|
+| D-P0-01 | 接口定义严重不一致：HLD 与 INTERFACE 中 gateway/supply-api/token-runtime 的路径、命名完全不同 | 开发团队无法确定真实契约，集成测试必败 | HLD §7, INTERFACE §2 | 召开接口对齐会，以 INTERFACE.md 为基准，生成 INTEGRATION_CONTRACT.md 作为唯一信源源 |
+| D-P0-02 | ER 图与 migration 存在 4 张表缺失：ai_ops_events、ai_ops_notifys、ai_ops_configs、ai_ops_snapshots | 核心流程（通知、快照、配置版本）无法落地 | HLD §4.1 vs §4.2, migration | 确认是否需要：若需要则补齐表结构和 migration；若不需要则从 ER 图删除并说明替代方案 |
+| D-P0-03 | 自愈动作类型命名不一致：HLD 用 restart_instance/switch_route，INTERFACE 用 restart_service/switch_provider | 存储序列化、API 校验、前端枚举全部混乱 | HLD §3.3, INTERFACE §1.3 | 统一命名，建议采用 snake_case 一致规范 |
+| D-P0-04 | IntegrationPlugin 接口未定义：集成模式核心契约无 Go interface，无生命周期、注册方式 | 集成模式无法编码实现，CI 无法断点检查 | HLD §1.3, §3.2, §7, §10.2 | 在 INTERFACE.md 中增加 IntegrationPlugin Go interface 定义 |
+
+### 2.2 需求完整性（2 项）
+
+| 编号 | 问题 | 影响 | 责任文档 | 修复方案 |
+|------|------|------|----------|----------|
+| R-P0-01 | 范围冲突：供应商智能切换未在 PRD In Scope 明确纳入，但功能清单作为 Phase 3 核心模块（16+ 任务） | 与 Out of Scope “不做自动扩容决策”擦边，开发阶段极易产生范围争议 | PRD §3, 功能清单 3.4 | 明确纳入 In Scope 或移入 Out of Scope，若纳入则在 AC 中补充验收标准 |
+| R-P0-02 | 自愈动作“重启实例”在功能清单中遗漏具体实现任务 | QA 无法验收该自愈动作 | PRD AC-6, 功能清单 3.1.2 | 补充重启实例实现任务（如调用 K8s API 或主机 agent） |
+
+### 2.3 测试设计完整性（4 项）
+
+| 编号 | 问题 | 影响 | 责任文档 | 修复方案 |
+|------|------|------|----------|----------|
+| T-P0-01 | AC 负向测试用例大面积缺失：12 个 AC 中至少 8 个无负向/异常输入用例 | 无法验证非法输入、边界越界、权限不足等场景，生产缺陷逃逸 | TEST_DESIGN.md, CASES.md | 为 AC-01/02/04/05/06/09/10/11 各补充至少 1 条负向用例 |
+| T-P0-02 | CASES.md 遗漏异常流程 F-05~F-08（审计满盘、级联故障、数据库中断、看板超时） | 核心容灾与降级场景无测试用例实底 | CASES.md | 补充 TC-E5~E8 四条异常流程用例 |
+| T-P0-03 | CI 集成零配置：STRATEGY.md 仅文字描述，无 workflow 文件、覆盖率阻断逻辑、失败通知机制 | 无法形成自动化质量门禁 | STRATEGY.md | 创建 `.github/workflows/ci.yml`，含覆盖率解析与阻断、失败通知 |
+| T-P0-04 | 性能压测无执行载体：k6 脚本、环境规格、P99 计算方式、持续时间均未定义 | 性能基准无法复现和验证，灰度门禁无法判定 | TEST_DESIGN.md §9.1 | 创建 `test/perf/` 目录，含 k6 脚本和环境规格文档 |
+
+### 2.4 安全设计完整性（6 项）
+
+| 编号 | 问题 | 影响 | 责任文档 | 修复方案 |
+|------|------|------|----------|----------|
+| S-P0-01 | LLM 特有风险未覆盖：提示注入、提示泄露、幻觉、模型偷取等 OWASP LLM Top 10 风险 | 系统集成 LLM/Gateway 后可能遭受提示攻击或数据泄露 | HLD §10.1 | 在威胁建模中增加 LLM 特有风险识别与缓解策略 |
+| S-P0-02 | 审计表无防篡改触发器：migration 未创建 `audit_log_prevent_update_delete` 类似触发器 | 审计日志可被更新或删除，违背不可篡改要求 | migration | 补充 PostgreSQL 触发器或在应用层强制只追加 |
+| S-P0-03 | Append-only 审计设计未在 HLD 中明确陈述：无“先写审计再执行业务”的 fail-closed 设计 | 业务操作失败时可能丢失审计记录，影响故障定责 | HLD §3.3 | 明确审计写入与业务执行的事务顺序和回滚机制 |
+| S-P0-04 | WebSocket 接口无鉴权说明：告警数据为敏感生产信息 | 公网可能监听告警流，数据泄露风险 | INTERFACE §3.4 | 补充 JWT Token 鉴权说明，包括连接建立时的 token 校验 |
+| S-P0-05 | SQL 注入防护无明确设计：HLD 未强制参数化/预编译查询 | 自定义规则、日志查询等功能存在 SQL 注入风险 | HLD §4 | 在 HLD 数据层设计中增加参数化查询强制要求 |
+| S-P0-06 | /metrics 探针端点无鉴权说明：揭露生产指标给公网风险 | 攻击者可通过 /metrics 获取系统运行状态和敏感信息 | INTERFACE §3.2 | 限制内网 IP 访问或增加 API Key 鉴权 |
+
+---
+
+## 三、P1 重要级问题（合计 18 项，已去重）
+
+### 3.1 需求与产品
+
+| 编号 | 问题 | 责任文档 |
+|------|------|----------|
+| R-P1-01 | 双重失败判定线：开发期 vs 上线后 30 天阈值不统一（20% vs 15%） | PRD §2, §8.3 |
+| R-P1-02 | In Scope 使用“不仅仅包括于”留下范围蔓延口子 | PRD §3 In Scope |
+| R-P1-03 | 通知渠道定义不一致：PRD 未含钉钉，功能清单出现钉钉 | PRD AC-4, 功能清单 2.3.2/3.4.3 |
+| R-P1-04 | AC-7 “不可篡改”缺乏技术实现定义 | PRD AC-7 |
+| R-P1-05 | AC-8 “操作前值有效”定义模糊 | PRD AC-8 |
+| R-P1-06 | 级联故障回退（F-6）未在 AC 中体现 | PRD F-6, AC-6 |
+| R-P1-07 | 容量预测算法缺可测试标准（“仅供参考”导致无法验收） | PRD AC-9 |
+| R-P1-08 | 缺少 UI/UX 最低兼容性要求 | PRD 全文 |
+| R-P1-09 | 角色权限矩阵过粗，缺少 API 级权限对照 | PRD AC-12, 功能清单 G1 |
+
+### 3.2 技术设计
+
+| 编号 | 问题 | 责任文档 |
+|------|------|----------|
+| D-P1-05 | DEPLOYMENT “主备”与 active-active 多活逻辑矛盾 | DEPLOYMENT §1.1 vs §4.2 |
+| D-P1-06 | Worker 执行 migration 存在多副本并发冲突风险 | DEPLOYMENT §3.2 |
+| D-P1-07 | `ai_ops_roles` 表在 HLD 中提及但 migration 未定义 | HLD §8.1 vs migration |
+| D-P1-08 | 快照表缺失影响级联故障回退 | HLD §3.3 |
+| D-P1-09 | 告警聚合状态机不完整（解除规则未定义） | HLD §5.2 |
+| D-P1-10 | 规则评估性能扩展性未给出分片策略 | HLD §9.1/9.2 |
+
+### 3.3 测试
+
+| 编号 | 问题 | 责任文档 |
+|------|------|----------|
+| T-P1-01 | 覆盖率门槛缺少验证机制 | STRATEGY.md |
+| T-P1-02 | 混沌测试无具体用例设计 | STRATEGY.md, TEST_DESIGN.md |
+| T-P1-03 | 测试数据管理策略缺关键细节 | STRATEGY.md |
+| T-P1-04 | 灰度门禁缺自动化判定脚本 | TEST_DESIGN.md §5.2 |
+| T-P1-05 | 安全扫描工具与阈值未指定 | STRATEGY.md |
+| T-P1-06 | E2E 测试缺少详细场景设计 | STRATEGY.md, TEST_DESIGN.md |
+
+### 3.4 安全
+
+| 编号 | 问题 | 责任文档 |
+|------|------|----------|
+| S-P1-01 | 敏感字段脱敏策略仅有文字，无具体实现（如密码替换、数据加密） | HLD §8 |
+| S-P1-02 | 自愈引擎权限边界未明确（如何防止自愈动作被滥用去重启关键服务） | PRD AC-6, HLD §3.3 |
+
+---
+
+## 四、P2 改进建议（关键项）
+
+| 编号 | 问题 | 建议 |
+|------|------|------|
+| R-P2-01 | 商业化闭环缺 ROI 量化模型 | 补充运维人力成本节省计算示例 |
+| R-P2-02 | 发布策略缺量化门控标准 | 补充告警噪声率<10%、通知成功率>95% 等可量化条件 |
+| R-P2-03 | 审计日志 90 天保留未评估存储成本 | 补充压缩/归档策略或存储成本上限 |
+| D-P2-11 | 错误码排版混淆（4001 与 4101 相邻易混） | 重新分段排版或增加注释说明 |
+| D-P2-12 | metrics 分区表仅有 DEFAULT，无按天分区和自动清理 | 引入 pg_partman 或应用层定时任务 |
+| D-P2-14 | Graceful Shutdown 未说明 WebSocket 长连接关闭策略 | 补充 close frame + ack 等待机制 |
+| D-P2-15 | 存储估算假设 Prometheus 每样本 8 bytes，与实际严重偏低 | 参考官方容量规划公式重新估算 |
+| T-P2-01 | 用例编号风格不统一（TC-01-01 vs TC-1.1） | 统一为 TC-{AC}-{seq} |
+| T-P2-02 | CASES.md TC-E2 漏掉 5xx 场景 | 补充 Webhook 5xx 测试 |
+
+---
+
+## 五、改进任务清单（按模块分类，已去重排序）
+
+### Phase 0 — 文档修复与对齐（开发前必须完成）
+
+| 任务 ID | 任务名称 | 严重度 | 责任文档 | 估算工时 | 验收标准 |
+|----------|----------|--------|----------|----------|----------|
+| D0-01 | 召开接口对齐会，统一 gateway/supply-api/token-runtime 路径、命名、字段 | P0 | INTEGRATION_CONTRACT.md | 0.5d | 三份文档无接口冲突 |
+| D0-02 | 补齐或删除 ER 图中 4 张缺失表（events/notifys/configs/snapshots） | P0 | HLD §4.2, migration | 0.5d | migration 与 ER 图一致 |
+| D0-03 | 统一自愈动作命名并同步到所有文档 | P0 | HLD, INTERFACE, 功能清单 | 0.5d | 全文档自愈动作命名一致 |
+| D0-04 | 定义 IntegrationPlugin Go interface 并写入 INTERFACE.md | P0 | INTERFACE.md | 0.5d | interface 定义包含 Init/RegisterRoutes/HealthChecks/Shutdown |
+| R0-01 | 解决范围冲突：明确供应商智能切换 In/Out of Scope 定位 | P0 | PRD §3, 功能清单 | 0.5d | PRD 与功能清单范围一致 |
+| R0-02 | 重新估算工期：138 任务按复杂度系数 + 20%联调 + 15%风险缓冲 | P0 | 功能清单 | 0.5d | 工期估算在 30~40 人天 |
+| R0-03 | 补充自愈动作“重启实例”实现任务 | P0 | 功能清单 3.1.2 | 0.5d | 功能清单包含重启实例任务 |
+| S0-01 | 在威胁建模中增加 LLM 特有风险（提示注入、幻觉、模型偷取） | P0 | HLD §10.1 | 0.5d | 威胁建模覆盖 LLM Top 5 风险 |
+| S0-02 | 补充审计表防篡改触发器或应用层只追加约束 | P0 | migration | 0.5d | 审计表无法 UPDATE/DELETE |
+| S0-03 | 明确审计写入与业务执行的事务顺序（fail-closed） | P0 | HLD §3.3 | 0.5d | 文档明确"先写审计再执行业务" |
+| S0-04 | 补充 WebSocket JWT 鉴权说明 | P0 | INTERFACE §3.4 | 0.5d | WebSocket 接口含鉴权流程 |
+| S0-05 | 在 HLD 中增加参数化查询强制要求 | P0 | HLD §4 | 0.5d | 所有数据库交互层必须使用参数化查询 |
+| S0-06 | 限制 /metrics 端点访问（内网 IP 或 API Key） | P0 | INTERFACE §3.2 | 0.5d | /metrics 含访问控制说明 |
+| T0-01 | 为 8 个缺失负向用例的 AC 补充负向用例 | P0 | TEST_DESIGN.md, CASES.md | 1d | 每个 AC 至少 1 正向 + 1 负向 |
+| T0-02 | 补充 F-05~F-08 异常流程用例（TC-E5~E8） | P0 | CASES.md | 0.5d | 8 条异常流程全部覆盖 |
+| T0-03 | 创建 `.github/workflows/ci.yml` 含覆盖率阻断与失败通知 | P0 | STRATEGY.md, ci.yml | 0.5d | PR 提交时自动触发并阻断不达标 PR |
+| T0-04 | 创建 `test/perf/` 目录含 k6 脚本和环境规格 | P0 | TEST_DESIGN.md, test/perf/ | 0.5d | 性能压测可复现执行 |
+
+### Phase 1 — 需求与产品级 P1 闭环
+
+| 任务 ID | 任务名称 | 严重度 | 责任文档 | 估算工时 |
+|----------|----------|--------|----------|----------|
+| R1-01 | 统一失败判定线：上线后 30 天为统一窗口，噪声率<15% | P1 | PRD §2, §8.3 | 0.5d |
+| R1-02 | 删除 In Scope 中“不仅仅包括于”，改为封闭列表 | P1 | PRD §3 | 0.5d |
+| R1-03 | 统一通知渠道列表（是否含钉钉） | P1 | PRD AC-4, 功能清单 | 0.5d |
+| R1-04 | AC-7 补充不可篡改的技术实现定义 | P1 | PRD AC-7 | 0.5d |
+| R1-05 | AC-8 补充“有效”的判定标准 | P1 | PRD AC-8 | 0.5d |
+| R1-06 | 在 AC-6 中补充级联故障回退验收点 | P1 | PRD AC-6 | 0.5d |
+| R1-07 | 为容量预测（AC-9）补充可测试标准（如 MAPE<30%） | P1 | PRD AC-9 | 0.5d |
+| R1-08 | 补充 UI 最低兼容性要求 | P1 | PRD | 0.5d |
+| R1-09 | 细化角色权限矩阵到 API 级别 | P1 | PRD AC-12, 功能清单 G1 | 0.5d |
+
+### Phase 2 — 技术设计级 P1 闭环
+
+| 任务 ID | 任务名称 | 严重度 | 责任文档 | 估算工时 |
+|----------|----------|--------|----------|----------|
+| D1-05 | 修正 DEPLOYMENT “主备”为 active-active 多活 | P1 | DEPLOYMENT §1.1 | 0.5d |
+| D1-06 | 分离 migration 执行从 Worker 启动逻辑（init container 或 Job） | P1 | DEPLOYMENT §3.2 | 0.5d |
+| D1-07 | 补充 `ai_ops_roles` 表结构 | P1 | HLD §8.1, migration | 0.5d |
+| D1-08 | 补充 `ai_ops_snapshots` 表结构（级联故障回退） | P1 | HLD §3.3, migration | 0.5d |
+| D1-09 | 完善告警聚合状态机（解除规则、子告警同步） | P1 | HLD §5.2 | 0.5d |
+| D1-10 | 补充规则评估分片策略与负载均衡方案 | P1 | HLD §9.1/9.2 | 0.5d |
+| D2-12 | 完善 metrics 分区表管理策略（pg_partman 或应用层） | P2 | migration, HLD | 0.5d |
+| D2-14 | 补充 Graceful Shutdown 中 WebSocket 关闭策略 | P2 | DEPLOYMENT §3.2 | 0.5d |
+| D2-15 | 重新校准时序存储容量估算 | P2 | HLD §9.3 | 0.5d |
+
+### Phase 3 — 测试资产完善
+
+| 任务 ID | 任务名称 | 严重度 | 责任文档 | 估算工时 |
+|----------|----------|--------|----------|----------|
+| T1-01 | 建立覆盖率验证机制（CI 解析 domain≥70%, service≥80%） | P1 | STRATEGY.md | 0.5d |
+| T1-02 | 设计 3 条混沌测试用例（Pod 杀死、Redis 分区、PG 主从切换） | P1 | TEST_DESIGN.md | 0.5d |
+| T1-03 | 完善测试数据管理规范（fixtures 目录结构、大数据生成脚本、并行隔离） | P1 | STRATEGY.md | 0.5d |
+| T1-04 | 为灰度门禁增加自动化判定脚本 | P1 | TEST_DESIGN.md §5.2 | 0.5d |
+| T1-05 | 明确安全扫描工具（Trivy/Gosec）与阈值 | P1 | STRATEGY.md | 0.5d |
+| T1-06 | 补充 E2E 详细场景设计（完整链路） | P1 | TEST_DESIGN.md, CASES.md | 0.5d |
+| T2-01 | 统一用例编号风格为 TC-{AC}-{seq} | P2 | TEST_DESIGN.md, CASES.md | 0.5d |
+| T2-02 | 补充 Webhook 5xx 测试场景 | P2 | CASES.md TC-E2 | 0.5d |
+
+### Phase 4 — 安全与运营工具
+
+| 任务 ID | 任务名称 | 严重度 | 责任文档 | 估算工时 |
+|----------|----------|--------|----------|----------|
+| S1-01 | 补充敏感字段脱敏具体实现（密码替换、加密） | P1 | HLD §8 | 0.5d |
+| S1-02 | 明确自愈引擎权限边界（防止滥用重启关键服务） | P1 | PRD AC-6, HLD §3.3 | 0.5d |
+| R2-01 | 补充 ROI 量化模型与财务指标 | P2 | PRD, competitor-analysis | 0.5d |
+| R2-02 | 补充发布策略量化门控标准 | P2 | PRD §8 | 0.5d |
+| R2-03 | 补充审计日志存储成本评估与压缩策略 | P2 | PRD, HLD §9.3 | 0.5d |
+| D2-11 | 优化错误码排版并增加注释说明 | P2 | INTERFACE §3.3 | 0.5d |
+
+---
+
+## 六、总体改进计划
+
+| 阶段 | 任务数 | 预估工时 | 目标 |
+|------|--------|----------|------|
+| Phase 0 文档修复与对齐 | 16 项 | 8 人天 | 消除所有 P0 问题，文档间一致 |
+| Phase 1 需求与产品级 P1 | 9 项 | 4.5 人天 | PRD 完善，AC 可测试，权限明确 |
+| Phase 2 技术设计级 P1 | 9 项 | 4.5 人天 | HLD/DEPLOYMENT 完善，部署可执行 |
+| Phase 3 测试资产完善 | 8 项 | 4 人天 | 测试用例完整，CI 可运行 |
+| Phase 4 安全与运营工具 | 6 项 | 3 人天 | 威胁建模完善，安全门禁可执行 |
+| **合计** | **48 项** | **24 人天** | 达到生产级设计质量 |
+
+---
+
+## 七、小龙结论
+
+1. **当前状态不能进入开发**：合计 16 项 P0 阻塞级问题，涵盖文档一致性、测试完整性、安全基线三大类。
+2. **最危险的系统性风险是接口定义不一致**：HLD/INTERFACE/DEPLOYMENT 三份文档对同一集成点有不同路径和命名，开发团队无法确定真实契约，必须第一时间对齐。
+3. **QA 是最薄弱环节**：评级 C，负向用例大面积缺失、CI 零配置、性能压测无载体。建议优先补齐 T0-01~T0-04。
+4. **Security 未覆盖 LLM 特有风险**：项目集成 LLM/Gateway 后，提示注入、幻觉等风险可能导致严重安全事故，必须在威胁建模中补充。
+5. **工期估算严重失真**：138 任务仅 18 人天，实际至少需要 30~40 人天，建议重新估算并预留 20% 联调 + 15% 风险缓冲。
+6. **建议执行顺序**：Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4，每个 Phase 完成后由对应角色复审，所有 P0 闭环后才能进入开发。