@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.
Files changed (13) hide show
  1. package/README.md +39 -1
  2. package/README.zh-CN.md +13 -1
  3. package/assets/skills/superflow-design/SKILL.md +16 -8
  4. package/assets/skills/superflow-docs/SKILL.md +17 -8
  5. package/assets/skills/superflow-pipeline/references/api-design-template.md +99 -63
  6. package/assets/skills/superflow-pipeline/references/batch-prompt-template.md +62 -14
  7. package/assets/skills/superflow-pipeline/references/implementation-prompt-template.md +114 -67
  8. package/assets/skills/superflow-pipeline/references/quality-gate.md +104 -102
  9. package/assets/skills/superflow-pipeline/references/superpower-technical-design-template.md +45 -19
  10. package/assets/skills/superflow-pipeline/scripts/superflow-guard.sh +35 -0
  11. package/dist/commands/design.js +25 -3
  12. package/dist/commands/design.js.map +1 -1
  13. package/package.json +1 -1
package/README.md CHANGED
@@ -46,6 +46,42 @@ real verified delivery. SuperBridge Flow makes that gap explicit:
46
46
  The CLI installs skills, hooks or command aliases, rules, scripts, handoff
47
47
  state, and dependency guards for Claude Code, Codex, and OpenCode.
48
48
 
49
+ ## Highlights
50
+
51
+ - **9 catalogued failure modes, blocked at the gate.** Nine real ways AI breaks
52
+ in production — swallowing the whole PRD then forgetting details, editing
53
+ only the setter while missing consumers, SQL drift across dev/test/DB
54
+ layers, mock-only "已验证" reports, and more — each baked into a hard check
55
+ the agent cannot skip.
56
+ - **Architecture 6-questions before cross-service code.** Any change crossing
57
+ service / SDK / MQ / device / callback / gateway boundaries must answer six
58
+ questions in the technical design: who owns the module, what is the call
59
+ direction, where are existing entry/exit points, are new ones allowed, which
60
+ paths are forbidden, what is the evidence anchor.
61
+ - **Field And Status Reverse Impact matrix.** Every schema / status / enum
62
+ change must enumerate its write sites, read sites, filter conditions,
63
+ derived / sync sites, cross-module consumers, and test coverage — including
64
+ reverse-recovery scenarios (down then up again, deleted then re-created, old
65
+ value unavailable while upstream didn't send the field).
66
+ - **6 productized lessons as gates, not reminders.** Full-impact discovery,
67
+ business semantics over HTTP 200, no default fallbacks, DB reconciliation,
68
+ real-entry evidence, code-data verification — each baked into a specific
69
+ phase and a specific hook. Missing evidence blocks the next phase.
70
+ - **5 phases × 5+ guard scripts as hard gates.** `superflow-guard.sh` +
71
+ `superflow-hook-guard.sh` + `superflow-contract-hooks.sh` +
72
+ `superflow-sql-sync-hook.py` + `superflow-test-report-lint.py` +
73
+ `superflow-verify-integration.sh`. No handoff hash → no implementation. No
74
+ real-entry evidence → no "verified" report.
75
+ - **Context-drift proof via handoff + state + sha256.** When long sessions
76
+ compress, when agents switch, when multiple workers parallelize —
77
+ `.sdd/handoff/sdd-context.{md,json}` + sha256 + `.sdd/state.yaml` keep
78
+ Worker / Tester / Reviewer on the same source of truth. Stale prompts
79
+ blocked by hash mismatch.
80
+ - **User says one sentence, pipeline runs 9 steps.** No prompt engineering
81
+ required: `> use SuperFlow to handle this requirement` triggers clarify →
82
+ docs → design → implement → verify → archive. Phase progression, guards,
83
+ hashes, and hooks are flow-enforced, not user-discipline.
84
+
49
85
  ## Workflow
50
86
 
51
87
  ```text
@@ -211,7 +247,9 @@ keeps the same workflow contracts.
211
247
  The chart is generated by Star History from public GitHub star data. It may stay
212
248
  empty while the repository is private.
213
249
 
214
- [![Star History Chart](https://api.star-history.com/svg?repos=BasketballNotFound-ManKun/superflow-cli&type=Date)](https://star-history.com/#BasketballNotFound-ManKun/superflow-cli&Date)
250
+ [![Star History Chart](https://api.star-history.com/svg?repos=basketballnotfound-mankun/superflow-cli&type=Date)](https://star-history.com/#basketballnotfound-mankun/superflow-cli&Date)
251
+
252
+ [Open the Star History chart](https://star-history.com/#basketballnotfound-mankun/superflow-cli&Date)
215
253
 
216
254
  ## License
217
255
 
package/README.zh-CN.md CHANGED
@@ -41,6 +41,16 @@ CLI 会把 SuperBridge Flow 技能、配套 hook/command 脚本整合为单一 n
41
41
  - OpenCode：`.opencode/skills/`、`.opencode/commands/`、`.opencode/scripts/`
42
42
  或全局 `~/.config/opencode/`
43
43
 
44
+ ## 亮点
45
+
46
+ - **9 类翻车场景，沉淀成门禁。** 我们见过的 AI 翻车——需求一次吞、字段漏查消费者、SQL 漂移、mock-only 报告、跨服务只看到"能调"……9 种典型形态都被固化成 guard，AI 想跳过都不行。
47
+ - **跨服务代码必须先答架构 6 问。** 涉及跨仓、跨服务、SDK、MQ、设备、回调、网关的改动，技术详设里必须先回答：owner 是谁、调用方向、新入口是否允许、禁止路径、证据锚点——答不全不让进入实现。
48
+ - **改字段之前先填"字段与状态反向影响"矩阵。** 任何 schema、状态、枚举的改动，必须枚举写入点、读取点、过滤点、派生 / 同步点、跨模块消费者、测试覆盖，还要列反向恢复场景（下线后重上线、旧值不可用但上游没传字段、历史脏数据被新过滤条件消费）。
49
+ - **6 条踩坑经验产品化，不是提醒是门禁。** 影响面要查全、业务语义 > 接口成功、禁止默认兜底、数据库收口、真实入口验证、代码与数据关系核实——每条绑定特定阶段和特定 hook，缺证据就阻断下一阶段。
50
+ - **5 个阶段 × 5+ 门禁脚本硬阻断。** `superflow-guard.sh` + `superflow-hook-guard.sh` + `superflow-contract-hooks.sh` + `superflow-sql-sync-hook.py` + `superflow-test-report-lint.py` + `superflow-verify-integration.sh`。没有 handoff hash 不进实现，没有真实入口证据不写"通过"。
51
+ - **用 handoff + state + sha256 治上下文漂移。** 长会话压缩、切 agent、并行 worktree——`.sdd/handoff/sdd-context.{md,json}` + sha256 + `.sdd/state.yaml` 让 Worker / Tester / Reviewer 始终基于同一份上下文，hash 对不上的旧 prompt 自动被 guard 拒绝。
52
+ - **用户只说一句话，流水线跑 9 步。** 不用写复杂 prompt：`> 用 SuperFlow 处理这个需求` 触发 clarify → docs → design → implement → verify → archive。阶段推进、guard、hash、hook 全是流程强制，不靠用户自觉。
53
+
44
54
  ## 工作流
45
55
 
46
56
  ```text
@@ -179,7 +189,9 @@ export SUPERFLOW_UPDATE_MIN_INTERVAL_SECONDS=21600
179
189
  下图由 Star History 根据 GitHub 公开 star 数据动态生成。仓库保持 private
180
190
  时，第三方服务通常读不到完整数据；切换为 public 后会正常展示趋势。
181
191
 
182
- [![Star History Chart](https://api.star-history.com/svg?repos=BasketballNotFound-ManKun/superflow-cli&type=Date)](https://star-history.com/#BasketballNotFound-ManKun/superflow-cli&Date)
192
+ [![Star History Chart](https://api.star-history.com/svg?repos=basketballnotfound-mankun/superflow-cli&type=Date)](https://star-history.com/#basketballnotfound-mankun/superflow-cli&Date)
193
+
194
+ [打开 Star History 趋势图](https://star-history.com/#basketballnotfound-mankun/superflow-cli&Date)
183
195
 
184
196
  ## 许可证
185
197
 
package/assets/skills/superflow-design/SKILL.md CHANGED
@@ -55,14 +55,21 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
55
55
  orchestrator, stop and return to `$superflow-docs` unless the OpenSpec/SDD
56
56
  contract explicitly grants that ownership with approval evidence.
57
57
  6. For field/status/enum/sync changes, include `Field And Status Reverse
58
- Impact` and prove writers, readers, filters, derived sync paths, consumers,
58
+ Impact` and prove writers, readers, filters, derived sync paths, consumers,
59
59
  and tests. Direct setter-only design is blocked.
60
- 7. Record state:
60
+ 7. For third-party, SDK, BEM/parking, payment/refund, financial display,
61
+ source/origin, status sync, or external dictionary fields, include
62
+ `External Enum Binding`. Prove local source fields/enums, external fields,
63
+ external enum values, display/business/financial meaning, source evidence,
64
+ owner confirmation, unresolved handling, and test evidence. A request
65
+ succeeding or a field being non-null is not enough; unconfirmed values are
66
+ blockers and must be returned to `$superflow-docs` or the user.
67
+ 8. Record state:
61
68
  ```bash
62
69
  ../superflow-pipeline/scripts/superflow-state.sh set <change-dir> technical_design docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md
63
70
  ../superflow-pipeline/scripts/superflow-state.sh set <change-dir> design_doc design.md
64
71
  ```
65
- 8. Update `design.md` with `Superpowers Technical Design Handoff`, update
72
+ 9. Update `design.md` with `Superpowers Technical Design Handoff`, update
66
73
  `sdd-quality-gate.md` with the technical design path and hash, then run
67
74
  `../superflow-pipeline/scripts/superflow-handoff.sh <change-dir> --refresh`.
68
75
  If the guard reports a stale or missing hash, record the printed hash in
@@ -70,11 +77,12 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
70
77
  `--refresh` again. Do not set `design_doc` to the Superpowers document;
71
78
  `design_doc` is the OpenSpec/SDD contract design, while `technical_design`
72
79
  is the Superpowers HOW document.
73
- 9. Run:
74
- ```bash
75
- ../superflow-pipeline/scripts/superflow-yaml-validate.sh <change-dir>
76
- ../superflow-pipeline/scripts/superflow-guard.sh <change-dir> design --apply
77
- ```
80
+ 10. Run:
81
+
82
+ ```bash
83
+ ../superflow-pipeline/scripts/superflow-yaml-validate.sh <change-dir>
84
+ ../superflow-pipeline/scripts/superflow-guard.sh <change-dir> design --apply
85
+ ```
78
86
 
79
87
  ## Completion
80
88
 
package/assets/skills/superflow-docs/SKILL.md CHANGED
@@ -76,6 +76,15 @@ For complex requirements, verify these before writing docs:
76
76
  If the docs only prove that a value exists, is non-null, or lets the request
77
77
  succeed, stop and return to `$superflow-clarify`. If fallback/default/keep-old-value
78
78
  behavior is proposed without explicit requirement or owner approval, stop.
79
+ - For third-party, SDK, BEM/parking, payment/refund, financial display,
80
+ source/origin, status sync, or external dictionary/enum fields, `api.md` and
81
+ `sdd-quality-gate.md` must include `外部枚举绑定确认` / `External Enum
82
+ Binding` with:
83
+ `业务字段 | 本系统真源字段/枚举 | 外部系统字段 | 外部枚举/字典值 |
84
+ 展示文案/业务语义/财务语义 | 取值来源 | owner/确认时间 |
85
+ 不确定项/阻塞处理 | 测试证据`. Unconfirmed values are blockers; do not
86
+ invent numeric values, origin/source values, display meanings, or fallback
87
+ mappings.
79
88
  - For low-freedom implementation handoff, docs include the five hard gates:
80
89
  field semantic contract, write-through persistence closure, real-entry call
81
90
  chain, no-fallback/no-guessing boundary, and pre-coding agent self-check. If
@@ -202,7 +211,7 @@ Use references only as needed:
202
211
  - Do not freeze cross-module design from "this module can technically call it"
203
212
  evidence. `design.md` or `traceability-matrix.md` must include:
204
213
  `链路步骤 | 调用方向 | 业务入口 owner | 出口/适配 owner | 既有入口/出口 |
205
- 拟新增入口/出口 | 是否符合职责 | 证据锚点 | 禁止绕路`.
214
+ 拟新增入口/出口 | 是否符合职责 | 证据锚点 | 禁止绕路`.
206
215
  Outbound adapters, protocol translators, MQ notification consumers, and
207
216
  device gateways must not be promoted into business-entry orchestrators unless
208
217
  the contract says they own that entry and records approval.
@@ -231,14 +240,14 @@ Use references only as needed:
231
240
  - `design.md` must reference the frozen `api.md` fields and errors.
232
241
  - `design.md` must include a "字段语义合同" table for every risky field:
233
242
  `字段 | 来源表/DTO/事件 | 真实语义 | 目标字段 | 目标语义 | 是否可等价 |
234
- 证据锚点 | 禁止用法 | 不确定项/owner`.
243
+ 证据锚点 | 禁止用法 | 不确定项/owner`.
235
244
  - `design.md` or `traceability-matrix.md` must include a "写入闭环" table for
236
245
  every persisted or synchronized value:
237
246
  `业务动作 | Java setter/赋值点 | Converter/DTO 映射 | Mapper insert/update |
238
- DB column | 后续读取方 | 消费入口 | 验证 SQL | 测试用例`.
247
+ DB column | 后续读取方 | 消费入口 | 验证 SQL | 测试用例`.
239
248
  - `design.md` must include a "真实入口调用链" table:
240
249
  `用户/外部动作 | 上游服务/接口 | 本仓入口 | MQ/异步回调 | 关键字段变化 |
241
- DB 状态 | 结算/通知/展示消费点 | 真实验证方式`.
250
+ DB 状态 | 结算/通知/展示消费点 | 真实验证方式`.
242
251
  - `design.md` or `sdd-quality-gate.md` must include a "禁止 fallback 与猜测实现"
243
252
  section. It must explicitly list forbidden defaults, fallback queries,
244
253
  substitute fields, keep-old-value behavior, null conversion, and downstream
@@ -252,14 +261,14 @@ Use references only as needed:
252
261
  The final technical design is created by `$superflow-design`, not `$superflow-docs`.
253
262
  - `test-report.md` skeleton must include an "Agent 执行前自检" section with:
254
263
  `真实入口已定位 | 字段语义合同已核对 | 写入闭环已核对 |
255
- 禁止兜底边界已确认 | RED 测试已执行 | 允许修改文件 | 禁止修改文件 |
256
- 阻塞项`.
264
+ 禁止兜底边界已确认 | RED 测试已执行 | 允许修改文件 | 禁止修改文件 |
265
+ 阻塞项`.
257
266
  - `tasks.md`, `tests.md`, and later prompts must use the same field names as `api.md`.
258
267
  - `tests.md` is a pre-implementation contract. It must not be a vague checklist.
259
268
  Every case must include:
260
269
  `用例ID | 需求/Scenario | 层级L1/L2/L3/L4 | 前置数据 | 操作步骤 |
261
- 自动化命令 | 响应断言 | DB断言 | 日志断言 | RED预期失败 | GREEN预期通过 |
262
- test-report证据位置`.
270
+ 自动化命令 | 响应断言 | DB断言 | 日志断言 | RED预期失败 | GREEN预期通过 |
271
+ test-report证据位置`.
263
272
  - Each visible UI field, button action, list column, dropdown, and enum must map to API/DTO/DB/tests or be explicitly out of scope.
264
273
  - Every spec scenario must have at least one test case.
265
274
  - Every implementation batch must have at least one test that can fail before
package/assets/skills/superflow-pipeline/references/api-design-template.md CHANGED
@@ -12,7 +12,7 @@
12
12
 
13
13
  ## 文档结构
14
14
 
15
- ```markdown
15
+ ````markdown
16
16
  # API 设计文档：<模块名称>
17
17
 
18
18
  ## 0. 变更概览（本次提测变更）
@@ -20,13 +20,16 @@
20
20
  > **本节为提测变更增量视图，完整历史见第 8 节。变更标注规则详见 `api-doc-changelog` 技能。**
21
21
 
22
22
  首次版本：
23
+
23
24
  ```markdown
24
25
  ## 0. 变更概览（本次提测变更）
25
26
 
26
27
  > 首个版本，全部接口为新增。详见接口列表。
27
28
  ```
29
+ ````
28
30
 
29
31
  迭代版本（更新时必须填写）：
32
+
30
33
  ```markdown
31
34
  ## 0. 变更概览（本次提测变更）
32
35
 
@@ -34,24 +37,25 @@
34
37
 
35
38
  ### 新增接口
36
39
 
37
- | 接口 | 说明 |
38
- |------|------|
40
+ | 接口 | 说明 |
41
+ | --------------- | ------------- |
39
42
  | `POST /api/xxx` | 新增 xxx 功能 |
40
43
 
41
44
  ### 修改接口
42
45
 
43
- | 接口 | 变更摘要 |
44
- |------|----------|
46
+ | 接口 | 变更摘要 |
47
+ | -------------- | ---------------------------------------------- |
45
48
  | `GET /api/yyy` | 新增 query 参数 `keyword`；响应增加 `tag` 字段 |
46
49
 
47
50
  ### 废弃接口
48
51
 
49
- | 接口 | 替代方案 | 移除计划 |
50
- |------|----------|----------|
52
+ | 接口 | 替代方案 | 移除计划 |
53
+ | -------------- | ------------------- | --------- |
51
54
  | `GET /api/old` | 使用 `GET /api/new` | v2.0 移除 |
52
55
  ```
53
56
 
54
57
  **变更标注规则：**
58
+
55
59
  - 变更接口标题后加标签：`[新增]` / `[修改]` / `[废弃]`
56
60
  - 变更字段说明列末尾加标注：`【本次新增】` / `【本次变更：具体改了什么】` / `【本次废弃】`
57
61
  - 下一轮提测时清除上一轮所有标签和标注
@@ -62,11 +66,13 @@
62
66
  ## 1. 通用约定
63
67
 
64
68
  ### 1.0 参数命名约束
69
+
65
70
  - 在填写接口参数前，**必须先检查目标仓库现有 Controller、Query DTO、分页基类、历史 `api.md`**，复用已有命名。
66
71
  - 不得因为新文档是 AI 生成就擅自切换参数口径，例如已有代码主流使用 `pageNo/pageSize` 时，不得写成 `pageNum/pageSize`。
67
72
  - 分页、排序、筛选字段优先跟随现有代码模型命名，而不是套用通用模板名。
68
73
 
69
74
  ### 1.0.1 前端契约对账约束
75
+
70
76
  - 涉及页面、弹窗、列表、下拉框或前端联调时，先列出原始需求/原型字段，再映射到 API 字段、DTO/VO 字段和数据库字段。
71
77
  - 字段名不一致时必须写明兼容策略：后端兼容前端字段、前端改字段、或双字段过渡。
72
78
  - 字段被合并表达时必须写明规则，例如前端 `{limitType} + {limitValue}` 如果映射为后端 `{businessLimit}`，必须说明每个哨兵值和正数值的业务含义。
@@ -74,16 +80,18 @@
74
80
  - 页面、原型和产品文字都没有的字段，默认不得作为必填入参；若后端确实需要，必须写明由后端默认或后端推导。
75
81
 
76
82
  ### 1.1 基础信息
83
+
77
84
  - **Base URL**: `http://{host}:{port}{context-path}`
78
85
  - **Content-Type**: `application/json`
79
86
  - **字符编码**: UTF-8
80
87
  - **时间格式**: `yyyy-MM-dd HH:mm:ss`
81
88
 
82
89
  ### 1.2 认证方式
90
+
83
91
  - [ ] JWT Bearer Token（Header: `Authorization: Bearer {token}`）
84
92
  - [ ] HMAC-SHA256 签名（Headers: `X-Timestamp`, `X-Nonce`, `X-Sign`）
85
93
  - [ ] API Key（Header: `X-Api-Key`）
86
- - [ ] 其他：____
94
+ - [ ] 其他：\_\_\_\_
87
95
 
88
96
  ### 1.3 通用响应格式
89
97
 
@@ -97,15 +105,15 @@
97
105
 
98
106
  ### 1.4 全局错误码
99
107
 
100
- | 错误码 | 说明 | HTTP 状态码 |
101
- |--------|------|-------------|
102
- | 0 | 成功 | 200 |
103
- | 400 | 请求参数错误 | 400 |
104
- | 401 | 未授权 | 401 |
105
- | 403 | 禁止访问 | 403 |
106
- | 404 | 资源不存在 | 404 |
107
- | 500 | 服务器内部错误 | 500 |
108
- | 1001 | 业务错误：____ | 200 |
108
+ | 错误码 | 说明 | HTTP 状态码 |
109
+ | ------ | ------------------ | ----------- |
110
+ | 0 | 成功 | 200 |
111
+ | 400 | 请求参数错误 | 400 |
112
+ | 401 | 未授权 | 401 |
113
+ | 403 | 禁止访问 | 403 |
114
+ | 404 | 资源不存在 | 404 |
115
+ | 500 | 服务器内部错误 | 500 |
116
+ | 1001 | 业务错误：\_\_\_\_ | 200 |
109
117
 
110
118
  ---
111
119
 
@@ -114,8 +122,9 @@
114
122
  ### 2.1 接口名称
115
123
 
116
124
  #### 基本信息
125
+
117
126
  - **接口路径**: `POST /api/v1/xxx`
118
- - **接口说明**: ____
127
+ - **接口说明**: \_\_\_\_
119
128
  - **调用方**: [前端 / 移动端 / 第三方 / 内部服务]
120
129
  - **是否需要认证**: [是 / 否]
121
130
 
@@ -133,35 +142,37 @@
133
142
  | pageSize | Integer | 否 | 每页大小，默认 20；若仓库已有分页对象使用其他命名，则必须以源码为准 | 20 |
134
143
 
135
144
  **请求体（Body）**
145
+
136
146
  ```json
137
147
  {
138
- "field1": "string", // 必填，说明
139
- "field2": 0, // 可选，说明，默认 0
140
- "field3": ["item"] // 可选，数组说明
148
+ "field1": "string", // 必填，说明
149
+ "field2": 0, // 可选，说明，默认 0
150
+ "field3": ["item"] // 可选，数组说明
141
151
  }
142
152
  ```
143
153
 
144
- | 字段 | 类型 | 必填 | 说明 | 校验规则 |
145
- |------|------|------|------|----------|
146
- | field1 | String | 是 | ____ | 长度 1-64 |
147
- | field2 | Integer | 否 | ____ | 范围 0-100 |
148
- | field3 | Array | 否 | ____ | 元素个数 0-10 |
154
+ | 字段 | 类型 | 必填 | 说明 | 校验规则 |
155
+ | ------ | ------- | ---- | -------- | ------------- |
156
+ | field1 | String | 是 | \_\_\_\_ | 长度 1-64 |
157
+ | field2 | Integer | 否 | \_\_\_\_ | 范围 0-100 |
158
+ | field3 | Array | 否 | \_\_\_\_ | 元素个数 0-10 |
149
159
 
150
160
  #### 字段映射与兼容
151
161
 
152
- | 原型/前端字段 | API 字段 | DTO/VO 字段 | DB 字段 | 取值/枚举 | 来源 | 策略 |
153
- |---|---|---|---|---|---|---|
154
- | ____ | ____ | ____ | ____ | ____ | PRD / 原型 / 源码 / 后端推导 | 前端提交 / 后端默认 / 后端推导 / 后端兼容 / 前端改名 / 双字段过渡 / 废弃 |
162
+ | 原型/前端字段 | API 字段 | DTO/VO 字段 | DB 字段 | 取值/枚举 | 来源 | 策略 |
163
+ | ------------- | -------- | ----------- | -------- | --------- | ---------------------------- | ------------------------------------------------------------------------ |
164
+ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | PRD / 原型 / 源码 / 后端推导 | 前端提交 / 后端默认 / 后端推导 / 后端兼容 / 前端改名 / 双字段过渡 / 废弃 |
155
165
 
156
166
  #### 条件必填与互斥
157
167
 
158
- | 条件 | 必填字段 | 必须为空字段 | 失败提示 |
159
- |---|---|---|---|
160
- | ____ | ____ | ____ | ____ |
168
+ | 条件 | 必填字段 | 必须为空字段 | 失败提示 |
169
+ | -------- | -------- | ------------ | -------- |
170
+ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ |
161
171
 
162
172
  #### 响应示例
163
173
 
164
174
  **成功（code = 0）**
175
+
165
176
  ```json
166
177
  {
167
178
  "code": 0,
@@ -175,6 +186,7 @@
175
186
  ```
176
187
 
177
188
  **失败（code ≠ 0）**
189
+
178
190
  ```json
179
191
  {
180
192
  "code": 1001,
@@ -184,11 +196,12 @@
184
196
  ```
185
197
 
186
198
  #### 边界说明
187
- - 字段为 null 时的处理：____
188
- - 数组为空时的处理：____
189
- - 并发调用时的限制：____
190
- - 参数命名与现有源码差异：____（若无差异，明确写“无，沿用现有命名”）
191
- - 前端兼容策略：____（如无兼容需求，明确写“无，前后端字段名一致”）
199
+
200
+ - 字段为 null 时的处理：\_\_\_\_
201
+ - 数组为空时的处理：\_\_\_\_
202
+ - 并发调用时的限制：\_\_\_\_
203
+ - 参数命名与现有源码差异：\_\_\_\_（若无差异，明确写“无，沿用现有命名”）
204
+ - 前端兼容策略：\_\_\_\_（如无兼容需求，明确写“无，前后端字段名一致”）
192
205
 
193
206
  #### 联调验收 curl
194
207
 
@@ -200,9 +213,11 @@ curl -s -X POST "http://localhost:{port}{context-path}/api/..." \
200
213
  ```
201
214
 
202
215
  断言：
203
- - `message.code` / `code`: ____
204
- - `data` 关键字段：____
205
- ```
216
+
217
+ - `message.code` / `code`: \_\_\_\_
218
+ - `data` 关键字段：\_\_\_\_
219
+
220
+ ````
206
221
 
207
222
  ---
208
223
 
@@ -217,7 +232,7 @@ curl -s -X POST "http://localhost:{port}{context-path}/api/..." \
217
232
  |---|---|---|---|---|---|---|---|---|---|---|
218
233
  | 1 | {页面}-{按钮} | POST | /api/v1/xxx | application/json | body | JSON: {code:0,data:{}} | JSON: {code:1001,message:""} | code === 0 | 超管/运营商/子账号 | 否 |
219
234
  | 2 | {页面}-{导出按钮} | GET | /api/v1/xxx/export | - | query | 文件流(application/octet-stream) | JSON: {code:1001,message:""} | Content-Disposition 存在 | 超管/运营商 | 否 |
220
- ```
235
+ ````
221
236
 
222
237
  参数位置可选项：`path` / `query` / `body` / `form-data` / `file`
223
238
 
@@ -237,10 +252,10 @@ curl -s -X POST "http://localhost:{port}{context-path}/api/..." \
237
252
  ```markdown
238
253
  ### 文件接口契约
239
254
 
240
- | # | 接口 | 类型 | 成功 Content-Type | Content-Disposition | 文件名规则 | 失败响应 | 前端如何判断成功 | 复用列表筛选 | 受分页影响 |
241
- |---|---|---|---|---|---|---|---|---|---|
242
- | 1 | GET /api/v1/xxx/export | 导出 | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | attachment; filename="{name}.xlsx" | {模块}_{日期}.xlsx | JSON: {code:1001,message:""} | 响应头含 Content-Disposition | 是 | 否 |
243
- | 2 | GET /api/v1/xxx/template | 模板下载 | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | attachment; filename="template.xlsx" | {功能}_导入模板.xlsx | JSON: {code:1001,message:""} | 响应头含 Content-Disposition | 否 | 否 |
255
+ | # | 接口 | 类型 | 成功 Content-Type | Content-Disposition | 文件名规则 | 失败响应 | 前端如何判断成功 | 复用列表筛选 | 受分页影响 |
256
+ | --- | ------------------------ | -------- | ----------------------------------------------------------------- | ------------------------------------ | --------------------- | ---------------------------- | ---------------------------- | ------------ | ---------- |
257
+ | 1 | GET /api/v1/xxx/export | 导出 | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | attachment; filename="{name}.xlsx" | {模块}\_{日期}.xlsx | JSON: {code:1001,message:""} | 响应头含 Content-Disposition | 是 | 否 |
258
+ | 2 | GET /api/v1/xxx/template | 模板下载 | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | attachment; filename="template.xlsx" | {功能}\_导入模板.xlsx | JSON: {code:1001,message:""} | 响应头含 Content-Disposition | 否 | 否 |
244
259
  ```
245
260
 
246
261
  ### 文件接口红线
@@ -255,20 +270,21 @@ curl -s -X POST "http://localhost:{port}{context-path}/api/..." \
255
270
 
256
271
  ## 5. Excel 导入/导出契约（强制，涉及 Excel 导入时必须填写）
257
272
 
258
- ```markdown
273
+ ````markdown
259
274
  ### Excel 导入契约
260
275
 
261
276
  #### 模板定义
262
277
 
263
- | 列序号 | 列头名称 | 对应 DTO 字段 | 必填 | 允许为空 | 数据校验规则 | 说明 |
264
- |---|---|---|---|---|---|---|
265
- | 1 | 站点名称 | siteName | 是 | 否 | 长度 1-64 | |
266
- | 2 | 生效日期 | effectiveDate | 是 | 否 | 日期格式：yyyy-MM-dd 或 yyyy-MM-dd HH:mm:ss | 只有日期时补 00:00:00 |
267
- | 3 | 业务名称 | recordName | 否 | 是 | 长度 0-64 | |
278
+ | 列序号 | 列头名称 | 对应 DTO 字段 | 必填 | 允许为空 | 数据校验规则 | 说明 |
279
+ | ------ | -------- | ------------- | ---- | -------- | ------------------------------------------- | --------------------- |
280
+ | 1 | 站点名称 | siteName | 是 | 否 | 长度 1-64 | |
281
+ | 2 | 生效日期 | effectiveDate | 是 | 否 | 日期格式：yyyy-MM-dd 或 yyyy-MM-dd HH:mm:ss | 只有日期时补 00:00:00 |
282
+ | 3 | 业务名称 | recordName | 否 | 是 | 长度 0-64 | |
268
283
 
269
284
  #### 导入响应
270
285
 
271
286
  成功导入全部行：
287
+
272
288
  ```json
273
289
  {
274
290
  "code": 0,
@@ -281,8 +297,10 @@ curl -s -X POST "http://localhost:{port}{context-path}/api/..." \
281
297
  }
282
298
  }
283
299
  ```
300
+ ````
284
301
 
285
302
  部分失败：
303
+
286
304
  ```json
287
305
  {
288
306
  "code": 1002,
@@ -292,20 +310,22 @@ curl -s -X POST "http://localhost:{port}{context-path}/api/..." \
292
310
  "successCount": 8,
293
311
  "failureCount": 2,
294
312
  "failureRows": [
295
- {"row": 3, "reason": "站点不存在"},
296
- {"row": 7, "reason": "日期格式错误"}
313
+ { "row": 3, "reason": "站点不存在" },
314
+ { "row": 7, "reason": "日期格式错误" }
297
315
  ]
298
316
  }
299
317
  }
300
318
  ```
301
319
 
302
320
  #### 导入规则
321
+
303
322
  - failureCount > 0 时，业务 code 必须为非 0（前端通过 code !== 0 判断失败）。
304
- - 单次导入上限：____ 行。
305
- - 是否允许同一文件包含多业务类型/多站点/多对象：____。
323
+ - 单次导入上限：\_\_\_\_ 行。
324
+ - 是否允许同一文件包含多业务类型/多站点/多对象：\_\_\_\_。
306
325
  - 日期格式必须兼容 yyyy-MM-dd 和 yyyy-MM-dd HH:mm:ss。
307
326
  - 行级错误必须保留具体行号和原因。
308
- ```
327
+
328
+ ````
309
329
 
310
330
  ### Excel 导入红线
311
331
 
@@ -339,11 +359,13 @@ curl -s -X POST "http://localhost:{port}{context-path}/api/..." \
339
359
  - 详情越权响应：（返回"无权限"还是"数据不存在"）
340
360
  - 导出是否复用列表权限：是/否
341
361
  - 待确认问题：（如有）
342
- ```
362
+ ````
343
363
 
344
364
  已确认示例：
365
+
345
366
  ```markdown
346
367
  **数据权限：**
368
+
347
369
  - 是否访问业务数据：是
348
370
  - 是否需要数据权限：需要
349
371
  - 判断依据：参考现有订单列表接口的数据范围处理
@@ -357,8 +379,10 @@ curl -s -X POST "http://localhost:{port}{context-path}/api/..." \
357
379
  ```
358
380
 
359
381
  不确定示例：
382
+
360
383
  ```markdown
361
384
  **数据权限：**
385
+
362
386
  - 是否访问业务数据：是
363
387
  - 是否需要数据权限：不确定
364
388
  - 不确定原因：PRD 未说明该列表是否按组织/商户/运营主体隔离
@@ -377,6 +401,7 @@ curl -s -X POST "http://localhost:{port}{context-path}/api/..." \
377
401
  ### 6.3 不做数据权限的说明
378
402
 
379
403
  如果某个接口不做数据权限，必须说明原因，例如：
404
+
380
405
  - 公开字典/枚举/配置接口
381
406
  - 无业务敏感数据
382
407
  - 只返回当前用户上下文
@@ -410,9 +435,18 @@ D. 复用某个已有接口的数据权限规则，请指定参考接口
410
435
  ```markdown
411
436
  ### 外部依赖契约
412
437
 
413
- | # | 依赖名称 | 类型 | SDK 版本 | 参数来源 | 字段含义 | 成功响应样例 | 失败响应样例 | 阻塞时的处理 |
414
- |---|---|---|---|---|---|---|---|---|
415
- | 1 | XX SDK | Java SDK | 1.2.3 | 页面表单提交 -> DTO -> SDK Request | appId: 应用ID | {"code":0,"data":{...}} | {"code":500,"message":"timeout"} | 记录阻塞证据，标记外部阻塞 |
438
+ | # | 依赖名称 | 类型 | SDK 版本 | 参数来源 | 字段含义 | 成功响应样例 | 失败响应样例 | 阻塞时的处理 |
439
+ | --- | -------- | -------- | -------- | ---------------------------------- | ------------- | ----------------------- | -------------------------------- | -------------------------- |
440
+ | 1 | XX SDK | Java SDK | 1.2.3 | 页面表单提交 -> DTO -> SDK Request | appId: 应用ID | {"code":0,"data":{...}} | {"code":500,"message":"timeout"} | 记录阻塞证据，标记外部阻塞 |
441
+
442
+ ### 外部枚举绑定确认
443
+
444
+ 涉及第三方、SDK、BEM/停车系统、支付/退款、财务展示、来源字段、状态同步、
445
+ 外部字典或外部枚举时必须填写。未确认的枚举值不得进入实现。
446
+
447
+ | 业务字段 | 本系统真源字段/枚举 | 外部系统字段 | 外部枚举/字典值 | 展示文案/业务语义/财务语义 | 取值来源 | owner/确认时间 | 不确定项/阻塞处理 | 测试证据 |
448
+ | -------- | ------------------- | ------------ | --------------- | -------------------------- | --------------------------------- | -------------- | ---------------------- | ------------------------- |
449
+ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | 文档 / 日志 / 接口样例 / 用户确认 | \_\_\_\_ | 无 / Blocked: \_\_\_\_ | tests.md / test-report.md |
416
450
  ```
417
451
 
418
452
  ### 外部依赖红线
@@ -421,11 +455,13 @@ D. 复用某个已有接口的数据权限规则，请指定参考接口
421
455
  - SDK 版本变更必须记录原因和影响范围。
422
456
  - 真实环境可用时，不得仅用 mock 代替。必须在 tests.md 记录真实请求/响应。
423
457
  - 外部服务不可用时，只能标记为"外部阻塞"或"Mock 验证"，不得宣称真实链路通过。
458
+ - 不得用"请求成功"、"值非空"、"字段存在"替代外部枚举业务语义确认。
459
+ - 未经 owner 确认，不得自造外部枚举值、支付来源、财务展示含义或兜底映射。
424
460
 
425
461
  ---
426
462
 
427
463
  ## 8. 接口变更记录
428
464
 
429
- | 版本 | 日期 | 变更内容 | 影响范围 |
430
- |------|------|----------|----------|
431
- | v1.0 | 2026-05-09 | 初始版本 | 全部 |
465
+ | 版本 | 日期 | 变更内容 | 影响范围 |
466
+ | ---- | ---------- | -------- | -------- |
467
+ | v1.0 | 2026-05-09 | 初始版本 | 全部 |