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

docs/_overview/04b-feedback/P1-7-admin-api-prd-evaluation.md

@@ -0,0 +1,188 @@
+# 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。