root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(prd): admin-web API 全景总览 + 批 1 PRD (W1-T7 / P1-7)

Browse Source 
Wave 1 Day 4 admin-web 后端 API PRD 批 1 撰写。

00-overview.md (338 行):
- 151 端点 / 34 标签全清单(实际 vs P1-7 估算 80,多 71 个)
- 5 批 PRD 拆分映射
- OpenAPI 与代码不同步告警(本批缺 10+ 端点,Wave 5 修复抓取脚本)

batch1-runtime-context-and-ai.md (924 行):
- 23 端点 PRD: admin-ai 17 + runtime-context 5 + triggers 1
- 41 评估发现: P0x8 / P1x20 / P2x13
- 每端点带 file:line 引用 + 调用方定位

工作量修正: P1-7 估算 60-65h -> 实际 100-130h (按 5 批分散到 Wave 1-5)。

参考: docs/audit/changes/2026-05-04__wave1_t7_admin_api_prd_batch1.md
This commit is contained in:
Neo
2026-05-04 09:54:35 +08:00
parent e74ce4242f
commit c58599d29b
3 changed files with 1400 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

370
docs/_overview/admin-api-prd/00-overview.md Normal file
View File

@@ -0,0 +1,370 @@
# admin-web API 全景总览
> 日期:2026-05-04 / Wave 1 W1-T7 / 来源:`docs/contracts/openapi/backend-api.json`
> 端点总数:**151** / 标签数:**34**
>
> 配套:[`docs/_overview/04b-feedback/P1-7-admin-api-prd-evaluation.md`](../04b-feedback/P1-7-admin-api-prd-evaluation.md) Neo 二轮决策"接受 B+D 混合,Wave 1 起批 1"
## 三、汇总注
- 实际 151 端点比 P1-7 评估的 80 多 71 个,其中:
- 小程序 API(`/api/xcx/*`)约 60 个(批 2-5 视范围而定)
- admin-web API(`/api/admin/*`)约 50 个
- 租户 API(`/api/tenant/*`)约 30 个
- 其他(`/api/auth/*` `/api/db/*` `/api/internal/*` `/api/wx/*` 等)约 10 个
- 总耗时按 80 个估算的 60-65 小时需修正为 100-130 小时(不含批 1 已完成部分)
- P1-7 评估方案 B+D 混合保留,但 Wave 5 聚合时重新评估
## 四、OpenAPI 与代码不同步告警
**批 1 撰写过程中发现:OpenAPI 文件 `backend-api.json` 与代码严重不同步**,本批 23 端点中 **10 个不在 OpenAPI**:
- 全部 `/api/admin/runtime-context/*`(5 个)缺失
- `/api/admin/triggers/unified`(1 个)缺失
- `admin_ai` 后期扩展 4 个端点缺失(`/run/{app_type}`、`/triggers` GET/PATCH、`/prewarm/progress`、`/trigger-event`)
**意味着**:
- 本"自动生成总表"覆盖率仅约 93%(151/总实际端点)
- Wave 5 聚合 PRD 之前,**必须先修复 OpenAPI 抓取流程**(否则总表会持续少 5-15 个端点)
- 可能机制:OpenAPI 静态导出脚本未含 admin-runtime-context router,或 router 注册顺序问题
**Wave 5 必修项**:
1. 修复 `tools/codex/...` 或类似 OpenAPI 抽取脚本
2. 重新生成 backend-api.json,与代码对照 0 缺漏后再聚合 PRD
## 五、批 1 详细 PRD
详见 [`batch1-runtime-context-and-ai.md`](batch1-runtime-context-and-ai.md)(924 行 / 23 端点 / 41 个评估发现 P0×8 / P1×20 / P2×13)。
## 一、5 批 PRD 拆分映射
| 批次 | 范围 | tag | 端点数 | Wave |
|---|---|---|---|---|
| 批 1 | Runtime Context + AI 管理 + Triggers (P1-6) | admin-ai / admin-runtime-context / admin-triggers / 调度管理 | — | Wave 1 (本批) |
| 批 2-3 | ETL 任务管理 + 任务调度 | 任务执行 / 调度管理 / ETL 状态 / 业务运行 / xcx-... | — | Wave 2 |
| 批 4 | 租户管理 + 用户审核 + Excel | 租户用户管理 / 租户管理员 / 租户Excel上传 / 后台审核管理 / 后台租户管理员 | — | Wave 3 |
| 批 5 | 系统设置 + 日志 + 内部 API | 环境管理 / 数据库查看器 / 后台调试日志 / internal-* / 微信回调 / 维客线索 | — | Wave 4 |
| 聚合 | 5 批合并 NS-admin-web-backend-api.md | 全部 | — | Wave 5 |
## 二、按标签分组(34 tag / 151 端点)
### admin-ai(13 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/admin/ai/alerts` | List Alerts |
| POST | `/api/admin/ai/alerts/{log_id}/ack` | Ack Alert |
| POST | `/api/admin/ai/alerts/{log_id}/ignore` | Ignore Alert |
| POST | `/api/admin/ai/batch-run` | Create Batch Run |
| POST | `/api/admin/ai/batch-run/confirm` | Confirm Batch Run |
| GET | `/api/admin/ai/budget` | Get Budget |
| POST | `/api/admin/ai/cache/invalidate` | Invalidate Cache |
| GET | `/api/admin/ai/dashboard` | Get Dashboard |
| GET | `/api/admin/ai/run-logs` | List Run Logs |
| GET | `/api/admin/ai/run-logs/{log_id}` | Get Run Log |
| GET | `/api/admin/ai/trigger-jobs` | List Trigger Jobs |
| GET | `/api/admin/ai/trigger-jobs/{job_id}` | Get Trigger Job |
| POST | `/api/admin/ai/trigger-jobs/{job_id}/retry` | Retry Trigger Job |
### 小程序认证(12 端点)
| Method | Path | 用途 |
|---|---|---|
| POST | `/api/xcx/apply` | Submit Application |
| POST | `/api/xcx/cancel-application` | Cancel My Application |
| GET | `/api/xcx/dev-context` | Dev Context |
| POST | `/api/xcx/dev-login` | Dev Login |
| POST | `/api/xcx/dev-switch-binding` | Dev Switch Binding |
| POST | `/api/xcx/dev-switch-role` | Dev Switch Role |
| POST | `/api/xcx/dev-switch-status` | Dev Switch Status |
| POST | `/api/xcx/login` | Wx Login |
| GET | `/api/xcx/me` | Get My Status |
| GET | `/api/xcx/me/sites` | Get My Sites |
| POST | `/api/xcx/refresh` | Refresh Token |
| POST | `/api/xcx/switch-site` | Switch Site |
### 租户用户管理(11 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/tenant/applications` | List Applications |
| POST | `/api/tenant/applications/{application_id}/approve` | Approve Application |
| GET | `/api/tenant/applications/{application_id}/match-suggestions` | Get Match Suggestions |
| POST | `/api/tenant/applications/{application_id}/reject` | Reject Application |
| GET | `/api/tenant/my-sites` | List My Sites |
| GET | `/api/tenant/roles` | List Roles |
| GET | `/api/tenant/site-staff` | List Site Staff |
| GET | `/api/tenant/users` | List Users |
| PATCH | `/api/tenant/users/{user_id}` | Edit User |
| DELETE | `/api/tenant/users/{user_id}` | Remove User |
| PUT | `/api/tenant/users/{user_id}/binding` | Update Binding |
### 任务执行(9 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/execution/history` | Get Execution History |
| GET | `/api/execution/queue` | Get Queue |
| POST | `/api/execution/queue` | Enqueue Task |
| PUT | `/api/execution/queue/reorder` | Reorder Queue |
| DELETE | `/api/execution/queue/{task_id}` | Delete Queue Task |
| POST | `/api/execution/run` | Run Task |
| POST | `/api/execution/{execution_id}/cancel` | Cancel Execution |
| GET | `/api/execution/{execution_id}/logs` | Get Execution Logs |
| POST | `/api/execution/{execution_id}/rerun` | Rerun Execution |
### 运维面板(9 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/ops/env-file/{env}` | Get Env File |
| GET | `/api/ops/git` | Get Git Info |
| POST | `/api/ops/git/{env}/pull` | Git Pull |
| POST | `/api/ops/git/{env}/sync-deps` | Sync Deps |
| GET | `/api/ops/services` | Get Services Status |
| POST | `/api/ops/services/{env}/restart` | Restart Service |
| POST | `/api/ops/services/{env}/start` | Start Service |
| POST | `/api/ops/services/{env}/stop` | Stop Service |
| GET | `/api/ops/system` | Get System Info |
### 开发调试日志(8 端点)
| Method | Path | 用途 |
|---|---|---|
| POST | `/api/admin/dev-trace/cleanup` | Cleanup Logs |
| GET | `/api/admin/dev-trace/coverage` | Get Coverage |
| POST | `/api/admin/dev-trace/coverage/scan` | Trigger Coverage Scan |
| GET | `/api/admin/dev-trace/dates` | List Dates |
| GET | `/api/admin/dev-trace/request/{request_id}` | Get Request Detail |
| GET | `/api/admin/dev-trace/requests` | List Requests |
| GET | `/api/admin/dev-trace/settings` | Get Settings |
| PUT | `/api/admin/dev-trace/settings` | Update Settings |
### admin-registry(7 端点)
| Method | Path | 用途 |
|---|---|---|
| POST | `/api/admin/sites` | Create Site |
| POST | `/api/admin/sites/sync` | Sync Sites |
| DELETE | `/api/admin/sites/{site_id}` | Delete Site |
| PUT | `/api/admin/sites/{site_id}/site-code` | Update Site Code |
| GET | `/api/admin/sites/{site_id}/site-code-history` | Get Site Code History |
| GET | `/api/admin/tenants` | List Tenants |
| GET | `/api/admin/tenants/{tenant_id}/sites` | List Tenant Sites |
### 调度管理(7 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/schedules` | List Schedules |
| POST | `/api/schedules` | Create Schedule |
| PUT | `/api/schedules/{schedule_id}` | Update Schedule |
| DELETE | `/api/schedules/{schedule_id}` | Delete Schedule |
| GET | `/api/schedules/{schedule_id}/history` | Get Schedule History |
| POST | `/api/schedules/{schedule_id}/run` | Run Schedule Now |
| PATCH | `/api/schedules/{schedule_id}/toggle` | Toggle Schedule |
### 小程序任务(6 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/xcx/tasks` | Get Tasks |
| GET | `/api/xcx/tasks/{task_id}` | Get Task Detail |
| POST | `/api/xcx/tasks/{task_id}/abandon` | Abandon Task |
| POST | `/api/xcx/tasks/{task_id}/pin` | Pin Task |
| POST | `/api/xcx/tasks/{task_id}/restore` | Restore Task |
| POST | `/api/xcx/tasks/{task_id}/unpin` | Unpin Task |
### 任务配置(5 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/tasks/dwd-tables` | Get Dwd Tables |
| GET | `/api/tasks/flows` | Get Flows |
| GET | `/api/tasks/registry` | Get Task Registry |
| GET | `/api/tasks/sync-check` | Sync Check |
| POST | `/api/tasks/validate` | Validate Task Config |
### 小程序 CHAT(5 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/xcx/chat/history` | List Chat History |
| GET | `/api/xcx/chat/messages` | Get Chat Messages By Context |
| POST | `/api/xcx/chat/stream` | Chat Stream |
| GET | `/api/xcx/chat/{chat_id}/messages` | Get Chat Messages |
| POST | `/api/xcx/chat/{chat_id}/messages` | Send Message |
### 租户店铺管理员(5 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/tenant/site-admins` | List Site Admins |
| POST | `/api/tenant/site-admins` | Create Site Admin |
| PATCH | `/api/tenant/site-admins/{admin_id}` | Edit Site Admin |
| DELETE | `/api/tenant/site-admins/{admin_id}` | Delete Site Admin |
| POST | `/api/tenant/site-admins/{admin_id}/reset-password` | Reset Site Admin Password |
### 管理端租户管理员(5 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/admin/tenant-admins` | List Tenant Admins |
| POST | `/api/admin/tenant-admins` | Create Tenant Admin |
| PATCH | `/api/admin/tenant-admins/{admin_id}` | Edit Tenant Admin |
| DELETE | `/api/admin/tenant-admins/{admin_id}` | Delete Tenant Admin |
| POST | `/api/admin/tenant-admins/{admin_id}/reset-password` | Reset Password |
### 维客线索管理(5 端点)
| Method | Path | 用途 |
|---|---|---|
| PATCH | `/api/tenant/clues/{clue_id}` | Edit Clue |
| DELETE | `/api/tenant/clues/{clue_id}` | Delete Clue |
| PATCH | `/api/tenant/clues/{clue_id}/visibility` | Toggle Clue Visibility |
| GET | `/api/tenant/customers/search` | Search Customers |
| GET | `/api/tenant/customers/{member_id}/clues` | List Customer Clues |
### 数据库查看器(4 端点)
| Method | Path | 用途 |
|---|---|---|
| POST | `/api/db/query` | Execute Query |
| GET | `/api/db/schemas` | List Schemas |
| GET | `/api/db/schemas/{name}/tables` | List Tables |
| GET | `/api/db/tables/{schema}/{table}/columns` | List Columns |
### 租户Excel上传(4 端点)
| Method | Path | 用途 |
|---|---|---|
| POST | `/api/tenant/excel/confirm` | Confirm Upload |
| GET | `/api/tenant/excel/logs` | List Upload Logs |
| GET | `/api/tenant/excel/template/{template_type}` | Download Template |
| POST | `/api/tenant/excel/upload` | Upload Excel |
### 管理端审核(4 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/admin/applications` | List Applications |
| GET | `/api/admin/applications/{application_id}` | Get Application Detail |
| POST | `/api/admin/applications/{application_id}/approve` | Approve |
| POST | `/api/admin/applications/{application_id}/reject` | Reject |
### xcx-board(3 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/xcx/board/coaches` | Get Coach Board |
| GET | `/api/xcx/board/customers` | Get Customer Board |
| GET | `/api/xcx/board/finance` | Get Finance Board |
### 小程序备注(3 端点)
| Method | Path | 用途 |
|---|---|---|
| POST | `/api/xcx/notes` | Create Note |
| GET | `/api/xcx/notes` | Get Notes |
| DELETE | `/api/xcx/notes/{note_id}` | Delete Note |
### 环境配置(3 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/env-config` | Get Env Config |
| PUT | `/api/env-config` | Update Env Config |
| GET | `/api/env-config/export` | Export Env Config |
### 维客线索(3 端点)
| Method | Path | 用途 |
|---|---|---|
| POST | `/api/retention-clue` | Submit Retention Clue |
| DELETE | `/api/retention-clue/{clue_id}` | Delete Retention Clue |
| GET | `/api/retention-clue/{member_id}` | Get Retention Clues |
### ETL 状态(2 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/etl-status/cursors` | List Cursors |
| GET | `/api/etl-status/recent-runs` | List Recent Runs |
### 小程序客户(2 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/xcx/customers/{customer_id}` | Get Customer Detail |
| GET | `/api/xcx/customers/{customer_id}/records` | Get Customer Records |
### 小程序绩效(2 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/xcx/performance` | Get Performance Overview |
| GET | `/api/xcx/performance/records` | Get Performance Records |
### 微信回调(2 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/wx/callback` | Verify |
| POST | `/api/wx/callback` | Receive Message |
### 租户认证(2 端点)
| Method | Path | 用途 |
|---|---|---|
| POST | `/api/tenant/auth/login` | Tenant Login |
| POST | `/api/tenant/auth/refresh` | Tenant Refresh |
### 系统(2 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/debug/config-paths` | Debug Config Paths |
| GET | `/health` | Health Check |
### 认证(2 端点)
| Method | Path | 用途 |
|---|---|---|
| POST | `/api/auth/login` | Login |
| POST | `/api/auth/refresh` | Refresh |
### internal-ai(1 端点)
| Method | Path | 用途 |
|---|---|---|
| POST | `/api/internal/ai/trigger` | Trigger Ai Event |
### xcx-config(1 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/xcx/config/skill-types` | Get Skill Types |
### 业务配置(1 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/config/business-day` | Get Business Day Config |
### 小程序 AI 缓存(1 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/ai/cache/{cache_type}` | Get Ai Cache |
### 小程序MVP(1 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/xcx-test` | Get Xcx Test |
### 小程序助教(1 端点)
| Method | Path | 用途 |
|---|---|---|
| GET | `/api/xcx/coaches/{coach_id}` | Get Coach Detail |