@chenmk/superflow 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -8,80 +8,81 @@
8
8
 
9
9
  ### 基础检查项(全部项目必做)
10
10
 
11
- | # | 检查项 | 标准 |
12
- |---|---|---|
13
- | 1 | 源码分析(1→1.1)/ 架构设计(0→1) | 引用具体类名、方法名、行号 / architecture.md 含技术选型、模块划分、数据模型 |
14
- | 2 | 变更矩阵(1→1.1) | design.md 每个 Requirement 映射到文件+方法 |
15
- | 3 | 可追溯性 | tasks.md 每个任务关联到 spec Requirement ID |
16
- | 4 | Scenario 覆盖 | spec 每个 Scenario 有 tests 对应测试用例 |
17
- | 5 | 任务原子性 | 每个任务只改一个文件或一个方法 |
18
- | 6 | 依赖声明 | 任务间依赖用 `blocked by` 标注 |
19
- | 7 | 事务边界 | DB 变更任务明确说明事务边界 |
20
- | 8 | 测试自动化 | 每个测试标注 [自动化] 或 [需手工] |
21
- | 9 | 应用配置 | tests.md 已确认端口、上下文路径、配置文件 |
22
- | 10 | 接口 URL | 每个接口测试构造完整 URL |
23
- | 11 | 修复指南 | tests.md 包含测试失败修复指南和质量红线 |
24
- | 12 | **Prompt 拆分合理性** | **如触发拆分条件,已按功能闭环拆分,每份 prompt 边界清晰** |
25
- | 13 | **需求/原型字段对账** | 涉及页面、截图、原型或前端联调时,已建立"页面字段 -> API 字段 -> DTO/VO -> DB -> 测试"映射 |
26
- | 14 | **功能点串行门禁** | 复杂 PRD、飞书文档、原型图或口头大需求必须具备 `source-ingestion.md`、`feature-gates.md`、`feature-inventory.md`、`ui-contract.md`、`gap-analysis.md`、`spec-freeze-review.md`,且当前功能点状态为 `已冻结` |
11
+ | # | 检查项 | 标准 |
12
+ | --- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13
+ | 1 | 源码分析(1→1.1)/ 架构设计(0→1) | 引用具体类名、方法名、行号 / architecture.md 含技术选型、模块划分、数据模型 |
14
+ | 2 | 变更矩阵(1→1.1) | design.md 每个 Requirement 映射到文件+方法 |
15
+ | 3 | 可追溯性 | tasks.md 每个任务关联到 spec Requirement ID |
16
+ | 4 | Scenario 覆盖 | spec 每个 Scenario 有 tests 对应测试用例 |
17
+ | 5 | 任务原子性 | 每个任务只改一个文件或一个方法 |
18
+ | 6 | 依赖声明 | 任务间依赖用 `blocked by` 标注 |
19
+ | 7 | 事务边界 | DB 变更任务明确说明事务边界 |
20
+ | 8 | 测试自动化 | 每个测试标注 [自动化] 或 [需手工] |
21
+ | 9 | 应用配置 | tests.md 已确认端口、上下文路径、配置文件 |
22
+ | 10 | 接口 URL | 每个接口测试构造完整 URL |
23
+ | 11 | 修复指南 | tests.md 包含测试失败修复指南和质量红线 |
24
+ | 12 | **Prompt 拆分合理性** | **如触发拆分条件,已按功能闭环拆分,每份 prompt 边界清晰** |
25
+ | 13 | **需求/原型字段对账** | 涉及页面、截图、原型或前端联调时,已建立"页面字段 -> API 字段 -> DTO/VO -> DB -> 测试"映射 |
26
+ | 14 | **功能点串行门禁** | 复杂 PRD、飞书文档、原型图或口头大需求必须具备 `source-ingestion.md`、`feature-gates.md`、`feature-inventory.md`、`ui-contract.md`、`gap-analysis.md`、`spec-freeze-review.md`,且当前功能点状态为 `已冻结` |
27
27
 
28
28
  ### 按需检查项(涉及则必须检查)
29
29
 
30
- | # | 检查项 | 触发条件 | 标准 |
31
- |---|---|---|---|
32
- | 15 | API 先行冻结 | **涉及接口新增或出入参变更时强制** | api.md 在 design/tasks/tests/prompt 前生成并确认,含完整契约(Path/Query/Body/Response/错误码/示例 curl/枚举/条件必填);不得实现后补档,不得只写"核心字段"或"同 POST" |
33
- | 16 | 前端契约兼容 | 前端字段与后端字段命名不同、字段合并或哨兵值表达 | api.md 必须写清兼容策略、字段映射和过渡方案;tests.md 必须覆盖前端真实 payload |
34
- | 17 | 下拉/枚举接口 | 页面存在下拉框、选择器或枚举展示 | api.md 必须说明数据来源接口、请求参数、响应字段和过滤规则;列表字段必须说明枚举取值 |
35
- | 18 | 反过度设计 | 涉及页面、原型、截图、前端联调 | 页面和产品文档没有、编程人员未确认的字段不得作为 API 必填;后端需要的字段必须标记为后端默认或后端推导 |
36
- | 19 | Mock 策略 | 涉及外部依赖/设备/第三方 | mock.md 声明 Mock 方式、假设条件、替代验证 |
37
- | 20 | 测试执行记录 | 执行了测试 | test-report.md 含环境、命令、结果汇总 |
38
- | 21 | 真实测试证据 | 声称接口、联调或真实测试完成 | 每个关键接口有 curl/请求体/响应/断言/真实参数来源;tests skipped、未启动应用、未连测试库、缺真实参数、mock-only、外部泛化失败时不得标记通过 |
39
- | 21.1 | 测试报告证据一致性 | 出现 test-report.md、Maven/Gradle 测试、跨仓测试或源码锚点 | `~/.codex/hooks/superflow-test-report-lint.py --tests <tests.md> <test-report.md>` 通过;同一命令的 `Tests run` 和 `N/N` 不矛盾;`Tests are skipped` 不得写成通过;tests.md 声明 L3/L4/真实入口/第三方/dev 工具时,报告必须有真实命令、环境、响应断言、DB、日志和外部回调/终态证据;源码锚点仍存在或明确标记为旧实现已删除 |
40
- | 22 | 提示词记录 | 使用 AI 辅助开发 | prompt/ 目录含完整 prompt、采纳情况、修改点 |
41
- | 23 | **可追溯性矩阵** | **拆分为多批时强制** | traceability-matrix.md 含需求/设计/任务/测试/prompt 映射,无设计漂移、无实现遗漏 |
42
- | 24 | **Reviewer 清单** | **拆分为多批时强制** | reviewer-checklist.md 含 19 项检查,用于分批评审 |
43
- | 25 | Red-Green 证据 | Bug 修复或 CR/Px 联调补项 | test-report.md 先记录修复前同一路径失败证据,再记录修复后通过证据;不能只写最终通过 |
44
- | 26 | **文件接口契约** | **涉及导出/下载/上传时强制** | api.md 含文件接口契约表(Content-Type、Content-Disposition、文件名规则、前端判断方式);Controller 方法直接操作 HttpServletResponse;tests.md 验证响应头和文件体 |
45
- | 27 | **Excel 导入契约** | **涉及 Excel 导入时强制** | api.md 含模板列头表、failureCount 与 code 映射规则、日期格式兼容说明;模板 DTO 与导入 DTO 列头一致;tests.md 覆盖部分失败和短日期格式 |
46
- | 28 | **路由一致性** | **涉及新增 Controller mapping 时强制** | api.md 路径与 Controller mapping 双向一致;固定路径与 `{id}` 无冲突或已提示风险;tests.md 含路由映射用例 |
47
- | 29 | **数据权限决策** | **涉及访问业务数据的接口时强制** | api.md 每个访问业务数据的接口有明确数据权限决策(需要/不需要/不确定);"不确定"项已向用户确认;复用当前仓库已有权限模式;tests.md 覆盖至少两个角色 |
48
- | 30 | **外部依赖契约** | **涉及 SDK/第三方/RPC/MQ 时强制** | api.md 含外部依赖契约(参数来源、SDK 版本、响应样例);tests.md 含真实请求/响应或阻塞证据 |
49
- | 31 | **跨仓数据合同** | **多仓共享表、复制 PO/Mapper、MyBatis-Plus BaseMapper、字段删除/迁移时强制** | 已列出表结构真源和全部消费仓;每个消费仓完成实体/Mapper/SQL 与实际库字段对账;不存在列已删除或标注 `@TableField(exist = false)`;查询条件已按最终合同迁移 |
50
- | 32 | **真实入口验收** | **第三方、外部集成、支付、设备、回调、客户端或跨系统链路时强制** | test-report 区分 Mock/测试端点/真实入口;真实入口包含 payload、响应、trace 日志、DB 证据;mock-only 不得写 Passed |
51
- | 33 | **三层验收门禁** | **涉及接口、CRUD、Mapper/XML、数据库字段或配置驱动行为时强制** | prompt 明确完成定义;hook 标记 `.sdd-enforced`/`.db-verified` 已启用;交付前执行 `~/.codex/hooks/superflow-verify-integration.sh <test-report.md>` 且通过 |
52
- | 34 | **测试合同冻结** | **所有实现任务强制** | tests.md 每个用例包含用例ID、层级、前置数据、自动化命令、响应/DB/日志断言、RED预期失败、GREEN预期通过、test-report证据位置;没有可执行命令不得进入实现 |
53
- | 35 | **接口自动化前置** | **涉及接口、CRUD、Mapper/XML、配置驱动、MQ/任务或跨系统链路时强制** | 每个 L3/L4 用例有完整 Base URL、token/cookie 获取、curl/Postman/Newman/pytest/RestAssured 命令、请求体、响应断言、DB SELECT、日志关键词 |
54
- | 36 | **字段语义合同** | **涉及 ID/状态/类型/金额/设备/站点/订单/订阅/外部流水/枚举/跨表关联字段时强制** | design.md 包含 `字段 | 来源表/DTO/事件 | 真实语义 | 目标字段 | 目标语义 | 是否可等价 | 证据锚点 | 禁止用法 | 不确定项/owner`;字段语义不确定时阻塞 |
55
- | 37 | **写入闭环** | **涉及回填/落库/绑定/持久化/快照/同步/状态推进时强制** | design.md 或 traceability-matrix.md 包含 `业务动作 | Java setter/赋值点 | Converter/DTO 映射 | Mapper insert/update | DB column | 后续读取方 | 消费入口 | 验证 SQL | 测试用例`;只证明 setter 不通过 |
56
- | 38 | **真实入口调用链** | **所有接口/MQ/定时/设备/小程序/第三方/后台操作链路强制** | design.md 包含 `用户/外部动作 | 上游服务/接口 | 本仓入口 | MQ/异步回调 | 关键字段变化 | DB 状态 | 结算/通知/展示消费点 | 真实验证方式`;测试端点不能替代真实入口 |
57
- | 39 | **禁止 fallback 与猜测实现** | **所有实现任务强制** | sdd-quality-gate.md 或 design.md 明确禁止默认值、兜底反查、替代字段、保留旧值、空值转可用、静默跳过、下游补偿;批准兼容必须有 owner 确认和暴露/移除规则 |
58
- | 40 | **Agent 执行前自检占位** | **所有实现 prompt 强制** | test-report.md 或 prompt 中预置 `真实入口已定位 | 字段语义合同已核对 | 写入闭环已核对 | 禁止兜底边界已确认 | RED 测试已执行 | 允许修改文件 | 禁止修改文件 | 阻塞项` |
59
- | 41 | **Superpowers 技术详设(HOW)** | **完整 SDD 实现任务强制** | `docs/superpowers/specs/YYYY-MM-DD-*-technical-design.md` 存在并记录当前 handoff_hash;Superpowers 接管源码级 HOW、TDD/RED 切入点、团队/Reviewer/Tester 分工、worktree/端口计划和执行风险;不得覆盖 OpenSpec/SDD 的需求、API、DB、SQL、字段语义、tests 或验收门禁 |
60
- | 42 | **字段/状态反向影响面** | **涉及字段值、状态/枚举、在线离线、删除恢复、同步标记、支付退款状态、第三方状态时强制** | Superpowers 技术详设包含 `Field And Status Reverse Impact`,列出 `字段/状态 | 写入点 | 读取/过滤点 | 派生/同步点 | 跨模块消费方 | 消费方测试 | 缺口/阻塞`;必须执行 `rg`/Mapper XML/实体/DTO/SQL/定时/MQ/回调/第三方/兄弟仓反查;只改直接 setter/writer 阻塞 |
61
- | 43 | **架构师视角的模块职责与调用方向** | **涉及跨仓、跨服务、SDK、MQ、定时、设备、回调、第三方、小程序、网关或适配层时强制** | Superpowers 技术详设包含 `Architecture Boundary And Call Direction`,列出 `链路步骤 | 调用方向 | owner模块 | 既有入口/出口 | 拟新增入口/出口 | 是否允许 | 证据锚点 | 禁止绕路`;必须证明业务入口、出口适配、协议转换、设备网关、MQ 消费者的职责边界没有反转;不能仅以“技术上能调用”为设计依据 |
62
- | 44 | **上下文防漂移 handoff** | **所有进入实现的任务强制** | `.sdd/handoff/sdd-context.md`、`.json`、`.sha256` 和 `.sdd/state.yaml` 已生成;design.md、sdd-quality-gate.md、prompt、test-report 记录同一 handoff_hash;`superflow-guard.sh <change-dir> docs` 通过 |
63
- | 45 | **SDD 状态机字段** | **所有进入实现的任务强制** | `.sdd/state.yaml` 包含 workflow、phase、handoff_hash、build_mode、isolation、tdd_mode、review_mode、verify_mode、implementation_prompt、verification_report、archived;`superflow-state.sh status/next/recover` 输出一致 |
30
+ | # | 检查项 | 触发条件 | 标准 |
31
+ | ---- | ---------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------ | -------------------- | -------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
32
+ | 15 | API 先行冻结 | **涉及接口新增或出入参变更时强制** | api.md 在 design/tasks/tests/prompt 前生成并确认,含完整契约(Path/Query/Body/Response/错误码/示例 curl/枚举/条件必填);不得实现后补档,不得只写"核心字段"或"同 POST" |
33
+ | 16 | 前端契约兼容 | 前端字段与后端字段命名不同、字段合并或哨兵值表达 | api.md 必须写清兼容策略、字段映射和过渡方案;tests.md 必须覆盖前端真实 payload |
34
+ | 17 | 下拉/枚举接口 | 页面存在下拉框、选择器或枚举展示 | api.md 必须说明数据来源接口、请求参数、响应字段和过滤规则;列表字段必须说明枚举取值 |
35
+ | 18 | 反过度设计 | 涉及页面、原型、截图、前端联调 | 页面和产品文档没有、编程人员未确认的字段不得作为 API 必填;后端需要的字段必须标记为后端默认或后端推导 |
36
+ | 19 | Mock 策略 | 涉及外部依赖/设备/第三方 | mock.md 声明 Mock 方式、假设条件、替代验证 |
37
+ | 20 | 测试执行记录 | 执行了测试 | test-report.md 含环境、命令、结果汇总 |
38
+ | 21 | 真实测试证据 | 声称接口、联调或真实测试完成 | 每个关键接口有 curl/请求体/响应/断言/真实参数来源;tests skipped、未启动应用、未连测试库、缺真实参数、mock-only、外部泛化失败时不得标记通过 |
39
+ | 21.1 | 测试报告证据一致性 | 出现 test-report.md、Maven/Gradle 测试、跨仓测试或源码锚点 | `~/.codex/hooks/superflow-test-report-lint.py --tests <tests.md> <test-report.md>` 通过;同一命令的 `Tests run` 和 `N/N` 不矛盾;`Tests are skipped` 不得写成通过;tests.md 声明 L3/L4/真实入口/第三方/dev 工具时,报告必须有真实命令、环境、响应断言、DB、日志和外部回调/终态证据;源码锚点仍存在或明确标记为旧实现已删除 |
40
+ | 22 | 提示词记录 | 使用 AI 辅助开发 | prompt/ 目录含完整 prompt、采纳情况、修改点 |
41
+ | 23 | **可追溯性矩阵** | **拆分为多批时强制** | traceability-matrix.md 含需求/设计/任务/测试/prompt 映射,无设计漂移、无实现遗漏 |
42
+ | 24 | **Reviewer 清单** | **拆分为多批时强制** | reviewer-checklist.md 含 19 项检查,用于分批评审 |
43
+ | 25 | Red-Green 证据 | Bug 修复或 CR/Px 联调补项 | test-report.md 先记录修复前同一路径失败证据,再记录修复后通过证据;不能只写最终通过 |
44
+ | 26 | **文件接口契约** | **涉及导出/下载/上传时强制** | api.md 含文件接口契约表(Content-Type、Content-Disposition、文件名规则、前端判断方式);Controller 方法直接操作 HttpServletResponse;tests.md 验证响应头和文件体 |
45
+ | 27 | **Excel 导入契约** | **涉及 Excel 导入时强制** | api.md 含模板列头表、failureCount 与 code 映射规则、日期格式兼容说明;模板 DTO 与导入 DTO 列头一致;tests.md 覆盖部分失败和短日期格式 |
46
+ | 28 | **路由一致性** | **涉及新增 Controller mapping 时强制** | api.md 路径与 Controller mapping 双向一致;固定路径与 `{id}` 无冲突或已提示风险;tests.md 含路由映射用例 |
47
+ | 29 | **数据权限决策** | **涉及访问业务数据的接口时强制** | api.md 每个访问业务数据的接口有明确数据权限决策(需要/不需要/不确定);"不确定"项已向用户确认;复用当前仓库已有权限模式;tests.md 覆盖至少两个角色 |
48
+ | 30 | **外部依赖契约** | **涉及 SDK/第三方/RPC/MQ 时强制** | api.md 含外部依赖契约(参数来源、SDK 版本、响应样例);tests.md 含真实请求/响应或阻塞证据 |
49
+ | 31 | **跨仓数据合同** | **多仓共享表、复制 PO/Mapper、MyBatis-Plus BaseMapper、字段删除/迁移时强制** | 已列出表结构真源和全部消费仓;每个消费仓完成实体/Mapper/SQL 与实际库字段对账;不存在列已删除或标注 `@TableField(exist = false)`;查询条件已按最终合同迁移 |
50
+ | 32 | **真实入口验收** | **第三方、外部集成、支付、设备、回调、客户端或跨系统链路时强制** | test-report 区分 Mock/测试端点/真实入口;真实入口包含 payload、响应、trace 日志、DB 证据;mock-only 不得写 Passed |
51
+ | 33 | **三层验收门禁** | **涉及接口、CRUD、Mapper/XML、数据库字段或配置驱动行为时强制** | prompt 明确完成定义;hook 标记 `.sdd-enforced`/`.db-verified` 已启用;交付前执行 `~/.codex/hooks/superflow-verify-integration.sh <test-report.md>` 且通过 |
52
+ | 34 | **测试合同冻结** | **所有实现任务强制** | tests.md 每个用例包含用例ID、层级、前置数据、自动化命令、响应/DB/日志断言、RED预期失败、GREEN预期通过、test-report证据位置;没有可执行命令不得进入实现 |
53
+ | 35 | **接口自动化前置** | **涉及接口、CRUD、Mapper/XML、配置驱动、MQ/任务或跨系统链路时强制** | 每个 L3/L4 用例有完整 Base URL、token/cookie 获取、curl/Postman/Newman/pytest/RestAssured 命令、请求体、响应断言、DB SELECT、日志关键词 |
54
+ | 36 | **字段语义合同** | **涉及 ID/状态/类型/金额/设备/站点/订单/订阅/外部流水/枚举/跨表关联字段时强制** | design.md 包含 `字段 | 来源表/DTO/事件 | 真实语义 | 目标字段 | 目标语义 | 是否可等价 | 证据锚点 | 禁止用法 | 不确定项/owner`;字段语义不确定时阻塞 |
55
+ | 37 | **写入闭环** | **涉及回填/落库/绑定/持久化/快照/同步/状态推进时强制** | design.md 或 traceability-matrix.md 包含 `业务动作 | Java setter/赋值点 | Converter/DTO 映射 | Mapper insert/update | DB column | 后续读取方 | 消费入口 | 验证 SQL | 测试用例`;只证明 setter 不通过 |
56
+ | 38 | **真实入口调用链** | **所有接口/MQ/定时/设备/小程序/第三方/后台操作链路强制** | design.md 包含 `用户/外部动作 | 上游服务/接口 | 本仓入口 | MQ/异步回调 | 关键字段变化 | DB 状态 | 结算/通知/展示消费点 | 真实验证方式`;测试端点不能替代真实入口 |
57
+ | 39 | **禁止 fallback 与猜测实现** | **所有实现任务强制** | sdd-quality-gate.md 或 design.md 明确禁止默认值、兜底反查、替代字段、保留旧值、空值转可用、静默跳过、下游补偿;批准兼容必须有 owner 确认和暴露/移除规则 |
58
+ | 40 | **Agent 执行前自检占位** | **所有实现 prompt 强制** | test-report.md 或 prompt 中预置 `真实入口已定位 | 字段语义合同已核对 | 写入闭环已核对 | 禁止兜底边界已确认 | RED 测试已执行 | 允许修改文件 | 禁止修改文件 | 阻塞项` |
59
+ | 41 | **Superpowers 技术详设(HOW)** | **完整 SDD 实现任务强制** | `docs/superpowers/specs/YYYY-MM-DD-*-technical-design.md` 存在并记录当前 handoff_hash;Superpowers 接管源码级 HOW、TDD/RED 切入点、团队/Reviewer/Tester 分工、worktree/端口计划和执行风险;不得覆盖 OpenSpec/SDD 的需求、API、DB、SQL、字段语义、tests 或验收门禁 |
60
+ | 42 | **字段/状态反向影响面** | **涉及字段值、状态/枚举、在线离线、删除恢复、同步标记、支付退款状态、第三方状态时强制** | Superpowers 技术详设包含 `Field And Status Reverse Impact`,列出 `字段/状态 | 写入点 | 读取/过滤点 | 派生/同步点 | 跨模块消费方 | 消费方测试 | 缺口/阻塞`;必须执行 `rg`/Mapper XML/实体/DTO/SQL/定时/MQ/回调/第三方/兄弟仓反查;只改直接 setter/writer 阻塞 |
61
+ | 43 | **架构师视角的模块职责与调用方向** | **涉及跨仓、跨服务、SDK、MQ、定时、设备、回调、第三方、小程序、网关或适配层时强制** | Superpowers 技术详设包含 `Architecture Boundary And Call Direction`,列出 `链路步骤 | 调用方向 | owner模块 | 既有入口/出口 | 拟新增入口/出口 | 是否允许 | 证据锚点 | 禁止绕路`;必须证明业务入口、出口适配、协议转换、设备网关、MQ 消费者的职责边界没有反转;不能仅以“技术上能调用”为设计依据 |
62
+ | 44 | **上下文防漂移 handoff** | **所有进入实现的任务强制** | `.sdd/handoff/sdd-context.md`、`.json`、`.sha256` 和 `.sdd/state.yaml` 已生成;design.md、sdd-quality-gate.md、prompt、test-report 记录同一 handoff_hash;`superflow-guard.sh <change-dir> docs` 通过 |
63
+ | 45 | **SDD 状态机字段** | **所有进入实现的任务强制** | `.sdd/state.yaml` 包含 workflow、phase、handoff_hash、build_mode、isolation、tdd_mode、review_mode、verify_mode、implementation_prompt、verification_report、archived;`superflow-state.sh status/next/recover` 输出一致 |
64
+ | 46 | **外部枚举绑定确认** | **涉及第三方、SDK、BEM/停车、支付退款、财务展示、来源字段、状态同步或外部字典时强制** | api.md、sdd-quality-gate.md 和 Superpowers 技术详设包含 `外部枚举绑定确认` / `External Enum Binding`,列出 `业务字段 | 本系统真源字段/枚举 | 外部系统字段 | 外部枚举/字典值 | 展示文案/业务语义/财务语义 | 取值来源 | owner/确认时间 | 不确定项/阻塞处理 | 测试证据`;不得用请求成功、值非空或字段存在替代业务语义确认;未确认时必须阻塞 |
64
65
 
65
66
  ### 文档完整性强制检查(新增,全部项目必做)
66
67
 
67
- | # | 检查项 | 标准 |
68
- |---|---|---|
69
- | 26 | **嵌入式变更文档完整性** | 每个 embedded change 目录包含 `.openspec.yaml`、`api.md`、`spec.md`、`design.md`、`tasks.md`、`tests.md`、`review-checklist.md`、`sdd-quality-gate.md`,缺一不可 |
70
- | 27 | **顶层文档同步更新** | 新增/修改 embedded change 后,`tasks.md`、`traceability-matrix.md`、`sdd-quality-gate.md`、`tests.md`、`test-report.md` 已同步更新 |
71
- | 28 | **implementation prompt 文档引用** | prompt 中"必读文档"列表必须包含 `design.md`、`tests.md`、`review-checklist.md`、`sdd-quality-gate.md`,不能只引用 `api.md` 和 `spec.md` |
72
- | 29 | **无"待后续生成"占位符** | 文档中不存在"待后续生成"、"待补充"、"TODO"等未完成的占位标记 |
73
- | 30 | **需求级汇总 SQL 文件** | 如涉及数据库变更,已创建需求级汇总 SQL 文件(如 `sql/{version}.sql`),且 tasks.md / tests.md / prompt 中已明确引用该文件路径 |
74
- | 31 | **tasks.md 标注 SQL 依赖** | 每个涉及数据库的任务已标注依赖的汇总 SQL 文件路径,不需要 SQL 的任务已写明"本任务不新增 SQL,但开始前仍需核查依赖表结构" |
75
- | 32 | **tests.md 包含数据库结构核查用例** | 测试用例中包含 SHOW CREATE TABLE / SHOW COLUMNS 等数据库结构核查用例 |
76
- | 33 | **汇总 SQL 格式规范** | SQL 脚本采用简单直接格式(ALTER TABLE / INSERT),不使用 INFORMATION_SCHEMA 判断、PREPARE/EXECUTE 等过度兼容脚本,按任务编号或功能块追加注释 |
77
- | 34 | **数据库迁移类任务 prompt 强制顺序(阻塞级)** | 涉及表结构重构、旧数据迁移、状态字段变更、分页筛选依赖新表/新状态时:① prompt/pXX-xxx.md 中必须包含"强制执行顺序"章节;② 章节必须覆盖:核对数据库结构 → 执行表结构改造 → 执行旧数据迁移 → 回填 test-report 证据 → 才允许 Java 编码;③ 任一缺失视为文档交付不完整,阻塞进入开发阶段 |
78
- | 35 | **版本总 SQL 收口对账(阻塞级)** | 每个涉及数据库的 P/CR 任务必须提供 `P编号 | 表 | 字段/索引/数据 | 源码引用 | 总SQL位置 | 开发库状态 | 测试库状态 | 处理结论` 对账表;开发库已有但源码依赖且总 SQL 缺失时必须补总 SQL;测试库已有字段不得重复 ADD,类型/注释不一致时生成 MODIFY;无对账表不得标记完成 |
79
- | 41 | **跨仓实体字段对账(阻塞级)** | 多仓共享表、复制实体、MyBatis-Plus `@TableName`/`BaseMapper` 时:① 必须提供 `表 | 真源结构 | 消费仓 | 实体/Mapper/SQL 字段 | 实际库字段 | 处理结论 | 验证证据`;② 任一消费仓映射不存在列或查询旧字段时阻塞;③ 不得通过给测试库补废弃字段绕过 |
80
- | 42 | **真实入口与测试端点分级(阻塞级)** | 涉及外部系统链路时:① test-report 必须分开记录 `Mock 验证`、`测试端点验证`、`真实入口验证`;② 测试 Controller/绕过鉴权端点只能标记局部通过;③ 无真实入口 payload/响应/trace/DB 时,不得写真实链路通过 |
81
- | 44 | **Red-Green 证据占位(阻塞级)** | test-report.md 必须预置 `RED 失败证据`、`GREEN 通过证据`、`接口自动化证据`、`DB 核查证据`、`日志核查证据`、`未自动化/阻塞用例`;每项绑定 tests.md 用例 ID |
82
- | 45 | **Superpowers 技术详设继承(阻塞级)** | implementation prompt 必须包含 `Superpower 技术详设继承`,链接 state 中的 `technical_design`,继承源码级 HOW、TDD/RED 顺序、团队分工和执行边界;prompt 不得让 agent 覆盖 OpenSpec/SDD 的 API、DB、字段语义、tests 或验收门禁 |
83
- | 46 | **handoff hash 继承(阻塞级)** | implementation prompt 必须包含 `上下文防漂移与状态继承`,链接 `.sdd/handoff/sdd-context.md`,记录 handoff_hash,并要求修改 SDD 文档后重跑 `superflow-handoff.sh --refresh` 和 `superflow-guard.sh <change-dir> implement` |
84
- | 47 | **状态机执行决策(阻塞级)** | implementation prompt 必须包含 `状态机执行决策`,记录 build_mode、isolation、tdd_mode、review_mode、implementation_prompt、worktree_ports,并要求进入 verify 前执行 `superflow-state.sh scale` 和 `superflow-guard.sh implement --apply` |
68
+ | # | 检查项 | 标准 |
69
+ | --- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------- | -------------------- | ---------- | ---------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
70
+ | 26 | **嵌入式变更文档完整性** | 每个 embedded change 目录包含 `.openspec.yaml`、`api.md`、`spec.md`、`design.md`、`tasks.md`、`tests.md`、`review-checklist.md`、`sdd-quality-gate.md`,缺一不可 |
71
+ | 27 | **顶层文档同步更新** | 新增/修改 embedded change 后,`tasks.md`、`traceability-matrix.md`、`sdd-quality-gate.md`、`tests.md`、`test-report.md` 已同步更新 |
72
+ | 28 | **implementation prompt 文档引用** | prompt 中"必读文档"列表必须包含 `design.md`、`tests.md`、`review-checklist.md`、`sdd-quality-gate.md`,不能只引用 `api.md` 和 `spec.md` |
73
+ | 29 | **无"待后续生成"占位符** | 文档中不存在"待后续生成"、"待补充"、"TODO"等未完成的占位标记 |
74
+ | 30 | **需求级汇总 SQL 文件** | 如涉及数据库变更,已创建需求级汇总 SQL 文件(如 `sql/{version}.sql`),且 tasks.md / tests.md / prompt 中已明确引用该文件路径 |
75
+ | 31 | **tasks.md 标注 SQL 依赖** | 每个涉及数据库的任务已标注依赖的汇总 SQL 文件路径,不需要 SQL 的任务已写明"本任务不新增 SQL,但开始前仍需核查依赖表结构" |
76
+ | 32 | **tests.md 包含数据库结构核查用例** | 测试用例中包含 SHOW CREATE TABLE / SHOW COLUMNS 等数据库结构核查用例 |
77
+ | 33 | **汇总 SQL 格式规范** | SQL 脚本采用简单直接格式(ALTER TABLE / INSERT),不使用 INFORMATION_SCHEMA 判断、PREPARE/EXECUTE 等过度兼容脚本,按任务编号或功能块追加注释 |
78
+ | 34 | **数据库迁移类任务 prompt 强制顺序(阻塞级)** | 涉及表结构重构、旧数据迁移、状态字段变更、分页筛选依赖新表/新状态时:① prompt/pXX-xxx.md 中必须包含"强制执行顺序"章节;② 章节必须覆盖:核对数据库结构 → 执行表结构改造 → 执行旧数据迁移 → 回填 test-report 证据 → 才允许 Java 编码;③ 任一缺失视为文档交付不完整,阻塞进入开发阶段 |
79
+ | 35 | **版本总 SQL 收口对账(阻塞级)** | 每个涉及数据库的 P/CR 任务必须提供 `P编号 | 表 | 字段/索引/数据 | 源码引用 | 总SQL位置 | 开发库状态 | 测试库状态 | 处理结论` 对账表;开发库已有但源码依赖且总 SQL 缺失时必须补总 SQL;测试库已有字段不得重复 ADD,类型/注释不一致时生成 MODIFY;无对账表不得标记完成 |
80
+ | 41 | **跨仓实体字段对账(阻塞级)** | 多仓共享表、复制实体、MyBatis-Plus `@TableName`/`BaseMapper` 时:① 必须提供 `表 | 真源结构 | 消费仓 | 实体/Mapper/SQL 字段 | 实际库字段 | 处理结论 | 验证证据`;② 任一消费仓映射不存在列或查询旧字段时阻塞;③ 不得通过给测试库补废弃字段绕过 |
81
+ | 42 | **真实入口与测试端点分级(阻塞级)** | 涉及外部系统链路时:① test-report 必须分开记录 `Mock 验证`、`测试端点验证`、`真实入口验证`;② 测试 Controller/绕过鉴权端点只能标记局部通过;③ 无真实入口 payload/响应/trace/DB 时,不得写真实链路通过 |
82
+ | 44 | **Red-Green 证据占位(阻塞级)** | test-report.md 必须预置 `RED 失败证据`、`GREEN 通过证据`、`接口自动化证据`、`DB 核查证据`、`日志核查证据`、`未自动化/阻塞用例`;每项绑定 tests.md 用例 ID |
83
+ | 45 | **Superpowers 技术详设继承(阻塞级)** | implementation prompt 必须包含 `Superpower 技术详设继承`,链接 state 中的 `technical_design`,继承源码级 HOW、TDD/RED 顺序、团队分工和执行边界;prompt 不得让 agent 覆盖 OpenSpec/SDD 的 API、DB、字段语义、tests 或验收门禁 |
84
+ | 46 | **handoff hash 继承(阻塞级)** | implementation prompt 必须包含 `上下文防漂移与状态继承`,链接 `.sdd/handoff/sdd-context.md`,记录 handoff_hash,并要求修改 SDD 文档后重跑 `superflow-handoff.sh --refresh` 和 `superflow-guard.sh <change-dir> implement` |
85
+ | 47 | **状态机执行决策(阻塞级)** | implementation prompt 必须包含 `状态机执行决策`,记录 build_mode、isolation、tdd_mode、review_mode、implementation_prompt、worktree_ports,并要求进入 verify 前执行 `superflow-state.sh scale` 和 `superflow-guard.sh implement --apply` |
85
86
 
86
87
  **结果处理**
87
88
 
@@ -96,41 +97,42 @@
96
97
 
97
98
  ### 批次通用门禁
98
99
 
99
- | # | 门禁 | 执行方式 | 通过标准 | 验证人 |
100
- |---|------|---------|---------|--------|
101
- | 1 | 编译 | `mvn/gradle clean compile` | BUILD SUCCESS | Worker |
102
- | 2 | 启动 | 正确命令启动 + 进程验证 | 新进程、健康检查 UP | Worker |
103
- | 3 | 范围合规 | `git diff --name-only` | 只修改了 prompt 允许范围内的文件 | Worker + Reviewer |
104
- | 4 | 代码评审 | `code-review-java` / reviewer-checklist | 无 HIGH+ 问题,评审清单全部通过 | Reviewer |
105
- | 5 | 接口测试 | curl 调接口 | 本批用例全部断言通过 | Tester |
106
- | 6 | 数据库 | mysql 查询 | 数据状态符合预期 | Tester |
107
- | 7 | 日志 | grep ERROR | 无 ERROR,关键日志出现 | Tester |
108
- | 8 | **SDD 集成验收脚本** | `~/.codex/hooks/superflow-verify-integration.sh <test-report.md>` | 启动、curl、DB、日志、证据等级检查全部通过 | Leader |
109
- | 9 | **批次报告** | 检查报告格式 | 包含全部必填项(完成范围、文件清单、测试执行、不一致项) | Leader |
110
- | 9 | **数据库前置门禁** | 报告中数据库核查章节 | 包含:检查的表/字段/索引、汇总 SQL 文件路径、执行的脚本、执行结果、复查确认 | Worker + Leader |
111
- | 10 | **SQL 文件管理** | 检查 SQL 文件数量 | 本需求下只维护一个汇总 SQL 文件,无独立 SQL 文件 | Leader |
112
- | 11 | **无代码绕过** | 检查业务代码 | 未因字段/默认值/初始化数据缺失而在业务代码中写绕过逻辑 | Reviewer + Leader |
113
- | 12 | **总 SQL 收口** | 检查源码/Mapper、开发库、测试库现状+总 SQL | 源码读写字段均可在最终数据库结构中找到;总 SQL 覆盖本批新增/变更;无测试库重复 ADD | Reviewer + Leader |
114
- | 13 | **跨仓数据合同收口** | 检查全部消费仓实体/Mapper/SQL 与真实库结构 | 无实体映射不存在列;无 Mapper 查询旧字段;字段迁移后的查询条件已同步;无法验证的消费仓明确阻塞 | Reviewer + Leader |
115
- | 14 | **真实入口验收收口** | 检查 test-report 证据等级 | Mock、测试端点、真实入口分级清楚;关键链路至少一条真实入口证据闭环,或明确标记外部阻塞 | Tester + Leader |
116
- | 15 | **RED-GREEN 收口** | 检查 test-report 同一用例的前后证据 | 编码前 RED 失败输出存在且失败原因正确;编码后同一命令 GREEN 通过;测试后补或未观察 RED 一律阻塞 | Worker + Tester + Leader |
117
- | 16 | **接口自动化收口** | 检查每个 L3/L4 用例证据 | 包含真实命令、请求体来源、响应断言、DB SELECT、日志关键词和环境信息;HTTP 200 或 DB-only 不能单独通过 | Tester + Leader |
118
- | 17 | **五项硬门禁收口** | 检查 prompt/test-report/design/tests | 字段语义合同、写入闭环、真实入口调用链、禁止 fallback 与猜测实现、Agent 执行前自检均有证据;任一缺失阻塞 | Reviewer + Leader |
119
- | 18 | **上下文防漂移收口** | 检查 `.sdd/handoff/*`、`.sdd/state.yaml`、prompt、test-report | handoff_hash 一致;`superflow-guard.sh <change-dir> implement` 或 `verify` 通过;换会话/并行窗口后的执行报告证明已重读 handoff 和原始文档 | Leader |
120
- | 19 | **状态机收口** | 检查 `.sdd/state.yaml` 和 `superflow-state.sh recover/next` | verify 前 phase 已由 implement guard 推进;verify 后 verification_report、verify_result、verified_at 正确;archive 前必须等待用户确认 | Leader |
100
+ | # | 门禁 | 执行方式 | 通过标准 | 验证人 |
101
+ | --- | -------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
102
+ | 1 | 编译 | `mvn/gradle clean compile` | BUILD SUCCESS | Worker |
103
+ | 2 | 启动 | 正确命令启动 + 进程验证 | 新进程、健康检查 UP | Worker |
104
+ | 3 | 范围合规 | `git diff --name-only` | 只修改了 prompt 允许范围内的文件 | Worker + Reviewer |
105
+ | 4 | 代码评审 | `code-review-java` / reviewer-checklist | 无 HIGH+ 问题,评审清单全部通过 | Reviewer |
106
+ | 5 | 接口测试 | curl 调接口 | 本批用例全部断言通过 | Tester |
107
+ | 6 | 数据库 | mysql 查询 | 数据状态符合预期 | Tester |
108
+ | 7 | 日志 | grep ERROR | 无 ERROR,关键日志出现 | Tester |
109
+ | 8 | **SDD 集成验收脚本** | `~/.codex/hooks/superflow-verify-integration.sh <test-report.md>` | 启动、curl、DB、日志、证据等级检查全部通过 | Leader |
110
+ | 9 | **批次报告** | 检查报告格式 | 包含全部必填项(完成范围、文件清单、测试执行、不一致项) | Leader |
111
+ | 9 | **数据库前置门禁** | 报告中数据库核查章节 | 包含:检查的表/字段/索引、汇总 SQL 文件路径、执行的脚本、执行结果、复查确认 | Worker + Leader |
112
+ | 10 | **SQL 文件管理** | 检查 SQL 文件数量 | 本需求下只维护一个汇总 SQL 文件,无独立 SQL 文件 | Leader |
113
+ | 11 | **无代码绕过** | 检查业务代码 | 未因字段/默认值/初始化数据缺失而在业务代码中写绕过逻辑 | Reviewer + Leader |
114
+ | 12 | **总 SQL 收口** | 检查源码/Mapper、开发库、测试库现状+总 SQL | 源码读写字段均可在最终数据库结构中找到;总 SQL 覆盖本批新增/变更;无测试库重复 ADD | Reviewer + Leader |
115
+ | 13 | **跨仓数据合同收口** | 检查全部消费仓实体/Mapper/SQL 与真实库结构 | 无实体映射不存在列;无 Mapper 查询旧字段;字段迁移后的查询条件已同步;无法验证的消费仓明确阻塞 | Reviewer + Leader |
116
+ | 14 | **真实入口验收收口** | 检查 test-report 证据等级 | Mock、测试端点、真实入口分级清楚;关键链路至少一条真实入口证据闭环,或明确标记外部阻塞 | Tester + Leader |
117
+ | 15 | **RED-GREEN 收口** | 检查 test-report 同一用例的前后证据 | 编码前 RED 失败输出存在且失败原因正确;编码后同一命令 GREEN 通过;测试后补或未观察 RED 一律阻塞 | Worker + Tester + Leader |
118
+ | 16 | **接口自动化收口** | 检查每个 L3/L4 用例证据 | 包含真实命令、请求体来源、响应断言、DB SELECT、日志关键词和环境信息;HTTP 200 或 DB-only 不能单独通过 | Tester + Leader |
119
+ | 17 | **五项硬门禁收口** | 检查 prompt/test-report/design/tests | 字段语义合同、写入闭环、真实入口调用链、禁止 fallback 与猜测实现、Agent 执行前自检均有证据;任一缺失阻塞 | Reviewer + Leader |
120
+ | 18 | **上下文防漂移收口** | 检查 `.sdd/handoff/*`、`.sdd/state.yaml`、prompt、test-report | handoff_hash 一致;`superflow-guard.sh <change-dir> implement` 或 `verify` 通过;换会话/并行窗口后的执行报告证明已重读 handoff 和原始文档 | Leader |
121
+ | 19 | **状态机收口** | 检查 `.sdd/state.yaml` 和 `superflow-state.sh recover/next` | verify 前 phase 已由 implement guard 推进;verify 后 verification_report、verify_result、verified_at 正确;archive 前必须等待用户确认 | Leader |
121
122
 
122
123
  ### 数据库迁移类任务特有加禁(触发条件:涉及表结构重构、旧数据迁移、状态字段变更、分页筛选依赖新表/新状态)
123
124
 
124
- | # | 门禁 | 执行方式 | 通过标准 | 验证人 |
125
- |---|------|---------|---------|--------|
126
- | D1 | **数据库前置核查** | `SHOW CREATE TABLE` / `DESC` / `SELECT COUNT` | 已核对当前开发环境数据库结构,新表/新字段/旧字段状态与设计一致 | Worker |
127
- | D2 | **表结构改造 SQL** | 执行基线 SQL + 迁移 SQL | 新库基线 SQL 按最终结构整理;开发库/测试库使用单独迁移 SQL 并已执行成功;`SHOW CREATE TABLE` 复查确认 | Worker + Leader |
128
- | D3 | **旧数据迁移 SQL** | 执行迁移脚本 + 数量核对 | 迁移前 COUNT、迁移后 COUNT 一致;迁移失败已停止并报告,未绕过 | Worker + Leader |
129
- | D4 | **迁移证据已回填 test-report** | 检查 test-report.md | 包含:SQL 文件路径、数据库连接来源、执行时间、执行结果、`SHOW CREATE TABLE` 摘要、迁移前后数量对比、关键联查结果 | Leader |
130
- | D5 | **Java 编码是否允许开始** | 综合判定 D1~D4 | D1~D4 全部通过,标记为"允许开始";任一未通过,标记为"禁止开始",必须阻塞 | Leader |
131
- | D6 | **版本总 SQL 收口** | 对比源码/Mapper、开发库、测试库现状+总 SQL | 每个独立任务 SQL 已合并到版本总 SQL;临时/独立 SQL 不作为交付依据;测试库已有字段不重复 ADD;字段类型/注释差异已有 MODIFY 或明确不采纳说明 | Leader |
125
+ | # | 门禁 | 执行方式 | 通过标准 | 验证人 |
126
+ | --- | ------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
127
+ | D1 | **数据库前置核查** | `SHOW CREATE TABLE` / `DESC` / `SELECT COUNT` | 已核对当前开发环境数据库结构,新表/新字段/旧字段状态与设计一致 | Worker |
128
+ | D2 | **表结构改造 SQL** | 执行基线 SQL + 迁移 SQL | 新库基线 SQL 按最终结构整理;开发库/测试库使用单独迁移 SQL 并已执行成功;`SHOW CREATE TABLE` 复查确认 | Worker + Leader |
129
+ | D3 | **旧数据迁移 SQL** | 执行迁移脚本 + 数量核对 | 迁移前 COUNT、迁移后 COUNT 一致;迁移失败已停止并报告,未绕过 | Worker + Leader |
130
+ | D4 | **迁移证据已回填 test-report** | 检查 test-report.md | 包含:SQL 文件路径、数据库连接来源、执行时间、执行结果、`SHOW CREATE TABLE` 摘要、迁移前后数量对比、关键联查结果 | Leader |
131
+ | D5 | **Java 编码是否允许开始** | 综合判定 D1~D4 | D1~D4 全部通过,标记为"允许开始";任一未通过,标记为"禁止开始",必须阻塞 | Leader |
132
+ | D6 | **版本总 SQL 收口** | 对比源码/Mapper、开发库、测试库现状+总 SQL | 每个独立任务 SQL 已合并到版本总 SQL;临时/独立 SQL 不作为交付依据;测试库已有字段不重复 ADD;字段类型/注释差异已有 MODIFY 或明确不采纳说明 | Leader |
132
133
 
133
134
  **数据库迁移类任务阻塞规则:**
135
+
134
136
  - 如果 D1(数据库前置核查)未执行或发现结构不一致 → **阻塞**,必须先完成核查
135
137
  - 如果 D2(表结构改造 SQL)执行失败 → **阻塞**,修复 SQL 后重新执行,禁止先写 Java 代码
136
138
  - 如果 D3(旧数据迁移 SQL)执行失败或数量核对不一致 → **阻塞**,必须解决迁移问题,禁止用业务代码绕过
@@ -140,10 +142,10 @@
140
142
 
141
143
  ### P0 基线特有加禁
142
144
 
143
- | # | 门禁 | 执行方式 | 通过标准 |
144
- |---|------|---------|---------|
145
- | 9 | 工作树干净 | `git status` | 无未提交改动,无脏文件 |
146
- | 10 | 字段一致性 | 对比 SQL/实体/Mapper/DTO | 全部一致,或已修复/上报 |
145
+ | # | 门禁 | 执行方式 | 通过标准 |
146
+ | --- | ---------- | ------------------------ | ----------------------- |
147
+ | 9 | 工作树干净 | `git status` | 无未提交改动,无脏文件 |
148
+ | 10 | 字段一致性 | 对比 SQL/实体/Mapper/DTO | 全部一致,或已修复/上报 |
147
149
 
148
150
  ### 结果处理
149
151
 
@@ -7,7 +7,7 @@ semantics, tests, and acceptance gates.
7
7
  **Output path**:
8
8
  `docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md`
9
9
 
10
- ```markdown
10
+ ````markdown
11
11
  ---
12
12
  change: <change-id>
13
13
  status: draft|ready|final
@@ -31,9 +31,9 @@ canonical_sources:
31
31
 
32
32
  ## Source-Level HOW
33
33
 
34
- | Requirement/Scenario | Code anchor | Current behavior | Target HOW | Files/methods | Risk |
35
- |---|---|---|---|---|---|
36
- | <R1/S1> | `<file>:<line>` | <observed fact> | <implementation approach> | <files> | <risk> |
34
+ | Requirement/Scenario | Code anchor | Current behavior | Target HOW | Files/methods | Risk |
35
+ | -------------------- | --------------- | ---------------- | ------------------------- | ------------- | ------ |
36
+ | <R1/S1> | `<file>:<line>` | <observed fact> | <implementation approach> | <files> | <risk> |
37
37
 
38
38
  ## Architecture Boundary And Call Direction
39
39
 
@@ -41,9 +41,9 @@ Use this whenever the change crosses repositories, services, SDKs, MQ,
41
41
  schedulers, device protocols, callbacks, third-party platforms, mini-programs,
42
42
  gateway layers, or adapter modules.
43
43
 
44
- | Flow step | Direction | Owner module | Existing entry/exit | Proposed entry/exit | Allowed? | Evidence anchor | Forbidden shortcut |
45
- |---|---|---|---|---|---|---|---|
46
- | `<user/system action>` | `<upstream -> downstream>` | `<module>` | `<existing API/MQ/adapter>` | `<target API/MQ/adapter>` | `yes/no/blocker` | `<file:line/log/doc>` | `<what must not be routed through>` |
44
+ | Flow step | Direction | Owner module | Existing entry/exit | Proposed entry/exit | Allowed? | Evidence anchor | Forbidden shortcut |
45
+ | ---------------------- | -------------------------- | ------------ | --------------------------- | ------------------------- | ---------------- | --------------------- | ----------------------------------- |
46
+ | `<user/system action>` | `<upstream -> downstream>` | `<module>` | `<existing API/MQ/adapter>` | `<target API/MQ/adapter>` | `yes/no/blocker` | `<file:line/log/doc>` | `<what must not be routed through>` |
47
47
 
48
48
  Required boundary checks:
49
49
 
@@ -51,6 +51,7 @@ Required boundary checks:
51
51
  rg -n "<module>|<interface>|<topic>|<protocol>|<callback>" .
52
52
  rg -n "<existing entry>|<existing exit>|<adapter>|<client>" <repo-a> <repo-b>
53
53
  ```
54
+ ````
54
55
 
55
56
  The technical design must prove service ownership and call direction before
56
57
  choosing an implementation path. Do not turn an outbound adapter, protocol
@@ -65,9 +66,9 @@ Use this whenever changing field values, enum/status values, derived fields,
65
66
  sync flags, online/offline state, deletion/restoration state, payment/refund
66
67
  state, third-party status, or any value that other code may read.
67
68
 
68
- | Field/status | Write/update points | Read/filter points | Derived/sync points | Cross-module consumers | Tests covering consumers | Missing coverage/blocker |
69
- |---|---|---|---|---|---|---|
70
- | `running_status` | `<repository/service>` | `<query/filter/mapper>` | `<heartbeat/realtime/sync>` | `<module/repo>` | `<case IDs>` | `<none/blocker>` |
69
+ | Field/status | Write/update points | Read/filter points | Derived/sync points | Cross-module consumers | Tests covering consumers | Missing coverage/blocker |
70
+ | ---------------- | ---------------------- | ----------------------- | --------------------------- | ---------------------- | ------------------------ | ------------------------ |
71
+ | `running_status` | `<repository/service>` | `<query/filter/mapper>` | `<heartbeat/realtime/sync>` | `<module/repo>` | `<case IDs>` | `<none/blocker>` |
71
72
 
72
73
  Required reverse-search commands:
73
74
 
@@ -83,6 +84,29 @@ third-party adapters, and sibling repos when the table or DTO is shared.
83
84
  The technical design must say which references are intentionally unchanged and
84
85
  why. A change is not ready when only the direct setter/writer is designed.
85
86
 
87
+ ## External Enum Binding
88
+
89
+ Use this whenever a change sends values to, receives values from, or maps values
90
+ for third-party platforms, SDKs, BEM/parking systems, payment/refund systems,
91
+ financial display fields, source/origin fields, status synchronization, or any
92
+ external dictionary/enum.
93
+
94
+ | Business field | Local source field/enum | External system field | External enum/dictionary value | Display/business/financial meaning | Source evidence | Owner/confirmation time | Unresolved handling | Test evidence |
95
+ | -------------- | -------------------------- | --------------------- | ------------------------------ | -------------------------------------------------- | ---------------------------------------- | ----------------------- | ------------------- | -------------------- |
96
+ | `payMode` | `<table.field / DTO enum>` | `<BEM field>` | `<0/1/4/5/...>` | `<cash/wechat/alipay/unknown as displayed by BEM>` | `<doc/log/API sample/user confirmation>` | `<owner + time>` | `<none/blocker>` | `<test-report case>` |
97
+
98
+ Required binding checks:
99
+
100
+ ```bash
101
+ rg -n "<external field>|<enum value>|<display text>|<SDK request field>" .
102
+ rg -n "<local pay/status/source field>|<converter>|<client request>" src test
103
+ ```
104
+
105
+ External enum binding is blocked until the business meaning is confirmed. A
106
+ successful request, non-null value, or "field exists" proof is not enough. Do
107
+ not invent numeric enum values, source/origin values, financial display
108
+ semantics, fallback values, or compatibility mappings without owner approval.
109
+
86
110
  ## Execution Architecture
87
111
 
88
112
  - Worker boundaries:
@@ -93,21 +117,22 @@ why. A change is not ready when only the direct setter/writer is designed.
93
117
 
94
118
  ## TDD And RED Entry Points
95
119
 
96
- | Case ID | Failing command first | Expected RED failure | GREEN command | Evidence target |
97
- |---|---|---|---|---|
98
- | T1 | `<command>` | <failure> | `<command>` | `test-report.md#...` |
120
+ | Case ID | Failing command first | Expected RED failure | GREEN command | Evidence target |
121
+ | ------- | --------------------- | -------------------- | ------------- | -------------------- |
122
+ | T1 | `<command>` | <failure> | `<command>` | `test-report.md#...` |
99
123
 
100
124
  ## Implementation Plan Shape
101
125
 
102
- | Batch | Scope | Dependencies | Allowed files | Forbidden files | Done evidence |
103
- |---|---|---|---|---|---|
104
- | P0 | <baseline> | none | <paths> | <paths> | <evidence> |
126
+ | Batch | Scope | Dependencies | Allowed files | Forbidden files | Done evidence |
127
+ | ----- | ---------- | ------------ | ------------- | --------------- | ------------- |
128
+ | P0 | <baseline> | none | <paths> | <paths> | <evidence> |
105
129
 
106
130
  ## Drift And Blockers
107
131
 
108
- | Topic | Status | Required action |
109
- |---|---|---|
110
- | <unclear source fact> | blocked|partial|clear | <action> |
132
+ | Topic | Status | Required action |
133
+ | --------------------- | ------- | --------------- | ----- | -------- |
134
+ | <unclear source fact> | blocked | partial | clear | <action> |
135
+
111
136
  ```
112
137
 
113
138
  ## Rules
@@ -123,3 +148,4 @@ why. A change is not ready when only the direct setter/writer is designed.
123
148
  acceptance criteria.
124
149
  - Keep unresolved source facts as blockers. Do not convert them to guesses.
125
150
  - Record the same `handoff_hash` as `.sdd/handoff/sdd-context.sha256`.
151
+ ```
@@ -248,6 +248,17 @@ change_has_field_status_risk() {
248
248
  "$CHANGE_DIR"/*.md "$CHANGE_DIR"/**/*.md 2>/dev/null
249
249
  }
250
250
 
251
+ change_has_external_enum_risk() {
252
+ grep -RIEiq \
253
+ 'BEM|payOrigin|payMode|支付来源|支付方式|财务口径|第三方枚举|第三方字段|third[- ]party enum|source system|SDK.*枚举|枚举.*SDK' \
254
+ "$CHANGE_DIR/proposal.md" \
255
+ "$CHANGE_DIR/api.md" \
256
+ "$CHANGE_DIR/design.md" \
257
+ "$CHANGE_DIR/tests.md" \
258
+ "$CHANGE_DIR/spec.md" \
259
+ "$CHANGE_DIR"/specs/*/spec.md 2>/dev/null
260
+ }
261
+
251
262
  change_has_architecture_boundary_risk() {
252
263
  grep -RIEiq \
253
264
  '跨仓|跨服务|sibling|SDK|MQ|topic|consumer|scheduler|定时|device|设备|callback|回调|third[- ]party|第三方|mini[- ]program|小程序|gateway|网关|adapter|适配|protocol|协议|interconnect|互联互通|调用链|入口|出口' \
@@ -281,6 +292,17 @@ require_prompt_set() {
281
292
  fi
282
293
  }
283
294
 
295
+ require_external_enum_contract() {
296
+ local path="$1"
297
+ local label="$2"
298
+ require_grep 'External Enum Binding|外部枚举绑定|第三方字段语义绑定|外部字段.*外部枚举|外部枚举.*展示文案|owner.*确认' "$path" "$label"
299
+ require_grep '外部字段|外部系统字段|External field|target field' "$path" "$label external field column"
300
+ require_grep '外部枚举|外部字典|External enum|target enum' "$path" "$label external enum column"
301
+ require_grep '展示文案|业务语义|财务语义|display|business meaning' "$path" "$label display/business meaning column"
302
+ require_grep 'owner|确认|confirmed|approval' "$path" "$label owner confirmation column"
303
+ require_grep '不确定|阻塞|blocker|unknown|待确认' "$path" "$label unresolved/blocker column"
304
+ }
305
+
284
306
  transition_event=""
285
307
 
286
308
  if [[ -x "$VALIDATE" && -f "$CHANGE_DIR/.sdd/state.yaml" ]]; then
@@ -310,6 +332,10 @@ case "$PHASE" in
310
332
  require_grep 'RED|红绿|GREEN' tests.md "RED/GREEN test contract"
311
333
  require_grep 'curl|Postman|Newman|pytest|RestAssured|自动化命令' tests.md "interface automation command"
312
334
  require_grep 'handoff_hash|sdd-context|上下文包|防漂移' sdd-quality-gate.md "handoff/context-drift gate"
335
+ if change_has_external_enum_risk; then
336
+ require_external_enum_contract api.md "external enum binding contract"
337
+ require_external_enum_contract sdd-quality-gate.md "external enum binding quality gate"
338
+ fi
313
339
  require_markdown_links_valid
314
340
  transition_event="docs-complete"
315
341
  ;;
@@ -342,6 +368,9 @@ case "$PHASE" in
342
368
  if change_has_field_status_risk; then
343
369
  require_grep 'Field And Status Reverse Impact|字段/状态反向影响面|写入点.*读取|读取/过滤点|派生/同步点' "$technical_design_rel" "field/status reverse impact matrix"
344
370
  fi
371
+ if change_has_external_enum_risk; then
372
+ require_external_enum_contract "$technical_design_rel" "external enum binding matrix"
373
+ fi
345
374
  fi
346
375
  fi
347
376
  require_grep 'Superpowers Technical Design Handoff|Superpower 技术详设|technical_design|源码级 HOW' design.md "Superpowers technical design handoff"
@@ -367,6 +396,9 @@ case "$PHASE" in
367
396
  if change_has_field_status_risk; then
368
397
  require_grep '字段/状态反向影响面|Field And Status Reverse Impact|读取/过滤点|派生/同步点' "$prompt_rel" "prompt field/status reverse impact inheritance"
369
398
  fi
399
+ if change_has_external_enum_risk; then
400
+ require_external_enum_contract "$prompt_rel" "prompt external enum binding inheritance"
401
+ fi
370
402
  fi
371
403
  require_grep '上下文防漂移|handoff_hash|sdd-context' "$prompt_rel" "prompt context drift inheritance"
372
404
  fi
@@ -392,6 +424,9 @@ case "$PHASE" in
392
424
  require_grep '接口自动化|curl|Postman|Newman|pytest|RestAssured' test-report.md "interface automation evidence"
393
425
  require_grep 'DB|数据库|SELECT|SHOW CREATE' test-report.md "DB evidence"
394
426
  require_grep 'superflow-verify-integration|superflow-delivery-check|superflow-test-report-lint' test-report.md "SuperBridge Flow hook/script evidence"
427
+ if change_has_external_enum_risk; then
428
+ require_grep 'External Enum Binding|外部枚举绑定|第三方字段语义绑定|外部展示|展示文案|业务语义|财务语义|BEM|真实入口' test-report.md "external enum binding runtime evidence"
429
+ fi
395
430
  require_test_report_lint
396
431
  require_markdown_links_valid
397
432
  if [[ "$(state_get verification_report)" == "" || "$(state_get verification_report)" == "null" ]]; then
@@ -1,6 +1,28 @@
1
- import { checkSkillDeployment } from '../core/skill-check.js';
2
- const SKILL_NAME = 'superflow-design';
3
- export async function designCommand(_change, options = {}) {
1
+ import { execFileSync } from "node:child_process";
2
+ import { existsSync } from "node:fs";
3
+ import path from "node:path";
4
+ import { fileURLToPath } from "node:url";
5
+ import { checkSkillDeployment, } from "../core/skill-check.js";
6
+ const SKILL_NAME = "superflow-design";
7
+ const __filename = fileURLToPath(import.meta.url);
8
+ const __dirname = path.dirname(__filename);
9
+ const GUARD = path.resolve(__dirname, "..", "..", "assets", "skills", "superflow-pipeline", "scripts", "superflow-guard.sh");
10
+ export async function designCommand(change, options = {}) {
11
+ if (change) {
12
+ runDesignGuard(resolveChangeDir(change));
13
+ }
4
14
  checkSkillDeployment(SKILL_NAME, options);
5
15
  }
16
+ function resolveChangeDir(change) {
17
+ const direct = path.resolve(change);
18
+ if (existsSync(direct))
19
+ return direct;
20
+ const openspecChange = path.resolve("openspec", "changes", change);
21
+ if (existsSync(openspecChange))
22
+ return openspecChange;
23
+ return direct;
24
+ }
25
+ function runDesignGuard(changeDir) {
26
+ execFileSync("bash", [GUARD, changeDir, "design"], { stdio: "inherit" });
27
+ }
6
28
  //# sourceMappingURL=design.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"design.js","sourceRoot":"","sources":["../../src/commands/design.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAA0B,MAAM,wBAAwB,CAAC;AAEtF,MAAM,UAAU,GAAG,kBAAkB,CAAC;AAEtC,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAgB,EAChB,UAA6B,EAAE;IAE/B,oBAAoB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC"}
1
+ {"version":3,"file":"design.js","sourceRoot":"","sources":["../../src/commands/design.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EACL,oBAAoB,GAErB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,UAAU,GAAG,kBAAkB,CAAC;AACtC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CACxB,SAAS,EACT,IAAI,EACJ,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,oBAAoB,EACpB,SAAS,EACT,oBAAoB,CACrB,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAe,EACf,UAA6B,EAAE;IAE/B,IAAI,MAAM,EAAE,CAAC;QACX,cAAc,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3C,CAAC;IACD,oBAAoB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAc;IACtC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IAEtC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IACnE,IAAI,UAAU,CAAC,cAAc,CAAC;QAAE,OAAO,cAAc,CAAC;IAEtD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,cAAc,CAAC,SAAiB;IACvC,YAAY,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;AAC3E,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chenmk/superflow",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "SuperBridge Flow workflow CLI for Claude Code, Codex, and OpenCode",
5
5
  "license": "MIT",
6
6
  "type": "module",