adspecs 0.1.12

package/skills/adspecs-tasks/SKILL.md

@@ -0,0 +1,630 @@
+---
+name: "adspecs-tasks"
+description: "基于统一系统设计文档（_system-design.md），为 ECP 平台功能生成 TDD 就绪的、按依赖排序的 tasks.md 文件"
+argument-hint: "指定系统设计文档路径，如 docs/30-system-design/crm/M06-01-销售预测_system-design.md"
+compatibility: "需要 adspecs 项目结构，含 adspecs/ 目录 + CLAUDE.md（ECP 编码规范）+ docs/30-system-design + .adspecs/templates"
+metadata:
+  author: "qingwen"
+  source: "基于 adspecs-tasks 通用模板 + ECP 平台编码规范 + TDD 流程改造"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+在处理之前**必须**考虑用户输入（若不为空）。用户输入应为**统一系统设计文档的路径**（如 `docs/30-system-design/crm/M06-01-销售预测_system-design.md`），若为空则尝试从上下文推导。
+
+## 路径配置加载
+
+在开始执行之前，先确定输入/输出目录：
+
+1. 检查项目根目录是否存在 `.adspecs/paths.json`
+2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键
+3. 如果不存在或配置键缺失，使用下方表格中的默认值
+
+| 配置键       | 默认值                  | 用途                                       |
+| ------------ | ----------------------- | ------------------------------------------ |
+| `design_dir` | `docs/30-system-design` | 系统设计文档目录（输入）和任务清单输出目录 |
+
+将解析后的路径记为 `DESIGN_DIR`，后续步骤中引用此变量而非硬编码路径。
+
+## 执行前检查
+
+**检查扩展钩子（任务生成前）**：
+
+- 检查项目根目录下是否存在 `.adspecs/extensions.yml` 文件。
+- 如果存在，读取该文件并查找 `hooks.before_tasks` 键下的条目。
+- 如果 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` 不存在，则静默跳过。
+
+---
+
+## ECP 平台编码规范（任务生成强制校验清单）
+
+> **来源**：CLAUDE.md §"Code Generation Rules (ECP Backend)"。
+> **以下10条规则在生成每个任务时必须满足，违反任何一条即为不合格任务。**
+
+| #   | 规则                                     | 说明                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **Entity 规范**                          | `extends BaseEntity<Entity>`, `@TableName` 用反引号, 所有字段 `@TableField` + `@Schema`, `IdType.ASSIGN_ID`。审计字段继承自 BaseEntity，Entity 中禁止重复声明                                                                                                                                                                                                                                                              |
+| 2   | **DTO 规范**                             | `extends ReqeustCommonDataBean`（注意平台拼写），校验分组为内部接口（`saveXxx`/`updateXxx`），日期字段 `@JSONField(format = "yyyy-MM-dd HH:mm:ss")`，消息格式 `{port}_{table_snake}_{三位序号}`                                                                                                                                                                                                                            |
+| 3   | **DAO 规范**                             | `extends BaseCommonDAO_HI<Entity>`, `@Component("{camel}DAO")`，**MyBatis XML 与 DAO 接口同包路径**，所有 SELECT 必须含 `WHERE delete_flag = 0`，resultMap 映射所有字段含审计字段                                                                                                                                                                                                                                          |
+| 4   | **禁止 QueryWrapper/LambdaQueryWrapper** | 所有 DB 操作通过 MyBatis XML 实现，绝对禁止使用 MyBatis Plus 条件构造器                                                                                                                                                                                                                                                                                                                                                    |
+| 5   | **Service 规范**                         | 接口 `II{Entity}`（双I前缀）`extends IBaseCommon<Entity>`，实现 `extends BaseCommonServer<Entity>`, `@Component("{camel}Service")`。Save 用 **FastJSON**：`JSONObject.parseObject(JSONObject.toJSONString(dto), Entity.class)`。Update 用 **Spring BeanUtils**：`BeanUtils.copyProperties(dto, entity, "createdBy", "creationDate", "versionNum")`。软删除：`this.deleteById(id, true)`。分页默认排序 `creation_date desc` |
+| 6   | **Controller 规范**                      | `extends CommonAbstractService`，重写 `getBaseCommonServer()`，所有端点 `@CheckToken`。标准路径：`/get-id`, `/find-pagination`, `/save`, `/update`, `/delete`。请求包装 `RequestData<Dto>` / `PaginationRequestData<Dto>`，响应包装 `ResponseData<T>`                                                                                                                                                                      |
+| 7   | **Ro（只读视图）规范**                   | `implements Serializable` + `serialVersionUID`，手动声明所有字段（不继承 BaseEntity），置于 `model/entity/readonly/`。日期字段标注 `@DateTimeFormat @JsonFormat`                                                                                                                                                                                                                                                           |
+| 8   | **异常处理**                             | **异常在 Service 层抛出**（`RecordNotExistsException`、`GushenRuntimeException`），Controller 仅做参数空校验返回 `ResponseData.fail()`。所有消息引用 `ResponseMsgCode` 枚举，**禁止硬编码字符串**                                                                                                                                                                                                                          |
+| 9   | **i18n 规范**                            | 每个模块 7 个 `.properties` 文件（default/zh_CN/zh_TW/en_US/vi_VN/th_TH/hu_HU），位于 `src/main/resources/config/`，**每个语言文件必须包含该语言的实际翻译内容**                                                                                                                                                                                                                                                           |
+| 10  | **注入与工具**                           | `@Autowired` 注入（Spring），FastJSON 序列化，Hutool 工具类优先（`StrUtil`, `CollUtil`, `BeanUtil`, `ObjectUtil`），SLF4J 日志                                                                                                                                                                                                                                                                                             |
+
+### ECP 三模块结构速查
+
+```
+{port}-{service}-api/          # 契约层：Feign Client + DTO
+{port}-{service}-model/        # 数据层：Entity + DAO + Mapper XML + Ro
+{port}-{service}-application/   # 实现层：Service + Controller + Config + Consumer + Enum + i18n
+```
+
+### ECP 平台关键依赖速查
+
+| 平台能力 | 使用方式                                                                             | 适用场景                   |
+| -------- | ------------------------------------------------------------------------------------ | -------------------------- |
+| Redis    | `DawnRedis`，键格式 `{port}:{business}:{identifier}`，通过 `ICacheKey` 枚举管理      | 配置缓存、详情缓存         |
+| ES       | `Es.chainLambdaQuery(Class)` / `Es.chainLambdaUpdate(Class)`                         | 列表搜索（本期可能不涉及） |
+| 分布式锁 | `@Klock(keys = {"#dto.field"}, waitTime=60, leaseTime=60)`，**禁止空 keys**          | 变更单并发控制等           |
+| 文件中心 | `IotBaseAttachmentClient`，业务类型命名 `{module}_{entity}_{type}`                   | 附件上传（本期可能不涉及） |
+| BPM/审批 | `BpmHelper.startProcess(processDefKey, businessId)`，Consumer 为 `@Configuration` 类 | 变更单审批流程             |
+| IdToName | `@IdToName(alias="nameField", type=IdToNameType.USER)` + `@EnableIdToName`           | 提报人/审批人名称回填      |
+| 自动编码 | `AutoCodeRuleService.generate(prefix, length)`                                       | 预测单号/变更单号生成      |
+| 加密     | `EncryUtil.encrypt(plainText)` / `decrypt(cipherText)`                               | 敏感字段（本期可能不涉及） |
+| 配置     | `ServerConfigConmonUtil.get(key, tenantId, redisTemplate, defaultValue)`             | 提报提前期/强制转FO天数    |
+
+---
+
+## 大纲
+
+### 1. 定位统一系统设计文档
+
+1. **确定设计文档路径**：
+   - 从 `$ARGUMENTS` 获取设计文档路径（如 `{DESIGN_DIR}/crm/M06-01-销售预测_system-design.md`）
+   - 若 `$ARGUMENTS` 为空，搜索 `{DESIGN_DIR}/crm/` 或 `{DESIGN_DIR}/mom/` 下最新修改的 `*_system-design.md` 文件
+   - 若仍找不到，搜索当前打开文件或上下文中引用的设计文档
+   - 确认文件存在且可读取
+
+2. **加载 CLAUDE.md**：读取项目根目录下的 `CLAUDE.md`，获取完整的平台编码规范和代码生成规则
+
+3. **定位模板文件**（如果存在）：
+   - 检查 `.adspecs/templates/05-后端任务清单模板.md` 下的相关模板
+
+### 2. 提取设计文档信息
+
+> 统一设计文档（由 `adspecs-plan` 产出）包含 13 个章节，一次性覆盖 OOA+OOD。按以下顺序提取所有任务生成所需信息。
+
+#### 2.1 从 §1 提取：需求映射与模块上下文
+
+| 提取项        | 来源                  | 用途                         |
+| ------------- | --------------------- | ---------------------------- |
+| 用户故事映射  | §1.1.1 用户故事映射表 | 生成用户故事阶段（Phase 3+） |
+| 业务规则映射  | §1.1.2 业务规则映射表 | 生成 Service 校验逻辑任务    |
+| 功能条目映射  | §1.1.3 功能条目映射表 | 生成 Controller 端点任务     |
+| 权限映射      | §1.1.4 权限映射表     | 生成权限配置任务             |
+| 模块名称/端口 | §1.2 模块定位         | 生成三模块路径 + 消息码前缀  |
+| 上下游依赖    | §1.3 上下文边界       | 生成 Feign Client 任务       |
+| 核心职责      | §1.4 核心职责         | 验证任务覆盖完整性           |
+
+#### 2.2 从 §2 提取：实体与领域对象
+
+| 提取项      | 来源                                   | 用途                                 |
+| ----------- | -------------------------------------- | ------------------------------------ |
+| Entity 清单 | §2.2 实体清单 → 每个实体的完整字段表   | 生成 Entity 类任务（字段+注解+索引） |
+| DTO 清单    | §2.3 DTO 清单 → 字段+校验规则+验证分组 | 生成 DTO 类任务                      |
+| Ro 清单     | §2.4 Ro 清单 → 字段+注解               | 生成 Ro 类任务                       |
+
+#### 2.3 从 §3 提取：数据模型
+
+| 提取项       | 来源                                  | 用途                    |
+| ------------ | ------------------------------------- | ----------------------- |
+| 数据库表结构 | §3.2 数据库表设计 → 表名+字段+索引    | 生成 Liquibase DDL 任务 |
+| MyBatis 映射 | §3.3 MyBatis 映射 → DAO 接口+XML 结构 | 生成 DAO + XML 任务     |
+
+#### 2.4 从 §4 提取：业务行为与 Service
+
+| 提取项       | 来源                                  | 用途                           |
+| ------------ | ------------------------------------- | ------------------------------ |
+| 业务行为清单 | §4.1 业务行为清单                     | 生成 Service 方法任务          |
+| 状态机       | §4.3 状态机图 → 状态+转换条件         | 确保状态流转任务覆盖           |
+| Service 接口 | §4.4 Service 接口设计 → 方法签名+事务 | 生成 Service 接口+实现任务     |
+| 关键方法逻辑 | §4.5 Service 实现逻辑 → 伪代码        | 确保实现任务描述精确           |
+| 事务边界     | §4.6 事务边界汇总                     | 确保 `@Transactional` 标记准确 |
+
+#### 2.5 从 §5 提取：接口与 Controller
+
+| 提取项          | 来源                                    | 用途                     |
+| --------------- | --------------------------------------- | ------------------------ |
+| 端点清单        | §5.1 端点清单 → HTTP+路径+请求/响应包装 | 生成 Controller 方法任务 |
+| Controller 骨架 | §5.2 Controller 代码骨架 → 方法路由表   | 确保路由映射准确         |
+| 权限矩阵        | §5.4 权限矩阵                           | 生成权限控制任务         |
+
+#### 2.6 从 §6 提取：枚举与数据字典
+
+| 提取项   | 来源                                      | 用途                       |
+| -------- | ----------------------------------------- | -------------------------- |
+| 枚举定义 | §6.1 枚举值定义 → 每个枚举的编码+显示名称 | **每个枚举独立成一个任务** |
+| 校验规则 | §6.2 数据校验规则 → 字段+注解+消息码      | 生成 DTO 校验注解任务      |
+
+#### 2.7 从 §7 提取：异常处理
+
+| 提取项       | 来源                                         | 用途                        |
+| ------------ | -------------------------------------------- | --------------------------- |
+| 业务异常清单 | §7.1 业务异常清单 → 消息码+触发条件+抛出位置 | 生成异常处理+消息码常量任务 |
+| 消息码汇总   | §7.3 消息码汇总 → properties 内容            | 生成 i18n 文件任务          |
+
+#### 2.8 从 §8-§12 提取：横切关注点
+
+| 提取项       | 来源                                | 用途                        |
+| ------------ | ----------------------------------- | --------------------------- |
+| 缓存策略     | §8.1 缓存策略 → 键格式+过期时间     | 生成缓存配置任务            |
+| 并发控制     | §8.3 并发控制 → 乐观锁/@Klock       | 生成并发控制任务            |
+| 领域事件     | §9 领域事件 → 发布/消费事件         | 生成 Kafka Consumer 任务    |
+| 跨模块依赖   | §10 跨模块依赖 → Feign Client + SDK | 生成 Feign Client 任务      |
+| 非功能性需求 | §11 非功能性需求                    | 生成收尾阶段的性能/安全任务 |
+
+#### 2.9 从 §13 提取：代码结构
+
+| 提取项     | 来源                            | 用途                               |
+| ---------- | ------------------------------- | ---------------------------------- |
+| 完整目录树 | §13 附录 → 3模块 ~45 个文件路径 | **作为所有任务文件路径的权威来源** |
+| 目录统计   | §13 目录树统计                  | 验证任务总数覆盖                   |
+
+### 3. 执行任务生成工作流
+
+按以下顺序生成任务：
+
+1. **从 §13 提取三模块目录结构**：
+   - 确定 `{port}`（如 `3103`）、`{service}`（如 `sales-forecast`）
+   - 确定包根路径（如 `com.sie.gushen.salesforecast`）
+   - 列出所有 ~45 个目标文件路径
+
+2. **从 §1.1.1 提取用户故事并按优先级分组**：
+   - P1 故事：US-01~US-05, US-09（预测单创建/提交/评审/排产/转FO/变更/撤回）→ 核心流程
+   - P2 故事：US-06~US-08, US-10（概览/释放/取消删除/配置）→ 辅助功能
+   - 确认故事间依赖关系
+
+3. **按 ECP 三模块 + TDD 顺序组织任务**（详见 §任务生成规则）
+
+4. **生成依赖关系图**
+
+5. **创建并行执行示例**
+
+6. **验证任务完整性**：
+   - 所有实体/DTO/Ro/DAO/Service/Controller 都有对应任务
+   - 所有枚举都有独立任务
+   - 所有消息码都有 i18n 任务
+   - 所有 Feign Client 依赖都有任务
+   - 所有消费者/定时任务都有任务
+
+### 4. 生成 tasks.md
+
+使用 `.adspecs/templates/05-后端任务清单模板.md` 下的任务模板作为结构参考（若不存在则按本节结构生成）。必须包含以下全部章节：
+
+1. **功能名称 + 元数据**（来源设计文档 §1.2）
+2. **文件路径速查表**（所有目标文件的绝对路径清单，按三模块组织）
+3. **ECP 合规检查清单**（10 条规则，标记每条是否满足）
+4. **Phase 1**：项目初始化（Maven POM、启动类、application.yml、三模块目录）
+5. **Phase 2**：基础设施（枚举类 ×N、消息码常量、Liquibase DDL、MyBatis Plus 配置）
+6. **Phase 3+**：每个用户故事一个阶段（P1→P2 顺序），阶段内按 TDD 顺序排列
+7. **Final Phase**：集成与收尾（集成测试、代码评审、API 文档、安全清单、性能验证）
+8. **依赖关系图**（故事完成顺序 + 并行机会）
+9. **并行执行示例**（每个故事的并行执行策略）
+10. **实现策略**（MVP 范围 = P1 故事，增量交付路径）
+11. **TDD 执行指南**（每个故事阶段内测试→实现→验证的严格顺序）
+
+---
+
+## 强制性执行后钩子
+
+**在向用户报告完成之前，必须完成此部分。**
+
+检查项目根目录下是否存在 `.adspecs/extensions.yml` 文件。
+
+- 如果不存在，或 `hooks.after_tasks` 下没有注册任何钩子，则跳到《完成报告》。
+- 如果存在，读取该文件并查找 `hooks.after_tasks` 键下的条目。
+- 如果 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}`
+    ```
+
+## 完成报告
+
+输出生成的 tasks.md 路径及摘要：
+
+- **设计文档来源**：使用的 `_system-design.md` 路径
+- **任务总数**：含各阶段分布
+- **每个用户故事的任务数量**：含 TDD 测试任务/实现任务分别计数
+- **文件覆盖**：Entity ×N, DTO ×N, Ro ×N, DAO ×N, Service ×N, Controller ×N, Feign ×N, Enum ×N, i18n ×7, Consumer ×N, Config ×N
+- **ECP 合规检查结果**：10 条规则逐条确认通过
+- **TDD 就绪确认**：是否每个故事阶段内测试任务均在实现任务之前
+- **识别到的并行执行机会**：标注可并行的任务数
+- **每个故事的独立测试标准**：从设计文档 §12 提取
+- **建议的 MVP 范围**：P1 用户故事（US-01~US-05 + US-09）
+- **格式验证**：确认所有任务遵循 `[TaskID] [P?] [TDD?] [Story?] 描述 + 文件路径` 格式
+
+---
+
+## 任务生成规则
+
+### 关键约束
+
+1. **任务必须按用户故事组织**：每个故事独立可测试，支持独立实现
+2. **TDD 严格排序**：每个故事阶段内，测试任务必须在实现任务之前
+3. **ECP 编码规范强制遵守**：每个任务描述必须包含正确的 ECP 父类/注解/命名
+4. **文件路径精确**：每个任务必须包含从三模块根目录开始的完整文件路径
+5. **设计文档全量覆盖**：§1~§13 的所有设计元素都必须映射到对应任务
+
+### 检查清单格式（必需）
+
+每个任务必须严格遵循以下格式：
+
+```text
+- [ ] [TaskID] [P?] [TDD?] [Story?] 包含精确文件路径的描述
+```
+
+**格式组成**：
+
+1. **复选框**：始终以 `- [ ]`（markdown 复选框）开头
+2. **任务 ID**：全局递增的顺序编号（T001, T002, T003...）
+3. **[P] 标记**：仅当任务可并行执行时添加（操作不同文件、不依赖未完成的任务）
+4. **[TDD] 标记**：仅当任务是测试任务时添加（单元测试/集成测试），**必须在同故事的实现任务之前**
+5. **[Story] 标签**：
+   - 格式：[US1], [US2], [US3]...（对应设计文档 §1.1.1 中的用户故事编号）
+   - Phase 1（项目初始化）：无故事标签
+   - Phase 2（基础设施）：无故事标签
+   - Phase 3+（用户故事）：**必须**有故事标签
+   - Final Phase（集成收尾）：无故事标签
+6. **描述**：明确操作 + 精确的文件路径（从 `{port}-{service}-{layer}/` 开始）
+
+**正确示例（ECP 风格）**：
+
+```text
+- [ ] T012 [TDD] [US1] 编写 ForecastOrderService 提交预测单测试
+      文件: 3103-sales-forecast-application/src/test/java/com/sie/gushen/salesforecast/model/service/impl/ForecastOrderServiceTest.java
+- [ ] T013 [US1] 创建 ForecastOrderEntity（extends BaseEntity<ForecastOrderEntity>, @TableName(`forecast_order`), 雪花ID主键）
+      文件: 3103-sales-forecast-model/src/main/java/com/sie/gushen/salesforecast/model/entity/ForecastOrderEntity.java
+- [ ] T014 [P] [US1] 创建 ForecastOrderDto（extends ReqeustCommonDataBean, 含 saveForecastOrder/updateForecastOrder 校验分组）
+      文件: 3103-sales-forecast-api/src/main/java/com/sie/gushen/salesforecast/api/dto/ForecastOrderDto.java
+- [ ] T015 [P] [US1] 创建 ForecastOrderDAO 接口 + ForecastOrderDAO.xml（extends BaseCommonDAO_HI, Base_Column_List, BaseResultMap, WHERE delete_flag=0）
+      文件: 3103-sales-forecast-model/src/main/java/com/sie/gushen/salesforecast/model/dao/ForecastOrderDAO.java
+      文件: 3103-sales-forecast-model/src/main/java/com/sie/gushen/salesforecast/model/dao/ForecastOrderDAO.xml
+```
+
+**错误示例**：
+
+```text
+- ❌ 错误：`- [ ] 创建 ForecastOrder 实体`（缺少 TaskID + 文件路径 + Story标签）
+- ❌ 错误：`T001 [US1] 创建 Entity`（缺少复选框 + 精确文件路径）
+- ❌ 错误：`- [ ] T001 [US1] 创建 Entity`（缺少文件路径）
+- ❌ 错误：`- [ ] T010 [US1] 实现提交预测单 Service 方法`（缺少文件路径，且故事阶段内未先写测试）
+- ❌ 错误：`- [ ] T020 [TDD] [US1] 测试提交`（文件路径缺失，描述模糊）
+```
+
+### TDD 任务排序规则（每个用户故事阶段内）
+
+> **关键原则**：`test-driven-development` skill 要求 "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"。tasks.md 的任务顺序必须体现此规则。
+
+每个用户故事阶段内的任务遵循严格排序：
+
+```
+[TDD] 测试任务（先写，先失败）
+  ↓
+枚举类（若该故事引入新枚举值且 Phase 2 未创建）
+  ↓
+Entity + DTO + Ro 类
+  ↓
+DAO 接口 + MyBatis XML
+  ↓
+Service 接口
+  ↓
+Service 实现（最小代码使测试通过）
+  ↓
+Controller 端点
+  ↓
+Feign Client（若涉及外部调用）
+  ↓
+i18n 配置
+```
+
+**测试任务粒度**：
+
+- 每个 Service 方法至少对应 1 个测试任务（正常场景 + 异常场景 + 边界场景）
+- 每个 Controller 端点至少对应 1 个集成测试任务
+- 测试任务标记 `[TDD]`，与 `[P]` 可共存（如：不同 Service 方法的测试可并行编写）
+
+**测试任务设计**：从设计文档 §12（测试场景）提取测试数据：
+
+- §12.1 正常场景 → 每个场景对应 1 个 `[TDD]` 任务
+- §12.2 异常场景 → 每个场景对应 1 个 `[TDD]` 任务
+- §12.3 边界场景 → 每个场景对应 1 个 `[TDD]` 任务
+
+### 任务组织方式
+
+#### 基于用户故事（设计文档 §1.1.1）——主要组织方式
+
+每个用户故事按故事优先级（P1 → P2）各占一个阶段：
+
+- P1 故事可以并行实现（如果它们操作不同的实体/模块）
+- P2 故事通常依赖 P1 故事的基础设施
+
+每个故事阶段内映射以下设计文档元素：
+
+- 该故事涉及的**实体**（§2.2）
+- 该故事涉及的**DTO**（§2.3）
+- 该故事涉及的**Ro**（§2.4）
+- 该故事涉及的**Service 方法**（§4.4）
+- 该故事涉及的**Controller 端点**（§5.1）
+- 该故事涉及的**异常**（§7.1）
+- 该故事涉及的**权限**（§5.4）
+
+#### 基于实体与数据模型（设计文档 §2+§3）
+
+- 每个 Entity 独立成一个任务，包含完整字段（带 @TableField + @Schema 注解）
+- 每个 DTO 独立成一个任务，包含校验分组（save/update 内部接口）
+- 每个 Ro 独立成一个任务，包含所有字段手动声明
+- 每个 DAO 接口 + XML 独立成一个任务组
+- 若实体服务于多个故事：放入最早依赖它的故事阶段，或 Phase 2 基础设施
+
+#### 基于枚举（设计文档 §6.1）
+
+**每个枚举类独立成一个任务**（Phase 2 基础设施阶段），原因：
+
+- 枚举被多个用户故事共享
+- 枚举定义是小而独立的单元
+- 枚举任务可并行执行（无相互依赖）
+
+#### 基于异常与消息码（设计文档 §7）
+
+- 所有消息码汇总到 `ResponseMsgCode` 常量类 → Phase 2 基础设施阶段
+- 消息码按前缀分组：`3103_forecast_order_*` / `3103_forecast_change_order_*`
+- 每个 Service 实现任务描述中必须注明可能抛出的异常
+
+#### i18n 任务生成规则
+
+- **每个模块 7 个 .properties 文件**：`{port}-{service}-application_*.properties`
+- 所有消息码文本从设计文档 §7.3 提取
+- i18n 任务可放在 Final Phase 或最后一个故事阶段（因为消息码在基础设施阶段已定义常量）
+
+#### Liquibase 任务生成规则
+
+- 从设计文档 §3.2 提取表结构 → 生成 DDL SQL
+- 3 个文件：`master.xml` → `v1.0.xml`（changeLog）→ `DDL_1.0_YYYYMMDD.sql`
+- 路径：`3103-sales-forecast-model/src/main/resources/liquibase/mysql/sales_forecast/`
+- 作为 Phase 2 基础设施的一个任务组
+
+#### Feign Client 任务生成规则
+
+- 从设计文档 §10.2 提取外部依赖 → 每个外部模块一个 Feign Client 接口
+- 如：`CtctClient.java`（P01 CTCT查询）、`BondedManualClient.java`（P03 保税手册）、`FoClient.java`（FO创建）、`ApsClient.java`（APS排产进度）
+- 路径：`3103-sales-forecast-api/src/main/java/com/sie/gushen/salesforecast/api/client/`
+
+#### Kafka Consumer 任务生成规则
+
+- 从设计文档 §9.1（发布事件）和 §9.2（消费事件）提取
+- 每个 Consumer 一个任务
+- 路径：`3103-sales-forecast-application/src/main/java/com/sie/gushen/salesforecast/app/consume/`
+
+### 阶段结构
+
+```
+Phase 1: 项目初始化
+  ├── T001 Maven 三模块 POM 配置（parent POM + 3 个 module POM）
+  ├── T002 启动类 {Service}Application（extends CommonApplication, @SpringBootApplication, @EnableDiscoveryClient, @EnableFeignClients, @MapperScan, @ComponentScan）
+  ├── T003 application.yml / bootstrap.yml 基础配置
+  └── T004 三模块目录结构创建
+
+Phase 2: 基础设施（阻塞性前置 — 所有用户故事依赖）
+  ├── 枚举类（每个枚举一个任务，可并行 [P]）
+  │   ├── ForecastOrderStatusEnum
+  │   ├── ChangeOrderStatusEnum
+  │   ├── DomesticForeignEnum
+  │   ├── ProductTypeEnum
+  │   ├── TransferStatusEnum
+  │   ├── QuantityUnitEnum
+  │   └── DeliveryLocationEnum
+  ├── 消息码常量 ResponseMsgCode
+  ├── Liquibase DDL（master.xml + v1.0.xml + DDL.sql）
+  ├── MyBatis Plus 配置（分页插件 + 乐观锁插件）
+  ├── SpringDoc API 文档配置
+  ├── 数据源配置 DataSourceConfig
+  └── 工具类（如强制转FO时间计算）
+
+Phase 3: US-01 创建并提报预测单 [P1]
+  ├── [TDD] 测试任务（至少 3 个：正常场景 + 提报提前期拦截 + MOQ 警告）
+  ├── ForecastOrderEntity
+  ├── ForecastOrderDto（saveForecastOrder/updateForecastOrder 分组）
+  ├── ForecastOrderEntityRo
+  ├── ForecastOrderDAO + XML（findPagination）
+  ├── IIForecastOrder 接口
+  ├── ForecastOrderService（saveForecastOrder, updateForecastOrder, submitForecastOrder）
+  ├── ForecastOrderController（save, update, submit 端点）
+  └── Feign Client（CtctClient — CTCT物料查询）
+
+Phase 4: US-02 计划部门评审预测单 [P1]
+  ├── [TDD] 测试任务（接收场景 + 驳回场景 + 状态校验）
+  ├── ForecastOrderService（acceptForecastOrder, rejectForecastOrder）
+  ├── ForecastOrderController（accept, reject 端点）
+  └── 权限配置
+
+Phase 5: US-09 撤回预测单 + US-08 取消/删除 [P1+P2]
+  ├── [TDD] 测试任务（撤回 + 已排产阻止 + 取消 + 物理删除）
+  ├── ForecastOrderService（withdrawForecastOrder, cancelForecastOrder, deleteForecastOrder）
+  └── ForecastOrderController（withdraw, cancel, delete 端点）
+
+Phase 6: US-03 查看APS排产反馈 [P1]
+  ├── [TDD] 测试任务（排产确认 + 乐观锁冲突）
+  ├── ForecastOrderService（scheduleConfirm）
+  ├── ForecastOrderController（schedule-confirm 端点）
+  ├── Kafka Consumer（ApsScheduleConfirmConsumer）
+  └── Feign Client（ApsClient — APS排产进度查询）
+
+Phase 7: US-04 预测单转履约单 [P1]
+  ├── [TDD] 测试任务（全部转 + 部分转 + 转单超限 + 状态校验）
+  ├── DTO（TransferToFoDto）
+  ├── ForecastOrderService（transferToFO）
+  ├── ForecastOrderController（transfer-to-fo 端点）
+  └── Feign Client（FoClient — FO创建 + SoClient — SO行项目查询）
+
+Phase 8: US-05 变更单修改预测单 [P1]
+  ├── [TDD] 测试任务（新增变更单 + 提交审批 + 审批通过联动 + 审批驳回 + 并发控制 + 校验场景）
+  ├── ForecastChangeOrderEntity
+  ├── ForecastChangeOrderDto + ApproveDto
+  ├── ForecastChangeOrderDAO + XML（findListByForecastOrderId, findIncompleteByForecastOrderId）
+  ├── IIForecastChangeOrder 接口
+  ├── ForecastChangeOrderService（save/submit/approve/reject/withdraw/delete/void）
+  ├── ForecastChangeOrderController（9 个端点）
+  └── Feign Client（BondedManualClient — P03 保税手册查询）+ BPM/BpmHelper 集成
+
+Phase 9: US-06 多维度概览 + US-07 释放预测单 [P2]
+  ├── [TDD] 测试任务（概览聚合 + 强制释放）
+  ├── ForecastOrderService（findOverview, forceRelease）
+  ├── ForecastOrderController（overview, force-release 端点）
+  └── 定时任务配置
+
+Phase 10: US-10 系统配置管理 [P2]
+  ├── 提报提前期配置接口
+  ├── 强制转FO天数配置接口
+  └── Feign Client（P01 组织架构 + P03 保税手册）
+
+Final Phase: 集成与收尾
+  ├── 集成测试（端到端流程 + Feign 联调）
+  ├── i18n 7 文件（所有消息码的全语言翻译）
+  ├── API 文档（SpringDoc 注解完善）
+  ├── 代码评审（按 ECP 编码规范检查）
+  ├── 安全清单（@CheckToken + 权限矩阵验证）
+  └── 性能验证（索引 + 缓存 + 分页）
+```
+
+### TDD 就绪确认
+
+生成 tasks.md 后，必须确认以下条件：
+
+- [ ] 每个用户故事阶段内，至少 1 个 `[TDD]` 任务排在所有实现任务之前
+- [ ] 每个 `[TDD]` 任务描述了明确的测试场景（正常/异常/边界）和测试数据
+- [ ] 测试任务与实现任务的对应关系清晰（1 个测试 → 1 个或多个实现任务）
+- [ ] tasks.md 包含 TDD 执行指南章节，说明 RED→GREEN→REFACTOR 循环
+- [ ] 任务顺序与 `test-driven-development` skill 的流程一致（先测试失败 → 最小实现 → 重构）
+
+### ECP 合规确认
+
+生成 tasks.md 后，必须确认：
+
+- [ ] 所有 Entity 任务描述包含 `extends BaseEntity<Entity>`
+- [ ] 所有 DTO 任务描述包含 `extends ReqeustCommonDataBean`（注意拼写）
+- [ ] 所有 DAO 任务描述包含 `extends BaseCommonDAO_HI` + `WHERE delete_flag = 0`
+- [ ] 无任何 QueryWrapper/LambdaQueryWrapper 相关任务
+- [ ] 所有 Service 任务描述包含 FastJSON（save）/ SpringBeanUtils（update）区分
+- [ ] 所有 Controller 任务描述包含 `extends CommonAbstractService` + `@CheckToken` + ResponseData
+- [ ] 所有 Ro 任务描述包含 `implements Serializable` + 手动字段
+- [ ] 异常任务描述中异常均来自 Service 层
+- [ ] i18n 任务覆盖 7 个语言文件
+- [ ] Feign Client 任务放入 `-api/client/` 路径
+
+---
+
+## 完成标准
+
+- [ ] tasks.md 已生成，包含所有阶段、TDD 标记、精确文件路径
+- [ ] 扩展钩子已根据上述《强制性执行后钩子》的规则派发或跳过
+- [ ] 所有 10 条 ECP 编码规范已通过合规确认
+- [ ] 所有故事阶段 TDD 就绪（测试任务在实现任务之前）
+- [ ] 已向用户报告完成情况
+
+---
+
+## 参考：设计文档章节 → 任务生成速查表
+
+| 设计文档章节         | 提取内容                | 生成任务类型                 | Phase                          |
+| -------------------- | ----------------------- | ---------------------------- | ------------------------------ |
+| §1.1.1 用户故事      | US-01~US-10 优先级      | 阶段划分                     | Phase 3+                       |
+| §1.2 模块定位        | 服务名/端口/包路径      | 路径前缀                     | Phase 1                        |
+| §1.3 上下文边界      | 上下游依赖              | Feign Client, Kafka Consumer | Phase 7, 8, 9                  |
+| §2.2 实体清单        | Entity 完整字段 + 索引  | Entity 类                    | Phase 3+                       |
+| §2.3 DTO 清单        | DTO 字段 + 校验 + 分组  | DTO 类                       | Phase 3+                       |
+| §2.4 Ro 清单         | Ro 字段                 | Ro 类                        | Phase 3+                       |
+| §3.2 数据库表设计    | DDL                     | Liquibase                    | Phase 2                        |
+| §3.3 MyBatis 映射    | DAO + XML 结构          | DAO 接口 + XML               | Phase 3+                       |
+| §4.1 业务行为        | 行为清单                | Service 方法                 | Phase 3+                       |
+| §4.3 状态机          | 状态+转换               | Service 状态流转             | Phase 3+                       |
+| §4.4 Service 接口    | 方法签名                | Service 接口 + 实现          | Phase 3+                       |
+| §4.6 事务边界        | @Transactional          | 事务注解                     | Phase 3+                       |
+| §5.1 端点清单        | HTTP+路径               | Controller 方法              | Phase 3+                       |
+| §5.2 Controller 骨架 | 方法路由表              | Controller 类                | Phase 3+                       |
+| §5.4 权限矩阵        | @CheckToken + 角色      | 权限控制                     | Phase 3+                       |
+| §6.1 枚举定义        | 枚举值+编码             | 枚举类                       | Phase 2                        |
+| §6.2 校验规则        | Bean Validation         | DTO 注解                     | Phase 3+                       |
+| §7.1 业务异常        | 消息码+触发条件         | Service 异常处理             | Phase 3+                       |
+| §7.3 消息码汇总      | properties 文本         | i18n 7 文件                  | Final Phase                    |
+| §8.1 缓存策略        | Redis 键设计            | 缓存配置                     | Phase 2 / Final                |
+| §8.3 并发控制        | @Klock / version_num    | 并发控制                     | Phase 3+                       |
+| §9 领域事件          | 事件 Payload + Consumer | Kafka Consumer               | Phase 6, 8                     |
+| §10 跨模块依赖       | Feign Client 契约       | Feign Client 接口            | Phase 3+                       |
+| §12 测试场景         | 测试数据 + 预期结果     | TDD 测试任务                 | Phase 3+（在每个故事阶段开头） |
+| §13 附录             | 目录树 ~45 文件         | 文件路径速查表               | tasks.md 开头                  |