root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
2dfc926f96681f7e054b01016b15266b3e3ee0ab
Neo-ZQYY/docs/_overview/admin-api-prd/00-overview.md
Neo c58599d29b docs(prd): admin-web API 全景总览 + 批 1 PRD (W1-T7 / P1-7) 
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
2026-05-04 09:54:35 +08:00

371 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 |
Reference in New Issue View Git Blame Copy Permalink