Skip to content

API_COVERAGE.md

Latest commit

 

History

History
132 lines (102 loc) · 8.81 KB

API_COVERAGE.md

File metadata and controls

132 lines (102 loc) · 8.81 KB
Raw

后端接口覆盖 Checklist

维护规则:每完成一个端点的 UI 入口实现,把 [ ] 改成 [x]。 完成 = 在某个 view 里调到对应 shared/api/xxx.ts 的函数 + 有真实表单/按钮触发 + 错误走 useToast/useConfirm/usePurge。 占位按钮(只 toast 不调 API)不算完成。

状态图例:

  • [x] 已接通 —— view 里有真实表单/按钮触发对应 API 函数
  • [~] 函数就绪未单独调用 —— API 函数已实现,但详情视图复用列表数据(或 readiness 已覆盖健康态),不再单独发 GET 请求
  • [—] 按设计不做 UI

后端 Controller 总数:8 个 后端端点总数:36 当前覆盖:已接通 28 / 函数就绪未单独调 7 / 不做 UI 1(7 个 GET-by-id 详情统一复用 list 数据,liveness 由 readiness 覆盖)

AdminTenantController (8 endpoints)

# METHOD PATH UI 入口 API 函数 状态
1 GET /admin/tenants Tenants 列表页左栏 / 危险区软删 tab (?deleted=true) tenantsApi.list [x]
2 GET /admin/tenants/{id} Tenants 中栏详情(复用 list 行数据, find()) tenantsApi.get [~]
3 POST /admin/tenants 列表 + ADD TENANT → 抽屉表单 tenantsApi.create [x]
4 PUT /admin/tenants/{id} 详情编辑表单 (rate-limit / tier / name) tenantsApi.update [x]
5 DELETE /admin/tenants/{id} 详情 disable 按钮 + useConfirm tenantsApi.softDelete [x]
6 POST /admin/tenants/{id}/refresh 详情 refresh cache 按钮 tenantsApi.refreshCache [x]
7 POST /admin/tenants/{id}/restore 列表筛选"已软删"行的恢复按钮 / Danger Zone tenantsApi.restore [x]
8 DELETE /admin/tenants/{id}/purge 详情 PURGE 按钮 → EcPurgeModal tenantsApi.purge [x]

AdminActionConfigController (6 endpoints)

# METHOD PATH UI 入口 API 函数 状态
9 GET /admin/tenants/{tid}/action-configs Tenants 中栏 Actions tab 列表 actionConfigsApi.list [x]
10 GET /admin/tenants/{tid}/actions/{action}/grant 点击 action 行 → 右栏详情(复用 list 行) actionConfigsApi.get [~]
11 POST /admin/tenants/{tid}/actions/{action}/grant + Grant new 按钮 → 抽屉表单 (选模板 + ds_override + customSql + customParams) actionConfigsApi.grant [x]
12 PUT /admin/tenants/{tid}/actions/{action}/grant 右栏 SQL 编辑器 Validate & Save actionConfigsApi.update [x]
13 DELETE /admin/tenants/{tid}/actions/{action}/grant action 行 ⋯ 菜单 → revoke + useConfirm actionConfigsApi.revoke [x]
14 POST /admin/tenants/{tid}/actions/grant-all-defaults + Grant all defaults 按钮 + useConfirm actionConfigsApi.grantAllDefaults [x]

AdminDatasourceController (7 endpoints)

# METHOD PATH UI 入口 API 函数 状态
20 GET /admin/datasources/{tid} Tenants 中栏 Datasources tab 列表 / 危险区 (?deleted=true) datasourcesApi.list [x]
21 GET /admin/datasources/{tid}/{ds} 点击 ds 行 → 详情抽屉(复用 list 行) datasourcesApi.get [~]
22 POST /admin/datasources/{tid}/{ds} + ADD DATASOURCE (DB / API 双表单, accessType 决定) datasourcesApi.create [x]
23 PUT /admin/datasources/{tid}/{ds} 详情抽屉编辑表单 datasourcesApi.update [x]
24 DELETE /admin/datasources/{tid}/{ds} 详情 DISABLE + useConfirm datasourcesApi.softDelete [x]
25 POST /admin/datasources/{tid}/{ds}/restore Danger Zone / 软删行 restore datasourcesApi.restore [x]
26 DELETE /admin/datasources/{tid}/{ds}/purge 详情 PURGE → EcPurgeModal datasourcesApi.purge [x]

AdminTemplateController (7 endpoints)

# METHOD PATH UI 入口 API 函数 状态
27 GET /admin/templates Templates 分组列表 (按 action GROUP BY) / 危险区 (?deleted=true) templatesApi.list [x]
28 GET /admin/templates/{id} 行点击 → 展开 family diff(list 已含全部字段, 未单独调) templatesApi.get [~]
29 POST /admin/templates + NEW TEMPLATE → SQL/paramSchema 编辑表单 templatesApi.create [x]
30 PUT /admin/templates/{id} 详情编辑 templatesApi.update [x]
31 DELETE /admin/templates/{id} 详情 DISABLE + useConfirm templatesApi.softDelete [x]
32 POST /admin/templates/{id}/restore Danger Zone templatesApi.restore [x]
33 DELETE /admin/templates/{id}/purge Danger Zone → EcPurgeModal templatesApi.purge [x]

AdminTaskController (2 endpoints)

# METHOD PATH UI 入口 API 函数 状态
15 GET /admin/tasks Tasks 页列表 + 筛选 (tenant/status/action) tasksApi.list [x]
16 GET /admin/tasks/{taskId} 点击任务 → 详情抽屉 (params/result/error/traceId, 复用 list 行) tasksApi.get [~]

AdminDictController (3 endpoints)

# METHOD PATH UI 入口 API 函数 状态
17 GET /admin/dicts Dictionary 表格 (可按 group 过滤) dictApi.list [x]
18 GET /admin/dicts/{key} 行点击查详情 (一般直接列表里 inline 编辑就够, 未单独调) dictApi.get [~]
19 PUT /admin/dicts/{key} 表格行 inline 编辑 value, 失焦提交 + Redis pub/sub toast dictApi.update [x]

HealthController (2 endpoints)

# METHOD PATH UI 入口 API 函数 状态
34 GET /health/liveness 顶栏 ● connected 灯(readiness 已覆盖健康态, 未单独调) healthApi.liveness [~]
35 GET /health/readiness Overview SYSTEM 卡片 (轮询 5s) healthApi.readiness [x]

Actuator (Overview 可观测指标, 非 36 端点契约内)

Spring Boot Actuator 端点, 后端 management.endpoints.web.exposure.include = health,info,prometheus,metrics, AuthInterceptor 放行 /actuator/** (无需 X-API-Key)。前端走 actuatorApi (shared/api/metrics.ts) 读取。 全部为只读观测, 用于 Overview 首页 5s 轮询, 不计入 36 端点契约。

METRIC 用途 Overview 卡片 备注
process.uptime 进程运行时长 SYSTEM · uptime JVM 自带, 始终存在
connector.datasource.pool.size 活跃租户 DS 池数 POOLS · active 惰性: 无业务时为 0
connector.async.task.active 运行中/排队任务 (按 status tag) POOLS · running/pending 惰性
http.server.requests 请求累计 (COUNT) / 最大延迟 (MAX) / 错误率 RATE + QPS Spring 自带, 始终存在; QPS 由前端按 ΔCOUNT/Δt 实时差分
GET /admin/tasks 最近任务 (复用端点 #15) RECENT TASKS 即清单 #15, 此处仅复用

McpWebhookController (1 endpoint)

# METHOD PATH UI 入口 状态
36 POST /internal/callback 无 UI (后端 AsyncTaskService 自回调入口, 走 X-Callback-Secret header) [—] 不需要做

验收命令

# 统计已接通端点数 (在工程根目录)
grep -c '`\[x\]`' docs/API_COVERAGE.md       # 已接通 (有真实 UI 调用)
grep -c '`\[~\]`' docs/API_COVERAGE.md       # 函数就绪未单独调

完成度目标:

  • Phase 1 (scaffold): 0 / 36
  • Phase 2 (read paths): ≥ 12 / 36 (所有 GET 类端点)
  • Phase 3 (full CRUD): ≥ 30 / 36 (除 purge / restore 之外都做完)
  • Phase 4 (danger ops): 35 / 36 (含 purge / restore, 唯一不做 UI 的是 #36) ← 当前在此(28 直接接通 + 7 复用 list 数据)
  • GA: 35 / 36 + 至少 60% 端点有 e2e 测试(测试用例待补)

与后端契约的同步规则

后端新增 / 修改端点时,必须:

  1. 在 shared/api/<controller>.ts 加 / 改函数
  2. 在本文件加 / 改一行
  3. 在对应 view 加入口 (不要直接调 axios)
  4. PR 标题前缀 feat(api): / chore(api): 便于检索