root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
c58599d29baf04aeff0c9ab8fb423d12608cdc42
Neo-ZQYY/docs/_overview/04b-feedback/P1-7-admin-api-prd-evaluation.md
Neo 509cf43284 chore(docs): Wave 0 调研产出 + P0/P1/P2 反馈调研 
建立项目级标杆文档 docs/_overview/ 作为产品全景索引,
解决"PRD 零碎、文档膨胀、跨子系统调研无入口"的问题。

主要内容:
- 00-index 总索引 + 维护协议 + 与 CLAUDE.md 关系
- 01-product-overview 产品全景脑图(6 角色 / 6 子系统 / 数据流 /
  7 业务概念 / 8+1 AI 矩阵 / 22 术语)
- 02a-miniprogram-page-matrix 小程序 21 页业务指纹
- 02b-adminweb-page-matrix admin-web 19 路由业务指纹
- 03-test-spec 测试规范 (L1-L5 分层 + 走查模板 + 75-95 case 估算)
- 04-doc-conflicts 39 条冲突索引(P0×8 / P1×13 / P2×13 + 5 子项)
- 04a/b/c-conflicts-*-detail 业务故事卡(7 字段:关联/逻辑/影响/选项/判定)
- 05-orphan-pages-cleanup admin-web 6 孤儿页面处置(1 归档 + 4 保留)
- WAVES-MASTER-PLAN.md 全 Wave 主计划(0-5,共 22-32 工作日)
- WAVE-1-KICKOFF.md Wave 1 实施 kickoff
- GLOBAL-DECISION-DASHBOARD.md 全局决策仪表板

反馈调研产物:
- 04a-feedback/ P0 两轮反馈(8+8 项决策 + D-1/2/3 + F-1/2 子代理产出)
- 04b-feedback/ P1 两轮反馈(13+1+5 项 + E-1/2/3/4 + G-1/2 子代理产出)
- 04c-feedback/ P2 反馈(13 项 + 5 子项 + H-1/2/3 子代理产出)
- NEO-DECISIONS-LOG 累积决策记录

关键追加发现 8 处 D Bug(原蓝本 0):
- P0-3 看板沙箱接入(Wave 1 W1-T1)
- P0-5 致命 1 (4 处 fdw_etl 残留, 已修 commit 17f045a)
- P0-5 致命 2 (JWT aud 缺失, 已修 commit 17f045a)
- P0-6 clearAllTasks 守卫 (Wave 3)
- P0-8 DBViewer 黑名单漏 (已修 commit 17f045a)
- P1-3 task-detail 跳转传 task_id 而非 customer_id
- P2-7 board-finance 隐式 null
- 2 个独立 Bug (page_context.created_at + ClueCategory 字典)

参考: docs/_overview/00-index.md
2026-05-04 07:38:28 +08:00

189 lines
7.2 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.
# 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。
Reference in New Issue View Git Blame Copy Permalink