Neo-ZQYY/docs/_overview/wave1-findings/F2-1-openapi-history.md

F2-1 OpenAPI 与代码不同步 历史调研

日期:2026-05-04 / 触发:Neo 担忧"有历史原因被忽略" / Wave 1 W1-T7 P1-7 批 1 后续

一、backend-api.json 历史

文件路径:docs/contracts/openapi/backend-api.json(16327 行)。

git 全历史只有 4 次入仓,且每次都是综合性"批量"提交,没有专门的"重抓 OpenAPI"提交:

commit	时间	message 概要	文件规模变化
ded6dfb	2026-02-15 14:58	init: 项目初始提交	首次入仓,仅 35 行(占位)
6e20987	2026-03-09 01:19	微信小程序页面迁移校验之前 P5 任务处理之前	增量更新
79f9a0e	2026-03-20 01:43	feat: batch update gift card breakdown spec, backend APIs ...	增量更新
6f8f123	2026-04-06 00:03	feat: 累积功能变更 — 聊天集成、租户管理、小程序更新、ETL 增强、迁移脚本	+14315 / -X 行,最后一次更新

关键事实:backend-api.json 自 2026-04-06 后再未入仓,距今(2026-05-04)整整 28 天。

二、抓取脚本现状(已被归档)

2.1 当前现状:仓库内不存在抓取脚本

• scripts/ops/ 下:Glob scripts/**/_export_openapi* → 0 命中
• tools/ 下:无 OpenAPI 抓取脚本
• Glob **/_export_openapi* → 仅命中 _DEL/_DEL/scripts/ops/_export_openapi.py

2.2 历史脚本:scripts/ops/_export_openapi.py(已归档到 _DEL/)

源文件 _DEL/_DEL/scripts/ops/_export_openapi.py(12 行,极简):

"""从运行中的 FastAPI app 导出 OpenAPI spec 到 docs/contracts/openapi/backend-api.json"""
import json, pathlib, 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")

实现思路:直接 import app.main,调 app.openapi(),写文件。无 run 服务、无 router 排除条件 — 只要 app.main 能 import 成功,所有已 include_router 的路由都会被囊括。

2.3 抓取脚本 git 时间线

commit	时间	动作
6e20987	2026-03-09 01:19	首次创建(A)
779b2f6	2026-04-06 00:39	删除(D),归档到 _DEL/
66c9ae8	2026-04-10 06:45	仅路径迁移 C:\NeoZQYY → C:\Project\NeoZQYY

779b2f6 commit message 节选:

chore: v1 整理 — 清理历史文件、DDL 合并、文档归档

• 清理 1155 个已删除的历史文件(废弃 prompt_logs、tmp、旧 ops 脚本)
• export/ 数据文件从 git 移除(已在 .gitignore)

_export_openapi.py 与 export_v4_report.py、export_v5_report.py 等"v4/v5/v6/v8 报告导出"脚本一起被当作"旧 ops 脚本"误删。这是一次"误伤" — 该脚本与 v4-v8 报告脚本名称都以 export_ 开头,在批量整理时未被分别审视。

2.4 抓取脚本与最后一次 backend-api.json 更新的时间关系

6f8f123 (2026-04-06 00:03)  最后一次 backend-api.json 入仓 (含手抓产物)
                            ↓ 36 分钟后 ↓
779b2f6 (2026-04-06 00:39)  抓取脚本 _export_openapi.py 被归档删除

完美吻合:最后一次手动跑脚本抓 OpenAPI(6f8f123),当晚把脚本归档清理(779b2f6)。从此抓取手段被"撤掉脚手架"却忘了搭新的 — 而 backend-api.json 也再没人手动重抓过。

三、缺失 10 端点的 router 首次注册时间(timeline 对照)

backend-api.json 上次更新:2026-04-06 00:03(commit 6f8f123)。

端点	router 文件	router 首次入仓 commit	时间	是否晚于 backend-api.json?
/api/admin/runtime-context/*(5 个)	apps/backend/app/routers/admin_runtime_context.py	caf179a	2026-05-04 02:30	是,晚 28 天
/api/admin/triggers/unified	apps/backend/app/routers/admin_triggers.py	6f8f123	2026-04-06 00:03	同 commit(见下)
/api/admin/ai/run/{app_type}	apps/backend/app/routers/admin_ai.py(后期扩展)	caf179a	2026-05-04 02:30	是,晚 28 天
/api/admin/ai/triggers GET&PATCH	admin_ai.py(后期扩展)	caf179a	2026-05-04 02:30	是,晚 28 天
/api/admin/ai/prewarm/progress	admin_ai.py(后期扩展)	caf179a	2026-05-04 02:30	是,晚 28 天
/api/admin/ai/trigger-event	admin_ai.py(后期扩展)	caf179a	2026-05-04 02:30	是,晚 28 天

注:admin_triggers.py 与 admin_ai.py 都首次出现在 6f8f123(2026-04-06),但 6f8f123 commit message 显示"缓 14315 行 backend-api.json,已含 admin_ai 早期 13 个端点"。grep 验证 backend-api.json 中已含 /api/admin/ai/dashboard、/api/admin/ai/trigger-jobs、/api/admin/ai/cache/invalidate、/api/admin/ai/budget、/api/admin/ai/batch-run、/api/admin/ai/alerts/... 等 13 个端点,不含 /api/admin/triggers/unified。即 6f8f123 当天导出时:admin_triggers.py 已合并但 app.include_router(admin_triggers.router) 顺序在 app.include_router(admin_ai.router) 之后(diff 显示 +app.include_router(admin_ai.router) 与 +app.include_router(admin_triggers.router) 同 hunk 出现)。最可能的原因:人工手抓时,服务先以"未含 admin_triggers"的旧分支启动跑了导出,然后才在同 commit 把 admin_triggers 合并进来。

两种 stale 性质同时存在:

1. 5 月新增的 5+4=9 端点(runtime-context 全部 + admin_ai 后期扩展):纯粹"忘抓" — 28 天没人重跑 app.openapi(),而脚本本身已不在仓库。
2. /api/admin/triggers/unified 1 端点:同 commit 内的并发问题 — 4 月 6 日抓取流程不稳健,导出时 router 还没 include。

四、回答 Neo 的"历史原因"

Q1:backend-api.json 上次更新?

2026-04-06 00:03,commit 6f8f123(message"feat: 累积功能变更 — 聊天集成、租户管理、小程序更新、ETL 增强、迁移脚本")。距今 28 天。

Q2:OpenAPI 抓取脚本在哪?

当前不存在。曾经存在 scripts/ops/_export_openapi.py(12 行,2026-03-09 创建),已于 2026-04-06 00:39 commit 779b2f6 删除归档至 _DEL/_DEL/scripts/ops/_export_openapi.py。

实现极简:from app.main import app; spec = app.openapi()。无 router 排除逻辑、无服务启动条件 — 只要 import 成功,所有 include_router 路径都会被收录。脚本本身没 bug。

backend-api.json 当前的"维护方式":事实上无任何自动化 — 仅 .claude/commands/spec-close.md 第 45 行提到"新增/修改 API 端点时手工同步 backend-api.json",但没指明用什么工具。

Q3:缺失 10 端点 router 首次注册时间?(timeline 判定)

• 9 个端点的 router 都是 2026-05-04 02:30 caf179a — 远晚于 backend-api.json 上次更新(2026-04-06)。
• 1 个端点(/api/admin/triggers/unified)是 2026-04-06 同 commit — 抓取与合并并行竞态。

判定:9/10 是"忘了重抓",1/10 是"抓取流程不稳健 + 脚本即将被删,无后续补救"。抓取脚本本身没有 bug,bug 在流程 — 脚本被删后,无人发现"维护手段已消失",于是 W1-T7 才在 28 天后撞上 stale。

Q4:是否有历史决策刻意排除某些 router?

没有。docs/audit/changes/ 35 份提及 OpenAPI 的审计记录中,无任何"排除特定 router"的决策。反而:

• 2026-02-26 audit 记录强调"接口代码已变更但 OpenAPI spec 可能未同步,待手动操作:运行 python scripts/ops/_export_openapi.py"。
• 2026-02-27 audit 记录"接口代码已变更,OpenAPI spec 已重新导出(59 paths, 59 schemas)"— 工作流是清晰的"改 router → 跑脚本 → 入仓"。
• 2026-03-04 commit 显示 backend-api.json +5096 行,即"全量重抓"是常态,无排除清单。
• 2026-03-22 P16 spec 收尾文档明文"更新 OpenAPI spec,补充 P16 相关的接口定义和 Schema 字段"。

结论:无刻意排除,完全是工程链路被切断。

Q5:.mcp.json 中 openapi(awslabs.openapi-mcp-server)与 backend-api.json 关系?

MCP 是单向消费方,不反向生成。.mcp.json:51 配置:

"--api-url", "http://127.0.0.1:8000",
"--spec-path", "C:\\Project\\NeoZQYY\\docs\\contracts\\openapi\\backend-api.json",

awslabs.openapi-mcp-server 把 backend-api.json(spec-path)转成 MCP 工具供 Claude/Cursor 调用,它读 spec、不写 spec。意味着:

• spec stale → MCP 看到的就是 stale 接口集 → AI 写代码可能引用不存在的端点(实际不存在)或忽略已存在的端点(本次 W1-T7 的暴露场景)。
• MCP 没"拉 /openapi.json 自动更新"模式(api-url 仅作为调用 base url,spec 始终来自 spec-path)。

真相判定

主因:抓取脚本"误删"导致维护手段消失,且无人发现。

具体链路:

1. 2026-03-09:抓取脚本入仓,工作流"改 router → 跑脚本 → 提交"运转良好(2-3 月份多次 audit 记录验证)。
2. 2026-04-06 00:03:最后一次成功抓取并提交(commit 6f8f123,加 14315 行)。
3. 2026-04-06 00:39:36 分钟后,脚本与 v4-v8 报告脚本一起被批量归档(commit 779b2f6,message 写"清理废弃 prompt_logs、tmp、旧 ops 脚本")— 该归档动作由 Claude Opus 4.6 协助完成,未识别 _export_openapi.py 是"活的工具"而非"废脚本"。
4. 2026-04-15 ~ 2026-05-04:admin_runtime_context、admin_ai 后期扩展等大量端点新增,无任何人手动同步 backend-api.json(28 天空窗)。
5. 2026-05-04(W1-T7 P1-7 批 1):Neo 用 backend-api.json 作为 PRD 权威源,撞上 stale,发现 30%+ 端点缺失。

被忽略的历史原因(根本原因):"AI 一键清理废弃文件"时把"活的工具"当"废脚本"误删,且未走逐文件审议。该归档 commit 的 message 描述是"清理 1155 个已删除的历史文件",数量级巨大,人工逐个审议不现实 — 这暴露了大批量归档时工具识别不足的工程治理风险。

第二次"被忽略"则是流程层:spec-close.md 第 45 行的"新增/修改 API 端点时手工同步 backend-api.json"是唯一的同步约定,但它没指明用什么命令,且无 hook 强制 — 当抓取脚本被删后,没有任何机制告警"工具已消失"。

五、修复路径推荐(基于真相)

选项 A:从 _DEL/ 恢复脚本 + 跑一次重抓 + 入仓

操作:

1. cp _DEL/_DEL/scripts/ops/_export_openapi.py scripts/ops/_export_openapi.py(脚本就 12 行,无需修改)。
2. cd apps/backend && python ../../scripts/ops/_export_openapi.py(脚本自带 sys.path.insert,可从仓库根直接跑,但更稳是在 apps/backend 下激活 venv 跑)。
3. git add scripts/ops/_export_openapi.py docs/contracts/openapi/backend-api.json && git commit。

优:成本最低、行为可预期(脚本本身没 bug)、立即解锁 Wave 1 W1-T7 后续批次。 劣:无防再次断裂的护栏;下次再有人"清理 ops 脚本"还可能误删。

选项 B:选项 A + 加 hook / pre-commit 防再断

在 .claude/hooks/ 加一个 PostToolUse hook(matcher = Edit|Write,匹配 apps/backend/app/routers/*.py),提醒"router 改动需重抓 OpenAPI"。或加 pre-commit 钩子:检测到 apps/backend/app/routers/ 改动但 docs/contracts/openapi/backend-api.json 未变 → 警告。

优:堵漏;与已有 hook 体系(post_edit_db_doc_sync.py、post_edit_rls_dual_schema.py)一致风格。 劣:hook 只能提醒,不能强制重抓;开发人员仍可"忽略告警"提交。

选项 C:废弃静态 backend-api.json,改运行时拉 /openapi.json

让 .mcp.json 把 spec 直接读 http://127.0.0.1:8000/openapi.json(MCP 支持 url 形式 spec 源),并把 backend-api.json 改成"快照归档"(每 N 周或 release 时手动 dump 一份,标注 release 版本)。

优:根本上消除"代码改 vs 文档改"的同步问题。 劣:依赖后端服务运行;离线开发(无后端跑)时 MCP 不可用;PRD 工作流(P1-7)需要静态 spec 文件作引文锚点,改成动态后引文不稳。

推荐组合:A + B

• A 立即恢复脚本 + 重抓,不晚于 Wave 2 撰写前(批 2-5 还要继续依赖 OpenAPI)。
• B 加一个轻量 hook(提醒级,不阻断),复用现有 hook 模式;或在 spec-close.md 第 45 行明文写出脚本路径与调用命令,弥补"约定无锚点"问题。

C 留作 Wave 5 治理收尾时的远期方案,本轮不动。

六、给 Neo 的决策清单

1. 是否同意"恢复脚本 + 重抓"(选项 A 主路径,5 分钟可完成)?

   • 若同意:子代理可在 W1-T7 批 2 撰写前,把 _DEL/_DEL/scripts/ops/_export_openapi.py 复制回 scripts/ops/,然后由 Neo(或 main agent)跑一次 + 入仓。不在本调研子代理职责内(本任务约定"只调研不改代码")。

2. 是否要加 hook 防再断(选项 B)?

   • 推荐内容:PostToolUse 匹配 apps/backend/app/routers/*.py 的 Edit/Write,提醒"router 已改,记得跑 python scripts/ops/_export_openapi.py 同步 OpenAPI"。
   • 是否加在本轮 W1-T7 完成前,还是单独立一个 Wave 2 任务?

3. 是否要在 spec-close.md 第 45 行补脚本路径?

   • 现在仅"新增/修改 API 端点时 → docs/contracts/openapi/backend-api.json"。建议补成"docs/contracts/openapi/backend-api.json(运行 python scripts/ops/_export_openapi.py 重抓)"。

4. 是否要留一份这次"AI 清理误删"的教训记录?

   • 建议在 docs/audit/changes/ 加一份"2026-05-04__openapi-script-recovery.md"(若选项 A 执行后),把"批量清理时把活工具当废脚本"作为治理教训登记,避免后续再误删 tools/ scripts/ops/ 中的活工具。