root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
8952ca2969820e745577fc2e49258aea0d70eedb
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

7.2 KiB
Raw Blame History

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