6aspec 2.0.0-dev.27 → 2.0.0-dev.29

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 (6) hide show
  1. package/.6aspec/rules/brown/brown_design_sop.md +188 -155
  2. package/.6aspec/rules/brown/brown_implement_sop.md +88 -46
  3. package/.6aspec/rules/brown/brown_proposal_sop.md +17 -25
  4. package/.6aspec/rules/brown/brown_specs_sop.md +65 -56
  5. package/.6aspec/rules/brown/brown_tasks_sop.md +196 -80
  6. package/package.json +1 -1
package/.6aspec/rules/brown/brown_design_sop.md CHANGED
@@ -1,17 +1,23 @@
1
1
  # 棕地需求 - Design SOP
2
2
 
3
- 技术方案设计 - 适用于所有流程级别
3
+ 技术方案设计（Design）- 适用于所有流程级别
4
+
5
+ > **阶段定位**：Design 的目标是输出“可评审的技术蓝图”，聚焦模块划分、服务边界、数据模型、事件流、集成方案与迁移/兼容策略。
6
+ > - ✅ 写：架构与模块边界、关键决策（可含 ADR）、数据语义与演进策略、事件流与幂等语义、集成点与失败边界、迁移/兼容/灰度/回滚策略、风险与验证方式。
7
+ > - ❌ 不写：具体代码实现说明（类/方法/注解/代码片段）、前端逐字段交互表、API 具体出入参字段清单（放 Tasks）、存量表改动的全量 DDL（放 Tasks）。
8
+ > - ✅ 例外：**若新增数据库表**，Design 必须给出 DDL（用于评审关键约束与整体形态）。
4
9
 
5
10
  **输入**：`/6aspec:brown:design` 后可选需求名称。
6
11
 
7
- **步骤**
12
+ ---
13
+
14
+ ## 步骤
8
15
 
9
16
  1. **选择需求并检查状态**
10
17
 
11
18
  - 读取 `6aspecdoc/brown/<name>/status.json`
12
- - 根据 `flowDepth` 检查前置阶段：
13
- - **轻量级**：确认 `phases.specs` 为 "done"，如果未完成提示先运行 `/6aspec:brown:specs`
14
- - **标准级/完整级**：确认 `phases.specs` 为 "done"，如果未完成提示先运行 `/6aspec:brown:specs`
19
+ - 检查前置阶段：
20
+ - 所有流程级别：确认 `phases.specs` 为 "done"；如未完成，提示先运行 `/6aspec:brown:specs`
15
21
 
16
22
  2. **读取前置文档**
17
23
 
@@ -20,8 +26,10 @@
20
26
  **轻量级流程**：
21
27
  - `6aspecdoc/brown/<name>/artifacts/proposal.md`
22
28
  - `6aspecdoc/brown/<name>/artifacts/specs.md`
29
+ - `6aspecdoc/brown/<name>/explore-summary.md` - 探索摘要（如果存在）
23
30
 
24
31
  **标准级/完整级流程**：
32
+ - `6aspecdoc/brown/<name>/artifacts/proposal.md`
25
33
  - `6aspecdoc/brown/<name>/artifacts/specs.md`
26
34
  - `6aspecdoc/brown/<name>/artifacts/understanding.md`
27
35
  - `6aspecdoc/brown/<name>/artifacts/impact-analysis.md`
@@ -29,79 +37,93 @@
29
37
  3. **按需探索代码库（可选）**
30
38
 
31
39
  **触发条件**：
32
- - 需要了解现有架构模式、技术选型
33
- - 需要了解现有的数据库设计模式（如字段类型、索引策略）
34
- - 需要了解现有的前端组件和交互模式
35
- - 需要了解现有的测试框架和测试模式
40
+ - 需要了解现有架构模式、技术选型、模块边界与集成点
41
+ - 需要了解现有的事件/定时/回调处理方式（幂等、重试、补偿）
42
+ - 需要确认数据落库策略、迁移方式（但不在此阶段写实现）
36
43
  - 用户明确要求探索（例如："先了解一下现有架构"）
37
- - 信息不足，需要参考现有代码才能设计准确的技术方案
44
+ - 信息不足，需要参考现有代码才能做出可评审的方案决策
38
45
 
39
46
  **探索方式**：
40
47
 
41
- a. **简单搜索**（使用Grep/Glob工具）：
42
- ```bash
43
- # 搜索相关Service类的实现模式
44
- rg "class.*Service" --type java -g "*Service.java"
45
-
46
- # 搜索相关Controller类的实现模式
47
- rg "class.*Controller" --type java -g "*Controller.java"
48
-
49
- # 搜索配置文件
50
- rg "spring.datasource|mybatis" --type yaml -g "*.yml"
51
-
52
- # 搜索测试框架使用
53
- rg "@Test|@SpringBootTest" --type java -g "*Test.java"
48
+ a. **简单搜索**（使用 Grep/Glob 工具）：
49
+ - 搜索现有服务/模块边界：pattern = `class.*Service|interface.*Service`，type = `java`
50
+ - 搜索 Controller/接口入口：pattern = `class.*Controller`，type = `java`
51
+ - 搜索事件/消息相关：pattern = `Event|Message|Consumer|Producer`（按项目实际关键字调整）
52
+ - 搜索定时任务：pattern = `@Scheduled|cron`（按项目实际关键字调整）
53
+ - 搜索外部回调/集成：pattern = `callback|webhook|client`（按项目实际关键字调整）
54
54
 
55
- # 搜索前端组件
56
- rg "export.*component" --type typescript -g "*.tsx"
57
- ```
58
-
59
- b. **复杂探索**（使用Task工具调用Explore agent）：
60
- - 当需要深入理解现有架构模式时
61
- - 当需要跨多个文件理解技术选型时
62
- - 当需要了解复杂的集成方案时
55
+ b. **复杂探索**（使用 Task 工具调用 Explore agent）：
56
+ - 当需要跨多个文件理解现有架构模式、集成链路、事件流与一致性策略时
63
57
 
64
58
  **探索结果处理**：
65
59
  - 探索发现直接用于技术方案设计
66
60
  - 不生成独立文档
67
- - 在design.md中可以标注"参考现有实现：<文件路径>"
61
+ - 在 `design.md` 中可以标注 "参考现有实现：<文件路径>"（仅用于佐证方案合理性）
68
62
 
69
63
  **注意**：
70
64
  - 探索是可选的，不是强制的
71
- - 如果前置文档（specs、understanding、impact）已经提供了足够信息，可以跳过探索
72
- - 探索应该聚焦、快速，避免过度探索
73
- - 重点关注架构模式、技术选型、实现风格，而不是具体业务逻辑
65
+ - 探索应聚焦架构模式、边界与关键决策，不展开实现细节
66
+
67
+ 4. **模块划分（Module Decomposition）**
68
+
69
+ - 列出本次变更涉及的模块/子系统（现有/新增）
70
+ - 明确每个模块的职责边界（1-3 条即可）
71
+ - 明确模块之间的依赖关系（调用/事件订阅/数据依赖）
72
+
73
+ 5. **服务边界（Service Boundaries）**
74
+
75
+ - 明确服务（或领域/应用层边界）以及所有权：
76
+ - 谁拥有数据（source of truth）
77
+ - 谁负责状态流转
78
+ - 谁发布事件、谁消费事件
79
+ - 明确失败边界与业务表现（例如：失败是否允许重试、是否需要补偿或人工介入）
74
80
 
75
- 4. **设计数据库变更方案**
81
+ 6. **事件流（Event Flow）**
76
82
 
77
- - 字段名、类型、约束
78
- - 默认值和历史数据处理
79
- - 索引建议
80
- - 数据迁移脚本（如需要）
83
+ - 覆盖 Specs 中的触发类型：用户操作｜系统事件｜定时任务｜外部系统触发
84
+ - 定义关键事件流：触发 → 处理 → 状态变化 → 后续事件/通知
85
+ - 定义事件/触发的业务幂等语义（重复投递/重复触发时的业务表现）
86
+ - 定义关键一致性要求（强一致/最终一致）与边界（原则级）
81
87
 
82
- 5. **设计代码实现方案**
88
+ 7. **集成方案（Integration）**
83
89
 
84
- - 实体类字段添加（含注解）
85
- - 业务逻辑实现（含关键代码示例）
86
- - 校验逻辑（必填、值域、约束）
87
- - 错误提示（使用多语言资源）
90
+ - 列出所有集成点（外部系统/内部系统/第三方回调/消息系统等）
91
+ - 明确集成方式与责任边界：
92
+ - 同步调用 / 异步事件 / 回调驱动
93
+ - 认证与鉴权（策略级）
94
+ - 超时/失败/重试的业务语义（不写具体参数）
95
+ - 明确可观测性要求：必须能追踪一次处理的触发来源与处理结果（用于排障与验收）
88
96
 
89
- 6. **设计前端 UI 方案**
97
+ > 注意：API/回调的**具体出入参字段清单**放在 Tasks 阶段落地；Design 只描述“接口/事件的语义与契约要点”。
90
98
 
91
- - 各页面字段状态（可编辑/只读/隐藏）
92
- - 交互逻辑（下拉选择、提示信息）
93
- - 错误提示
94
- - 多语言支持
99
+ 8. **数据模型与数据库方案（Data Model & DB Plan）**
95
100
 
96
- 7. **设计测试方案**
101
+ - 对齐 Specs 的 Key Entities：说明关键业务对象如何落库（表级）
102
+ - 列出受影响的表清单（新增/修改/废弃）与改动原因（业务语义）
103
+ - 明确关键数据约束（唯一性、关联关系、审计字段、幂等关联键等）
97
104
 
98
- - 单元测试（函数级别）
99
- - 集成测试（流程级别）
100
- - 数据一致性验证（SQL 验证）
105
+ **DDL 要求**：
106
+ - **新增表**：必须在 Design 中给出 DDL（CREATE TABLE），用于评审整体形态与关键约束
107
+ - **修改存量表**：Design 只写“字段语义/约束/迁移策略”；具体 ALTER、索引、脚本与校验 SQL 放 Tasks
101
108
 
102
- 8. **架构决策记录（涉及架构决策时创建）**
109
+ 9. **迁移 / 兼容（Migration / Compatibility）**
103
110
 
104
- 如果需求涉及重要的架构决策（如技术选型、数据模型设计、集成方案等），创建 ADR：
111
+ - 存量数据处理策略：回填/补齐/默认语义/是否允许历史数据为空
112
+ - 兼容性策略：
113
+ - 行为兼容（旧流程是否变化）
114
+ - 数据兼容（新字段对旧逻辑的影响）
115
+ - 集成兼容（外部系统/调用方是否受影响）
116
+ - 发布策略：是否需要灰度/开关（原则级）
117
+ - 回滚策略：回滚对业务与数据的影响（原则级）
118
+
119
+ 10. **风险与验证方式（Risk & Validation）**
120
+
121
+ - 风险清单：列出 3-7 个最关键风险（集成失败、回调乱序/重复、定时重复触发、数据回填错误等）
122
+ - 验证方式：将 Specs 的验收标准（AC）与 Scenarios（GWT）映射为验证矩阵（单元/集成/回归/对账/人工验证），但不在此阶段编写具体用例代码
123
+
124
+ 11. **架构决策记录（涉及关键决策时创建）**
125
+
126
+ 若涉及重要架构决策（技术选型、集成方案、关键一致性策略等），创建 ADR：
105
127
 
106
128
  创建 `6aspecdoc/brown/<name>/artifacts/ADR-<name>.md`：
107
129
  ```markdown
@@ -135,53 +157,85 @@
135
157
  <如何验证这个决策是正确的>
136
158
  ```
137
159
 
138
- 9. **技术债务识别**
139
-
140
- 识别实现过程中可能引入的技术债务：
160
+ 12. **技术债务识别（标准级/完整级推荐）**
141
161
 
142
162
  | 债务ID | 描述 | 类型 | 影响 | 偿还成本 | 优先级 |
143
163
  |--------|------|------|------|----------|--------|
144
- | DEBT-001 | 临时的硬编码逻辑 | 代码质量 | 中 | 2人日 | P1 |
164
+ | DEBT-001 | ... | ... | ... | ... | P1 |
145
165
 
146
- 10. **创建技术方案文档**
166
+ 13. **创建技术方案文档**
147
167
 
148
168
  创建 `6aspecdoc/brown/<name>/artifacts/design.md`
149
169
 
150
- 10. **更新状态**
151
-
152
- 更新 `6aspecdoc/brown/<name>/status.json`：
153
-
154
- **轻量级流程**：
155
- ```json
156
- {
157
- "status": "tasks_pending",
158
- "flowDepth": "lightweight",
159
- "phases": {
160
- "proposal": "done",
161
- "design": "done",
162
- "tasks": "pending",
163
- "implement": "blocked"
164
- },
165
- "artifacts": ["proposal.md", "design.md"]
166
- }
167
- ```
168
-
169
- **标准级/完整级流程**：
170
- ```json
171
- {
172
- "status": "tasks_pending",
173
- "flowDepth": "standard",
174
- "phases": {
175
- "understand": "done",
176
- "specs": "done",
177
- "impact": "done",
178
- "design": "done",
179
- "tasks": "pending",
180
- "implement": "blocked"
181
- },
182
- "artifacts": ["understanding.md", "specs.md", "impact-analysis.md", "design.md"]
183
- }
184
- ```
170
+ 建议结构（可按需裁剪）：
171
+ - 背景与目标 / 非目标
172
+ - 模块划分
173
+ - 服务边界
174
+ - 事件流
175
+ - 集成方案
176
+ - 数据模型与数据库方案（新增表附 DDL）
177
+ - 迁移 / 兼容 / 灰度 / 回滚
178
+ - 风险与验证矩阵
179
+ - ADR 列表（如有）
180
+ - 技术债务（如有）
181
+
182
+ 14. **更新状态**
183
+
184
+ 更新 `6aspecdoc/brown/<name>/status.json`：
185
+
186
+ **轻量级流程**：
187
+ ```json
188
+ {
189
+ "status": "tasks_pending",
190
+ "flowDepth": "lightweight",
191
+ "phases": {
192
+ "proposal": "done",
193
+ "specs": "done",
194
+ "design": "done",
195
+ "tasks": "pending",
196
+ "implement": "blocked"
197
+ },
198
+ "artifacts": ["proposal.md", "specs.md", "design.md"]
199
+ }
200
+ ```
201
+
202
+ **标准级流程**：
203
+ ```json
204
+ {
205
+ "status": "tasks_pending",
206
+ "flowDepth": "standard",
207
+ "phases": {
208
+ "understand": "done",
209
+ "impact": "done",
210
+ "proposal": "done",
211
+ "specs": "done",
212
+ "design": "done",
213
+ "tasks": "pending",
214
+ "implement": "blocked"
215
+ },
216
+ "artifacts": ["understanding.md", "impact-analysis.md", "proposal.md", "specs.md", "design.md"]
217
+ }
218
+ ```
219
+
220
+ **完整级流程**：
221
+ ```json
222
+ {
223
+ "status": "tasks_pending",
224
+ "flowDepth": "complete",
225
+ "phases": {
226
+ "understand": "done",
227
+ "impact": "done",
228
+ "proposal": "done",
229
+ "specs": "done",
230
+ "design": "done",
231
+ "tasks": "pending",
232
+ "implement": "blocked",
233
+ "verify": "blocked",
234
+ "review": "blocked"
235
+ },
236
+ "artifacts": ["understanding.md", "impact-analysis.md", "proposal.md", "specs.md", "design.md"]
237
+ }
238
+ ```
185
239
 
186
240
  同时更新 `6aspecdoc/brown/<name>/requirement.md`：
187
241
  - 更新"状态"字段为 `📋 Tasks 待开始`
@@ -190,29 +244,32 @@
190
244
  - 更新"下一步操作"为 `运行 /6aspec:brown:tasks 继续下一阶段`
191
245
  - 在"进度概览"中标记 Design 阶段为已完成 `[x]`
192
246
 
193
- **输出**
247
+ ---
248
+
249
+ ## 输出
194
250
 
195
- 根据 `flowDepth` 显示不同的输出信息：
251
+ 根据 `flowDepth` 显示不同的输出信息（示例）：
196
252
 
197
253
  **轻量级流程**：
198
254
  ```
199
255
  ## Design 完成：<name>
200
256
 
201
257
  **流程**: 轻量级
202
- **进度**: 2/4 阶段完成
258
+ **进度**: 3/5 阶段完成
203
259
 
204
260
  ### 方案概要
205
- - 数据库变更：<数量> 个表
206
- - 代码变更：<数量> 个类
207
- - 前端变更：<数量> 个页面
208
- - 测试用例：<数量> 个
261
+ - 模块划分：<数量> 个模块（新增/调整：<数量>）
262
+ - 服务边界：<数量> 个关键边界/所有权确认
263
+ - 事件流：<数量> 条关键链路（含触发类型覆盖）
264
+ - 集成点：<数量> 个（外部/内部）
265
+ - 迁移/兼容：<是否需要 + 简述>
209
266
 
210
267
  ### 关键设计决策
211
- <列出 2-3 个关键决策>
268
+ <列出 2-3 个关键决策（含是否创建 ADR）>
212
269
 
213
270
  ### 文档位置
214
271
  - 6aspecdoc/brown/<name>/artifacts/design.md
215
- - 6aspecdoc/brown/<name>/artifacts/ADR-<name>.md (如涉及架构决策)
272
+ - 6aspecdoc/brown/<name>/artifacts/ADR-<name>.md (如涉及)
216
273
 
217
274
  ### 下一步
218
275
  - 直接回复修正设计方案或补充细节 → 我会更新本阶段文档（design.md）
@@ -220,28 +277,28 @@
220
277
  - 运行 `/6aspec:brown:continue` → 自动进入下一阶段
221
278
  ```
222
279
 
223
- **标准级流程**：
280
+ **标准级/完整级流程**：
224
281
  ```
225
282
  ## Design 完成：<name>
226
283
 
227
- **流程**: 标准级
228
- **进度**: 4/6 阶段完成
284
+ **流程**: <标准级/完整级>
285
+ **进度**: <按流程深度计算>
229
286
 
230
287
  ### 方案概要
231
- - 数据库变更：<数量> 个表
232
- - 代码变更：<数量> 个类
233
- - 前端变更：<数量> 个页面
234
- - 测试用例：<数量> 个
288
+ - 模块划分：<...>
289
+ - 服务边界：<...>
290
+ - 事件流：<...>
291
+ - 集成点：<...>
292
+ - 数据模型：<新增表/改表概览；新增表 DDL：<有/无>>
293
+ - 迁移/兼容：<策略摘要>
235
294
 
236
- ### 关键设计决策
237
- <列出 2-3 个关键决策>
238
-
239
- ### 技术债务
240
- <列出识别的技术债务>
295
+ ### 风险与验证
296
+ - 关键风险：<数量>
297
+ - 验证矩阵：已覆盖 Specs 的 AC / Scenarios
241
298
 
242
299
  ### 文档位置
243
300
  - 6aspecdoc/brown/<name>/artifacts/design.md
244
- - 6aspecdoc/brown/<name>/artifacts/ADR-<name>.md (如涉及架构决策)
301
+ - 6aspecdoc/brown/<name>/artifacts/ADR-<name>.md (如涉及)
245
302
 
246
303
  ### 下一步
247
304
  - 直接回复修正设计方案或补充细节 → 我会更新本阶段文档（design.md）
@@ -249,47 +306,23 @@
249
306
  - 运行 `/6aspec:brown:continue` → 自动进入下一阶段
250
307
  ```
251
308
 
252
- **完整级流程**：
253
- ```
254
- ## Design 完成：<name>
255
-
256
- **流程**: 完整级
257
- **进度**: 4/8 阶段完成
258
-
259
- ### 方案概要
260
- - 数据库变更：<数量> 个表
261
- - 代码变更：<数量> 个类
262
- - 前端变更：<数量> 个页面
263
- - 测试用例：<数量> 个
264
-
265
- ### 关键设计决策
266
- <列出 2-3 个关键决策>
267
-
268
- ### 技术债务
269
- <列出识别的技术债务>
270
-
271
- ### 文档位置
272
- - 6aspecdoc/brown/<name>/artifacts/design.md
273
- - 6aspecdoc/brown/<name>/artifacts/ADR-<name>.md (如涉及架构决策)
274
-
275
- ### 下一步
276
- - 直接回复修正设计方案或补充细节 → 我会更新本阶段文档（design.md）
277
- - 运行 `/6aspec:brown:tasks` → 进入任务拆解阶段
278
- - 运行 `/6aspec:brown:continue` → 自动进入下一阶段
279
- ```
309
+ ---
280
310
 
281
- **用户补充信息时的处理**
311
+ ## 用户补充信息时的处理
282
312
 
283
- 当用户修正设计方案、补充技术细节、或对设计决策提出异议时（未使用阶段命令）：
313
+ 当用户修正设计方案、补充决策信息、或对设计决策提出异议时（未使用阶段命令）：
284
314
  1. 将用户的修正/补充整合到 `design.md` 的对应章节
285
315
  2. 展示变更摘要
286
316
  3. 再次提示：可以继续补充，或通过命令进入下一阶段
287
317
  4. **禁止**：不得自动进入下一阶段
288
318
 
289
- **防护措施**
290
- - 根据 `flowDepth` 检查前置阶段：
291
- - **轻量级**：必须先完成 proposal 阶段
292
- - **标准级/完整级**：必须先完成 impact 阶段
293
- - 涉及架构决策时必须创建 ADR（如技术选型、数据模型设计、集成方案等）
294
- - 代码示例必须完整可用
295
- - 技术债务必须明确标注（标准级/完整级）
319
+ ---
320
+
321
+ ## 防护措施
322
+
323
+ - 所有流程级别：必须先完成 specs 阶段（`phases.specs == done`）
324
+ - Design 文档必须覆盖：模块划分、服务边界、事件流、集成方案、数据模型、迁移/兼容、风险与验证
325
+ - **禁止**：把 Design 写成实现说明（代码片段、注解、方法级实现、前端逐字段交互、API 出入参字段清单等）
326
+ - **新增表**：必须提供 DDL；**改表**：不得在 Design 展开全量 DDL（放 Tasks）
327
+ - 涉及关键架构决策时必须创建 ADR（技术选型、集成方案、一致性策略等）
328
+ - 标准级/完整级：技术债务应明确标注（如有）