ai-ops/tech/TechLead_Review_Report.md

## TechLead 审核报告 — AI-Ops 智能运维系统

审核日期：2026-05-11
审核范围：HLD.md、INTERFACE.md、DEPLOYMENT.md、000001_init_schema.up.sql
审核人：TechLead

---

### 总体评级：B

架构方向正确，核心设计（审计防篡改、沙盒自愈、DualCache、独立/集成双模式）有成熟模式支撑。但三份文档之间存在多处接口命名和路径不一致，ER 图与 migration 存在表缺失，IntegrationPlugin 未定义接口，这些问题必须在进入开发前修复。

---

### 优点

1. 技术选型有明确决策理由和备选方案（Prometheus vs VictoriaMetrics、DualCache、CustomBatchLogger），降低未来换型风险。
2. 核心业务指标均有量化目标和验证方式（MTTR<10min、噪声率<5%、覆盖率>=60%），便于 QA 建立阻断测试。
3. 审计设计采用 append-only + 数据库触发器防篡改，符合合规和故障定责要求。
4. 安全设计覆盖 RBAC、敏感字段脱敏、Row Level Security 可选方案，数据隔离意识到位。
5. 风险分析包含威胁建模和六条具体风险项，并给出了缓解策略。
6. 支持独立运行与集成运行两种模式，且 schema 强制使用 `ai_ops_` 前缀，避免与主项目冲突。
7. 借鉴 LiteLLM 的 CustomBatchLogger、DualCache、DigestEntry 等模式，降低实现不确定性。

---

### 发现问题（按严重度分类）

#### P0 — 阻断开发

| 编号 | 问题描述 | 影响 | 位置 |
|------|---------|------|------|
| P0-1 | HLD 与 INTERFACE 外部集成接口定义严重不一致。gateway/：HLD 写 `POST /internal/gateway/throttle`、`/switch-route`、`/restart`；INTERFACE 写 `POST /internal/gateway/routes`。supply-api/：HLD 写 `/internal/suppliers/health`、`/audit/events`、`/usage/token-stats`；INTERFACE 写 `/internal/supply/accounts/health`、`/internal/supply/audit/schema`。token-runtime/：HLD 写 `/internal/tokens/status`；INTERFACE 写 `/internal/runtime/token-usage`。 | 开发团队无法确定真实调用契约，集成测试无法编写，联调必失败。 | HLD §7 / INTERFACE §2 |
| P0-2 | HLD ER 图（§4.1）中出现 `ai_ops_events`、`ai_ops_notifys`、`ai_ops_configs`、`ai_ops_snapshots` 四张表，但 HLD §4.2 表结构、INTERFACE、migration SQL 中均完全缺失。 | 数据模型不完整，核心流程（通知、快照、配置版本）无法落地。 | HLD §4.1 vs §4.2 / migration |
| P0-3 | 自愈动作类型命名不一致。HLD §3.3 定义 `switch_route`、`restart_instance`、`isolate_node`；INTERFACE §1.3 HealingAction.Type 注释写 `restart_service switch_provider throttle isolate_node`。 | 同一概念多个命名，导致存储序列化、API 校验、前端枚举全部混乱。 | HLD §3.3 / INTERFACE §1.3 |
| P0-4 | 集成运行模式的核心契约 `IntegrationPlugin` 未在任何文档中定义 Go interface。HLD 仅文字描述“通过 IntegrationPlugin 将检查逻辑注入到主程序的健康检查中”，但没有接口方法、生命周期、注册方式。 | 集成模式无法编码实现，也无法做 CI 阻断检查（HLD §10.2 要求 BuildServer/BuildRuntime 显式挂载约束落实为 CI 检查，但无接口无法执行）。 | HLD §1.3 / §3.2 / §7 / §10.2 |

#### P1 — 必须修复

| 编号 | 问题描述 | 影响 | 位置 |
|------|---------|------|------|
| P1-5 | DEPLOYMENT §1.1 写“AI-Ops API Server x 2 (主备)”，但 §4.2 写“负载均衡自动移除，剩余节点继续服务”。主备模式下备机不处理请求，与负载均衡多活逻辑矛盾。 | 部署架构描述混乱，SRE 无法按文档实施。 | DEPLOYMENT §1.1 / §4.2 |
| P1-6 | DEPLOYMENT §3.2 启动顺序让 Worker 执行 migration。若 Worker 为多副本，同时启动会导致并发 migration 冲突（锁竞争或重复执行）。 | 可能导致数据库状态损坏或启动失败。 | DEPLOYMENT §3.2 |
| P1-7 | HLD §8.1 提到“系统自带角色表 `ai_ops_roles`”，但 HLD §4.2 和 migration 中均无该表定义。 | RBAC 无法落地。 | HLD §8.1 vs migration |
| P1-8 | HLD §3.3 级联故障防护要求“记录当前状态快照（包含相关配置版本号）”，但无 `ai_ops_snapshots` 表结构。P0-2 已提，此处强调其业务必要性。 | 自愈回退和级联故障检测缺少数据支撑。 | HLD §3.3 |
| P1-9 | 告警聚合流程（HLD §5.2）定义了聚合触发条件（>20条/60s），但未定义聚合告警如何解除、子告警状态如何同步到父告警、聚合告警 resolved 后子告警是否自动 resolved。 | 告警状态机不完整，可能导致聚合告警永久挂起。 | HLD §5.2 |
| P1-10 | 性能目标“>= 50 条规则 / 15s”对于实时告警场景仅约 3.3 条规则/秒，未说明规则评估是否支持水平分片并行。若规则数增长到 200 条，单实例评估可能超时。 | 扩展性设计停留在文字，未给出分片策略和负载均衡方案。 | HLD §9.1 / §9.2 |

#### P2 — 建议优化

| 编号 | 问题描述 | 影响 | 位置 |
|------|---------|------|------|
| P2-11 | INTERFACE §3.3 错误码列表中 `OPS_AUD_4001`（403 无权）与 `OPS_AUD_4101`（400 回滚目标不存在）排版紧邻，且 `OPS_AUD_4101` 重复出现两次，易混淆。 | 错误码使用方容易误用。 | INTERFACE §3.3 |
| P2-12 | migration 中 `ai_ops_metrics_p` 仅创建 DEFAULT 分区，未建立按天 RANGE 分区，也未实现“自动删除 > 7 天的分区”。pg_partman 仅为注释。 | 时序缓存表会随着数据增长性能急剧下降，且无法自动清理。 | migration §6 |
| P2-13 | WebSocket 接口（INTERFACE §3.4）缺少鉴权机制说明。告警数据为敏感生产信息，公开 WebSocket 无鉴权存在数据泄露风险。 | 安全合规风险。 | INTERFACE §3.4 |
| P2-14 | Graceful Shutdown（DEPLOYMENT §3.2）未说明 WebSocket 长连接的关闭策略。若仅关闭 HTTP server，WebSocket 客户端可能异常断连。 | 用户体验和监控准确性下降。 | DEPLOYMENT §3.2 |
| P2-15 | HLD §9.3 存储估算假设 Prometheus 每个样本 8 bytes，实际 Prometheus TSDB 包含时间戳、变长标签、chunk 元数据等，真实存储远高于此。按此估算生产磁盘规划可能不足。 | 生产环境磁盘空间不足风险。 | HLD §9.3 |

---

### 改进建议

1. **统一三文档外部集成契约**：以 INTERFACE.md 为基准，组织一次 HLD + INTERFACE + DEPLOYMENT 的接口对齐评审，确定 gateway/supply-api/token-runtime 的正式路径、请求/响应字段、鉴权方式，形成一份 `INTEGRATION_CONTRACT.md` 作为唯一可信源。

2. **补齐或裁剪 ER 图**：
   - 若 `ai_ops_events`、`ai_ops_notifys`、`ai_ops_configs`、`ai_ops_snapshots` 确实需要，在 HLD §4.2 和 migration 中补充表结构、字段、索引、外键。
   - 若不需要，从 ER 图中删除，并说明替代方案（例如 `ai_ops_events` 是否被 `ai_ops_alerts` + `ai_ops_healings` 覆盖，`ai_ops_notifys` 是否被通知渠道 + alert status 覆盖）。

3. **定义 IntegrationPlugin 接口**：在 INTERFACE.md 中增加 `IntegrationPlugin` Go interface，至少包含：
   ```go
   type IntegrationPlugin interface {
       Name() string
       Init(ctx context.Context, cfg Config) error
       RegisterRoutes(mux *http.ServeMux) error
       HealthChecks() []HealthCheckFunc
       Shutdown(ctx context.Context) error
   }
   ```
   并说明注册方式（import + 显式 Enable）。

4. **修正 API Server 部署描述**：将 DEPLOYMENT §1.1 的“主备”改为“多实例 Active-Active + 负载均衡”，与 §4.2 的故障处理逻辑一致。

5. **分离 migration 执行**：将数据库 migration 从 Worker 启动逻辑中移出，改为：
   - 独立运行：使用 `cmd/migrate` 或 Docker init container 执行。
   - 集成运行：由主程序在启动前统一执行，或通过 Kubernetes Job 执行。

6. **补充缺失表结构**：至少补充 `ai_ops_roles`（RBAC 需要）和 `ai_ops_snapshots`（自愈回退需要）。

7. **建立 metrics 分区管理策略**：选择以下之一并在 migration 中体现：
   - 引入 `pg_partman` 扩展并编写初始化脚本；
   - 或在应用层编写定时任务每日创建新分区、删除旧分区。

8. **WebSocket 增加鉴权与优雅关闭**：
   - 连接建立时校验 JWT Token；
   - Shutdown 阶段先发送 close frame，等待客户端 ack 或超时（5s）后再关闭 TCP 连接。

9. **完善告警聚合状态机**：补充聚合告警的 resolved/escalated 规则，以及子告警状态与父告警的同步策略（例如父告警 resolved 时是否批量 resolved 子告警）。

10. **重新校准时序存储容量估算**：参考 Prometheus 官方容量规划公式（`bytes_per_sample ≈ 1-2 bytes 压缩后，但写放大和索引占主要空间`），给出更保守的磁盘规划建议。

---

### 审核结论

**当前状态：REQUEST_CHANGES**

本设计在架构层面具备可行性，核心决策有理据。但文档间的接口不一致和模型缺失是足以导致开发返工的系统性问题。建议在进入编码前：

1. 召开接口对齐会（1-2 小时），统一 HLD / INTERFACE / DEPLOYMENT 中的所有外部路径和命名；
2. 由架构负责人补充 IntegrationPlugin 接口定义和缺失的表结构；
3. 将上述修复重新提交 TechLead 审核，通过后方可进入开发。