feat: 模块化命令框架 + runbook 严格断言与查询结果回传

- core/module: 命令模板、门控(feature flag/confirm/dry-run)、ecode 错误标签、ResultFormatter
- runbook executor: http.get/http.post/assert.json(expect_success 严格断言)、目标主机管理、任务落库、最终 stdout 直接回传
- cf 模块: /cf dns list 支持域名自动解析 zone_id;dns list/zones/workers list 格式化回传;API success:false 判真失败
- 全部 CF/CPA runbook 接入严格断言,杜绝假阳性 success
- 新增 cpa/cfdav/mail/sub 模块与 runbooks;QQ 订阅到期提醒调度
- Web 后台: 模块设置(CF/CPA/cfdav/AI)、OPS 任务、渠道管理、审计页
This commit is contained in:
2026-09-13 07:42:17 +08:00
parent 9085c490f3
commit 81939825d1
86 changed files with 6885 additions and 467 deletions
+89
View File
@@ -0,0 +1,89 @@
# 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` 并行。