6aspec 2.0.0-dev.2

package/.6aspec/rules/green/6A_visual_logic_sop.md

@@ -0,0 +1,121 @@
+---
+description: 基于TDD生成 Mermaid 流程图/交互时序图/状态机图的标准操作流程 (Visual Logic Diagrams SOP)
+alwaysApply: false
+---
+
+# visual-logic: 基于 TDD 生成 Mermaid 图表的标准操作流程（按需生成）
+
+## 背景与原则
+本 SOP 用于在“需要时”生成业务逻辑可视化图表。不是每次需求都复杂，也不是每个业务功能都需要图表，因此本 SOP 强制遵守：
+- **按需生成**：由人来判断本次哪些流程/入口需要画图；未被选中的图表类型与范围，禁止为了完整性而补齐。
+- **只依赖既有设计**：图表必须严格基于已产出的 TDD（以及可选补充材料），不得自行脑补业务规则。
+
+## 角色
+你现在的角色是【技术方案可视化设计师】，负责把 TDD 中的写流程/异步流程/状态流转转换为 Mermaid 图表，以提升可读性与对齐效率。
+
+## 目标
+基于指定的 TDD 文档，按人类选择的范围输出以下一种或多种 Mermaid 图表：
+- **业务流程图（Flowchart）**
+- **交互时序图（Sequence Diagram）**
+- **状态机图（State Diagram）**
+
+## 输入要求
+### 必需输入
+- **TDD 文档路径**：`6aspecdoc/green/<feature-name>/artifacts/tech-design.md`（feature-name 使用 kebab-case 命名，如：user-authentication）
+- **人类选择的生成范围（必须明确，否则中断提问）**：
+  - 需要生成的图表类型：Flowchart / Sequence / State（可多选）
+  - 覆盖范围：具体到“哪些入口/哪些业务流程/哪些对象”（例如：仅 `3.1` 中某个写 API；或某个事件订阅；或某个后台任务）
+  - 抽象层级：是否细到 service/repository/facade 级别（建议默认到 service/repository/facade）
+
+### 可选输入（用于补齐 TDD 未显式写清的信息）
+- 数据模型文档：`6aspecdoc/green/<feature-name>/artifacts/domain-model.md`
+- PRD：`.prd/{功能名称}-prd.md`
+- 事件清单：`./.6aspec/biz/event-list.md`（当涉及事件订阅/发布时）
+- 能力地图：`./.6aspec/biz/functional-capability-Map.md`（当涉及跨模块 Facade 依赖时）
+
+## 中断机制（必须执行）
+如果出现以下任一情况，必须停止画图并输出“提问清单”，等待人类补充：
+- TDD 未明确对应入口的**执行逻辑**（关键分支/校验/写入/副作用）导致流程无法确定
+- 需要状态机图，但 TDD/模型未明确**状态集合、迁移条件、触发入口**
+- 需要时序图，但 TDD 未明确**参与者边界**（哪些模块/Facade/Repo/异步任务参与）
+- 人类未明确“生成范围”或范围过大且不可执行（例如：要求“全系统所有流程都画”）
+
+## 输出要求
+1. **输出格式**：Markdown 源码 + Mermaid 代码块（严禁截图）
+2. **输出位置**：`6aspecdoc/green/<feature-name>/artifacts/visual-logic.md`
+3. **引用关系**：在输出文档开头必须写明：
+   - 输入 TDD 文档路径
+   - 本次选择生成的图表类型与覆盖范围
+4. **禁止项**：不涉及 UI/交互/样式；不写测试用例；不新增查询接口设计
+
+## 标准操作流程（SOP）
+
+### 第一步：确认输入与范围（Gatekeeping）
+输出一个确认表（或列表），逐项确认：
+- TDD 路径是否存在、是否可读
+- 本次需要生成的图表类型（多选）
+- 本次覆盖范围（入口/流程/对象，必须具体）
+- 抽象层级（例如：Controller/Façade/Service/Repository/外部 Facade/JobWorker）
+
+若任意项缺失：停止并输出提问清单。
+
+### 第二步：从 TDD 抽取“可视化要素”
+只允许从 TDD（以及人类提供的补充输入）中抽取：
+- 入口清单（写 API / 定时任务 / 事件订阅 / 后台任务）
+- 每个入口的执行逻辑（含关键分支）
+- 幂等/并发控制点（用于标注关键节点）
+- 外部依赖与调用点（用于时序图参与者）
+- 状态与迁移信息（仅当选择生成状态机图）
+
+### 第三步：生成 Mermaid 图表（按选择的图表类型分别输出）
+
+#### 3.1 业务流程图（Flowchart）
+适用：存在多分支判断、异常分支、幂等/并发门禁、异步投递等逻辑。
+要求：
+- 每个被选中的入口至少 1 张流程图
+- 节点必须可映射回 TDD 的“执行逻辑”描述（禁止新增分支）
+
+#### 3.2 交互时序图（Sequence Diagram）
+适用：需要对齐模块边界、依赖调用顺序、异步链路。
+要求：
+- 参与者命名使用逻辑层级：Client/Controller/Façade/Service/Repository/ExternalFacade/JobProducer/JobWorker/EventBus 等
+- 清晰体现：同步调用、异步投递/消费、失败重试/补偿点（若 TDD 已描述）
+
+#### 3.3 状态机图（State Diagram）
+适用：对象存在明确状态集合与迁移（订单/合同/流程单/任务等）。
+要求：
+- 必须在图旁边列出：状态集合来源（来自 TDD 或模型的哪一段描述）
+- 迁移必须标注触发入口（API/事件/定时任务/后台任务）
+
+### 第四步：输出文档并自检
+1. 写入 `6aspecdoc/green/<feature-name>/artifacts/visual-logic.md`
+2. 自检：
+   - Mermaid 语法是否完整
+   - 是否严格遵循"按需生成"与"范围约束"
+   - 是否存在任何"凭空补充"的业务分支（如有则删除并提问）
+
+## 流程完成提示 (Workflow Progress)
+
+**重要提示**：本节内容仅用于向用户输出流程进度提示，**不要写入任何文档文件**。
+
+当完成本 SOP 流程后，必须向用户输出以下流程进度提示：
+
+---
+
+✅ **已完成：生成可视化逻辑图 (visual-logic) - 可选流程**
+
+📊 **进度：可选流程已完成**
+
+**下一步建议：**
+- 【主流程】任务拆解：命令 `tasks`
+  继续主流程，将技术方案拆解为可执行的开发任务
+
+**完整流程图：**
+```
+主流程：领域建模 ✅ → 技术方案 ✅ → 任务生成 → 执行任务 (2/4)
+可选流程：生成可视化逻辑图 ✅
+```
+
+---
+
+

package/.6aspec/rules/green/green_status_schema.md

@@ -0,0 +1,293 @@
+# 绿地需求状态文件结构定义
+
+## 概述
+
+每个绿地需求都有一个状态文件 `.green-status.json`，用于跟踪需求的生命周期状态、工件完成情况和任务进度。
+
+## 文件位置
+
+```
+6aspecdoc/green/<feature-name>/.green-status.json
+```
+
+## 状态文件结构
+
+```json
+{
+  "name": "string",              // 需求名称（kebab-case）
+  "status": "string",            // 当前生命周期状态
+  "created": "ISO8601",          // 创建时间
+  "lastModified": "ISO8601",     // 最后修改时间
+  "artifacts": {                 // 工件完成情况
+    "requirement": {
+      "status": "string",        // 工件状态：pending/ready/done/blocked
+      "path": "string",          // 工件路径
+      "completedAt": "ISO8601"   // 完成时间（可选）
+    },
+    "models": {
+      "status": "string",
+      "path": "string",
+      "completedAt": "ISO8601",
+      "files": ["string"]        // 模型文件列表（可选）
+    },
+    "design": {
+      "status": "string",
+      "path": "string",
+      "completedAt": "ISO8601"
+    },
+    "tasks": {
+      "status": "string",
+      "path": "string",
+      "completedAt": "ISO8601",
+      "files": ["string"]        // 任务文件列表（可选）
+    }
+  },
+  "tasks": {                     // 任务进度
+    "total": 0,                  // 总任务数
+    "completed": 0,              // 已完成任务数
+    "remaining": 0,              // 剩余任务数
+    "lastExecuted": "string"     // 最后执行的任务文件名（可选）
+  },
+  "nextAction": {                // 下一步建议（可选）
+    "command": "string",         // 建议的命令
+    "description": "string"      // 描述
+  }
+}
+```
+
+## 生命周期状态
+
+| 状态 | 说明 | 下一步命令 |
+|------|------|-----------|
+| `created` | 已创建，等待需求澄清 | `/6aspec:green:new` 或 `/6aspec:green:clarify` |
+| `requirement_clarified` | 需求已澄清 | `/6aspec:green:model`（可选：`/6aspec:green:clarify` 继续深化） |
+| `modeled` | 领域建模完成 | `/6aspec:green:design` |
+| `designed` | 技术方案完成 | `/6aspec:green:tasks` |
+| `tasks_created` | 任务已拆解 | `/6aspec:green:execute-task` |
+| `implementing` | 实施中 | `/6aspec:green:execute-task` |
+| `completed` | 已完成 | `/6aspec:green:archive` |
+| `archived` | 已归档 | - |
+
+## 工件状态
+
+| 状态 | 说明 |
+|------|------|
+| `pending` | 等待创建 |
+| `ready` | 准备就绪，可以创建 |
+| `done` | 已完成 |
+| `blocked` | 被阻塞，等待依赖工件完成 |
+
+## 工件依赖关系
+
+```
+requirement (需求澄清文档)
+  ↓
+models (领域模型)
+  ↓
+design (技术方案)
+  ↓
+tasks (任务列表)
+```
+
+## 状态转换规则
+
+1. **created → requirement_clarified**
+   - 条件：requirement 工件状态为 done
+   - 触发：完成需求澄清文档
+
+2. **requirement_clarified → modeled**
+   - 条件：models 工件状态为 done
+   - 触发：完成领域建模
+
+3. **modeled → designed**
+   - 条件：design 工件状态为 done
+   - 触发：完成技术方案
+
+4. **designed → tasks_created**
+   - 条件：tasks 工件状态为 done
+   - 触发：完成任务拆解
+
+5. **tasks_created → implementing**
+   - 条件：开始执行任务
+   - 触发：执行第一个任务
+
+6. **implementing → completed**
+   - 条件：所有任务完成（tasks.completed == tasks.total）
+   - 触发：完成最后一个任务
+
+7. **completed → archived**
+   - 条件：用户确认归档
+   - 触发：执行归档命令
+
+## 回退（rollback）
+
+仅允许**单步回退**，且**必须先提示用户、获得明确确认后**才可执行；执行时将删除当前阶段生成的工件。
+
+| 当前状态 | 回退后状态 | 触发命令 | 将删除的工件 |
+|----------|------------|----------|--------------|
+| `requirement_clarified` | `created` | `/6aspec:green:rollback` | requirement.md |
+| `modeled` | `requirement_clarified` | `/6aspec:green:rollback` | artifacts/domain-model.md |
+| `designed` | `modeled` | `/6aspec:green:rollback` | artifacts/tech-design.md、api-definition.md、visual-logic.md（若存在） |
+| `tasks_created` | `designed` | `/6aspec:green:rollback` | tasks/ 目录下全部文件 |
+
+**不允许回退**：`created`（无上一阶段）、`implementing`、`completed`、`archived`。详见 `.6aspec/rules/green/6A_rollback_sop.md`。
+
+## 示例
+
+### 初始状态（刚创建）
+
+```json
+{
+  "name": "user-authentication",
+  "status": "created",
+  "created": "2026-02-16T03:00:00Z",
+  "lastModified": "2026-02-16T03:00:00Z",
+  "artifacts": {
+    "requirement": {
+      "status": "pending",
+      "path": "6aspecdoc/green/user-authentication/requirement.md"
+    },
+    "models": {
+      "status": "blocked",
+      "path": "6aspecdoc/green/user-authentication/artifacts/"
+    },
+    "design": {
+      "status": "blocked",
+      "path": "6aspecdoc/green/user-authentication/artifacts/"
+    },
+    "tasks": {
+      "status": "blocked",
+      "path": "6aspecdoc/green/user-authentication/tasks/"
+    }
+  },
+  "tasks": {
+    "total": 0,
+    "completed": 0,
+    "remaining": 0
+  },
+  "nextAction": {
+    "command": "new",
+    "description": "开始需求澄清"
+  }
+}
+```
+
+### 需求澄清完成后
+
+```json
+{
+  "name": "user-authentication",
+  "status": "requirement_clarified",
+  "created": "2026-02-16T03:00:00Z",
+  "lastModified": "2026-02-16T03:15:00Z",
+  "artifacts": {
+    "requirement": {
+      "status": "done",
+      "path": "6aspecdoc/green/user-authentication/requirement.md",
+      "completedAt": "2026-02-16T03:15:00Z"
+    },
+    "models": {
+      "status": "ready",
+      "path": "6aspecdoc/green/user-authentication/artifacts/"
+    },
+    "design": {
+      "status": "blocked",
+      "path": "6aspecdoc/green/user-authentication/artifacts/"
+    },
+    "tasks": {
+      "status": "blocked",
+      "path": "6aspecdoc/green/user-authentication/tasks/"
+    }
+  },
+  "tasks": {
+    "total": 0,
+    "completed": 0,
+    "remaining": 0
+  },
+  "nextAction": {
+    "command": "model",
+    "description": "开始领域建模"
+  }
+}
+```
+
+### 实施中
+
+```json
+{
+  "name": "user-authentication",
+  "status": "implementing",
+  "created": "2026-02-16T03:00:00Z",
+  "lastModified": "2026-02-16T05:30:00Z",
+  "artifacts": {
+    "requirement": {
+      "status": "done",
+      "path": "6aspecdoc/green/user-authentication/requirement.md",
+      "completedAt": "2026-02-16T03:15:00Z"
+    },
+    "models": {
+      "status": "done",
+      "path": "6aspecdoc/green/user-authentication/artifacts/",
+      "completedAt": "2026-02-16T03:45:00Z",
+      "files": ["domain-model.md"]
+    },
+    "design": {
+      "status": "done",
+      "path": "6aspecdoc/green/user-authentication/artifacts/",
+      "completedAt": "2026-02-16T04:15:00Z"
+    },
+    "tasks": {
+      "status": "done",
+      "path": "6aspecdoc/green/user-authentication/tasks/",
+      "completedAt": "2026-02-16T04:30:00Z",
+      "files": ["task_01_user_model.md", "task_02_auth_api.md", "task_03_session.md"]
+    }
+  },
+  "tasks": {
+    "total": 8,
+    "completed": 5,
+    "remaining": 3,
+    "lastExecuted": "task_05_session_management.md"
+  },
+  "nextAction": {
+    "command": "execute-task",
+    "description": "继续执行剩余 3 个任务"
+  }
+}
+```
+
+## 使用说明
+
+### 读取状态
+
+所有命令在执行前应该读取状态文件，了解当前状态：
+
+```javascript
+const statusPath = '6aspecdoc/green/<feature-name>/.green-status.json';
+const status = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
+```
+
+### 更新状态
+
+命令执行后应该更新状态文件：
+
+```javascript
+status.lastModified = new Date().toISOString();
+status.artifacts.requirement.status = 'done';
+status.artifacts.requirement.completedAt = new Date().toISOString();
+status.status = 'requirement_clarified';
+fs.writeFileSync(statusPath, JSON.stringify(status, null, 2));
+```
+
+### 状态检查
+
+在执行命令前，检查状态是否符合预期：
+
+```javascript
+if (status.status !== 'requirement_clarified') {
+  console.error('错误：当前状态不允许执行此命令');
+  console.error(`当前状态：${status.status}`);
+  console.error(`期望状态：requirement_clarified`);
+  process.exit(1);
+}
+```