# Wave 1 W1-T7 — admin-web API PRD 批 1 (P1-7)

| 字段 | 值 |
|---|---|
| 日期 | 2026-05-04 |
| Wave | 1 / Day 4 |
| 范围 | admin-web API PRD 批 1:Runtime Context + AI 管理 + Triggers |
| 文件改动 | 1 总览 + 1 批 1 PRD(共 1262 行) |

## 一、产出

### 1.1 全景总览

`docs/_overview/admin-api-prd/00-overview.md`(338 行):
- 151 端点 / 34 标签 全清单
- 5 批 PRD 拆分映射
- 工作量修正:原估算 60-65h(80 端点)→ 100-130h(151 端点实际)
- OpenAPI 不同步告警

### 1.2 批 1 详细 PRD

`docs/_overview/admin-api-prd/batch1-runtime-context-and-ai.md`(924 行):
- **23 端点**:admin-ai(17)+ runtime-context(5)+ triggers(1)
- **41 评估发现**:P0×8 / P1×20 / P2×13
- 每端点:用途 + 权限 + 调用方 + Request/Response Schema + 业务语义 + 评估问题 + file:line 引用

## 二、关键发现

### 2.1 OpenAPI 与代码不同步(项目级问题)

`docs/contracts/openapi/backend-api.json` 缺**本批 10+ 端点**:
- 全部 `/api/admin/runtime-context/*`(5 个)
- `/api/admin/triggers/unified`(1 个)
- `admin_ai` 后期扩展 4 个端点

**意味着**:依赖 OpenAPI 自动生成总表的覆盖率仅 ~93%。Wave 5 聚合前**必须修复抓取流程**,否则其他批也可能漏端点。

**推测原因**:OpenAPI 静态导出脚本未含某些后注册的 router,或抓取时未启动包含全部 router 的服务。

**待治理**:留 Wave 5 文档收尾时统一修。

### 2.2 触发器域 4 套端点混乱(P1-6 已覆盖)

admin-web 实际 4 套相似端点:
- `/admin/ai/triggers` (admin_ai router)
- `/trigger-jobs` (trigger_jobs router)
- `/admin/triggers/unified` (admin_triggers router,跨表只读聚合)
- `ai_trigger_jobs` (执行历史)

**P1-6 已给方案 A 完全合并**:扩展 `/trigger-jobs` PATCH + 业务守卫 + 保留 unified。Wave 2 实施。

### 2.3 41 个评估问题分布

| 级别 | 数 | 代表 |
|---|---|---|
| P0 | 8 | 长事务无幂等 / PII 跨租户泄露 / batch_id 生命周期 / triggers/unified 权限过松 / 沙箱模式未校验 runtime_context / P1-6 双 API 合并(2)等 |
| P1 | 20 | 权限粒度过粗 / 缺分页 / 命名误导 / 字段重复 / 缺 audit 等 |
| P2 | 13 | RESTful 语义 / 命名一致性 / 性能优化等 |

部分 P0/P1 与 Wave 0 已知 D Bug 重叠(P0-5 致命 1+2 / P0-6 / P0-8 等),不重复登记。

## 三、对 Neo P1-7 评估的修正

| 项 | P1-7 估算 | 实际 |
|---|---|---|
| 端点总数 | 80 | **151** |
| 工作量(完整版)| 60-65h | **100-130h** |
| 拆分批次 | 5 批 | 保持 5 批,各批端点数重新分配 |
| Wave 1 批 1 | 5-8 端点 | **23 端点** |

工作量超出原估算 50%-100%,但因 Wave 0 调研充分 + 子代理高并发,实际批 1 仅消耗 ~1h 子代理时间。

## 四、风险与回滚

- **本 Wave 仅产出文档**,不修代码 / 不动 router → 零回滚成本
- **41 评估发现**不是工单 → 留 Wave 2-5 按优先级展开
- **OpenAPI 不同步**留 Wave 5 修复抓取脚本

## 五、未覆盖 / 后续 Wave

- 批 2-3:ETL 任务管理 + 任务调度 → Wave 2(P1-1 schema 迁移期间协同)
- 批 4:租户管理 + 用户审核 + Excel → Wave 3
- 批 5:系统设置 + 日志 + 内部 API → Wave 4
- 5 批合并 NS-admin-web-backend-api.md → Wave 5

## 六、commit 建议

```
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 评估发现: P0×8 / P1×20 / P2×13
- 每端点带 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
```
