90 lines
3.1 KiB
Markdown
90 lines
3.1 KiB
Markdown
# Ops-Assistant 后端独立化完成清单（Phase 1~6）
|
||
|
||
更新日期：2026-03-10
|
||
|
||
---
|
||
|
||
## 总览
|
||
|
||
目标：`ops-assistant` 后端从旧 `xiaji-go` 记账心智中独立，形成 Ops 场景可扩展架构。
|
||
|
||
当前结论：
|
||
- ✅ 核心链路已成型：`Command -> Module -> Policy -> Runbook -> Audit -> Reply`
|
||
- ✅ 三模块（CPA/CF/Mail）已纳入统一执行骨架（CF/Mail 为安全占位 runbook）
|
||
- ✅ Ops Web 数据面已具备（dashboard/modules/jobs/channels/audit/flags）
|
||
- ✅ Legacy 兼容层已进入可观测可下线阶段（usage/trend/readiness）
|
||
|
||
---
|
||
|
||
## Phase 状态
|
||
|
||
## Phase 1：API 基础收口
|
||
- ✅ 新增/改造接口统一 `{code,message,data}`
|
||
- ✅ 导出类接口保留文件流（`/api/v1/export`）
|
||
- ✅ 失败路径统一 JSON 错误
|
||
|
||
## Phase 2：模块管理后端
|
||
- ✅ `GET /api/v1/modules`
|
||
- ✅ `POST /api/v1/modules/:module/toggle`
|
||
- ✅ toggle reason 必填
|
||
- ✅ toggle 幂等 noop 返回
|
||
- ✅ 关键模块保护：禁止禁用 `cpa`
|
||
|
||
## Phase 3：Dashboard 聚合后端
|
||
- ✅ `GET /api/v1/dashboard/overview`
|
||
- ✅ `GET /api/v1/dashboard/summary`
|
||
- ✅ jobs 列表多维筛选（见 Phase 4）
|
||
|
||
## Phase 4：Ops Jobs 能力增强
|
||
- ✅ `GET /api/v1/ops/jobs` 支持筛选：
|
||
- `limit/status/target/runbook/request_id/operator/risk_level/q/from/to`
|
||
- ✅ `GET /api/v1/ops/jobs/request/:requestID`（含 `total`）
|
||
- ✅ `GET /api/v1/ops/jobs/:id`（`step_stats/step_total/duration`）
|
||
- ✅ `POST /api/v1/ops/jobs/:id/cancel`（reason 必填，状态校验）
|
||
- ✅ `POST /api/v1/ops/jobs/:id/retry`（reason 必填，仅 failed）
|
||
|
||
## Phase 5：策略与风控中心化（阶段性）
|
||
- ✅ `policy.CheckGate` 作为 gate 核心校验
|
||
- ✅ 新增 `policy.ParseCommonFlags`，统一 `--dry-run/--confirm`
|
||
- ✅ CPA 移除重复 guard（不再分散解析）
|
||
- ✅ CF/Mail 切到 Runner + Gate + Runbook 模式
|
||
- ⏳ 待补：更细粒度 permission/gate 模板化（跨模块统一声明）
|
||
|
||
## Phase 6：兼容层收缩与下线准备
|
||
- ✅ legacy 路由包装审计：
|
||
- `/api/records`
|
||
- `/delete/:id`
|
||
- `/export`
|
||
- ✅ 访问 legacy 自动写审计：`legacy.route.access`
|
||
- ✅ legacy deprecated 响应头：
|
||
- `X-API-Deprecated: true`
|
||
- `X-API-Replacement`
|
||
- `Warning: 299 ...`
|
||
- ✅ 迁移观测接口：
|
||
- `GET /api/v1/admin/legacy/usage`
|
||
- `GET /api/v1/admin/legacy/trend?days=...`
|
||
- `GET /api/v1/admin/legacy/readiness?days=...&zero_days=...`
|
||
|
||
---
|
||
|
||
## 仍在进行 / 建议下一步
|
||
|
||
1) Policy 进一步模板化
|
||
- 将 `NeedFlag/RequireConfirm/AllowDryRun` 配置抽成模块命令描述，减少模块内手写。
|
||
|
||
2) Channel Adapter 统一化
|
||
- TG/QQ/Feishu 进一步收敛到 `core/ports/channel.go` 统一适配层。
|
||
|
||
3) Legacy 软下线流程
|
||
- 当 `readiness.ready=true` 连续多日后，先灰度关闭 legacy，再完全移除路由映射。
|
||
|
||
4) 发布前整理
|
||
- 清理工作区改动并提交；执行 `make release-check`。
|
||
|
||
---
|
||
|
||
## 关键验证
|
||
|
||
- 最近多轮 `go build ./cmd/main.go` 均通过（仅 gojieba C++ deprecation warning，非阻塞）。
|
||
- 双服务并存策略维持不变：`xiaji-go` 与 `ops-assistant` 并行。
|