# P1-7 admin-web API 完整 PRD 评估报告

> 日期:2026-05-04 / 触发:Neo 在 04b P1-7 反馈选 A 完整 PRD
> Neo 原话:"在梳理完整 PRD 时,我希望你能顺便发现一些 API 的问题,比如 API 设计是否合理,架构是否合理,API 背后的处理是否合理清晰,性能可用性稳定性安全性是否需要优化,一些糟糕的 API 是否需要重构合并等评估。"

**本文不是 PRD 本身,是给 Neo 的"工作量评估 + 实施建议"**,用来判断"现在做、Wave 5 做、还是单开会话做"。

## 一、工作量评估

### 1.1 范围盘点

admin-web 后端 API 来源:
- **44 个后端 router**(从 `apps/backend/app/main.py` L203-L246 挂载列表)
- 其中 admin-web 调用约 **20+ router**(admin_*、env_config、db_viewer、etl_status、execution、schedules、tasks、wx_callback、ops_panel、business_day、internal_*、trigger_jobs)
- 估算 admin-web 实际调用 **80-120 个 API 端点**

### 1.2 单 API 撰写时长(基于 NS1 风格)

每个 API 完整 PRD 包含:
- 路径 + method + 权限要求
- 请求 schema(字段名 / 类型 / 必填 / 描述 / 示例)
- 响应 schema(同上)
- 业务语义(2-4 行)
- 错误码(典型 4xx / 5xx)
- 调用方(哪个前端组件)
- 数据来源(哪个 service / 表)

每个 API 仔细写完整 = **20-30 分钟**(含读代码反推 schema)。

### 1.3 总工作量

| 维度 | 估算 |
|---|---|
| 仅 PRD(不评估) | 80 个 API × 25 分钟 = **33 小时**(约 4 工作日) |
| PRD + 设计/架构评估 | +30%-50% = **45-50 小时**(5-6 工作日) |
| PRD + 评估 + 性能/安全/可用性专项 | +20-30% 再加 = **60-65 小时**(7-8 工作日) |

**完整版(Neo 要的全套):预计 60-65 小时,1.5-2 周专人时间**。

## 二、Neo 的"顺便评估"分解

### 2.1 API 设计是否合理

需要校核 9 个维度:
- RESTful 路径风格(`/api/admin/ai/triggers/:id` vs `/api/admin/ai-trigger-configs/:id`)
- HTTP method 语义(GET / POST / PATCH / DELETE 是否对应 CRUD)
- 请求 / 响应字段命名(camelCase vs snake_case 一致性)
- 路径前缀(`/api/admin/*` vs `/api/admin/*/v2` vs 无前缀)
- 错误响应结构统一性
- 分页约定(page/size vs limit/offset vs cursor)
- 认证授权要求(super_admin / site_admin / 任何登录)
- 幂等性约定(POST 是否幂等 / 重试安全)
- 国际化(暂无,但应记录)

**预计发现 30-50 个不一致点**(基于 Wave 0 调研的零散发现规模推算)。

### 2.2 架构是否合理

需要校核:
- router → service → repository 分层是否清晰
- 跨模块调用边界(避免 router 直接调另一个 router 的 service)
- 全局响应包装中间件覆盖率
- 数据库连接生命周期(每请求一连接 vs 连接池复用)
- WebSocket 与 REST 的边界

### 2.3 API 处理是否合理清晰

需要校核:
- 业务逻辑放 router / service / repository 哪一层
- 错误处理是否完备(try-except 粒度)
- 日志埋点完整性
- 请求参数验证(Pydantic schema 完整性)

### 2.4 性能 / 可用性 / 稳定性

需要校核:
- 慢查询(N+1 / 全表 scan / 缺索引)
- 大数据量响应(>10MB)
- 长事务
- 锁等待
- 缓存策略
- 超时配置
- 限流配置(暂无)
- 幂等保护
- 降级策略(暂无)

### 2.5 安全性

需要校核:
- 认证(JWT / session / cookie)
- 授权粒度(super_admin / site_admin / 业务用户)
- SQL 注入(Pydantic + asyncpg 默认安全,但要校 raw SQL 处)
- XSS / CSRF(admin-web 是否启用)
- 敏感数据脱敏(token / 密码不入日志)
- 越权访问(site_id 隔离边界)

**P0-8 DBViewer SELECT 拦截不全已是发现的安全问题(本次评估应包含此处)**。

### 2.6 重构合并候选

需要识别:
- 同表多 API(P1-6 双 API 已发现)
- 极少调用 API(grep 前端无引用)
- 历史 dev/test API 进入生产
- 重复逻辑(同样的 service 函数被多 router 调)

### 2.7 完整产出会发现的问题(预估)

| 类别 | 预估问题数 |
|---|---|
| 设计不一致(P2 体验) | 30-50 |
| 架构 / 分层(P1) | 5-10 |
| 性能(P1 / P2) | 5-15 |
| 安全(P0 / P1) | 5-10 |
| 重构合并候选(P2) | 10-20 |
| **合计** | **55-105 个工单** |

## 三、推荐拆分方案(Neo 选)

### 方案 A:**一次性完成**(推荐少数情况)

- 1.5-2 周专人时间 + 持续输出 PRD + 评估
- 优:全局视角,问题之间可以串联;一次性建立起完整文档体系
- 劣:阻塞 Wave 1-5 的具体修复;评估结果如未及时落地会过期

### 方案 B:**分批推进**(推荐)

把 API 按模块分 5-6 批,每批与一个 Wave 协同:

| 批次 | 模块 | 时机 | 工作量 |
|---|---|---|---|
| 1 | Runtime Context + AI 管理(admin_ai / admin_runtime_context) | Wave 1 | 5-8 API,1.5 工作日 |
| 2 | ETL 任务管理(tasks / execution / etl_status / business_day / schedules) | Wave 4 | 15-20 API,3-4 工作日 |
| 3 | 触发器(admin_triggers / trigger_jobs) | 同 Wave 1 | 8-10 API,1.5 工作日 |
| 4 | 租户管理 / 用户审核(admin_tenant_admins / admin_applications) | Wave 5 | 5-8 API,1.5 工作日 |
| 5 | 系统设置 / 日志(env_config / admin_dev_trace / db_viewer / admin_db_health) | Wave 5 | 8-12 API,2 工作日 |
| 6 | 内部 API(internal_ai / internal_events / wx_callback) | Wave 5 | 5-8 API,1 工作日 |

**总工作量分散到 5 个 Wave,每个 Wave 1-2 工作日**;评估结论与 Wave 修复同步落地,不脱节。

### 方案 C:**最小可行先行**(快速止损)

只产出"API 总览 + 问题清单",**不写完整每个 API 的 schema 描述**,聚焦"哪些有问题、为什么、怎么修"。

| 工作 | 工作量 |
|---|---|
| API 总览(80 行表格) | 0.5 工作日 |
| 问题清单(50-100 条) | 1-1.5 工作日 |
| **合计** | **2 工作日** |

优:最快揭露问题;劣:不补 schema 文档,新人 onboarding 仍要读代码

### 方案 D:**自动生成 + 人工审核**

利用 FastAPI 自动 OpenAPI:
- `/openapi.json` 已有(本次会话验证过)→ 自动生成 80 个 API 的 schema 描述
- 人工补"业务语义""权限""调用方""问题点"

| 工作 | 工作量 |
|---|---|
| 提取 OpenAPI + 转 markdown | 0.5 工作日 |
| 人工补语义 / 权限 / 调用方 | 2 工作日 |
| 问题评估(同方案 C) | 1.5 工作日 |
| **合计** | **4 工作日** |

优:Schema 自动化;劣:OpenAPI 默认描述质量取决于代码注释完整度

## 四、推荐路径

**强烈推荐方案 B(分批推进)+ 方案 D(自动生成)的混合**:

1. 立即:用 OpenAPI 自动生成 80 个 API 总表(0.5 工作日)→ 产出到 `docs/_overview/admin-web-api-overview.md`
2. Wave 1 协同时:细化 Wave 1 涉及的 5-8 个 API(Runtime Context + AI 管理),发现问题立即修
3. 后续每个 Wave:按方案 B 表逐批推进
4. 最终聚合:在 Wave 5 末尾把 6 批合并成一份 `NS-admin-web-backend-api.md`

**预计总工作量**:8-10 工作日,**分散到 5 个 Wave**,不阻塞主线。

## 五、给 Neo 的决策提问

1. 是否接受方案 B + 方案 D 混合(推荐)
2. 是否同意 Wave 1 立即开始批 1(Runtime Context + AI 管理)?
3. 评估问题打分级别(P0/P1/P2)的判定标准是否参考 04 文档冲突?
4. 评估发现的"重构合并候选"如果数量大(预估 10-20 个),是否要再开一个 Wave 6 专门做架构重构?

---

> 本评估不是 PRD 本身,是工作量与拆分建议。Neo 拍板方案后,主线启动批 1。