Neo
a99bbd9a74
历史教训 (F2-1A): OpenAPI 抓取脚本 2026-04-06 commit 779b2f6 被
Claude Opus 4.6 在批量清理 1155 个废弃文件时误归档到
_DEL/_DEL/scripts/ops/, 导致 docs/contracts/openapi/backend-api.json
28 天 stale (137 paths -> 实际 167 paths, 缺 30 端点)。
Neo 反馈: 建立机制不要让类似事件再发生。
F3-2C 配套需求: 建立 docs/ai/system-prompts/ 独立 MD 体系后,
维护流程依赖 3 步同步 (元信息日期 / 同步历史 / _INDEX.md 状态表),
容易遗漏造成漂移。
新增 2 个 PostToolUse hook (Edit|Write matcher, timeout 5s):
- post_edit_openapi_reminder.py: 改 apps/backend/app/routers/*.py
提醒重抓 OpenAPI 具体命令
(.venv/Scripts/python.exe scripts/ops/_export_openapi.py)
- post_edit_prompt_sync_reminder.py: 改 docs/ai/system-prompts/app*.md
提醒 3 步同步 (元信息 / 同步历史 / _INDEX.md 状态表)
settings.json 注册 2 个 hook 条目 (PostToolUse 末尾追加)。
spec-close.md 步骤 5 文档同步表:
- OpenAPI 行升级为具体命令 (避免手工同步漂移描述)
- 新增 docs/ai/system-prompts/app*.md 同步行
验证: stdin 模拟测试 3 场景全部符合预期 (匹配 router 输出 OpenAPI 提醒;
匹配 system-prompts MD 输出 prompt 同步提醒; 不匹配静默)。
详见 docs/audit/changes/2026-05-05__wave1_f2_1b_defense_hooks.md
3.1 KiB
3.1 KiB
/spec-close — Spec 收尾通用流程
当一个功能 spec 开发完成时，执行此收尾检查清单确保质量闭环。
执行步骤
步骤 1：最终测试检查点（必选）
- 运行 Monorepo 属性测试：
cd /c/NeoZQYY && pytest tests/ -v - 运行模块单元测试：
cd <模块路径> && pytest tests/ -v - 确保所有测试通过，有问题询问用户
步骤 2：前后端联调验证（涉及 API + 前端时必选）
- 启动后端服务，使用测试库验证各端点完整请求-响应链路
- 验证 JSON 响应结构与 Schema 定义一致（camelCase 序列化）
- 验证权限校验和数据隔离（
SET LOCAL app.current_site_id）在真实请求中生效 - 前端联调验证：确认前端页面能正确调用 API 并渲染数据
- 验证空数据/降级场景下前端不崩溃
步骤 3：数据库变更审计与 DDL 合并（涉及 DB 改动时必选）
- 审计本次实现中对数据库的所有改动（新建表、新增字段、新增索引、FDW 映射变更等）
- 必须通过 pg MCP 工具实际执行迁移 SQL（禁止仅标记完成而不执行）
- 执行后用查询验证表/字段/索引已正确创建
- RLS 视图双 schema：后端查询
app.v_*视图，新建 DWS RLS 视图时必须同时在原 schema 和appschema 下创建 - 合并到主 DDL 基线文件（ETL →
docs/database/ddl/etl_feiqiu__<schema>.sql，业务 →docs/database/ddl/zqyy_app__<schema>.sql） - 编写回滚脚本（逆序 DROP/ALTER）
步骤 4：BD 手册更新（涉及 DB 改动时必选）
- 业务库 →
docs/database/BD_manual_*.md - ETL 库 →
apps/etl/connectors/feiqiu/docs/database/<层级>/main/BD_manual_*.md - FDW →
docs/database/BD_manual_fdw*.md - 每份手册必须包含：字段明细、约束与索引、验证 SQL（≥3 条）、兼容性影响、回滚策略
步骤 5：项目文档同步更新（按涉及范围裁剪）
根据改动类型选择需要更新的文档：
| 文档 | 更新条件 |
|---|---|
| 模块 README | 模块内部结构变更时 |
apps/backend/docs/API-REFERENCE.md |
新增/修改后端路由时 |
docs/contracts/openapi/backend-api.json |
新增/修改 API 端点时 — 执行命令重抓:.venv/Scripts/python.exe scripts/ops/_export_openapi.py(避免手工同步漂移;hook post_edit_openapi_reminder.py 会在改 router 时自动提醒) |
docs/ai/system-prompts/app*.md |
从百炼控制台同步 system prompt 时 — 改 §一 元信息"最后同步"+ §同步历史追加一行 + 同步 _INDEX.md §四 状态表(hook post_edit_prompt_sync_reminder.py 会自动提醒) |
docs/DOCUMENTATION-MAP.md |
新增任何文档条目时 |
步骤 6：变更审计收口（涉及高风险路径时必选）
执行 /audit 命令完成审计流程。
步骤 7：服务清理（启动了运行时服务时必选）
- 关闭浏览器实例、停止后端和前端服务、清理资源
按 Spec 类型裁剪
| 类型 | 必选步骤 |
|---|---|
| ETL 类（ODS/DWD/DWS） | 1, 3, 4, 5, 6 |
| 后端 API 类 | 1, 2, 5, 6 |
| 全栈类（前后端 + DB） | 1, 2, 3, 4, 5, 6 |
| 重构类 | 1, 5, 6 |