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

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 (4) hide show
  1. package/.6aspec/rules/brown/brown_design_sop.md +54 -13
  2. package/.6aspec/rules/brown/brown_specs_sop.md +45 -12
  3. package/.6aspec/rules/brown/brown_tasks_sop.md +1 -1
  4. package/package.json +1 -1
package/.6aspec/rules/brown/brown_design_sop.md CHANGED
@@ -2,9 +2,9 @@
2
2
 
3
3
  技术方案设计（Design）- 适用于所有流程级别
4
4
 
5
- > **阶段定位**：Design 的目标是输出“可评审的技术蓝图”，聚焦模块划分、服务边界、数据模型、事件流、集成方案与迁移/兼容策略。
6
- > - ✅ 写：架构与模块边界、关键决策（可含 ADR）、数据语义与演进策略、事件流与幂等语义、集成点与失败边界、迁移/兼容/灰度/回滚策略、风险与验证方式。
7
- > - ❌ 不写：具体代码实现说明（类/方法/注解/代码片段）、前端逐字段交互表、API 具体出入参字段清单（放 Tasks）、存量表改动的全量 DDL（放 Tasks）。
5
+ > **阶段定位**：Design 的目标是输出”可评审的技术蓝图”，聚焦模块划分、服务边界、数据模型、接口/入口规范、集成方案与迁移/兼容策略。
6
+ > - ✅ 写：架构与模块边界、关键决策（可含 ADR）、数据语义与演进策略、接口/入口规范（含幂等/并发/异常语义）、集成点与失败边界、迁移/兼容/灰度/回滚策略、风险与验证方式。
7
+ > - ❌ 不写：具体代码实现说明（类/方法/注解/代码片段/伪代码）、前端逐字段交互表、API 具体出入参字段清单（放 Tasks）、存量表改动的全量 DDL（放 Tasks）。
8
8
  > - ✅ 例外：**若新增数据库表**，Design 必须给出 DDL（用于评审关键约束与整体形态）。
9
9
 
10
10
  **输入**：`/6aspec:brown:design` 后可选需求名称。
@@ -78,12 +78,53 @@
78
78
  - 谁发布事件、谁消费事件
79
79
  - 明确失败边界与业务表现（例如：失败是否允许重试、是否需要补偿或人工介入）
80
80
 
81
- 6. **事件流（Event Flow）**
81
+ 6. **接口/入口规范（Entrypoints Design）**
82
82
 
83
- - 覆盖 Specs 中的触发类型：用户操作｜系统事件｜定时任务｜外部系统触发
84
- - 定义关键事件流：触发 → 处理 → 状态变化 → 后续事件/通知
85
- - 定义事件/触发的业务幂等语义（重复投递/重复触发时的业务表现）
86
- - 定义关键一致性要求（强一致/最终一致）与边界（原则级）
83
+ 将 Specs 中的触发类型映射为对应的技术入口，按入口类型分表格输出。**只设计本需求实际存在的入口类型，未涉及的直接省略，不要为了完整性补齐。**
84
+
85
+ **Specs 触发类型 → 技术入口映射**：
86
+
87
+ | Specs 触发类型 | Design 技术入口 |
88
+ |---|---|
89
+ | 用户操作 | REST API（Command API） |
90
+ | 外部系统触发 | REST API（Command API，对外暴露） |
91
+ | 事件订阅 | Event Subscribers |
92
+ | 定时任务 | Scheduled Tasks |
93
+
94
+ > 注意：后台任务（@Async 线程池异步执行）不是独立触发类型，而是某个入口内部的执行机制。若某个 API 或事件处理中存在后台任务，在对应入口的"执行逻辑"列中说明，并在下方单独列出后台任务表格。
95
+
96
+ #### REST API（Command API）
97
+ 对应 Specs 触发类型：用户操作 / 外部系统触发
98
+
99
+ | 名称 | URL | Method | 执行逻辑（步骤级） | 幂等设计 | 并发控制 | 边界与异常 | 性能考虑 |
100
+ |---|---|---|---|---|---|---|---|
101
+ | <接口名称> | /xxx/xxx | POST | 1. 权限校验<br>2. 状态校验<br>3. 状态流转<br>4. 发布领域事件 | <幂等方案> | <并发控制方案> | <异常场景> | <性能要求> |
102
+
103
+ *注意：URL 不使用路径变量；入参/出参 JSON 结构放 Tasks 阶段落地。*
104
+
105
+ #### 事件订阅（Event Subscribers）
106
+ 对应 Specs 触发类型：事件订阅
107
+
108
+ | 订阅者名称 | 订阅事件（中+英） | 执行逻辑（步骤级） | 幂等设计 | 并发控制 | 边界与异常 | 性能考虑 | 补偿/重试 |
109
+ |---|---|---|---|---|---|---|---|
110
+ | <订阅者名称> | <事件中文名>（EventName） | 1. ...<br>2. ... | <幂等方案> | <并发控制> | <异常场景> | <性能要求> | <重试策略> |
111
+
112
+ #### 定时任务（Scheduled Tasks）
113
+ 对应 Specs 触发类型：定时任务
114
+
115
+ | 任务名称 | Trigger（Cron/间隔） | 执行逻辑（步骤级） | 幂等设计 | 并发控制 | 边界与异常 | 性能考虑 | 补偿/重试 |
116
+ |---|---|---|---|---|---|---|---|
117
+ | <任务名称> | <Cron 表达式> | 1. ...<br>2. ... | <幂等方案> | <并发控制> | <异常场景> | <性能要求> | <重试策略> |
118
+
119
+ #### 后台任务（Async Background Job）
120
+ 适用于：某个入口内部将耗时/可重试逻辑投递到线程池异步执行（如 @Async）
121
+
122
+ | 任务名称 | 投递来源/时机 | 任务载荷（仅 ID） | 执行逻辑（步骤级） | 幂等设计 | 并发控制 | 边界与异常 | 性能考虑 | 补偿/重试 |
123
+ |---|---|---|---|---|---|---|---|---|
124
+ | <任务名称> | <哪个入口/何时投递> | <entityId 等> | 1. ...<br>2. ... | <幂等方案> | <并发控制> | <异常场景> | <性能要求> | <重试策略> |
125
+
126
+ **一致性要求**：
127
+ - 明确各入口的关键一致性要求（强一致/最终一致）与边界（原则级）
87
128
 
88
129
  7. **集成方案（Integration）**
89
130
 
@@ -171,7 +212,7 @@
171
212
  - 背景与目标 / 非目标
172
213
  - 模块划分
173
214
  - 服务边界
174
- - 事件流
215
+ - 接口/入口规范（REST API / 事件订阅 / 定时任务 / 后台任务）
175
216
  - 集成方案
176
217
  - 数据模型与数据库方案（新增表附 DDL）
177
218
  - 迁移 / 兼容 / 灰度 / 回滚
@@ -260,7 +301,7 @@
260
301
  ### 方案概要
261
302
  - 模块划分：<数量> 个模块（新增/调整：<数量>）
262
303
  - 服务边界：<数量> 个关键边界/所有权确认
263
- - 事件流：<数量> 条关键链路（含触发类型覆盖）
304
+ - 接口/入口：<数量> 个（REST API / 事件订阅 / 定时任务 / 后台任务，按需）
264
305
  - 集成点：<数量> 个（外部/内部）
265
306
  - 迁移/兼容：<是否需要 + 简述>
266
307
 
@@ -287,7 +328,7 @@
287
328
  ### 方案概要
288
329
  - 模块划分：<...>
289
330
  - 服务边界：<...>
290
- - 事件流：<...>
331
+ - 接口/入口：<...>
291
332
  - 集成点：<...>
292
333
  - 数据模型：<新增表/改表概览；新增表 DDL：<有/无>>
293
334
  - 迁移/兼容：<策略摘要>
@@ -321,8 +362,8 @@
321
362
  ## 防护措施
322
363
 
323
364
  - 所有流程级别：必须先完成 specs 阶段（`phases.specs == done`）
324
- - Design 文档必须覆盖：模块划分、服务边界、事件流、集成方案、数据模型、迁移/兼容、风险与验证
325
- - **禁止**：把 Design 写成实现说明（代码片段、注解、方法级实现、前端逐字段交互、API 出入参字段清单等）
365
+ - Design 文档必须覆盖：模块划分、服务边界、接口/入口规范、集成方案、数据模型、迁移/兼容、风险与验证
366
+ - **禁止**：把 Design 写成实现说明（代码片段、注解、方法级实现、伪代码、前端逐字段交互、API 出入参字段清单等）
326
367
  - **新增表**：必须提供 DDL；**改表**：不得在 Design 展开全量 DDL（放 Tasks）
327
368
  - 涉及关键架构决策时必须创建 ADR（技术选型、集成方案、一致性策略等）
328
369
  - 标准级/完整级：技术债务应明确标注（如有）
package/.6aspec/rules/brown/brown_specs_sop.md CHANGED
@@ -68,7 +68,36 @@
68
68
  - 如果前置文档（proposal、understanding、impact）已经提供了足够信息，可以跳过探索
69
69
  - 探索应该聚焦、快速，避免过度探索
70
70
 
71
- 5. **基于 Capabilities 定义功能需求**
71
+ 5. **明确 Key Entities 和 Business Rules**
72
+
73
+ 在定义功能需求之前，先从前置文档中识别业务对象和业务规则，作为后续需求定义的"词汇表"和"约束基础"。
74
+
75
+ **Key Entities（关键业务对象）**：
76
+ - 识别本次需求涉及的核心业务对象（不是数据库表，是业务概念）
77
+ - 明确每个实体的含义、关键属性口径、状态流转和与其他实体的关系
78
+ - 避免写数据库字段类型、类名等技术细节
79
+
80
+ **Business Rules（业务规则）**：
81
+ - 识别业务上必须成立的约束/推导规则（与实现无关）
82
+ - 按 Capability 分类组织，全局规则（跨 Capability）放在"通用规则"分类下
83
+ - 规则描述格式：条件 → 结果，或直接描述约束
84
+
85
+ **Business Rules 组织格式**：
86
+ ```markdown
87
+ ### 通用规则
88
+ - BR-001：<跨 Capability 的全局约束>
89
+
90
+ ### Capability: <capability-name>
91
+ - BR-002：<该能力特有的约束>
92
+ - BR-003：<该能力特有的约束>
93
+ ```
94
+
95
+ **注意**：
96
+ - 如果某个 Capability 没有特有规则，不需要单独列出
97
+ - 如果所有规则都是全局的，只写"通用规则"即可
98
+ - Business Rules 是业务约束，不是技术约束（技术约束放非功能需求）
99
+
100
+ 6. **基于 Capabilities 定义功能需求**
72
101
 
73
102
  从 proposal.md 中读取 Capabilities 列表，按 Capability 组织功能需求：
74
103
 
@@ -88,7 +117,7 @@
88
117
 
89
118
  ##### Scenario: <场景名称>
90
119
 
91
- - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
120
+ - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
92
121
  - **GIVEN** <前置条件（业务对象状态/权限/已有数据/开关等）>
93
122
  - **WHEN** <触发动作>
94
123
  - **THEN** <预期结果>
@@ -96,7 +125,7 @@
96
125
 
97
126
  ##### Scenario: <另一个场景名称>
98
127
 
99
- - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
128
+ - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
100
129
  - **GIVEN** <前置条件>
101
130
  - **WHEN** <触发动作>
102
131
  - **THEN** <预期结果>
@@ -110,7 +139,7 @@
110
139
 
111
140
  ##### Scenario: <场景名称>
112
141
 
113
- - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
142
+ - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
114
143
  - **GIVEN** <前置条件>
115
144
  - **WHEN** <触发动作>
116
145
  - **THEN** <预期结果>
@@ -122,7 +151,7 @@
122
151
  - 每个 Capability 下包含多个 Requirements
123
152
  - 每个 Requirement 应该是独立的、可验证的
124
153
  - 每个 Requirement SHOULD 显式列出验收标准（AC），用于快速评审覆盖面与边界
125
- - 每个 Scenario MUST 包含：触发类型 + GIVEN/WHEN/THEN（AND 可选）；触发类型只能从「用户操作｜系统事件｜定时任务｜外部系统触发」中选择
154
+ - 每个 Scenario MUST 包含：触发类型 + GIVEN/WHEN/THEN（AND 可选）；触发类型只能从「用户操作｜外部系统触发｜事件订阅｜定时任务」中选择
126
155
  - 使用 SHALL/MUST 关键字表示强制性要求，SHOULD 表示推荐性要求
127
156
  - 功能需求应该从用户视角描述（做什么，而不是怎么做）
128
157
  - 避免技术实现细节（技术细节放在 design 阶段）
@@ -226,10 +255,13 @@
226
255
 
227
256
  ## 3. Business Rules（业务规则）
228
257
 
229
- > 业务上必须成立的约束/推导规则（与实现无关）。
258
+ > 业务上必须成立的约束/推导规则（与实现无关）。按 Capability 分类，跨 Capability 的全局规则放在"通用规则"下。
259
+
260
+ ### 通用规则
261
+ - BR-001：<跨 Capability 的全局约束>
230
262
 
231
- - BR-001：<规则描述（条件/结果）>
232
- - BR-002：<规则描述>
263
+ ### Capability: <capability-name>
264
+ - BR-002：<该能力特有的约束>
233
265
 
234
266
  ## 4. 功能需求
235
267
 
@@ -247,7 +279,7 @@
247
279
 
248
280
  ##### Scenario: <场景名称>
249
281
 
250
- - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
282
+ - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
251
283
  - **GIVEN** <前置条件（业务对象状态/权限/已有数据/开关等）>
252
284
  - **WHEN** <触发动作>
253
285
  - **THEN** <预期结果>
@@ -255,7 +287,7 @@
255
287
 
256
288
  ##### Scenario: <另一个场景名称>
257
289
 
258
- - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
290
+ - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
259
291
  - **GIVEN** <前置条件>
260
292
  - **WHEN** <触发动作>
261
293
  - **THEN** <预期结果>
@@ -269,7 +301,7 @@
269
301
 
270
302
  ##### Scenario: <场景名称>
271
303
 
272
- - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
304
+ - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
273
305
  - **GIVEN** <前置条件>
274
306
  - **WHEN** <触发动作>
275
307
  - **THEN** <预期结果>
@@ -287,7 +319,7 @@
287
319
 
288
320
  ##### Scenario: <场景名称>
289
321
 
290
- - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
322
+ - **触发类型** 用户操作｜外部系统触发｜事件订阅｜定时任务
291
323
  - **GIVEN** <前置条件>
292
324
  - **WHEN** <触发动作>
293
325
  - **THEN** <预期结果>
@@ -478,6 +510,7 @@
478
510
  - 每个 Capability 必须标识变更类型：[ADD]（新增）、[MODIFY]（修改）、[REMOVE]（移除）
479
511
  - 每个 Capability 应该对应 proposal.md 中的一个能力
480
512
  - 功能需求必须使用 Requirement + Scenario (WHEN/THEN) 格式
513
+ - 每个 Scenario 的触发类型只能从「用户操作｜外部系统触发｜事件订阅｜定时任务」中选择
481
514
  - 使用 SHALL/MUST 表示强制性要求，SHOULD 表示推荐性要求
482
515
  - 每个 Scenario 必须可测试、可验证
483
516
  - 功能需求必须从用户视角描述，避免技术实现细节
package/.6aspec/rules/brown/brown_tasks_sop.md CHANGED
@@ -93,7 +93,7 @@ Phase 4: 任务拆解与排期
93
93
 
94
94
  ## 输入
95
95
  - specs.md：<引用相关 Capability/Requirement/AC/Scenario>
96
- - design.md：<引用相关模块/边界/事件流/集成/迁移策略>
96
+ - design.md：<引用相关模块/边界/接口入口规范/集成/迁移策略>
97
97
 
98
98
  ## 输出
99
99
  - <代码/脚本/配置/文档/验证产物>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "6aspec",
3
- "version": "2.0.0-dev.29",
3
+ "version": "2.0.0-dev.30",
4
4
  "description": "6Aspec - 轻量级 spec 驱动开发框架，支持 Cursor 和 Claude Code",
5
5
  "main": "lib/installer.js",
6
6
  "bin": {