Files

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

14 KiB

Raw Blame History

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 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 必修项:

修复 tools/codex/... 或类似 OpenAPI 抽取脚本
重新生成 backend-api.json,与代码对照 0 缺漏后再聚合 PRD

五、批 1 详细 PRD

详见 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

14 KiB Raw Blame History Unescape Escape