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

package/.6aspec/rules/brown/brown_design_sop.md

@@ -1,54 +1,170 @@
 # 棕地需求 - Design SOP
 
-Phase 3: 技术方案设计
+技术方案设计（Design）- 适用于所有流程级别
+
+> **阶段定位**：Design 的目标是输出”可评审的技术蓝图”，聚焦模块划分、服务边界、数据模型、接口/入口规范、集成方案与迁移/兼容策略。
+> - ✅ 写：架构与模块边界、关键决策（可含 ADR）、数据语义与演进策略、接口/入口规范（含幂等/并发/异常语义）、集成点与失败边界、迁移/兼容/灰度/回滚策略、风险与验证方式。
+> - ❌ 不写：具体代码实现说明（类/方法/注解/代码片段/伪代码）、前端逐字段交互表、API 具体出入参字段清单（放 Tasks）、存量表改动的全量 DDL（放 Tasks）。
+> - ✅ 例外：**若新增数据库表**，Design 必须给出 DDL（用于评审关键约束与整体形态）。
 
 **输入**：`/6aspec:brown:design` 后可选需求名称。
 
-**步骤**
+---
+
+## 步骤
 
 1. **选择需求并检查状态**
 
    - 读取 `6aspecdoc/brown/<name>/status.json`
-   - 确认 `phases.impact` 为 "done"
-   - 如果未完成 Phase 2，提示先运行 `/6aspec:brown:impact`
+   - 检查前置阶段：
+     - 所有流程级别：确认 `phases.specs` 为 "done"；如未完成，提示先运行 `/6aspec:brown:specs`
 
 2. **读取前置文档**
 
-   - `6aspecdoc/brown/<name>/requirement.md`
-   - `6aspecdoc/brown/<name>/artifacts/01-understanding.md`
-   - `6aspecdoc/brown/<name>/artifacts/01.5-specs.md`（标准级/完整级）
-   - `6aspecdoc/brown/<name>/artifacts/02-impact-analysis.md`
+   根据 `flowDepth` 读取不同的前置文档：
+
+   **轻量级流程**：
+   - `6aspecdoc/brown/<name>/artifacts/proposal.md`
+   - `6aspecdoc/brown/<name>/artifacts/specs.md`
+   - `6aspecdoc/brown/<name>/explore-summary.md` - 探索摘要（如果存在）
+
+   **标准级/完整级流程**：
+   - `6aspecdoc/brown/<name>/artifacts/proposal.md`
+   - `6aspecdoc/brown/<name>/artifacts/specs.md`
+   - `6aspecdoc/brown/<name>/artifacts/understanding.md`
+   - `6aspecdoc/brown/<name>/artifacts/impact-analysis.md`
+
+3. **按需探索代码库（可选）**
+
+   **触发条件**：
+   - 需要了解现有架构模式、技术选型、模块边界与集成点
+   - 需要了解现有的事件/定时/回调处理方式（幂等、重试、补偿）
+   - 需要确认数据落库策略、迁移方式（但不在此阶段写实现）
+   - 用户明确要求探索（例如："先了解一下现有架构"）
+   - 信息不足，需要参考现有代码才能做出可评审的方案决策
+
+   **探索方式**：
+
+   a. **简单搜索**（使用 Grep/Glob 工具）：
+   - 搜索现有服务/模块边界：pattern = `class.*Service|interface.*Service`，type = `java`
+   - 搜索 Controller/接口入口：pattern = `class.*Controller`，type = `java`
+   - 搜索事件/消息相关：pattern = `Event|Message|Consumer|Producer`（按项目实际关键字调整）
+   - 搜索定时任务：pattern = `@Scheduled|cron`（按项目实际关键字调整）
+   - 搜索外部回调/集成：pattern = `callback|webhook|client`（按项目实际关键字调整）
+
+   b. **复杂探索**（使用 Task 工具调用 Explore agent）：
+   - 当需要跨多个文件理解现有架构模式、集成链路、事件流与一致性策略时
+
+   **探索结果处理**：
+   - 探索发现直接用于技术方案设计
+   - 不生成独立文档
+   - 在 `design.md` 中可以标注 "参考现有实现：<文件路径>"（仅用于佐证方案合理性）
+
+   **注意**：
+   - 探索是可选的，不是强制的
+   - 探索应聚焦架构模式、边界与关键决策，不展开实现细节
+
+4. **模块划分（Module Decomposition）**
+
+   - 列出本次变更涉及的模块/子系统（现有/新增）
+   - 明确每个模块的职责边界（1-3 条即可）
+   - 明确模块之间的依赖关系（调用/事件订阅/数据依赖）
+
+5. **服务边界（Service Boundaries）**
+
+   - 明确服务（或领域/应用层边界）以及所有权：
+     - 谁拥有数据（source of truth）
+     - 谁负责状态流转
+     - 谁发布事件、谁消费事件
+   - 明确失败边界与业务表现（例如：失败是否允许重试、是否需要补偿或人工介入）
+
+6. **接口/入口规范（Entrypoints Design）**
+
+   将 Specs 中的触发类型映射为对应的技术入口，按入口类型分表格输出。**只设计本需求实际存在的入口类型，未涉及的直接省略，不要为了完整性补齐。**
+
+   **Specs 触发类型 → 技术入口映射**：
+
+   | Specs 触发类型 | Design 技术入口 |
+   |---|---|
+   | 用户操作 | REST API（Command API） |
+   | 外部系统触发 | REST API（Command API，对外暴露） |
+   | 事件订阅 | Event Subscribers |
+   | 定时任务 | Scheduled Tasks |
+
+   > 注意：后台任务（@Async 线程池异步执行）不是独立触发类型，而是某个入口内部的执行机制。若某个 API 或事件处理中存在后台任务，在对应入口的"执行逻辑"列中说明，并在下方单独列出后台任务表格。
+
+   #### REST API（Command API）
+   对应 Specs 触发类型：用户操作 / 外部系统触发
+
+   | 名称 | URL | Method | 执行逻辑（步骤级） | 幂等设计 | 并发控制 | 边界与异常 | 性能考虑 |
+   |---|---|---|---|---|---|---|---|
+   | <接口名称> | /xxx/xxx | POST | 1. 权限校验<br>2. 状态校验<br>3. 状态流转<br>4. 发布领域事件 | <幂等方案> | <并发控制方案> | <异常场景> | <性能要求> |
+
+   *注意：URL 不使用路径变量；入参/出参 JSON 结构放 Tasks 阶段落地。*
+
+   #### 事件订阅（Event Subscribers）
+   对应 Specs 触发类型：事件订阅
+
+   | 订阅者名称 | 订阅事件（中+英） | 执行逻辑（步骤级） | 幂等设计 | 并发控制 | 边界与异常 | 性能考虑 | 补偿/重试 |
+   |---|---|---|---|---|---|---|---|
+   | <订阅者名称> | <事件中文名>（EventName） | 1. ...<br>2. ... | <幂等方案> | <并发控制> | <异常场景> | <性能要求> | <重试策略> |
+
+   #### 定时任务（Scheduled Tasks）
+   对应 Specs 触发类型：定时任务
 
-3. **设计数据库变更方案**
+   | 任务名称 | Trigger（Cron/间隔） | 执行逻辑（步骤级） | 幂等设计 | 并发控制 | 边界与异常 | 性能考虑 | 补偿/重试 |
+   |---|---|---|---|---|---|---|---|
+   | <任务名称> | <Cron 表达式> | 1. ...<br>2. ... | <幂等方案> | <并发控制> | <异常场景> | <性能要求> | <重试策略> |
 
-   - 字段名、类型、约束
-   - 默认值和历史数据处理
-   - 索引建议
-   - 数据迁移脚本（如需要）
+   #### 后台任务（Async Background Job）
+   适用于：某个入口内部将耗时/可重试逻辑投递到线程池异步执行（如 @Async）
 
-4. **设计代码实现方案**
+   | 任务名称 | 投递来源/时机 | 任务载荷（仅 ID） | 执行逻辑（步骤级） | 幂等设计 | 并发控制 | 边界与异常 | 性能考虑 | 补偿/重试 |
+   |---|---|---|---|---|---|---|---|---|
+   | <任务名称> | <哪个入口/何时投递> | <entityId 等> | 1. ...<br>2. ... | <幂等方案> | <并发控制> | <异常场景> | <性能要求> | <重试策略> |
 
-   - 实体类字段添加（含注解）
-   - 业务逻辑实现（含关键代码示例）
-   - 校验逻辑（必填、值域、约束）
-   - 错误提示（使用多语言资源）
+   **一致性要求**：
+   - 明确各入口的关键一致性要求（强一致/最终一致）与边界（原则级）
 
-5. **设计前端 UI 方案**
+7. **集成方案（Integration）**
 
-   - 各页面字段状态（可编辑/只读/隐藏）
-   - 交互逻辑（下拉选择、提示信息）
-   - 错误提示
-   - 多语言支持
+   - 列出所有集成点（外部系统/内部系统/第三方回调/消息系统等）
+   - 明确集成方式与责任边界：
+     - 同步调用 / 异步事件 / 回调驱动
+     - 认证与鉴权（策略级）
+     - 超时/失败/重试的业务语义（不写具体参数）
+   - 明确可观测性要求：必须能追踪一次处理的触发来源与处理结果（用于排障与验收）
 
-6. **设计测试方案**
+   > 注意：API/回调的**具体出入参字段清单**放在 Tasks 阶段落地；Design 只描述“接口/事件的语义与契约要点”。
 
-   - 单元测试（函数级别）
-   - 集成测试（流程级别）
-   - 数据一致性验证（SQL 验证）
+8. **数据模型与数据库方案（Data Model & DB Plan）**
 
-7. **架构决策记录（P0 需求必须）**
+   - 对齐 Specs 的 Key Entities：说明关键业务对象如何落库（表级）
+   - 列出受影响的表清单（新增/修改/废弃）与改动原因（业务语义）
+   - 明确关键数据约束（唯一性、关联关系、审计字段、幂等关联键等）
 
-   如果是 P0 级需求，创建 ADR：
+   **DDL 要求**：
+   - **新增表**：必须在 Design 中给出 DDL（CREATE TABLE），用于评审整体形态与关键约束
+   - **修改存量表**：Design 只写“字段语义/约束/迁移策略”；具体 ALTER、索引、脚本与校验 SQL 放 Tasks
+
+9. **迁移 / 兼容（Migration / Compatibility）**
+
+   - 存量数据处理策略：回填/补齐/默认语义/是否允许历史数据为空
+   - 兼容性策略：
+     - 行为兼容（旧流程是否变化）
+     - 数据兼容（新字段对旧逻辑的影响）
+     - 集成兼容（外部系统/调用方是否受影响）
+   - 发布策略：是否需要灰度/开关（原则级）
+   - 回滚策略：回滚对业务与数据的影响（原则级）
+
+10. **风险与验证方式（Risk & Validation）**
+
+   - 风险清单：列出 3-7 个最关键风险（集成失败、回调乱序/重复、定时重复触发、数据回填错误等）
+   - 验证方式：将 Specs 的验收标准（AC）与 Scenarios（GWT）映射为验证矩阵（单元/集成/回归/对账/人工验证），但不在此阶段编写具体用例代码
+
+11. **架构决策记录（涉及关键决策时创建）**
+
+   若涉及重要架构决策（技术选型、集成方案、关键一致性策略等），创建 ADR：
 
    创建 `6aspecdoc/brown/<name>/artifacts/ADR-<name>.md`：
    ```markdown
@@ -82,74 +198,172 @@ Phase 3: 技术方案设计
    <如何验证这个决策是正确的>
    ```
 
-8. **技术债务识别**
-
-   识别实现过程中可能引入的技术债务：
+12. **技术债务识别（标准级/完整级推荐）**
 
    | 债务ID | 描述 | 类型 | 影响 | 偿还成本 | 优先级 |
    |--------|------|------|------|----------|--------|
-   | DEBT-001 | 临时的硬编码逻辑 | 代码质量 | 中 | 2人日 | P1 |
+   | DEBT-001 | ... | ... | ... | ... | P1 |
+
+13. **创建技术方案文档**
+
+   创建 `6aspecdoc/brown/<name>/artifacts/design.md`
+
+   建议结构（可按需裁剪）：
+   - 背景与目标 / 非目标
+   - 模块划分
+   - 服务边界
+   - 接口/入口规范（REST API / 事件订阅 / 定时任务 / 后台任务）
+   - 集成方案
+   - 数据模型与数据库方案（新增表附 DDL）
+   - 迁移 / 兼容 / 灰度 / 回滚
+   - 风险与验证矩阵
+   - ADR 列表（如有）
+   - 技术债务（如有）
+
+14. **更新状态**
+
+   更新 `6aspecdoc/brown/<name>/status.json`：
+
+   **轻量级流程**：
+   ```json
+   {
+     "status": "tasks_pending",
+     "flowDepth": "lightweight",
+     "phases": {
+       "proposal": "done",
+       "specs": "done",
+       "design": "done",
+       "tasks": "pending",
+       "implement": "blocked"
+     },
+     "artifacts": ["proposal.md", "specs.md", "design.md"]
+   }
+   ```
+
+   **标准级流程**：
+   ```json
+   {
+     "status": "tasks_pending",
+     "flowDepth": "standard",
+     "phases": {
+       "understand": "done",
+       "impact": "done",
+       "proposal": "done",
+       "specs": "done",
+       "design": "done",
+       "tasks": "pending",
+       "implement": "blocked"
+     },
+     "artifacts": ["understanding.md", "impact-analysis.md", "proposal.md", "specs.md", "design.md"]
+   }
+   ```
 
-9. **创建技术方案文档**
+   **完整级流程**：
+   ```json
+   {
+     "status": "tasks_pending",
+     "flowDepth": "complete",
+     "phases": {
+       "understand": "done",
+       "impact": "done",
+       "proposal": "done",
+       "specs": "done",
+       "design": "done",
+       "tasks": "pending",
+       "implement": "blocked",
+       "verify": "blocked",
+       "review": "blocked"
+     },
+     "artifacts": ["understanding.md", "impact-analysis.md", "proposal.md", "specs.md", "design.md"]
+   }
+   ```
 
-   创建 `6aspecdoc/brown/<name>/artifacts/03-technical-design.md`
+   同时更新 `6aspecdoc/brown/<name>/requirement.md`：
+   - 更新"状态"字段为 `📋 Tasks 待开始`
+   - 更新"最后修改"时间戳为 `<timestamp>`
+   - 更新"当前阶段"为 `Design - 技术方案设计（已完成）`
+   - 更新"下一步操作"为 `运行 /6aspec:brown:tasks 继续下一阶段`
+   - 在"进度概览"中标记 Design 阶段为已完成 `[x]`
 
-10. **更新状态**
+---
 
-    更新 `6aspecdoc/brown/<name>/status.json`：
-    ```json
-    {
-      "status": "tasks_pending",
-      "phases": {
-        "understand": "done",
-        "impact": "done",
-        "design": "done",
-        "tasks": "pending",
-        ...
-      }
-    }
-    ```
+## 输出
 
-**输出**
+根据 `flowDepth` 显示不同的输出信息（示例）：
 
+**轻量级流程**：
 ```
-## Phase 3 完成：技术方案设计
+## Design 完成：<name>
 
-**需求**: <name>
-**进度**: 4/5 阶段完成（标准级）或 4/6 阶段完成（完整级）
+**流程**: 轻量级
+**进度**: 3/5 阶段完成
 
 ### 方案概要
-- 数据库变更：<数量> 个表
-- 代码变更：<数量> 个类
-- 前端变更：<数量> 个页面
-- 测试用例：<数量> 个
+- 模块划分：<数量> 个模块（新增/调整：<数量>）
+- 服务边界：<数量> 个关键边界/所有权确认
+- 接口/入口：<数量> 个（REST API / 事件订阅 / 定时任务 / 后台任务，按需）
+- 集成点：<数量> 个（外部/内部）
+- 迁移/兼容：<是否需要 + 简述>
 
 ### 关键设计决策
-<列出 2-3 个关键决策>
+<列出 2-3 个关键决策（含是否创建 ADR）>
+
+### 文档位置
+- 6aspecdoc/brown/<name>/artifacts/design.md
+- 6aspecdoc/brown/<name>/artifacts/ADR-<name>.md (如涉及)
 
-### 技术债务
-<列出识别的技术债务>
+### 下一步
+- 直接回复修正设计方案或补充细节 → 我会更新本阶段文档（design.md）
+- 运行 `/6aspec:brown:tasks` → 进入任务拆解阶段
+- 运行 `/6aspec:brown:continue` → 自动进入下一阶段
+```
+
+**标准级/完整级流程**：
+```
+## Design 完成：<name>
+
+**流程**: <标准级/完整级>
+**进度**: <按流程深度计算>
+
+### 方案概要
+- 模块划分：<...>
+- 服务边界：<...>
+- 接口/入口：<...>
+- 集成点：<...>
+- 数据模型：<新增表/改表概览；新增表 DDL：<有/无>>
+- 迁移/兼容：<策略摘要>
+
+### 风险与验证
+- 关键风险：<数量>
+- 验证矩阵：已覆盖 Specs 的 AC / Scenarios
 
 ### 文档位置
-- 6aspecdoc/brown/<name>/artifacts/03-technical-design.md
-- 6aspecdoc/brown/<name>/artifacts/ADR-<name>.md (P0)
+- 6aspecdoc/brown/<name>/artifacts/design.md
+- 6aspecdoc/brown/<name>/artifacts/ADR-<name>.md (如涉及)
 
 ### 下一步
-- 直接回复修正设计方案或补充细节 → 我会更新本阶段文档（03-technical-design.md）
+- 直接回复修正设计方案或补充细节 → 我会更新本阶段文档（design.md）
 - 运行 `/6aspec:brown:tasks` → 进入任务拆解阶段
 - 运行 `/6aspec:brown:continue` → 自动进入下一阶段
 ```
 
-**用户补充信息时的处理**
+---
 
-当用户修正设计方案、补充技术细节、或对设计决策提出异议时（未使用阶段命令）：
-1. 将用户的修正/补充整合到 `03-technical-design.md` 的对应章节
+## 用户补充信息时的处理
+
+当用户修正设计方案、补充决策信息、或对设计决策提出异议时（未使用阶段命令）：
+1. 将用户的修正/补充整合到 `design.md` 的对应章节
 2. 展示变更摘要
 3. 再次提示：可以继续补充，或通过命令进入下一阶段
 4. **禁止**：不得自动进入下一阶段
 
-**防护措施**
-- 必须先完成 Phase 2
-- P0 需求必须创建 ADR
-- 代码示例必须完整可用
-- 技术债务必须明确标注
+---
+
+## 防护措施
+
+- 所有流程级别：必须先完成 specs 阶段（`phases.specs == done`）
+- Design 文档必须覆盖：模块划分、服务边界、接口/入口规范、集成方案、数据模型、迁移/兼容、风险与验证
+- **禁止**：把 Design 写成实现说明（代码片段、注解、方法级实现、伪代码、前端逐字段交互、API 出入参字段清单等）
+- **新增表**：必须提供 DDL；**改表**：不得在 Design 展开全量 DDL（放 Tasks）
+- 涉及关键架构决策时必须创建 ADR（技术选型、集成方案、一致性策略等）
+- 标准级/完整级：技术债务应明确标注（如有）