ops-assistant/docs/backend-independence-status.md

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 并行。