adspecs 0.1.12

package/skills/adspecs-architecture-planning/SKILL.md

@@ -0,0 +1,875 @@
+---
+name: "adspecs-architecture-planning"
+description: "基于自然语言项目/业务描述，支持3种架构规划类型：①功能架构 ②子模块依赖关系 ③统一数据建模（含Mermaid ER图）。用户可选择执行1种、2种或全部3种，后两者依赖功能架构完成"
+argument-hint: "描述项目名称、行业领域、核心业务和系统边界，如：华峰铝业CRM平台，覆盖销售全生命周期"
+compatibility: "需要 adspecs 项目结构及 docs/ 目录"
+metadata:
+  author: "Qingwen Chen"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+**必须** 在继续之前考虑用户输入（如果非空）。
+
+## 路径配置加载
+
+在开始执行之前，先确定输出目录：
+
+1. 检查项目根目录是否存在 `.adspecs/paths.json`
+2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键
+3. 如果不存在或配置键缺失，使用下方表格中的默认值
+
+| 配置键             | 默认值                 | 用途                                          |
+| ------------------ | ---------------------- | --------------------------------------------- |
+| `architecture_dir` | `docs/10-architecture` | 架构规划设计文档输出目录                      |
+| `planning_dir`     | `docs/00-planning`     | 规划阶段文档目录（步骤1可能引用已有规划文档） |
+
+将解析后的路径记为 `ARCH_DIR` 和 `PLANNING_DIR`，后续步骤中引用此变量而非硬编码路径。
+
+## 执行前检查
+
+**检查扩展钩子（规划前）**:
+
+- 检查项目根目录是否存在 `.adspecs/extensions.yml`。
+- 如果存在，读取它并查找 `hooks.before_planning` 下的条目。
+- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续正常执行。
+- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
+- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
+  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
+  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
+- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
+- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
+  - **可选钩子** (`optional: true`):
+
+    ```
+    ## 扩展钩子
+
+    **可选前置钩子**: {extension}
+    命令: `/{command}`
+    描述: {description}
+
+    提示: {prompt}
+    执行: `/{command}`
+    ```
+
+  - **必选钩子** (`optional: false`):
+
+    ```
+    ## 扩展钩子
+
+    **自动前置钩子**: {extension}
+    执行: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    等待钩子命令结果后再继续执行。
+    ```
+
+- 如果没有注册钩子或 `.adspecs/extensions.yml` 不存在，静默跳过。
+
+## 架构类型选择
+
+技能启动后，**必须**先向用户提供架构类型选择，而非默认串行执行全部 3 个步骤。
+
+### 可选架构类型
+
+| 编号 | 架构类型         | 输出文件                                              | 前置条件                         |
+| ---- | ---------------- | ----------------------------------------------------- | -------------------------------- |
+| 1    | **功能架构**     | `01-{project}_business_architecture.md`               | 无（可独立执行）                 |
+| 2    | **子模块依赖关系** | `03-{project}_sub_module_dependencies.md`           | **必须**已完成功能架构（类型1）  |
+| 3    | **统一数据建模** | `04-{project}_unified_data_model.md`                  | **必须**已完成功能架构（类型1）  |
+
+### 选择流程
+
+1. 向用户展示上述三种架构类型及前置条件
+2. 用户可选择执行 **1 种、2 种或全部 3 种**
+3. 如果用户选择了子模块依赖关系或统一数据建模，但功能架构文档不存在：
+   - 提示用户：「{ARCH_DIR}/01-{项目简称}_business_architecture.md 文件不存在，子模块依赖关系和统一数据建模依赖功能架构文档。请先执行功能架构规划。」
+   - 自动将功能架构加入执行计划
+4. 如果用户选择全部 3 种，则按 功能架构 → 子模块依赖关系 → 统一数据建模 的顺序串行执行
+5. 如果用户仅选择子模块依赖关系和统一数据建模（且功能架构文档已存在），两者之间无依赖关系，可按用户偏好顺序执行
+
+### 选择示例
+
+```
+请选择要执行的架构规划类型：
+
+1. 功能架构 — 业务模块体系、子模块拆分、业务场景设计
+2. 子模块依赖关系 — 模块依赖矩阵、价值链路径、领域事件（需先完成功能架构）
+3. 统一数据建模 — 聚合根设计、ER关系图、跨模块集成模型（需先完成功能架构）
+
+可输入编号组合，如：1 / 1,2 / 1,2,3 / 2,3
+```
+
+## 已存在文件处理
+
+在确定用户选择的架构类型后、正式开始执行前，**必须**检查对应的输出文件是否已存在。
+
+### 检查规则
+
+对用户选择的每种架构类型，检查对应输出文件是否存在：
+
+| 架构类型 | 检查文件                                                |
+| -------- | ------------------------------------------------------- |
+| 类型1    | `{ARCH_DIR}/01-{项目简称}_business_architecture.md`     |
+| 类型2    | `{ARCH_DIR}/03-{项目简称}_sub_module_dependencies.md`   |
+| 类型3    | `{ARCH_DIR}/04-{项目简称}_unified_data_model.md`        |
+
+### 处理流程
+
+**如果文件已存在**，对该类型向用户展示以下提示：
+
+```
+## 文件已存在
+
+检测到文件已存在：`{文件路径}`
+文件大小：{大小} | 最后修改：{时间}
+
+请选择处理方式：
+
+1. **重新编写** — 删除现有内容，基于当前输入重新生成完整文档
+2. **提示词优化** — 读取现有文档内容，基于用户补充提示词进行增量优化和完善
+3. **跳过** — 保留现有文档不做任何修改，跳过此架构类型
+```
+
+### 各选项行为
+
+#### 选项1：重新编写
+
+1. 读取并备份现有文档内容（记录原始版本信息用于提示）
+2. **完全覆盖**现有文件，基于当前输入和模板重新生成
+3. 按正常流程执行完整的质量检查
+
+#### 选项2：提示词优化
+
+1. **必须**先读取现有文档的完整内容
+2. 分析现有文档的结构完整度、内容覆盖度和质量
+3. 向用户展示现有文档的简要分析：
+   - 已包含的章节和内容概要
+   - 可能存在的缺失或待改进项
+4. 询问用户希望优化哪些方面（用户可描述具体的优化方向）
+5. **保留现有文档的整体结构和已有内容**，仅针对用户指定的方面进行增量优化：
+   - 补充缺失的章节或内容
+   - 完善不够详细的部分
+   - 修正不一致或错误的内容
+   - 根据用户新的提示词调整设计方向
+6. 执行质量检查时，同时验证新增内容与原有内容的一致性
+
+#### 选项3：跳过
+
+1. 保留现有文档不做任何修改
+2. 在后续流程中仍然将该文档作为可用输入（如类型2/3依赖类型1的文档）
+3. 在完成报告中标注该类型为"已跳过（文件已存在）"
+
+### 多文件存在时的处理
+
+如果用户选择了多种架构类型且多个文件都已存在，**逐个**向用户确认每种类型的处理方式，而非一次性询问。
+
+示例：
+
+```
+## 文件已存在检查
+
+✅ 功能架构文档已存在：docs/10-architecture/01-wms_business_architecture.md
+请选择：1.重新编写 / 2.提示词优化 / 3.跳过
+
+⬜ 子模块依赖关系文档已存在：docs/10-architecture/03-wms_sub_module_dependencies.md
+请选择：1.重新编写 / 2.提示词优化 / 3.跳过
+
+⬜ 统一数据模型文档不存在，将正常生成
+```
+
+### 跳过后的依赖处理
+
+如果用户选择跳过某个类型，但该类型的输出是其他已选类型的前置依赖：
+
+- **跳过类型1（功能架构）但选择了类型2/3**：类型2/3直接使用已有的功能架构文档作为输入，正常执行
+- **跳过类型2（子模块依赖关系）但选择了类型3**：类型3使用已有的子模块依赖关系文档作为输入（如果存在）；如果不存在，类型3仅基于功能架构文档执行
+
+## 概述
+
+用户在触发消息中 `/adspecs-planning` 之后输入的文本**就是**项目/业务描述。假设你在本次对话中始终可以获取到它，即使 `$ARGUMENTS` 字面上出现在下方。除非用户提供了空命令，否则不要要求用户重复输入。
+
+本技能支持 **3 种架构类型**，用户可按需选择执行。各类型之间存在依赖关系：
+
+```
+功能架构（类型1）→ 子模块依赖关系（类型2）
+                → 统一数据建模（类型3）
+```
+
+- **功能架构** 是基础，可独立执行
+- **子模块依赖关系** 和 **统一数据建模** 都依赖功能架构的输出，但两者之间互不依赖
+
+## 输入解析
+
+从用户输入中提取以下关键信息。如果用户输入不完整，按以下优先级主动澄清：
+
+### 必须明确的信息
+
+| 信息项           | 说明                                       | 澄清优先级 |
+| ---------------- | ------------------------------------------ | ---------- |
+| **项目名称**     | 完整名称，如"华峰铝业CRM平台"              | P0         |
+| **项目简称**     | 用于文件命名和编号前缀，如"crm"            | P0         |
+| **行业领域**     | 所属行业和业务领域，如"铝加工行业销售管理" | P0         |
+| **核心业务范围** | 系统要覆盖的核心业务功能清单               | P0         |
+| **适用组织**     | 使用本系统的组织/公司范围                  | P1         |
+
+### 可选信息（有则使用，无则做出合理推断）
+
+| 信息项       | 说明                       | 合理默认                              |
+| ------------ | -------------------------- | ------------------------------------- |
+| 外部系统边界 | 需要对接的外部系统         | 根据业务领域推断常见集成系统          |
+| 技术平台底座 | 底层技术平台名称           | "ECP"                                 |
+| 架构分层偏好 | 是否需要 L1/L2 等特殊分层  | 根据业务复杂度决定                    |
+| 分期策略     | 项目分期建设的优先级       | P0/P1/P2 三级                         |
+| 源文档       | 是否有已存在的功能规划文档 | 扫描 `docs/00-customer-requirements/` |
+
+### 输入解析流程
+
+1. **提取关键概念**：从描述中识别项目名、行业、核心业务、组织范围
+2. **检查已有文档**：扫描 `docs/00-customer-requirements/` 是否已有客户需求文档
+3. **检查已有架构**：扫描 `{ARCH_DIR}/` 是否已有部分架构文档（避免覆盖）
+4. **检查已有规划文档**：扫描 `{PLANNING_DIR}/` 是否已有规划阶段文档（避免重复创建）
+5. **做出合理推断**：对未明确的可选信息，基于行业标准和业务上下文推断
+6. **标记待澄清项**：仅对显著影响模块划分的关键决策标记 [NEEDS CLARIFICATION]（最多 3 个）
+
+**合理推断示例**（不要询问以下内容）：
+
+- M00 系统管理模块：所有项目都需要，包含组织架构/权限/流程/编码/通知等标准子模块
+- 审计字段规范：所有表包含 8 个标准审计字段（ECP 平台规范）
+- 微服务拆分粒度：按业务子域拆分，每服务 2-4 个相关模块
+
+## 准备工作
+
+1. **创建输出目录**：`mkdir -p {ARCH_DIR}`
+
+2. **加载模板**（按用户选择的架构类型）：
+   - 类型1（功能架构）模板：`.adspecs/templates/15-业务功能架构文档模板.md`
+   - 类型2（子模块依赖关系）模板：`.adspecs/templates/17-子模块依赖关系模板.md`
+   - 类型3（统一数据建模）模板：`.adspecs/templates/18-统一数据模型模板.md`
+
+3. **加载参考文件**（按需）：
+   - `CLAUDE.md` — 项目技术栈、模块结构、编码约定
+   - `docs/40-project_conventions/` — 项目编码规范（如有）
+   - `docs/00-customer-requirements/` — 客户需求文档（如有）
+   - `docs/00-planning/` — 已有规划文档（如有）
+   - `{ARCH_DIR}/01-{项目简称}_business_architecture.md` — 功能架构文档（如已执行类型1，用于类型2/3）
+   - `{ARCH_DIR}/03-{项目简称}_sub_module_dependencies.md` — 模块依赖文档（如已执行类型2，用于类型3，可选）
+
+4. **确定文件命名**（仅针对用户选择的类型）：
+   - 类型1：`{ARCH_DIR}/01-{项目简称}_business_architecture.md`
+   - 类型2：`{ARCH_DIR}/03-{项目简称}_sub_module_dependencies.md`
+   - 类型3：`{ARCH_DIR}/04-{项目简称}_unified_data_model.md`
+
+   其中 `{项目简称}` 从输入解析获得，转为小写英文+连字符格式（如 `crm`、`wms`、`erp`）。
+
+---
+
+## 步骤 1：业务功能架构规划（架构类型 1）
+
+> **模板**：`.adspecs/templates/15-业务功能架构文档模板.md`
+> **前置条件**：无（可独立执行）
+> **输出**：`{ARCH_DIR}/01-{项目简称}_business_architecture.md`
+
+### 1.1 分析与设计
+
+基于用户输入和已有文档，完成以下分析：
+
+#### 1.1.1 模块体系设计
+
+1. **识别业务域**：从核心业务范围中提取主要业务域
+2. **划分主模块**：每个业务域对应 1~3 个主模块，加上 P00 系统管理底座
+3. **编号分配**：P00 = 系统管理，P01~P{N} 按业务域逻辑分组
+4. **模块分层**：将模块按职责分为 3~5 个层级（如数据底座层、交易执行层、分析决策层等）
+5. **优先级评估**：为每个模块标注优先级（P0 一期核心 / P1 一期 / P2 远期）
+
+#### 1.1.2 子模块拆分
+
+为每个主模块拆分 4~12 个子模块：
+
+1. **P00 系统管理**：按标准子模块拆分（组织架构、权限、字段配置、流程配置、编码规则、数据字典、日志审计、集成接口、消息通知等）
+2. **业务模块**：根据业务场景拆分为可独立开发的子模块
+3. 每个子模块包含：编号、名称、说明、外部项目范围（如有）、分期规划
+
+#### 1.1.3 业务场景编写
+
+为每个模块编写 2~8 个业务场景：
+
+1. **场景编号**：S-P{XX}-{YY}-{ZZZ}
+2. **场景概述**：一句话描述业务目的
+3. **操作步骤表**：每步标注操作描述和所属子模块
+4. **一期 vs 远期**：一期场景详细编写，远期场景简述即可
+
+#### 1.1.4 端到端场景
+
+设计 2~4 个端到端业务场景：
+
+1. **场景编号**：E2E-{项目简称}-01, 02, ...
+2. **阶段-步骤表**：每步标注阶段、步骤、操作描述、涉及子模块
+3. 端到端场景应覆盖核心价值链的完整闭环
+
+#### 1.1.5 系统集成矩阵
+
+1. **外部系统清单**：列出所有需要对接的外部系统
+2. **集成方向**：双向/入站/出站
+3. **集成内容**：数据同步/事件订阅/流程协同
+4. **内部依赖关系图**：用 ASCII 图展示模块间的依赖方向
+
+### 1.2 文档生成
+
+按 `15-业务功能架构文档模板.md` 结构生成完整文档，包含：
+
+| 章节               | 内容                                                 | 必填 |
+| ------------------ | ---------------------------------------------------- | ---- |
+| 文档说明           | 设计原则、核心对象层级、编号规则、分层说明、适用范围 | ✅   |
+| 系统模块总览       | 主模块清单表 + 各模块子模块清单表                    | ✅   |
+| 各模块业务场景详述 | 每个模块的场景编号、概述、操作步骤表                 | ✅   |
+| 端到端业务场景     | 2~4 个跨模块端到端流程                               | ✅   |
+| 系统集成关系       | 外部系统集成矩阵 + 内部模块依赖关系图                | ✅   |
+
+### 1.3 步骤1质量检查
+
+生成文档后，逐项核对：
+
+- [ ] 所有主模块（含 P00）已定义且编号连续
+- [ ] 每个主模块有 4~12 个子模块
+- [ ] 每个子模块有清晰的说明和分期规划
+- [ ] 每个模块有 2~8 个业务场景，含操作步骤表
+- [ ] 至少有 2 个端到端场景，覆盖核心价值链
+- [ ] 端到端场景的步骤可追溯到具体子模块
+- [ ] 外部系统集成矩阵已列出所有已知外部系统
+- [ ] 模块分层合理（3~5 层），每层职责清晰
+- [ ] 一期/远期分期合理，P0 模块聚焦核心业务闭环
+- [ ] 模块编号规则统一（P00~P{N}，子模块 P{XX}-01~{NN}，场景 S-P{XX}-{YY}-{ZZZ}）
+- [ ] 核心对象层级关系和关键数量关系已定义
+- [ ] 文档无 [NEEDS CLARIFICATION] 残留
+
+### 1.4 用户确认
+
+向用户展示步骤1成果摘要：
+
+- 主模块数量及名称列表
+- 子模块总数
+- 业务场景总数
+- 端到端场景数量
+- 质量检查结果
+
+**如果用户选择了全部 3 种架构类型**，询问用户是否继续步骤2，或需要调整步骤1的内容。
+
+如果用户要求调整：
+
+1. 根据反馈修改文档
+2. 重新运行质量检查
+3. 再次确认后再进入步骤2
+
+**如果用户仅选择了功能架构（类型1）**，此处即为完成，直接进入完成报告。
+
+---
+
+## 步骤 2：模块依赖关系规划（架构类型 2）
+
+> **前置条件**：必须已完成步骤1（功能架构），且 `01-{项目简称}_business_architecture.md` 文件存在
+> **模板**：`.adspecs/templates/17-子模块依赖关系模板.md`
+> **输入**：步骤1产出的业务场景文档
+> **输出**：`{ARCH_DIR}/03-{项目简称}_sub_module_dependencies.md`
+
+### 前置检查
+
+在开始步骤2之前，**必须**验证：
+
+1. 检查 `{ARCH_DIR}/01-{项目简称}_business_architecture.md` 是否存在
+2. 如果不存在，提示用户：「功能架构文档不存在，请先执行步骤1（功能架构规划）」
+3. 读取功能架构文档，提取模块定义、业务场景、端到端场景等信息
+
+### 2.1 分析与设计
+
+基于步骤1的功能架构文档，完成以下分析：
+
+#### 2.1.1 架构分层定义
+
+1. 从步骤1的模块分层推导出架构层级
+2. 定义每个层级的依赖方向规则
+3. 定义依赖类型（✓ Client SDK / ⚡ 异步事件 / → 流程协同）
+4. 定义架构硬约束（禁止共享数据库表、禁止直接代码依赖、不允许循环依赖等）
+
+#### 2.1.2 主模块依赖矩阵
+
+构建 N×N 依赖矩阵（N = 主模块数量）：
+
+1. 逐对分析模块间的依赖关系
+2. 标注依赖类型（✓/⚡/—）
+3. 验证无循环依赖
+4. 标注与外部系统的依赖
+
+#### 2.1.3 核心价值链路径
+
+设计 3~5 条核心价值链依赖路径：
+
+1. **主交易链路**：从报价/订单到回款/结算的完整路径
+2. **数据底座链路**：基础数据（客户/产品）到业务消费的链路
+3. **平台支撑链路**：所有模块对 P00 的横切依赖
+4. **外部协同链路**（如有）：与关联系统的协同链路
+
+用 ASCII 图清晰展示每条路径。
+
+#### 2.1.4 全局共享服务
+
+列出被多模块消费的共享服务：
+
+- 认证授权、权限查询、流程引擎、编码生成、文件中心、消息推送、日志审计、数据字典等
+- 标注提供方、消费方、接口形式
+
+#### 2.1.5 循环依赖避免策略
+
+对每一对可能产生循环依赖的模块对：
+
+1. 识别双向交互场景
+2. 设计解耦策略（正向用 ✓ 同步、反向用 ⚡ 异步事件）
+3. 验证解耦后无循环
+
+#### 2.1.6 Saga 跨模块事务编排
+
+设计关键业务的 Saga 编排：
+
+1. 识别需要跨模块事务一致性的场景（如订单下单、发货结算、退换货等）
+2. 定义 Saga 步骤链路
+3. 定义每步的补偿策略
+
+#### 2.1.7 领域事件清单
+
+为每个模块定义领域事件：
+
+1. 事件名称（`{project}.{module}.{action}` 格式）
+2. Topic 名称（`{project}.m{xx}.{module}.{action}` 格式）
+3. 主要订阅者及用途
+4. P00 系统管理事件（平台复用）
+
+#### 2.1.8 共享 DTO 清单
+
+列出跨模块高频共享的 DTO：
+
+1. DTO 名称、提供方、消费方
+2. 核心字段列表
+
+#### 2.1.9 子模块级精细依赖
+
+为每个子模块列出跨模块依赖：
+
+- 格式：`源子模块 → 目标子模块 [依赖类型] 说明`
+- 包含 P00 系统管理的子模块级依赖
+
+#### 2.1.10 开发优先级建议
+
+1. **模块开发依赖层次**：从底向上分层（第0层=平台底座，第1层=数据底座，第2层=交易基础...）
+2. **开发顺序建议**：按周规划模块开发顺序
+3. **集成测试关键路径**：列出关键集成测试场景及涉及的模块链路
+
+### 2.2 文档生成
+
+按 `17-子模块依赖关系模板.md` 结构生成完整文档，包含：
+
+| 章节                 | 内容                                 | 必填 |
+| -------------------- | ------------------------------------ | ---- |
+| 依赖关系基本规则     | 架构分层、依赖类型、硬约束、外部边界 | ✅   |
+| 主模块依赖矩阵       | N×N 矩阵表                           | ✅   |
+| 核心价值链路径       | 3~5 条核心路径 ASCII 图              | ✅   |
+| 全局共享服务         | 共享服务清单表                       | ✅   |
+| 循环依赖避免策略     | 模块对解耦方案                       | ✅   |
+| Saga 跨模块事务编排  | 关键 Saga 链路和补偿策略             | ✅   |
+| 领域事件完整清单     | 按模块分组的事件表                   | ✅   |
+| 跨模块高频共享 DTO   | DTO 清单表                           | ✅   |
+| 子模块级精细依赖     | 每个子模块的跨模块依赖               | ✅   |
+| 跨模块实体ID引用关系 | 被引用最多的实体统计                 | ✅   |
+| 开发与测试优先级     | 开发层次、顺序、集成测试路径         | ✅   |
+
+### 2.3 步骤2质量检查
+
+- [ ] 依赖矩阵覆盖了所有主模块对（含外部系统列）
+- [ ] 无循环依赖（每对模块间的依赖方向清晰）
+- [ ] 每个 ✓ 依赖都有对应的子模块级精细依赖说明
+- [ ] 每个 ⚡ 事件依赖都有对应的领域事件定义
+- [ ] 所有核心价值链路径可追溯到具体模块
+- [ ] Saga 编排覆盖了关键跨模块事务场景
+- [ ] 领域事件命名遵循 `{project}.{module}.{action}` 格式
+- [ ] 每个领域事件至少有一个订阅者
+- [ ] 共享 DTO 清单覆盖了所有 ✓ 依赖关系
+- [ ] 开发优先级层次合理（从底向上）
+- [ ] 集成测试关键路径覆盖了核心端到端场景
+- [ ] 循环依赖避免策略覆盖了所有双向交互模块对
+- [ ] 全局共享服务清单完整
+
+### 2.4 用户确认
+
+向用户展示步骤2成果摘要：
+
+- 依赖矩阵概览（强依赖对数量、事件依赖数量）
+- 核心价值链路径列表
+- 领域事件总数（按模块分布）
+- Saga 编排数量
+- 建议开发顺序
+- 质量检查结果
+
+**如果用户选择了全部 3 种架构类型**，询问用户是否继续步骤3，或需要调整步骤2的内容。
+
+**如果用户仅选择了功能架构 + 子模块依赖关系（类型1+2）**，或仅选择了子模块依赖关系（类型2），此处即为完成，直接进入完成报告。
+
+---
+
+## 步骤 3：统一数据建模（架构类型 3）
+
+> **前置条件**：必须已完成步骤1（功能架构），且 `01-{项目简称}_business_architecture.md` 文件存在
+> **模板**：`.adspecs/templates/18-统一数据模型模板.md`
+> **输入**：步骤1的业务场景文档 + 步骤2的模块依赖文档（如果已执行步骤2）
+> **输出**：`{ARCH_DIR}/04-{项目简称}_unified_data_model.md`
+
+### 前置检查
+
+在开始步骤3之前，**必须**验证：
+
+1. 检查 `{ARCH_DIR}/01-{项目简称}_business_architecture.md` 是否存在
+2. 如果不存在，提示用户：「功能架构文档不存在，请先执行步骤1（功能架构规划）」
+3. 读取功能架构文档，提取模块定义、业务场景、实体关系等信息
+4. **可选**：检查 `{ARCH_DIR}/03-{项目简称}_sub_module_dependencies.md` 是否存在
+   - 如果存在，读取其中的依赖关系、领域事件、共享DTO等信息，用于完善数据建模
+   - 如果不存在，仅基于功能架构文档进行数据建模（跳过与依赖关系相关的内容）
+
+### 3.1 分析与设计
+
+基于步骤1的功能架构文档（以及步骤2的模块依赖文档，如果可用），完成以下分析：
+
+#### 3.1.1 共享内核设计
+
+1. **基础实体**：定义平台 BaseEntity 的审计字段规范
+2. **通用值对象**：提取跨模块复用的值对象（如 Address、Contact、Money、BankAccount 等）
+3. **共享枚举**：定义跨模块共享的枚举（如客户类型、状态枚举、币种、贸易术语等）
+
+#### 3.1.2 各模块数据模型
+
+为每个一期业务模块（P0/P1）设计完整数据模型：
+
+1. **聚合根**：
+   - 业务定位说明
+   - 完整字段表（字段名、类型、约束、说明）
+   - 标注 UK（唯一键）、FK（外键引用）
+   - 状态机定义（状态枚举 + 流转路径）
+
+2. **实体**：
+   - 与聚合根的关系（1:N / 1:1）
+   - 完整字段表
+
+3. **枚举**：
+   - 枚举值列表及说明
+   - 状态机枚举用箭头标注流转路径
+
+**每个聚合根/实体必须标注微服务归属（端口-服务名）。**
+
+#### 3.1.3 跨模块集成数据模型
+
+1. **共享 DTO 定义**：
+   - 每个 DTO 标注所属服务、核心字段、消费方
+   - 与步骤2的共享 DTO 清单对齐
+
+2. **领域事件 Payload Schema**：
+   - 为每个服务的关键事件定义 JSON Schema
+   - 与步骤2的领域事件清单对齐
+   - 包含 eventId、eventType、关键业务字段、timestamp
+
+3. **事件 Topic 路由表**：
+   - Topic、发布方、消费方、QoS（至少一次/恰好一次）
+
+#### 3.1.4 数据治理策略
+
+1. **快照冗余策略**：跨服务高频读取字段的创建时快照方案
+2. **版本管理**：报价单/合同/预测等需要版本化的实体策略
+3. **软删除**：统一遵循 delete_flag = 1 规范
+4. **数据生命周期**：操作日志、变更历史、已关闭单据、主数据的保留和归档策略
+
+#### 3.1.5 ER 关系总览
+
+**必须**同时提供 ASCII 图和 Mermaid 格式的 ER 关系图：
+
+##### ASCII 图（传统格式）
+
+用 ASCII 图绘制全局 ER 关系图：
+
+- 标注架构分层（如 L1/L2）
+- 标注服务归属（端口号）
+- 标注关系基数（1:1、1:N）
+- 标注跨服务引用
+
+##### Mermaid ER 图（推荐格式）
+
+使用 Mermaid erDiagram 语法绘制完整 ER 图，便于在支持 Mermaid 的工具中渲染：
+
+```mermaid
+erDiagram
+    %% 聚合根定义
+    CUSTOMER {
+        string id PK
+        string customer_code UK
+        string name
+        string type
+        string status
+        string contact_info
+        datetime created_at
+    }
+    
+    SALES_ORDER {
+        string id PK
+        string order_no UK
+        string customer_id FK
+        decimal total_amount
+        string status
+        datetime order_date
+        datetime created_at
+    }
+    
+    ORDER_LINE {
+        string id PK
+        string order_id FK
+        string product_id FK
+        int quantity
+        decimal unit_price
+        decimal subtotal
+    }
+    
+    PRODUCT {
+        string id PK
+        string product_code UK
+        string name
+        string category
+        decimal price
+        string status
+    }
+    
+    %% 关系定义
+    CUSTOMER ||--o{ SALES_ORDER : "拥有 (1:N)"
+    SALES_ORDER ||--|{ ORDER_LINE : "包含 (1:N)"
+    PRODUCT ||--o{ ORDER_LINE : "被引用 (1:N)"
+    
+    %% 跨服务引用标注
+    %% CUSTOMER 属于 M03 客户服务 [端口:8103]
+    %% SALES_ORDER 属于 M04 销售服务 [端口:8104]
+    %% PRODUCT 属于 M02 产品数据服务 [端口:8102]
+```
+
+**Mermaid ER 图要求**：
+
+1. **实体完整性**：覆盖所有一期（P0/P1）模块的聚合根
+2. **字段规范**：每个实体列出主键（PK）、唯一键（UK）、外键（FK）和核心业务字段
+3. **关系标注**：使用 Mermaid 标准关系符号（||--||、||--o{、}o--o{ 等）并添加中文注释说明
+4. **服务归属**：在注释中标注每个实体所属的微服务模块和端口号
+5. **跨服务引用**：用虚线或注释标注跨服务的 FK 引用关系
+6. **可读性**：按模块分组排列实体，避免关系线交叉过多
+
+**示例关系符号说明**：
+- `||--||` : 一对一（必须）
+- `||--o|` : 一对一（可选）
+- `||--|{` : 一对多（必须）
+- `||--o{` : 一对多（可选）
+- `}o--o{` : 多对多
+
+### 3.2 文档生成
+
+按 `18-统一数据模型模板.md` 结构生成完整文档，包含：
+
+| 章节               | 内容                                             | 必填 |
+| ------------------ | ------------------------------------------------ | ---- |
+| 文档说明           | 目的范围、设计原则、术语约定                     | ✅   |
+| 共享内核           | 基础实体、通用值对象、共享枚举                   | ✅   |
+| 各模块核心数据模型 | 每个一期模块的聚合根、实体、枚举、状态机         | ✅   |
+| 跨模块集成数据模型 | 共享DTO、事件Payload Schema、Topic路由表         | ✅   |
+| 数据治理策略       | 快照冗余、版本管理、软删除、数据生命周期         | ✅   |
+| ER 关系总览        | 全局 ER 关系图（ASCII 图 + Mermaid ER 图）       | ✅   |
+
+**Mermaid ER 图生成要求**：
+
+1. 在文档末尾单独设立「附录：Mermaid ER 关系图」章节
+2. 提供完整的 Mermaid erDiagram 代码块，可直接复制到支持 Mermaid 的工具中渲染
+3. 实体按模块分组，使用注释 `%%` 标注模块归属和服务端口
+4. 所有聚合根及其关系必须与 ASCII 图保持一致
+5. 如果实体数量过多（>20），可拆分为多个 Mermaid 图（按业务域分组）
+
+### 3.3 步骤3质量检查
+
+- [ ] 每个一期业务模块（P0/P1）都有完整的数据模型定义
+- [ ] 每个聚合根有完整字段表和状态机定义
+- [ ] 所有实体标注了微服务归属
+- [ ] 共享值对象（Address、Contact 等）被多模块引用，而非重复定义
+- [ ] 共享枚举列表与步骤1中的业务场景一致
+- [ ] 共享 DTO 清单与步骤2中的共享 DTO 清单完全对齐（如果步骤2已执行）
+- [ ] 每个领域事件有完整的 Payload JSON Schema（如果步骤2已执行）
+- [ ] Payload Schema 与步骤2的领域事件清单一一对应（如果步骤2已执行）
+- [ ] Topic 路由表覆盖了所有跨服务事件（如果步骤2已执行）
+- [ ] 快照冗余策略覆盖了所有跨服务高频读取字段
+- [ ] **ASCII ER 关系图**覆盖了所有聚合根及其关系
+- [ ] **Mermaid ER 图**覆盖了所有聚合根及其关系，且语法正确可渲染
+- [ ] ASCII 图与 Mermaid 图的实体和关系保持完全一致
+- [ ] Mermaid 图中的关系基数（1:1、1:N）与聚合根字段表一致
+- [ ] Mermaid 图中每个实体标注了 PK、UK、FK
+- [ ] Mermaid 图中使用注释标注了服务归属和端口号
+- [ ] ER 图中的关系基数（1:1、1:N）与聚合根字段表一致
+- [ ] 数据生命周期策略覆盖了所有数据类型
+- [ ] 所有 FK 引用指向有效的聚合根
+
+### 3.4 用户确认
+
+向用户展示步骤3成果摘要：
+
+- 聚合根总数（按模块分布）
+- 实体总数
+- 枚举总数
+- 共享 DTO 数量
+- 领域事件 Payload Schema 数量
+- 质量检查结果
+
+---
+
+## 完成报告
+
+全部选定架构类型完成后，向用户呈现完整报告：
+
+### 产出文件
+
+根据用户选择的架构类型，展示对应的产出文件：
+
+| 架构类型       | 文件             | 路径                                                  |
+| -------------- | ---------------- | ----------------------------------------------------- |
+| 功能架构（1）  | 业务功能架构规划 | `{ARCH_DIR}/01-{项目简称}_business_architecture.md`   |
+| 子模块依赖（2）| 模块依赖关系     | `{ARCH_DIR}/03-{项目简称}_sub_module_dependencies.md` |
+| 统一数据建模（3）| 统一数据模型   | `{ARCH_DIR}/04-{项目简称}_unified_data_model.md`      |
+
+### 统计概览
+
+根据已执行的架构类型，展示对应统计：
+
+**功能架构（如已执行）**：
+- 主模块数量 / 子模块总数 / 业务功能总数 / 端到端场景数
+
+**子模块依赖关系（如已执行）**：
+- 领域事件总数 / 共享 DTO 数量 / Saga 编排数量
+
+**统一数据建模（如已执行）**：
+- 聚合根数量 / 实体数量 / 枚举数量
+- **Mermaid ER 图已生成**（可复制到支持 Mermaid 的工具中渲染）
+
+**整体**：
+- 已生成文档的质量检查通过率
+- 跨文档共享元素一致性验证结果
+
+### 后续步骤建议
+
+```
+/adspecs-prd                    → 为具体模块生成 PRD
+/adspecs-clarify                → 澄清 PRD 中的模糊点
+/adspecs-plan                   → 为具体模块做详细系统设计（OOA+OOD+DDL）
+/adspecs-analyze                → 跨文档一致性检查
+/adspecs-adversarial-review     → 多角色对抗性评审
+```
+
+## 必选执行后钩子
+
+**必须在向用户报告完成之前完成本节。**
+
+检查项目根目录是否存在 `.adspecs/extensions.yml`。
+
+- 如果不存在，或 `hooks.after_planning` 下没有注册钩子，跳到完成报告。
+- 如果存在，读取它并查找 `hooks.after_planning` 下的条目。
+- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续完成报告。
+- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
+- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
+  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
+  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
+- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
+- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
+  - **必选钩子** (`optional: false`) — **必须为每个必选钩子发出 `EXECUTE_COMMAND:`**：
+
+    ```
+    ## 扩展钩子
+
+    **自动钩子**: {extension}
+    执行: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+
+  - **可选钩子** (`optional: true`):
+
+    ```
+    ## 扩展钩子
+
+    **可选钩子**: {extension}
+    命令: `/{command}`
+    描述: {description}
+
+    提示: {prompt}
+    执行: `/{command}`
+    ```
+
+## 关键规则
+
+- **灵活执行**：用户可选择执行 1 种、2 种或全部 3 种架构类型，而非强制串行执行全部步骤
+- **依赖约束**：子模块依赖关系（类型2）和统一数据建模（类型3）都依赖功能架构（类型1）的输出，但两者之间互不依赖
+- **前置检查**：步骤2和步骤3开始前必须验证功能架构文档存在，不存在则提示用户并自动加入执行计划
+- **可选输入**：步骤3的输入中，步骤2的模块依赖文档是可选的（如果用户未执行步骤2）
+- **模板驱动**：每种架构类型严格按照对应模板的结构生成，不遗漏必填章节
+- **可追溯性**：步骤2的依赖关系可追溯到步骤1的业务场景；步骤3的实体/事件可追溯到步骤1（+步骤2，如果可用）的定义
+- **一致性保障**：跨文档的共享元素（模块编号、事件名称、DTO名称）必须完全一致
+- **合理推断优先**：对非关键决策做出合理推断并记录假设，仅对显著影响模块划分的关键决策向用户澄清
+- **分期规划**：每个模块/子模块必须标注分期（一期P0/P1、远期P2），指导后续开发优先级
+- **ER 图双格式**：统一数据建模必须同时提供 ASCII 图和 Mermaid erDiagram 两种格式，且保持内容一致
+- **命名规范**：
+  - 文件命名：`{NN}-{项目简称}_{英文描述}.md`，全小写+下划线
+  - 模块编号：M00~M{N}
+  - 事件命名：`{project}.{module}.{action}`
+  - Topic命名：`{project}.m{xx}.{module}.{action}`
+- **禁止过度设计**：远期模块（P2）只需列出模块名和核心职责，不需要详细的子模块拆分和业务场景
+- **禁止虚构需求**：所有模块和场景必须从用户输入/已有文档中推导，不自行添加无关功能
+
+## 快速指南
+
+### AI 生成指南
+
+从用户描述创建架构规划文档时：
+
+1. **类型选择**：先让用户选择要执行的架构类型（1/2/3 或组合）
+2. **前置检查**：如果选择了类型2或类型3，验证类型1的文档已存在
+3. **模块识别**：从核心业务范围中提取业务域，每个业务域 1~3 个模块（类型1）
+4. **子模块拆分**：按业务场景拆分，确保每个子模块可独立开发（类型1）
+5. **场景编写**：聚焦"谁做什么"而非"系统如何实现"（类型1）
+6. **依赖分析**：从场景中的跨模块操作推导依赖关系（类型2）
+7. **数据建模**：从业务实体和状态流转推导聚合根和字段设计（类型3）
+8. **ER 图绘制**：同时生成 ASCII 图和 Mermaid erDiagram，保持一致性（类型3）
+9. **像架构师一样思考**：关注模块边界、依赖方向、数据一致性策略
+
+### 模块划分指南
+
+好的模块划分应该：
+
+1. **高内聚**：模块内的子模块共享相同的业务上下文
+2. **低耦合**：模块间通过明确定义的接口（Client SDK / 事件）交互
+3. **独立部署**：每个模块可映射到一个微服务
+4. **团队对齐**：一个开发团队可以负责一个模块的完整开发
+
+**不好的模块划分**：
+
+- 一个模块包含不相关的业务功能（如"客户+物流"合为一模块）
+- 同一业务实体被多个模块拥有（如"客户"同时出现在 M03 和 M07）
+- 模块粒度太细（如每个子模块都独立成模块）
+- 模块间存在循环依赖
+
+## 完成标志
+
+- [ ] 用户已选择要执行的架构类型（1/2/3 或组合）
+- [ ] 前置条件检查通过（类型2/3 需要类型1的文档存在）
+- [ ] 功能架构文档已生成并通过质量检查（如果选择了类型1）
+- [ ] 模块依赖文档已生成并通过质量检查（如果选择了类型2）
+- [ ] 统一数据模型文档已生成并通过质量检查（如果选择了类型3）
+- [ ] **Mermaid ER 图语法正确且与 ASCII 图一致**（如果选择了类型3）
+- [ ] 已生成文档间的共享元素（模块编号、事件名称、DTO名称）一致性已验证
+- [ ] 扩展钩子已根据必选执行后钩子规则分发或跳过
+- [ ] 完成报告已呈现给用户，包含产出文件路径、统计概览和后续步骤建议