@chenmk/superflow 0.1.0

package/assets/skills/superflow-pipeline/references/superpower-technical-design-template.md

@@ -0,0 +1,125 @@
+# Superpowers Technical Design Template
+
+Use this template for the Superpowers-owned source-level HOW document.
+OpenSpec/SDD documents remain canonical for WHAT, API, database, field
+semantics, tests, and acceptance gates.
+
+**Output path**:
+`docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md`
+
+```markdown
+---
+change: <change-id>
+status: draft|ready|final
+handoff_hash: <sha256>
+canonical_sources:
+  - ../../openspec/changes/<change-id>/proposal.md
+  - ../../openspec/changes/<change-id>/api.md
+  - ../../openspec/changes/<change-id>/design.md
+  - ../../openspec/changes/<change-id>/tests.md
+---
+
+# Superpowers Technical Design: <change title>
+
+## Boundary
+
+- This document owns source-level HOW only.
+- OpenSpec/SDD remains canonical for requirements, API, DB, field semantics,
+  SQL, tests, and acceptance gates.
+- If this document conflicts with canonical sources, stop and return to
+  `$superflow-docs`; do not let implementation prompts carry the conflict forward.
+
+## Source-Level HOW
+
+| Requirement/Scenario | Code anchor | Current behavior | Target HOW | Files/methods | Risk |
+|---|---|---|---|---|---|
+| <R1/S1> | `<file>:<line>` | <observed fact> | <implementation approach> | <files> | <risk> |
+
+## Architecture Boundary And Call Direction
+
+Use this whenever the change crosses repositories, services, SDKs, MQ,
+schedulers, device protocols, callbacks, third-party platforms, mini-programs,
+gateway layers, or adapter modules.
+
+| Flow step | Direction | Owner module | Existing entry/exit | Proposed entry/exit | Allowed? | Evidence anchor | Forbidden shortcut |
+|---|---|---|---|---|---|---|---|
+| `<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>` |
+
+Required boundary checks:
+
+```bash
+rg -n "<module>|<interface>|<topic>|<protocol>|<callback>" .
+rg -n "<existing entry>|<existing exit>|<adapter>|<client>" <repo-a> <repo-b>
+```
+
+The technical design must prove service ownership and call direction before
+choosing an implementation path. Do not turn an outbound adapter, protocol
+translator, notification consumer, or device gateway into a business-entry
+orchestrator unless the OpenSpec/SDD contract explicitly says that module owns
+the new entry point and records the owner approval. If the correct owner is
+unclear, mark the design blocked.
+
+## Field And Status Reverse Impact
+
+Use this whenever changing field values, enum/status values, derived fields,
+sync flags, online/offline state, deletion/restoration state, payment/refund
+state, third-party status, or any value that other code may read.
+
+| Field/status | Write/update points | Read/filter points | Derived/sync points | Cross-module consumers | Tests covering consumers | Missing coverage/blocker |
+|---|---|---|---|---|---|---|
+| `running_status` | `<repository/service>` | `<query/filter/mapper>` | `<heartbeat/realtime/sync>` | `<module/repo>` | `<case IDs>` | `<none/blocker>` |
+
+Required reverse-search commands:
+
+```bash
+rg -n "<field>|<enum>|<status>|<column>" .
+rg -n "<setter>|<getter>|<mapper column>|<dto field>" src test
+```
+
+If the value is database-backed, also inspect Mapper XML, entity annotations,
+DTO/VO fields, SQL migrations, scheduled jobs, MQ/event consumers, callbacks,
+third-party adapters, and sibling repos when the table or DTO is shared.
+
+The technical design must say which references are intentionally unchanged and
+why. A change is not ready when only the direct setter/writer is designed.
+
+## Execution Architecture
+
+- Worker boundaries:
+- Tester boundaries:
+- Reviewer boundaries:
+- Leader coordination:
+- Worktree/port plan:
+
+## TDD And RED Entry Points
+
+| Case ID | Failing command first | Expected RED failure | GREEN command | Evidence target |
+|---|---|---|---|---|
+| T1 | `<command>` | <failure> | `<command>` | `test-report.md#...` |
+
+## Implementation Plan Shape
+
+| Batch | Scope | Dependencies | Allowed files | Forbidden files | Done evidence |
+|---|---|---|---|---|---|
+| P0 | <baseline> | none | <paths> | <paths> | <evidence> |
+
+## Drift And Blockers
+
+| Topic | Status | Required action |
+|---|---|---|
+| <unclear source fact> | blocked|partial|clear | <action> |
+```
+
+## Rules
+
+- Use real source anchors, Mapper/XML anchors, table names, commands, and
+  prompt boundaries. Vague module names are not enough.
+- For cross-system changes, prove owner module, call direction, existing
+  entry/exit points, and forbidden shortcuts before implementation. A design
+  that only shows "can call through this module" is not ready.
+- For field/status changes, prove reverse impact before coding: writers,
+  readers, filters, derived sync paths, external consumers, and tests.
+- Do not invent API fields, DB columns, status semantics, fallback behavior, or
+  acceptance criteria.
+- Keep unresolved source facts as blockers. Do not convert them to guesses.
+- Record the same `handoff_hash` as `.sdd/handoff/sdd-context.sha256`.

package/assets/skills/superflow-pipeline/references/test-execution-template.md

@@ -0,0 +1,220 @@
+# 测试执行与结果记录模板
+
+记录测试的执行环境、执行过程和结果，作为交付物的一部分。
+
+## 文档结构
+
+```markdown
+# 测试执行报告
+
+## 1. 执行环境
+
+| 项目 | 信息 |
+|------|------|
+| 执行时间 | 2026-05-09 14:00 - 15:30 |
+| 执行人 | ____ |
+| 操作系统 | Linux / macOS / Windows |
+| JDK 版本 | 17 |
+| 数据库 | MySQL 8.0 / H2 |
+| Spring Profile | dev / test / cmk |
+| 应用端口 | 9527 |
+| 上下文路径 | / |
+
+## 2. 测试范围
+
+| 层次 | 类型 | 用例数 | 自动化 |
+|------|------|--------|--------|
+| L1 | 单元测试 | __ | [自动化] |
+| L2 | 集成测试 | __ | [自动化] |
+| L3 | 接口测试 | __ | [自动化 / 需手工] |
+| L4 | 验收测试 | __ | [需手工] |
+
+## 3. 执行方式
+
+### 3.1 自动化测试执行命令
+
+```bash
+# 全量单元测试 + 集成测试
+mvn clean test
+
+# 仅接口测试（需应用已启动）
+mvn test -Dtest=*IntegrationTest
+
+# 单测试类
+mvn test -Dtest=UserServiceTest
+```
+
+### 3.2 手工测试执行步骤
+
+1. 启动应用：`mvn spring-boot:run -Dspring-boot.run.profiles=dev`
+2. 确认健康检查：`curl http://localhost:9527/actuator/health`
+3. 按 tests.md 逐个执行 curl 命令
+4. 验证数据库状态
+5. 检查日志无 ERROR
+
+## 4. 测试结果汇总
+
+| 测试项 | 状态 | 通过 | 失败 | 跳过 | 备注 |
+|--------|------|------|------|------|------|
+| 单元测试 | ✅ / ❌ | __ | __ | __ | |
+| 集成测试 | ✅ / ❌ | __ | __ | __ | |
+| 接口测试 | ✅ / ❌ | __ | __ | __ | |
+| 回归测试 | ✅ / ❌ | __ | __ | __ | |
+
+**总体结果**: [全部通过 / 部分通过 / 未通过]
+
+## 4.1 真实测试数据与证据
+
+| 用例 ID | 真实参数 | 参数来源 | 自动化命令 | 证据等级 | 执行证据 | 结论 |
+|---------|----------|----------|------------|----------|----------|------|
+| TC-001 | parkCode=____ | 前端请求 / 用户提供 / DB查询 / Mock | curl/Newman/pytest/RestAssured | Mock only / 测试端点 / 真实入口 | 响应 + DB + 日志 | Passed / Blocked / Partial |
+
+缺少真实参数、token、站点/运营商归属、外部服务配置或设备环境时，不得填写
+`Passed`，必须标记为 `Blocked` 或 `Partial`。
+
+涉及第三方、外部集成、支付、设备、回调、客户端或跨系统链路时，测试
+Controller、mock endpoint、绕过鉴权端点只能填写 `Mock only` 或 `测试端点`。
+只有真实外部入口的 payload、响应、trace 日志、DB 证据闭环时，才能填写
+`Passed`。
+
+## 4.2 Red-Green 证据
+
+新功能、Bug 修复、CR/Px 联调补项都必须记录。RED 必须发生在生产代码修改前，
+且失败原因必须是预期业务断言，不是环境错误、编译错误、token 缺失或测试代码错误。
+
+| 用例 ID | RED 命令 | RED 失败摘要 | RED 判定 | GREEN 命令 | GREEN 通过摘要 |
+|---------|----------|---------------|----------|------------|----------------|
+| TC-001 | curl/test 命令 | 预期业务断言失败 | 正确失败/环境失败/阻塞 | 同一命令 | 响应/DB/日志均通过 |
+
+## 4.3 接口自动化证据
+
+涉及接口、CRUD、Mapper/XML、数据库字段、配置驱动、MQ、定时任务、设备、支付、
+退款、小程序或第三方链路时必须填写：
+
+| 用例 ID | Base URL | Token/Cookie 获取 | 请求命令 | 请求数据来源 | 响应断言 | DB SELECT | 日志关键词 | 结论 |
+|---------|----------|-------------------|----------|--------------|----------|-----------|------------|------|
+| TC-001 | http://localhost:____ | /captcha/image + /login | curl ... | tests.md / DB / 用户提供 | code/data/业务字段 | SELECT ... | traceId/业务日志 | Passed/Blocked/Partial |
+
+HTTP 200、字段非空、mock-only、DB-only、`BUILD SUCCESS`、`Tests are skipped`
+都不能单独作为接口通过证据。
+
+## 5. 详细结果
+
+### 5.1 通过的测试
+
+| 用例 ID | 用例名称 | 执行时间 | 验证方式 |
+|---------|----------|----------|----------|
+| TC-001 | 用户注册成功 | 2s | 接口返回 + 数据库查询 |
+
+### 5.2 失败的测试
+
+| 用例 ID | 用例名称 | 失败原因 | 处理措施 | 状态 |
+|---------|----------|----------|----------|------|
+| TC-005 | 并发下单 | 竞态条件导致超卖 | 增加分布式锁 | 已修复 ✅ |
+
+### 5.3 阻塞的测试
+
+| 用例 ID | 用例名称 | 阻塞原因 | 预计解决 |
+|---------|----------|----------|----------|
+| TC-010 | 设备回调 | 无真实设备 | Mock 验证替代 |
+
+## 6. 问题与风险
+
+| 问题 | 影响 | 应对方案 |
+|------|------|----------|
+| ____ | ____ | ____ |
+
+## 7. 数据库结构核查
+
+| 表名 | 核查命令 | 预期结构 | 实际结构 | 结论 |
+|------|----------|----------|----------|------|
+| {table_name} | `SHOW CREATE TABLE {table_name}` | {字段/索引/默认值} | {实际输出摘要} | 一致/不一致 |
+| {table_name} | `SELECT COUNT(*) FROM {table_name} WHERE {condition}` | N 条 | 实际 M 条 | 一致/不一致 |
+
+## 8. 汇总 SQL 执行记录
+
+| SQL 文件路径 | 执行的脚本（行号范围或注释标记） | 执行结果 | 复查确认 |
+|--------------|--------------------------------|----------|----------|
+| `openspec/changes/{change-id}/sql/{文件名}` | 第 XX-XX 行（如 "-- P16 业务字段补齐"） | 成功/失败 | SHOW CREATE TABLE 确认 |
+
+## 8.1 跨仓数据合同对账
+
+多仓共享表、复制 PO/Entity/Mapper、MyBatis-Plus BaseMapper 或字段迁移时必须填写：
+
+| 表 | 真源结构 | 消费仓 | 实体/Mapper/SQL 字段 | 实际库字段 | 处理结论 | 验证证据 |
+|----|----------|--------|----------------------|------------|----------|----------|
+| c_xxx | 版本总 SQL + SHOW CREATE TABLE | service-a | field_a, field_b | 一致/缺失 | 通过/阻塞/已修复 | 命令、文件、行号 |
+
+如果任一消费仓映射或查询不存在列，结论必须是 `阻塞`，不得通过给测试库补废弃字段绕过。
+
+## 9. 结论
+
+[是否达到交付标准，是否可以进入下一阶段]
+```
+
+## 任务完成 Checklist（全部满足才能标记完成）
+
+以下 checklist 用于判定一个实现任务是否真正完成。每完成一项勾选一项，**全部勾选后才能标记任务完成**。
+
+### 开发阶段（Worker 执行）
+- [ ] 已从 tests.md 提取本批次用例 ID、自动化命令和断言
+- [ ] 已在生产代码修改前执行 RED 命令
+- [ ] RED 失败原因是预期业务断言，非环境/编译/token/测试代码错误
+- [ ] RED 失败证据已回填 test-report
+- [ ] 代码已修改（git diff 确认修改了正确的文件）
+- [ ] 代码自审通过（无 CRITICAL/HIGH 问题，检查空指针/异常/事务/日志）
+- [ ] 编译通过（`mvn clean compile -DskipTests` BUILD SUCCESS）
+- [ ] 已执行同一命令确认 GREEN，并回填通过证据
+- [ ] 旧进程已停止（`pkill` + 端口确认无占用）
+- [ ] 应用已重新启动（`mvn spring-boot:run` 或 `./gradlew bootRun`）
+- [ ] 进程已验证（PID 存在、启动时间接近当前时间、端口绑定正确）
+- [ ] 健康检查通过（`curl /actuator/health` 返回 UP）
+- [ ] 日志确认是本次启动（时间戳匹配当前时间）
+
+### 接口测试阶段（Worker 逐项执行）
+- [ ] Token 已获取（完整的 `/captcha/image` + `/login` 流程，token 非空）
+- [ ] L3 接口用例已逐项执行（来自 tests.md 的每个 [自动化] 用例）
+- [ ] 每个用例的 curl 命令已记录
+- [ ] 每个用例的请求数据来源已记录
+- [ ] 每个用例的响应已记录
+- [ ] 每个用例的响应断言、DB 断言、日志断言已验证（通过/失败）
+
+### 数据库验证阶段（Worker 执行）
+- [ ] 已执行 `SHOW CREATE TABLE` 确认表结构
+- [ ] 已执行 `SELECT` 查询确认数据状态与预期一致
+- [ ] 数据库验证结果已记录
+
+### 日志检查阶段（Worker 执行）
+- [ ] 已执行 `grep ERROR` 检查应用日志
+- [ ] 无 ERROR（除已知无关错误外）
+- [ ] 关键日志已出现（如设计要求的特定标记）
+
+### 报告阶段（Worker 执行）
+- [ ] `embedded-changes/pXX-xxx/test-report.md` 已更新
+- [ ] 包含：RED/GREEN 命令和输出、curl 命令、响应摘要、数据库查询结果、日志检查结果
+- [ ] 包含：`Tests run:` 真实输出
+- [ ] 包含：进程验证证据（PID、启动时间、端口）
+
+### 独立验证阶段（Tester 执行）
+- [ ] Tester 独立执行全部用例（不参考 Worker 报告）
+- [ ] Tester 客观报告通过/失败
+
+### Leader 验证阶段（Leader 执行）
+- [ ] Leader 抽查至少 30% 关键用例
+- [ ] Leader 确认进程是新启动的
+- [ ] Leader 确认接口有真实调用证据
+
+**以上 checklist 全部勾选后，才能标记任务完成。**
+
+## 质量红线
+
+- 不允许不执行测试直接填写"通过"
+- 不允许先写生产代码再补 RED；未观察 RED 的用例不得 Passed
+- 不允许修改测试断言让失败变为通过
+- 不允许隐瞒失败测试，必须记录并说明原因
+- 不允许只用 HTTP 200、字段非空、DB-only、BUILD SUCCESS 或 skipped tests 证明业务通过
+- 不允许用占位参数或 mock-only 证据证明真实前端/外部系统链路已通过
+- 不允许用测试 Controller、mock endpoint、绕过鉴权端点证明真实外部入口已通过
+- 不允许把泛化外部失败当作通过，除非需求明确要求该失败结果
+- 不允许只检查主仓数据库结构就关闭跨仓共享表任务；必须覆盖全部消费仓实体/Mapper/SQL
+- **不允许"编译成功 + 单元测试通过"就标记任务完成，必须完成上述 checklist 全部项**

package/assets/skills/superflow-pipeline/references/test-guide.md

@@ -0,0 +1,30 @@
+# 测试失败修复指南
+
+## 失败类型与修复方向
+
+| 失败现象 | 可能原因 | 修复方向 |
+|---|---|---|
+| 应用启动失败 | 配置文件错误 / 端口冲突 / Bean 初始化失败 | 检查 `application.yml`，确认端口未被占用，检查 Bean 依赖注入 |
+| 接口返回 404 | URL 路径错误 / 上下文路径未拼接 / 接口未注册 | 核对 Controller 的 `@RequestMapping` 路径，确认 context-path 已拼接 |
+| 接口返回 500 | 空指针 / SQL 异常 / 事务回滚 | 查看日志栈追踪，定位具体异常行号，检查入参是否为空 |
+| 数据库断言失败 | SQL 未生效 / 事务未提交 / 缓存未更新 | 确认方法上有 `@Transactional`，检查 `updateByPrimaryKeySelective` 返回值 |
+| 日志断言失败 | 日志级别过滤 / 异步日志未刷新 | 检查 `logback.xml` 日志级别，确认日志输出时机 |
+| 并发测试失败 | 竞态条件 / 锁未生效 / 事务隔离级别 | 检查锁的实现（数据库锁 / 分布式锁），确认事务传播行为 |
+| 灯色下发验证失败 | DMS 未连接 / 异步任务未执行 | 确认 DMS 服务可用，检查 `@Async` 线程池配置 |
+| Excel 导出验证失败 | 文件格式错误 / 字段映射错误 | 检查 EasyExcel 或 POI 配置，确认字段注解正确 |
+
+## 修复流程
+
+1. **复现问题**：根据测试用例的前置条件和执行步骤，手动复现失败场景
+2. **查看日志**：启动应用时添加 `--debug` 或检查 `logs/` 目录下的日志文件
+3. **定位代码**：根据日志中的异常栈追踪，找到具体的源码位置（类名 + 方法名 + 行号）
+4. **分析根因**：对照 design.md 中的设计方案，确认实现是否与设计一致
+5. **修改代码**：修复 bug，确保不引入新的问题（回归测试）
+6. **重新测试**：重新执行失败的测试用例，确认修复成功
+7. **更新文档**：如果修复涉及设计变更，同步更新 design.md 和 tasks.md
+
+## 质量红线
+
+- 不允许跳过失败的测试用例直接提交代码
+- 不允许修改测试用例的断言标准来"让测试通过"
+- 不允许在没有测试覆盖的情况下修改核心逻辑

package/assets/skills/superflow-pipeline/references/traceability-matrix.md

@@ -0,0 +1,106 @@
+# 可追溯性矩阵
+
+## 目的
+
+确保从需求到设计到实现到测试的完整可追溯，避免"设计漂移"和"实现遗漏"。
+
+---
+
+## 矩阵结构
+
+```markdown
+# Traceability Matrix
+
+## 需求层（spec.md）
+
+| Req ID | Requirement | Scenario | 对应 Design | 对应 Task | 对应 Test | 对应 Prompt |
+|--------|-------------|----------|-------------|-----------|-----------|-------------|
+| R1 | 主数据支持多种业务类型 | S1.1 | design.md ## 主数据 | Task 1.1 | tests.md T1 | P1 |
+| R2 | 业务创建时校验用户资格或资源充足 | S2.1 | design.md ## 创建校验 | Task 2.1 | tests.md T2 | P2 |
+| ... | ... | ... | ... | ... | ... | ... |
+
+## 设计层（design.md）
+
+| Design 章节 | 涉及文件 | 涉及方法 | 对应 Task | 对应 Prompt |
+|-------------|----------|----------|-----------|-------------|
+| ## 主数据 | BusinessRecord.java | - | Task 1.1 | P1 |
+| ## 开通校验 | OrderService.java | validateBalance() | Task 2.1 | P2 |
+| ... | ... | ... | ... | ... |
+
+## 任务层（tasks.md）
+
+| Task ID | 文件 | 方法 | 对应 Design | 对应 Prompt | 状态 |
+|---------|------|------|-------------|-------------|------|
+| Task 1.1 | BusinessRecordMapper.xml | insert | design.md ## 主数据 | P1 | 待执行 |
+| ... | ... | ... | ... | ... | ... |
+
+## Prompt 层（prompt/*.md）
+
+| Prompt | 覆盖 Task | 覆盖 Design | 依赖 Prompt | 状态 |
+|--------|-----------|-------------|-------------|------|
+| P0 | - | - | 无 | 待执行 |
+| P1 | Task 1.1-1.5 | design.md ## 数据模型 | P0 | 待执行 |
+| ... | ... | ... | ... | ... |
+```
+
+---
+
+## 一致性检查规则
+
+### 规则 1：设计漂移检查
+
+**定义**：prompt 中出现了 design.md / api.md / database-contract.md 没有定义的新方案。
+
+**检查方法**：
+1. 读取每份 prompt 的"精确实现步骤"
+2. 检查每个步骤是否能在 design.md 中找到对应章节
+3. 检查 prompt 中提到的字段、接口、MQ topic 是否在设计文档中有定义
+
+**标记方式**：
+```
+⚠️ 设计漂移：prompt/p2-charge-order.md 步骤 3 提到"使用乐观锁防止并发下单"，
+   但 design.md ## 下单流程 中未提及乐观锁策略。
+   处理方式：上报 Leader 确认 / 按设计文档原方案实现
+```
+
+### 规则 2：实现遗漏检查
+
+**定义**：design.md 有章节，但没有对应的 prompt 覆盖。
+
+**检查方法**：
+1. 遍历 design.md 的所有章节
+2. 检查每个章节是否被至少一份 prompt 覆盖
+3. 检查 api.md 中的每个接口是否被至少一份 prompt 覆盖
+
+**标记方式**：
+```
+⚠️ 实现遗漏风险：design.md ## 订单快照 描述了快照表结构和写入时机，
+   但没有 prompt 覆盖该功能（P1-P4 均未提及）。
+   处理方式：补充 P2 或新增 Pn 覆盖
+```
+
+### 规则 3：测试覆盖检查
+
+**定义**：tests.md 中的用例与 prompt 的测试要求不一致。
+
+**检查方法**：
+1. 检查每份 prompt 的"测试要求"是否覆盖了 tests.md 中对应章节的全部用例
+2. 检查 prompt 中"未执行测试及原因"是否合理
+
+**标记方式**：
+```
+⚠️ 测试覆盖不足：tests.md T3.2（边界：资源刚好等于业务阈值）
+   在 prompt/p2-charge-order.md 中未提及。
+   处理方式：补充到 P2 测试要求中
+```
+
+---
+
+## 自动化检查建议
+
+在生成所有 prompt 后，执行以下检查：
+
+1. **生成矩阵**：从 spec.md、design.md、tasks.md、tests.md、prompt/*.md 中提取对应关系
+2. **扫描漂移**：对比 prompt 内容与设计文档，标记未定义的方案
+3. **扫描遗漏**：对比设计文档与 prompt 覆盖范围，标记未覆盖的章节
+4. **输出报告**：列出所有漂移和遗漏项，供人工确认

package/assets/skills/superflow-pipeline/references/validation-integrity.md

@@ -0,0 +1,134 @@
+# 验收证据完整性门禁
+
+Use this reference whenever SDD docs, implementation prompts, or test reports
+claim that an API, integration flow, external dependency, dropdown, enum, or
+frontend payload has been tested.
+
+## Hard Gates
+
+- Do not mark L3/L4 tests as passed without real evidence.
+- Do not mark any Maven or Gradle test evidence as passed when the output says
+  `Tests are skipped` / `测试被跳过`. `BUILD SUCCESS` only proves the build
+  finished; it does not prove tests ran.
+- Do not collapse multiple Maven commands into one test count. Each command
+  must have its own `Tests run` summary. If a wildcard such as
+  `-Dtest='*P47*'` does not match a needed test class, record and execute a
+  separate command for that class.
+- Do not keep deleted methods, removed classes, or old algorithms in current
+  evidence tables. Old anchors may be mentioned only as explicitly deleted or
+  historical context.
+- Do not treat a generic fallback error as success unless the requirement
+  explicitly defines that fallback as the expected business result.
+- Do not use placeholder values such as `TEST_PARK_001` to prove frontend or
+  production-like integration unless the source of that value is documented.
+- Do not let mock-only evidence close a case that requires real frontend data,
+  real database state, real operator/site/park codes, real token, or an external
+  SDK/service call.
+- Do not let a test controller, mock endpoint, bypass-auth endpoint, or direct
+  service-call endpoint close a case that requires a real external entry.
+- Do not treat one repository's schema verification as complete when sibling
+  services copy the same PO/Mapper or read the same table.
+- If required test data is missing, mark the case `Blocked: missing test data`
+  and ask for or discover the data before claiming completion.
+
+## tests.md Requirements
+
+For every L3/L4 or frontend integration case, include these columns or equivalent
+fields:
+
+| Field | Required content |
+|---|---|
+| 用例 ID | Stable test id, referenced from spec/tasks/prompt |
+| 接口/流程 | Full URL or user workflow |
+| 数据来源 | User-provided, frontend captured payload, DB query, seeded fixture, or mock |
+| 关键参数 | Real values such as parkCode/operatorId/plotId/templateId; no unexplained placeholders |
+| 预期断言 | Response, DB, log, and external-call assertions |
+| 证据要求 | curl/request/response/DB/log/external response required in test-report.md |
+| 证据等级 | Mock only / Test endpoint / Real external entry |
+
+For dropdowns, enums, external SDK calls, device callbacks, payment/refund,
+invoice, export, import, and cross-system flows, add at least one real-data case
+or explicitly mark the case blocked.
+
+## test-report.md Requirements
+
+Every passed L3/L4 case must include:
+
+- test id and requirement/spec reference
+- environment, profile, port, context path, branch, and commit
+- exact command or curl
+- real request parameters and where they came from
+- raw or summarized response
+- assertion result
+- database evidence when state changes or persistence matters
+- relevant logs
+- external SDK/service request and response when external dependencies matter
+- evidence level: `Mock only`, `Test endpoint`, `Partial real entry`, or
+  `Real integration passed`
+- for cross-repository database contracts: source schema, each consumer
+  repository, entity/Mapper/SQL fields, real database columns, and conclusion
+- exact command-to-result mapping for every automated test command. If the same
+  command appears with different `Tests run` values, the report is not
+  acceptable until reconciled.
+- for sibling repositories whose build config skips tests by default, record the
+  direct command result (`Tests are skipped` if applicable), the temporary
+  change or profile that makes tests run, the real `Tests run` output, and the
+  clean git status after rollback.
+
+If any of those are absent, status must be `Not executed`, `Blocked`, or
+`Partially verified`, not `Passed`.
+
+Before delivery, run:
+
+```bash
+~/.codex/hooks/superflow-test-report-lint.py <embedded test-report.md>
+```
+
+For root aggregate reports, run the same script with `--warn-only` and review
+all warnings before signing off.
+
+## Cross-Repository Schema Rule
+
+When a table is shared across repositories or a service copies another
+service's PO/Entity/Mapper:
+
+- identify the source-of-truth schema: version SQL, database contract, and
+  `SHOW CREATE TABLE`
+- list every consuming repository and runtime path, including interconnect,
+  callback, scheduled job, import/export, and test endpoint paths
+- compare MyBatis-Plus `@TableName` entity fields, `BaseMapper` default
+  selection, Mapper XML/resultMap, and handwritten SQL against real database
+  columns
+- fields removed from the final schema must be removed from mapped entities or
+  marked `@TableField(exist = false)`
+- if code still queries a removed column, the fix is code/schema contract
+  alignment, not adding obsolete columns back to test database
+
+The case is blocked if any consumer repository maps or queries a non-existent
+column.
+
+## Red-Green Rule
+
+For bug fixes and CR/Px follow-ups:
+
+1. Record the red evidence first: the exact failing test, curl, or workflow
+   before the fix, including the error response/log/DB mismatch.
+2. Apply the fix.
+3. Run the same evidence path again and record the green result.
+
+For new features where no old failing path exists, use a negative control:
+
+- one invalid or unauthorized case fails with the expected error
+- one real happy-path case passes with response and DB/log evidence
+
+## External Dependency Rule
+
+When an external service is unavailable:
+
+- record the external request parameters, endpoint/config source, exception type,
+  external code/message if available, and whether the failure is environmental or
+  code-related
+- do not mark the business case passed unless the requirement only promises a
+  stable error under external failure
+- keep the delivery conclusion explicit: `Blocked by external dependency`,
+  `Code path verified with mock`, or `Real integration passed`