ops-assistant/docs/frontend-joint-checklist.md

Ops-Assistant 前后端联调检查清单（给前端/Gemini）

更新日期：2026-03-10

---

A. 统一基础

• 所有请求走 /api/v1/*（禁用新代码调用 legacy 路由）
• apiClient 统一解析 {code,message,data}
• 全局错误 toast 仅展示 message
• 鉴权失败统一跳转登录

---

B. 登录后初始化

• 调 GET /api/v1/me
• 用 effective_capabilities 控制页面和按钮显隐
• 没有权限时不渲染可操作按钮

---

C. Dashboard

• 首屏并行请求：
  • GET /api/v1/dashboard/summary
  • GET /api/v1/dashboard/overview
• 状态卡片展示 jobs 统计、模块状态、通道状态
• 10~20 秒轮询刷新

---

D. Modules 页面

• 列表：GET /api/v1/modules
• 开关：POST /api/v1/modules/:module/toggle
  • reason 必填
  • 处理 message=noop
  • cpa 禁用失败提示
• 成功后刷新 modules + overview

---

E. Ops Jobs 页面

• 列表：GET /api/v1/ops/jobs
• 支持筛选字段：
  • status
  • target
  • runbook
  • request_id
  • operator
  • risk_level
  • q
  • from/to（RFC3339）
• 展示后端回显的 filters
• 详情：GET /api/v1/ops/jobs/:id
  • step_stats
  • step_total
  • duration.job_ms / duration.steps_ms_sum
• request_id 反查：GET /api/v1/ops/jobs/request/:requestID
• cancel/retry：
  • reason 必填
  • 按权限按钮显隐（can_cancel_ops / can_retry_ops）

---

F. Channels 页面

• GET /api/v1/admin/channels
• patch/publish/reload/apply 流程联通
• secrets 脱敏显示并正确提交

---

G. Audit 页面

• GET /api/v1/admin/audit
• 支持 from/to、action、target_type、result、actor_id

---

H. Legacy 迁移看板（管理页）

• GET /api/v1/admin/legacy/usage
• GET /api/v1/admin/legacy/trend?days=7
• GET /api/v1/admin/legacy/readiness?days=7&zero_days=3
• 显示 ready + recommendation

---

I. 验收标准

• 前端无新代码依赖 legacy 路由
• 所有核心页面可在 ops-assistant 独立运行
• 权限控制、错误处理、轮询刷新行为正常
• readiness 达标后可计划 legacy 下线窗口