ai-ops/specs/功能清单.md

# AI-Ops 功能清单（模块级）

> 版本：v1.1
> 日期：2026-05-11
> 说明：模块级功能清单，仅到达"功能级"精度。具体的按钮、动画、色彩、字体等前端实现细节由 Engineer 和前端工程师在开发阶段自行决定，不在 PM 规划范围内。
>
> **PM 范围：**模块定义、功能边界、数据模型、接口契约、验收标准。
> **Engineer 范围：**代码实现、前端组件选型、动画/交互细节、测试用例实现。
>
> **总工期估算**：34 人天（含 20% 协调缓冲） + 15% 风险缓冲 = **39 人天**。
> 估算方法：简单任务 0.5d / 中等任务 1d / 复杂任务 2d，模块级汇总后加缓冲。

---

## Phase 1：监控看板 + 日志查询（不触发自动动作）

> **工期估算**：8 人天（含 20% 协调缓冲）

### 模块 1.1：监控首页

#### 1.1.1 首页基础布局
- [ ] **任务**：实现首页路由 `/ops/dashboard`，返回监控首页 HTML 模板

#### 1.1.2 指标数据获取
- [ ] **任务**：实现 `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` 接口，返回未关闭告警数量

#### 1.1.3 指标下钻
- [ ] **任务**：实现 `GET /api/v1/ai-ops/metrics/query` 接口，支持 service/path/supplier 维度过滤

### 模块 1.2：日志查询

#### 1.2.1 日志查询页
- [ ] **任务**：实现日志查询页路由 `/ops/dashboard/logs`

#### 1.2.2 日志结果展示
- [ ] **任务**：日志列表以表格展示，每行显示：时间 / 服务名 / 路径 / 状态码 / 延迟 / 用户ID / 供应商ID
- [ ] **任务**：日志列表支持分页，每页 100 条，显示总条数
- [ ] **任务**：实现日志查询结果"导出 CSV"按钮，导出上限 10000 条

#### 1.2.3 日志查询性能
- [ ] **任务**：日志查询接口添加查询超时逻辑，超时返回部分结果并提示
- [ ] **任务**：实现日志查询结果缓存（Redis，5分钟 TTL），同一筛选条件命中缓存时直接返回

---

## Phase 2：告警规则引擎 + 通知渠道（告警只通知，不执行自愈）

> **工期估算**：12 人天（含 20% 协调缓冲）

### 模块 2.1：告警规则管理

#### 2.1.1 告警规则列表页
- [ ] **任务**：实现告警规则列表页路由 `/ops/dashboard/alerts/rules`
- [ ] **任务**：规则列表支持分页，每页 50 条

#### 2.1.2 创建/编辑告警规则
- [ ] **任务**：实现规则创建页路由 `/ops/dashboard/alerts/rules/create`
- [ ] **任务**：实现规则创建表单，包含字段：规则名称（必填）、监控指标（下拉：QPS/延迟/错误率/供应商健康度/Token消耗）、阈值类型（下拉：> / < / = / 正则匹配）、阈值数值（必填）、持续时间（分钟，必填）、告警级别（下拉：P0/P1/P2/P3，必填）、通知渠道（多选：Webhook/邮件/飞书/企微）
- [ ] **任务**：编辑页路由 `/ops/dashboard/alerts/rules/{rule_id}/edit`，回填已有数据

#### 2.1.3 告警规则引擎（后端）
- [ ] **任务**：实现规则引擎从 PostgreSQL 加载所有启用规则，每 30 秒刷新
- [ ] **任务**：实现规则引擎对每个指标数据点执行阈值评估
- [ ] **任务**：实现持续时间判定（指标超阈值必须持续 N 分钟才触发）
- [ ] **任务**：实现告警事件生成，写入 `ai_ops_alert_events` 表，状态 = triggered
- [ ] **任务**：实现同一规则同一目标 5 分钟抑制期逻辑（5 分钟内相同告警不重复生成）
- [ ] **任务**：实现告警升级逻辑（P2 持续 2 小时未确认 → 升级 P1）

### 模块 2.2：告警事件与处置

#### 2.2.1 告警事件列表
- [ ] **任务**：实现告警事件列表页路由 `/ops/dashboard/alerts/events`
- [ ] **任务**：事件列表每行显示：事件ID / 规则名称 / 级别 / 触发时间 / 持续时长 / 状态 / 操作

#### 2.2.2 告警集群聚合
- [ ] **任务**：实现告警聚合逻辑：同一服务/资源 1 分钟内触发 >20 条告警时，生成 1 条集群告警
- [ ] **任务**：集群告警列表每行显示：集群ID / 涉及规则数 / 累计告警数 / 首条时间 / 最新时间 / 级别

### 模块 2.3：通知渠道配置

#### 2.3.1 通知配置页
- [ ] **任务**：实现通知配置页路由 `/ops/dashboard/alerts/channels`

#### 2.3.2 通知发送后端
- [ ] **任务**：实现通知发送队列（内存队列 + Redis 持久化）
- [ ] **任务**：实现 P0/P1 通知 30 秒内发送，P2 通知 120 秒内发送
- [ ] **任务**：实现通知失败时自动切换备用渠道（Webhook 失败 → 邮件 → 飞书 → 企微）
- [ ] **任务**：实现通知日志记录，每次发送记录成功/失败原因到 `ai_ops_notification_logs`

---

## Phase 3：自愈引擎 + 审计回滚

> **工期估算**：14 人天（含 20% 协调缓冲）

### 模块 3.1：自愈规则配置

#### 3.1.1 自愈规则创建
- [ ] **任务**：在告警规则创建/编辑页，添加"自愈动作"可选配置区块
- [ ] **任务**：自愈动作类型下拉：无 / 切换备用路由 / 限流 / 重启实例 / 触发脚本
- [ ] **任务**：当选择"切换备用路由"时，显示供应商下拉框（选择目标备用供应商）
- [ ] **任务**：配置"沙盒模式"开关，默认开启（沙盒模式下自愈动作仅记录，不实际执行）
- [ ] **任务**："保存"按钮同时保存告警规则和自愈动作配置

#### 3.1.2 自愈执行后端
- [ ] **任务**：自愈引擎监听 triggered 状态的告警事件
- [ ] **任务**：当告警关联自愈动作且沙盒模式关闭时，执行自愈动作
- [ ] **任务**：执行切换备用路由：调用 gateway 管理接口，将流量切换到备用供应商
- [ ] **任务**：执行限流：调用 gateway 管理接口，设置速率限制
- [ ] **任务**：执行重启实例：通过 K8s API 或主机 agent 调用重启指定服务实例，配置超时 60 秒、最大重试 2 次
- [ ] **任务**：执行触发脚本：在隔离环境中执行指定的 shell/Python 脚本，超时 30 秒
- [ ] **任务**：自愈动作执行后 60 秒内评估监控指标是否恢复正常
- [ ] **任务**：自愈成功：事件状态更新为 resolved，记录动作结果
- [ ] **任务**：自愈失败（重试 1 次仍失败）：升级为 P0 人工告警（电话/短信），事件状态更新为 escalated

#### 3.1.3 自愈级联失败处理
- [ ] **任务**：切换备用路由后，监控新路由健康状态 2 分钟
- [ ] **任务**：若新路由也触发告警，立即回退到原始路由
- [ ] **任务**：回退完成后，升级为 P0 人工告警（电话/短信），注明"自愈级联失败"

### 模块 3.2：配置审计

#### 3.2.1 审计日志查询页
- [ ] **任务**：实现审计日志页路由 `/ops/dashboard/audit`
- [ ] **任务**：审计列表每行显示：审计ID / 操作时间 / 操作人 / 操作类型 / 资源类型 / 资源ID / 操作后值摘要
- [ ] **任务**：审计列表支持导出（最多 10000 条，按时间范围导出）

#### 3.2.2 审计后端
- [ ] **任务**：拦截所有配置变更操作（CREATE/UPDATE/DELETE），在事务内同步写入审计日志
- [ ] **任务**：审计日志写入使用追加模式（不支持 UPDATE/DELETE），数据库层设置禁止删除策略
- [ ] **任务**：审计日志保留期 >= 90 天，后台 job 每天清理过期数据

### 模块 3.3：配置回滚

#### 3.3.1 回滚操作入口
- [ ] **任务**：回滚成功提示："回滚成功，已恢复到 {时间} 的状态，耗时 X 秒"
- [ ] **任务**：回滚失败时显示错误码和原因（如 OPS_AUD_4101）

#### 3.3.2 回滚后端
- [ ] **任务**：实现回滚接口，根据审计记录 ID 查找操作前值
- [ ] **任务**：回滚前检查目标资源是否仍存在，不存在时返回错误码 `AUDIT_ROLLBACK_TARGET_LOST`
- [ ] **任务**：回滚操作在独立事务中执行，更新目标资源值
- [ ] **任务**：回滚成功后生成新审计记录，关联原始审计记录 ID（字段 `rolled_back_from_audit_id`）

---

## Phase 4：容量主板与高级分析

### 模块 4.1：容量视图

#### 4.1.1 容量主页
- [ ] **任务**：实现容量主页路由 `/ops/dashboard/capacity`

#### 4.1.2 容量数据后端
- [ ] **任务**：实现容量数据聚合 job（每小时执行），将原始指标聚合为小时级数据
- [ ] **任务**：实现增长率计算算法（基于过去 7 天数据线性回归）
- [ ] **任务**：实现负载等级判定（可配置阈值，默认为：正常 < 60% 利用率 < 警告 < 80% < 过载）

---

## 全局模块

### 模块 G1：认证与权限

- [ ] **任务**：实现登录页路由 `/ops/login`，支持账号密码登录
- [ ] **任务**：实现 JWT Token 签发，Token 有效期 8 小时
- [ ] **任务**：实现中间件，所有 `/api/v1/ai-ops/*` 接口需携带有效 JWT
- [ ] **任务**：实现角色权限中间件：查看者（GET only）、运维人员（可写告警规则）、管理员（可回滚、可管理用户）
- [ ] **任务**：实现权限不足时返回 HTTP 403，响应体包含错误码 `OPS_AUTH_1001`

### 模块 G2：健康检查

- [ ] **任务**：实现 `GET /actuator/health` 接口，返回整体健康状态
- [ ] **任务**：实现 `GET /actuator/health/live` 接口，用于 K8s liveness probe
- [ ] **任务**：实现 `GET /actuator/health/ready` 接口，用于 K8s readiness probe（依赖 DB + Redis 连通性）

### 模块 G3：OpenAPI 文档

- [ ] **任务**：实现 OpenAPI 3.0 JSON spec 生成，端点 `/openapi.json`
- [ ] **任务**：确保所有对外 API（路由/请求/响应/错误码）均在 spec 中体现

---

## 技术基础设施（各 Phase 共享）

### T1：项目骨架
- [ ] **任务**：初始化 Go module `github.com/lijiaoliao/ai-ops`
- [ ] **任务**：创建 `cmd/ai-ops/main.go` 入口，支持 `api` 和 `worker` 两种运行模式
- [ ] **任务**：创建 `internal/` 目录结构（domain/service/handler/infrastructure/repository）
- [ ] **任务**：配置 Viper 读取 `config.yaml`，支持环境变量覆盖
- [ ] **任务**：配置 `log/slog` 结构化日志，输出 JSON 格式
- [ ] **任务**：创建 PostgreSQL schema migration（使用 golang-migrate），表前缀 `ai_ops_`
- [ ] **任务**：创建 Redis 连接池配置
- [ ] **任务**：配置 Dockerfile 和 docker-compose.yml
- [ ] **任务**：编写 `DEPLOYMENT.md` 中的 docker-compose 启动命令

### T2：单元测试骨架
- [ ] **任务**：为每个 domain 层函数编写单元测试，覆盖率 >= 70%
- [ ] **任务**：为每个 service 层函数编写单元测试，覆盖率 >= 80%
- [ ] **任务**：配置 CI（GitHub Actions），PR 必须通过全部测试和覆盖率检查

### T3：IntegrationPlugin 接口
- [ ] **任务**：实现 `IntegrationPlugin` 接口（`Init() error` / `Serve() error` / `Shutdown() error`）
- [ ] **任务**：实现插件模式下各模块的开关配置（`viper` 读取 `ops.enabled_modules`）
- [ ] **任务**：编写集成测试：插件模式启动，所有功能正常运作

---

## 任务估算汇总

| Phase | 模块 | 任务数 | 估计工时 |
|-------|------|--------|---------|
| Phase 1 | 1.1 首页 + 1.2 日志查询 | 28 | 3 人天 |
| Phase 2 | 2.1 告警规则 + 2.2 事件处置 + 2.3 通知渠道 | 30 | 4 人天 |
| Phase 3 | 3.1 自愈引擎 + 3.2 审计 + 3.3 回滚 + 3.4 供应商切换 | 26+16=42 | 4 人天 + 2 人天 |
| Phase 4 | 4.1 容量视图 | 10 | 1.5 人天 |
| 全局 | G1 认证 + G2 健康 + G3 文档 | 14 | 1.5 人天 |
| 技术基础设施 | T1 骨架 + T2 测试 + T3 插件 | 14 | 2 人天 |
| **合计** | | **122+16=138** | **~16+2=18 人天** |

---

### 模块 3.4：供应商智能切换（参考 FreeRide 思路）

> FreeRide 是 OpenClaw 的自动模型切换插件，核心思路：实时排行 → 自动选择 → Fallback 链 → 限速无感知切换。对应到 AI-Ops 的供应商切换场景，可以把这个思路产品化。

#### 3.4.1 供应商质量监控

- [ ] **任务**：定时任务（每 5 分钟）调用各中转供应商的 `/models` 接口，记录可用模型列表
- [ ] **任务**：对每个供应商执行探测请求（测试请求），记录响应时间和错误率
- <a name="343-health-probe"></a>**任务**：探测结果写入 `supplier_health` 表，记录字段：supplier_id、probe_at、latency_ms、error_rate、available_models、elo_score
- [ ] **任务**：`GET /api/v1/ai-ops/suppliers/health` 接口返回所有供应商的实时健康状态
- [ ] **任务**：`GET /api/v1/ai-ops/suppliers/health/{supplier_id}` 接口返回指定供应商的详细健康状态
- [ ] **任务**：在供应商管理页显示健康状态标签（健康 / 延迟高 / 错误率高 / 不可用）
- [ ] **任务**：健康状态数据保留 7 天，支持趋势查看

#### 3.4.2 供应商 Fallback 链管理

- [ ] **任务**：为每个接入的模型配置主供应商 + 备用供应商列表（至少 1 主 + 1 备）
- [ ] **任务**：供应商配置数据结构：
  ```go
  type SupplierChain struct {
      Model         string   // 模型名
      Primary       string   // 主供应商ID
      Fallbacks     []string // 备用供应商ID列表（按优先级排序）
      CooldownSec   int      // 故障后多少秒内不切换回来（默认300s）
  }
  ```
- [ ] **任务**：配置页支持拖拽排序 Fallback 顺序
- [ ] **任务**：切换后的冷却期内，即使主供应商恢复也不同质（避免震荡）
- [ ] **任务**：切换记录写入审计日志，包含：切换时间、原供应商、目标供应商、切换原因

#### 3.4.3 智能切换策略

- [ ] **任务**：切换策略下拉：成本优先 / 质量优先 / 延迟优先 / 手动
- [ ] **任务**：**成本优先**：按 `input_cost_per_token + output_cost_per_token` 排序，选择最低者
- [ ] **任务**：**质量优先**：按最近 24h 成功率排序，选择最高者
- [ ] **任务**：**延迟优先**：按最近 probe 的 `latency_ms` 排序，选择最低者
- [ ] **任务**：**手动**：每次切换需人工确认
- [ ] **任务**：当主供应商触发告警（P1/P2），自动检查 Fallback 链是否可用
- [ ] **任务**：选择最佳备用供应商后，自动执行切换（若策略不是"手动"）
- [ ] **任务**：切换完成后发送通知（飞书/企微/钉钉），告知：原供应商、目标供应商、切换原因

#### 3.4.4 供应商切换执行

- [ ] **任务**：`POST /api/v1/ai-ops/suppliers/switch` 接口：传入 model + target_supplier，执行切换
- [ ] **任务**：调用 gateway 的 `/internal/suppliers/switch` 接口完成实际路由切换
- [ ] **任务**：切换后立即执行一次探针验证，确认新供应商可服务工作
- [ ] **任务**：验证失败时，回退到上一个供应商，并记录切换失败原因
- [ ] **任务**：供应商切换作为自愈动作之一，可关联告警规则（Phase 3.1 已覆盖）

#### 3.4.5 供应商健康看板

- [ ] **任务**：路由 `/ops/dashboard/suppliers` 显示供应商健康一览
- [ ] **任务**：卡片展示：今日切换次数 / 当前不可用供应商数 / 各供应商平均延迟 / 各供应商错误率
- [ ] **任务**：表格展示所有供应商：名称 / 健康状态 / 最后探针时间 / 平均延迟 / 24h 成功率 / 可用模型数
- [ ] **任务**：支持按健康状态筛选（全部 / 健康 / 延迟高 / 不可用）

#### 3.4.6 参考 FreeRide 的非破坏性配置更新

- [ ] **任务**：供应商配置更新采用原子替换策略：写临时文件 → 验证 → 原子替换
- [ ] **任务**：防止配置损坏导致系统不可用
- [ ] **任务**：配置更新前先在内存中验证 JSON Schema，不合法则拒绝更新