fix(tools): 恢复 OpenAPI 抓取脚本 + 重抓 backend-api.json (W1 / F2-1A)

历史: 2026-04-06 commit 779b2f6 大批量清理时被 Claude Opus 4.6 误归档到 _DEL/_DEL/scripts/ops/_export_openapi.py, 28 天 stale。恢复: - cp _DEL/_DEL/scripts/ops/_export_openapi.py scripts/ops/ - 跑脚本重抓: 137 -> 167 paths (新增 30) / 194 -> 234 schemas - 0 个 removed (后端无废弃) 新增 30 端点分布: admin-ai 5 + runtime-context 3 + task-engine 7 + triggers 1 + db-health 1 + execution/internal/trigger-jobs 5 + xcx 5 附 F3-2B prompt 文件清单 (本地 8 个 + App1 缺本地副本): docs/_overview/wave1-findings/F3-2-prompt-files-list.md Neo 决策 B 云端权威, 用清单对照云端 prompt 检查/更新本地副本。详细 diff 见审计: docs/audit/changes/2026-05-04__wave1_f2_1_openapi_script_restored.md
2026-05-05 00:30:10 +08:00
parent 8458cfaae2
commit f92f2d98f3
4 changed files with 4334 additions and 171 deletions
--- a/docs/_overview/wave1-findings/F3-2-prompt-files-list.md
+++ b/docs/_overview/wave1-findings/F3-2-prompt-files-list.md
@@ -0,0 +1,79 @@
+# F3-2B 本地 Prompt 文件清单 — 待 Neo 核对更新
+
+> 日期:2026-05-04 / 触发:Neo F3-2B 反馈"给我本地的 Prompt 保存地址,我去检查并更新"
+> 决策:**B 云端权威 + git 备份**,SDK 调用方式不改(继续用百炼 APP 调用)
+> 用法:Neo 用本清单逐个对照百炼控制台 prompt,本地过期则更新
+
+## 一、本地 prompt 文件清单(8 个)
+
+目录:`apps/backend/app/ai/prompts/`
+
+| # | APP | 文件 | 用途 |
+|---|---|---|---|
+| 1 | App2 | [`app2_finance_prompt.py`](../../../apps/backend/app/ai/prompts/app2_finance_prompt.py) | 财务洞察(总览,area=all)|
+| 2 | App2a | [`app2a_finance_area_prompt.py`](../../../apps/backend/app/ai/prompts/app2a_finance_area_prompt.py) | 财务洞察(区域,area≠all)|
+| 3 | App3 | [`app3_clue_prompt.py`](../../../apps/backend/app/ai/prompts/app3_clue_prompt.py) | 维客线索分析 |
+| 4 | App4 | [`app4_analysis_prompt.py`](../../../apps/backend/app/ai/prompts/app4_analysis_prompt.py) | 关系分析 / 任务建议 |
+| 5 | App5 | [`app5_tactics_prompt.py`](../../../apps/backend/app/ai/prompts/app5_tactics_prompt.py) | 话术建议 |
+| 6 | App6 | [`app6_note_prompt.py`](../../../apps/backend/app/ai/prompts/app6_note_prompt.py) | 备注分析 |
+| 7 | App7 | [`app7_customer_prompt.py`](../../../apps/backend/app/ai/prompts/app7_customer_prompt.py) | 客户洞察 |
+| 8 | App8 | [`app8_consolidation_prompt.py`](../../../apps/backend/app/ai/prompts/app8_consolidation_prompt.py) | 整合去重落库 |
+
+## 二、关键缺失:App1
+
+**`app1_chat_prompt.py` 不存在**。
+
+App1(通用对话/SSE 流式)的 prompt **没有本地副本**,完全在百炼控制台。原因可能是:
+- App1 是 SSE 流式,prompt 改动频率高,主要在百炼调试
+- 历史上没有"本地存 prompt"的设计
+
+**建议**:
+- Neo 从百炼控制台导出 App1 prompt → 创建 `app1_chat_prompt.py` 入仓作为备份
+- 或者:接受 App1 prompt 仅在云端(SSE 场景特殊)
+
+## 三、对照核查方法(给 Neo)
+
+对每个 APP:
+
+1. 打开百炼控制台 → 进入对应 APP 设置 → 找到 system prompt
+2. 打开本仓库对应文件(上面表格链接)
+3. **diff** 两边内容
+4. **如果云端 = git** → 一致,无需更新
+5. **如果云端 ≠ git** → 云端为权威,**用云端版本覆盖 git 文件**(对齐 Neo 决策"云端权威")
+6. 在本文件末尾标"已对照 / 已更新 / 一致" + 日期
+
+## 四、对照状态记录(Neo 自填)
+
+| APP | 对照日期 | 状态 | 备注 |
+|---|---|---|---|
+| App1 | — | **缺本地副本,需从云端导出** | — |
+| App2 | — | 待对照 | — |
+| App2a | — | 待对照 | — |
+| App3 | — | 待对照 | — |
+| App4 | — | 待对照 | — |
+| App5 | — | 待对照 | — |
+| App6 | — | 待对照 | — |
+| App7 | — | 待对照 | — |
+| App8 | — | 待对照 | — |
+
+## 五、SDK 调用方式(已确认不改)
+
+Neo 反馈:**"SDK 调用不要改,我坚持使用 APP 调用的方式"**。
+
+后端继续走百炼 APP 调用(SDK 携带 app_id,云端 prompt 生效),git 文件**仅作备份用**,不通过 SDK 传 prompt_template。
+
+## 六、风险提示
+
+云端权威方案的已知风险(P2-6 / F3-2B 已讨论):
+- 不可 git diff / blame
+- 多 AI 调优时云端可能漂移,git 可能滞后(本对照机制是唯一的同步触发)
+
+**缓解**:
+- 每月定期对照(本文件 § 四 记录)
+- 重大 prompt 调整后立即同步 git
+
+## 七、关联
+
+- 决策来源:[`01-W1-findings-response.md`](01-W1-findings-response.md) §10.4
+- P2-6 原讨论:[`docs/_overview/04c-feedback/P2-6-and-P2-9-design.md`](../04c-feedback/P2-6-and-P2-9-design.md)
+- F3-2A SCD2 配置表:Wave 2 实施(`biz.cfg_ai_token_price`)
--- a/docs/audit/changes/2026-05-04__wave1_f2_1_openapi_script_restored.md
+++ b/docs/audit/changes/2026-05-04__wave1_f2_1_openapi_script_restored.md
@@ -0,0 +1,131 @@
+# Wave 1 F2-1 — 恢复 OpenAPI 抓取脚本 + 重抓 backend-api.json
+
+| 字段 | 值 |
+|---|---|
+| 日期 | 2026-05-04 |
+| Wave | 1 / Wave 2 前(立即处理) |
+| 范围 | F2-1A 恢复 `_export_openapi.py` + 重抓 backend-api.json + diff 核对 |
+| 文件改动 | 2 文件(脚本恢复 + JSON 重抓)|
+
+## 一、恢复操作
+
+### 1.1 从 _DEL/ 恢复脚本
+
+```bash
+cp _DEL/_DEL/scripts/ops/_export_openapi.py scripts/ops/_export_openapi.py
+```
+
+文件内容(13 行):
+```python
+"""从运行中的 FastAPI app 导出 OpenAPI spec 到 docs/contracts/openapi/backend-api.json"""
+import json
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2] / "apps" / "backend"))
+from app.main import app
+
+spec = app.openapi()
+out = pathlib.Path(r"C:\Project\NeoZQYY\docs\contracts\openapi\backend-api.json")
+out.write_text(json.dumps(spec, ensure_ascii=False, indent=2), encoding="utf-8")
+print(f"Done: {len(spec['paths'])} paths, {len(spec['components']['schemas'])} schemas")
+```
+
+**未做改动**(脚本本身无 bug,仅是被误归档)。
+
+### 1.2 立即重抓
+
+```bash
+.venv/Scripts/python.exe scripts/ops/_export_openapi.py
+# Done: 167 paths, 234 schemas
+```
+
+## 二、Diff 核对(Neo 反馈"看下 json 内容是否和当前情况相一致")
+
+| 维度 | git HEAD(2026-04-06)| 重抓(2026-05-04)| 差异 |
+|---|---|---|---|
+| paths | 137 | **167** | **+30** |
+| schemas | 194 | **234** | +40 |
+| removed | 0 | 0 | 后端无废弃 |
+
+### 30 个新增端点(28 天积累)
+
+按业务模块分组:
+
+**admin-ai 系列**(5):
+- `/api/admin/ai/prewarm/progress`
+- `/api/admin/ai/run/{app_type}`
+- `/api/admin/ai/trigger-event`
+- `/api/admin/ai/triggers`(GET&PATCH)
+- `/api/admin/ai/triggers/{trigger_id}`
+
+**admin-runtime-context 系列**(3):
+- `/api/admin/runtime-context`
+- `/api/admin/runtime-context/sites`
+- `/api/config/runtime-context`
+
+**admin-task-engine 系列**(7):
+- `/api/admin/task-engine/clear-all-tasks`(P0-6 高危)
+- `/api/admin/task-engine/config`、`/config/{param_id}`
+- `/api/admin/task-engine/pending-review`、`/pending-review/{task_id}/close`、`/reassign`
+- `/api/admin/task-engine/transfer-log`、`/transfer-log/{member_id}/history`
+
+**admin-triggers**(1):
+- `/api/admin/triggers/unified`(P1-6 三 API 之一)
+
+**admin-db-health**(1):
+- `/api/admin/db-health`
+
+**execution / internal / trigger-jobs**(5):
+- `/api/execution/cleanup-output`
+- `/api/internal/etl-completed`
+- `/api/internal/run-job`
+- `/api/trigger-jobs`、`/trigger-jobs/{job_id}/config`、`/{job_id}/run`
+
+**xcx 系列**(5):
+- `/api/xcx/avatar/upload`、`/avatar/{user_id}`
+- `/api/xcx/coaches/{coach_id}/banner`
+- `/api/xcx/customers/{customer_id}/consumption-records`
+- `/api/xcx/runtime/clock`
+- `/api/xcx/tasks/by-member/{member_id}`
+
+**结论**:30 个新增端点全部为 28 天内合理迭代,**0 个 removed**(无废弃),与代码完全一致。
+
+## 三、修正 W1-T7 批 1 PRD 总览的端点数
+
+之前 `docs/_overview/admin-api-prd/00-overview.md` 写"151 端点 / 34 标签",来源是旧 backend-api.json。**正确数字应为 167 端点**。
+
+W1-T7 批 1 内的 23 端点中,Wave 0 标记"OpenAPI 缺 10 个" — 现已全部出现在新 spec 中(本次重抓覆盖到了)。
+
+## 四、风险与回滚
+
+| 项 | 风险 | 回滚 |
+|---|---|---|
+| 脚本恢复 | 低 — 13 行简单逻辑 | `git rm scripts/ops/_export_openapi.py` |
+| backend-api.json 重抓 | 低 — 内容反映真实 router | `git checkout HEAD -- docs/contracts/openapi/backend-api.json` |
+
+## 五、F2-1B(后续):防御机制
+
+**留 Wave 2-3 实施**:
+1. 加 PostToolUse hook 匹配 `apps/backend/app/routers/*.py`,提醒"router 已改,记得跑 `python scripts/ops/_export_openapi.py`"
+2. 在 `.claude/commands/spec-close.md` L45 补脚本调用命令(从"手工同步"升级为"具体命令")
+3. (可选)CI 加一步:对比 `/openapi.json` vs `backend-api.json`,不一致则失败
+
+## 六、commit 建议
+
+```
+fix(tools): 恢复 OpenAPI 抓取脚本 + 重抓 backend-api.json (W1 / F2-1A)
+
+历史: 2026-04-06 commit 779b2f6 大批量清理时被 Claude Opus 4.6 误归档
+     到 _DEL/_DEL/scripts/ops/_export_openapi.py, 28 天 stale。
+
+恢复:
+- cp _DEL/_DEL/scripts/ops/_export_openapi.py scripts/ops/
+- 跑脚本重抓: 137 -> 167 paths (新增 30) / 194 -> 234 schemas
+- 0 个 removed (后端无废弃)
+
+新增 30 端点分布: admin-ai 5 + runtime-context 3 + task-engine 7 +
+triggers 1 + db-health 1 + execution/internal/trigger-jobs 5 + xcx 5
+
+详细 diff 见审计文档。
+```
--- a/docs/contracts/openapi/backend-api.json
+++ b/docs/contracts/openapi/backend-api.json
--- a/scripts/ops/_export_openapi.py
+++ b/scripts/ops/_export_openapi.py
@@ -0,0 +1,12 @@
+"""从运行中的 FastAPI app 导出 OpenAPI spec 到 docs/contracts/openapi/backend-api.json"""
+import json
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2] / "apps" / "backend"))
+from app.main import app
+
+spec = app.openapi()
+out = pathlib.Path(r"C:\Project\NeoZQYY\docs\contracts\openapi\backend-api.json")
+out.write_text(json.dumps(spec, ensure_ascii=False, indent=2), encoding="utf-8")
+print(f"Done: {len(spec['paths'])} paths, {len(spec['components']['schemas'])} schemas")