---
name: "ads-front-tasks"
description: "基于前端设计文档（_前端设计.md），为前端功能生成 TDD 就绪的、按依赖排序的 tasks.md 文件。支持 Vue + Element Plus / React + Ant Design 技术栈自动检测"
agent_created: true
argument-hint: "指定前端设计文档路径，如 docs/30-system-design/crm/M06-01_销售预测_前端设计.md"
compatibility: "需要 docs/ 目录体系：docs/30-system-design（前端设计文档）+ .adspecs/templates（05b-前端任务清单模板）。支持 Vue + Element Plus 或 React + Ant Design 技术栈（自动检测），参考 references/front-demo/.claude/rules 或 references/ant6-front-standard"
metadata:
  author: "qingwen"
  source: "基于 ads-front-tasks 通用模板 + 项目技术栈（Vue/React 自动检测）+ TDD 流程改造"
user-invocable: true
disable-model-invocation: false
---

## 用户输入

```text
$ARGUMENTS
```

在处理之前**必须**考虑用户输入（若不为空）。用户输入应为**前端设计文档的路径**（如 `docs/30-system-design/crm/M06-01_销售预测_前端设计.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` → `/ads-git-commit`。
- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
  - **可选钩子**（`optional: true`）：

    ```
    ## 扩展钩子

    **可选前置钩子**：{extension}
    命令：`/{command}`
    描述：{description}

    提示：{prompt}
    执行方式：`/{command}`
    ```

  - **强制钩子**（`optional: false`）：

    ```
    ## 扩展钩子

    **自动前置钩子**：{extension}
    正在执行：`/{command}`
    EXECUTE_COMMAND: {command}

    等待钩子命令执行结果后再继续进入大纲阶段。
    ```

- 如果没有注册任何钩子，或 `.adspecs/extensions.yml` 不存在，则静默跳过。

---

## 技术栈检测（任务生成前置）

> **目的**：确定本项目的前端技术栈，后续所有术语、路径、示例均按检测到的栈展开。
> **输出变量**：`FRONTEND_STACK`（`vue` | `react`）和 `FRONTEND_PROJECT_DIR`（前端项目根目录名）。

按以下优先级依次尝试，命中任意一级即停止：

| 优先级 | 检测源 | 判定规则 |
| ------ | ------ | -------- |
| 1 | `.adspecs/project.json` | 读取 `frontend_stack` 字段（`vue` / `react`）。`/project-init` 在初始化时写入 |
| 2 | 项目根 `CLAUDE.md` §Frontend | 关键字命中：含 `Vue 3` / `Element Plus` / `Pinia` → `vue`；含 `React` / `Ant Design` / `Zustand` → `react` |
| 3 | 前端设计文档（`*_前端设计.md`）§1 | 文档开头"技术栈"或"项目路径"段落中声明的框架 |
| 4 | 项目目录结构启发式 | 存在 `src/views/**/*.vue` → `vue`；存在 `src/pages/**/*.tsx` → `react` |
| 5 | 回退：询问用户 | 使用 AskUserQuestion 让用户选择 `Vue + Element Plus` 或 `React + Ant Design` |

**`FRONTEND_PROJECT_DIR` 检测**：
- 优先从 `.adspecs/project.json` 的 `frontend_dir` 字段读取
- 其次从 `CLAUDE.md` §Frontend 中提取项目根目录名
- 默认值：`front-demo/`

检测完成后，在内部记录两个变量，后续章节按此展开：
```
FRONTEND_STACK = vue | react
FRONTEND_PROJECT_DIR = {前端项目根目录名}
```

---

## 前端编码规范（任务生成强制校验清单）

> **来源**：项目 `CLAUDE.md` §Frontend + `.adspecs/templates/05b-前端任务清单模板.md` + 项目技术栈参考（Vue 栈参考 `references/front-demo/.claude/rules/`；React 栈参考 `references/ant6-front-standard/`）。
> **以下 12 条规则为栈无关原则，在生成每个任务时必须满足，违反任何一条即为不合格任务。**
> **具体实现方式按 `FRONTEND_STACK` 查 §技术栈映射表 展开。**

| #   | 规则            | 说明（栈无关原则）                                                                                                                                       |
| --- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1   | **TypeScript 类型** | 所有组件/Store/API/工具函数有完整类型定义，禁用 `any`。类型定义文件放在 `src/types/{module}/`                                                          |
| 2   | **组件语法**    | 采用项目约定的组件语法（SFC 单文件组件 / 函数组件 + Hooks），Props 使用类型声明                                                                          |
| 3   | **UI 组件库**   | 统一使用项目选定的企业级组件库（表格/表单/标签/弹窗/分页等），状态标签使用组件库的颜色语义                                                                |
| 4   | **状态管理**    | 采用项目选定的状态管理方案，camelCase 命名，状态对齐前端设计文档 §状态管理                                                                                |
| 5   | **API 调用**    | 统一使用项目封装的 HTTP 客户端（`src/utils/request.ts`），不直接调用底层库。每个 API 模块独立文件放在 `src/api/{module}/`                                 |
| 6   | **路由配置**    | 层级清晰，页面组件懒加载，路由 meta 含权限标记                                                                                                            |
| 7   | **错误处理**    | 错误码映射表集中管理在 `src/utils/errorHandler.ts`，展示方式按前端设计（Message/Dialog/字段级三种）。后端返回的业务错误码映射为用户提示文案                |
| 8   | **状态标签**    | 使用通用状态标签组件，颜色语义严格遵循设计：蓝色=进行中、绿色=终态、红色=驳回/错误、橙色=警告/部分、灰色=草稿/取消/释放                                    |
| 9   | **表单校验**    | 声明式校验规则，校验文案使用 i18n key 或消息码映射。查询 loading 时禁用其他输入                                                                           |
| 10  | **乐观锁**      | 更新/撤回/排产确认操作携带版本号字段，冲突时展示友好提示"数据已被他人修改，请刷新后重试"                                                                  |
| 11  | **i18n 国际化** | 所有用户可见文案使用国际化函数，最少覆盖中/英两种语言                                                                                                     |
| 12  | **构建质量**    | `npm run build`（含类型检查 + 构建）零错误通过；`npm run lint` 和 `npm run format` 无报错                                                                 |

### 技术栈映射表

> 根据 §技术栈检测 得到的 `FRONTEND_STACK` 选择对应列。未在表中出现的概念（如错误处理、API 封装）两栈相同。

| 概念             | Vue 技术栈 (`FRONTEND_STACK=vue`)                           | React 技术栈 (`FRONTEND_STACK=react`)                         |
| ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 框架             | Vue 3.5 + `<script setup lang="ts">`                         | React 19 + 函数组件 + Hooks                                  |
| 类型             | TypeScript 5.8                                               | TypeScript 6                                                 |
| UI 库            | Element Plus 2.9（`<el-*>` 前缀）                            | Ant Design 6 + ProComponents（`<a-*>` / `<ProTable>` 等）    |
| 状态管理         | Pinia 3（`defineStore` setup 语法）                          | Zustand（`create<State>`）                                   |
| 路由             | vue-router 4（`defineAsyncComponent` 懒加载）                | react-router（`React.lazy` + `Suspense`）                    |
| i18n             | vue-i18n 11（`$t()` / `useI18n()`）                          | react-i18next（`useTranslation()` / `t()`）                  |
| 图表             | ECharts 5（按需引入 `echarts/core`）                         | ECharts 5（按需引入 `echarts/core`）                         |
| 构建             | Vite 6（`vue-tsc --build` 类型检查）                         | Vite 6（`tsc --noEmit` 类型检查）                            |
| 单元测试         | vitest                                                       | vitest                                                       |
| 组件测试库       | @vue/test-utils                                              | @testing-library/react                                       |
| 组件扩展名       | `.vue`                                                       | `.tsx`                                                       |
| 页面目录         | `src/views/{module}/`                                        | `src/pages/{module}/`                                        |
| 状态目录         | `src/store/modules/{module}/`                                | `src/stores/{module}/`                                       |
| API 目录         | `src/api/{module}/`                                          | `src/api/{module}/`                                          |
| 类型目录         | `src/types/{module}/`                                        | `src/types/{module}/`                                        |
| 路由目录         | `src/router/modules/{module}.ts`                             | `src/router/{module}.ts`                                     |
| i18n 目录        | `src/i18n/{locale}/{module}.ts`                              | `src/locales/{locale}/{module}.ts`                           |
| 通用组件目录     | `src/components/`                                            | `src/components/`                                            |
| Hooks 目录       | `src/hooks/`                                                 | `src/hooks/`                                                 |
| 请求封装         | `src/utils/request.ts`                                       | `src/utils/request.ts`                                       |
| 错误处理         | `src/utils/errorHandler.ts`                                  | `src/utils/errorHandler.ts`                                  |
| 状态标签组件     | `StatusTag.vue`                                              | `StatusTag.tsx`                                              |
| 操作按钮组件     | `ActionButtons.vue`                                          | `ActionButtons.tsx`                                          |
| 测试命令         | `npx vitest run {test-file}`                                 | `npx vitest run {test-file}`                                 |
| 参考规范         | `references/front-demo/.claude/rules/`                       | `references/ant6-front-standard/`                            |

### 前端项目路径约定

> 来源：CLAUDE.md §Frontend + `05b-前端任务清单模板.md`。下方目录树按 `FRONTEND_STACK` 展开，`{EXT}` 表示组件扩展名（Vue: `.vue`；React: `.tsx`）。

```
{FRONTEND_PROJECT_DIR}/                  # 前端项目根目录
├── src/
│   ├── api/                              # API 接口模块（HTTP 客户端封装）
│   │   └── {module}/                     #   按业务模块组织
│   │       ├── {entity}.ts               #     实体 CRUD + 业务操作接口
│   │       └── ...
│   ├── {PAGE_DIR}/                       # 页面组件（Vue: views/；React: pages/）
│   │   └── {module}/                     #   按业务模块组织
│   │       ├── {Entity}List{EXT}         #     列表页
│   │       ├── {Entity}Edit{EXT}         #     创建/编辑页
│   │       ├── {Entity}Detail{EXT}       #     详情页
│   │       ├── {Entity}Overview{EXT}     #     概览/图表页
│   │       ├── components/               #     页面级私有组件
│   │       │   ├── {Entity}Form{EXT}     #       表单组件
│   │       │   └── ...
│   │       └── __tests__/                #     页面组件测试
│   ├── router/                           # 路由配置
│   │   └── {module}.ts                   #   模块路由定义
│   ├── {STORE_DIR}/                      # 状态管理（Vue: store/modules/；React: stores/）
│   │   └── {module}/
│   │       ├── {entity}Store.ts          #   实体状态 Store
│   │       └── __tests__/                #   Store 单元测试
│   ├── components/                       # 全局共享组件
│   │   ├── StatusTag{EXT}                #   状态标签通用组件
│   │   └── ActionButtons{EXT}            #   动态操作按钮组
│   ├── types/                            # TypeScript 类型定义
│   │   └── {module}/
│   │       ├── {entity}.ts               #   实体类型 + 枚举
│   │       ├── enums.ts                  #   枚举（与后端编码一致）
│   │       └── api.ts                    #   API 请求/响应泛型类型
│   ├── utils/                            # 工具函数
│   │   ├── request.ts                    #   HTTP 客户端实例 + 拦截器
│   │   └── errorHandler.ts               #   错误码→用户提示文案映射表
│   ├── {I18N_DIR}/                       # 国际化（Vue: i18n/；React: locales/）
│   │   ├── zh-CN/{module}.ts             #   简体中文文案
│   │   └── en-US/{module}.ts             #   英文文案
│   └── hooks/                            # Composition API 钩子 / React Hooks
│       ├── usePagination.ts              #   分页管理
│       └── ...
```

**路径命名约定**：

- 目录名：kebab-case（`sales-forecast`）
- 文件名：组件文件 PascalCase（`{Entity}List{EXT}`）、`.ts` 文件 camelCase（`{entity}.ts`）
- Store 名：`use{Entity}Store.ts` 或 `{entity}Store.ts`

---

## 大纲

### 1. 定位前端设计文档

1. **确定前端设计文档路径**：
   - 从 `$ARGUMENTS` 获取前端设计文档路径（如 `{DESIGN_DIR}/crm/M06-01_销售预测_前端设计.md`）
   - 若 `$ARGUMENTS` 为空，搜索 `{DESIGN_DIR}/{crm|mom}/` 下最新修改的 `*_前端设计.md` 文件
   - 若仍找不到，搜索当前打开文件或上下文中引用的前端设计文档
   - 确认文件存在且可读取

2. **检测技术栈**：按 §技术栈检测 的 5 级回退链确定 `FRONTEND_STACK` 和 `FRONTEND_PROJECT_DIR`，后续所有术语、路径、示例均按此展开

3. **加载编码规范参考**：根据 `FRONTEND_STACK` 加载对应规范目录：
   - Vue 栈：`references/front-demo/.claude/rules/`
   - React 栈：`references/ant6-front-standard/`

4. **定位任务模板**：读取 `.adspecs/templates/05b-前端任务清单模板.md` 作为输出结构参考

5. **可选加载后端设计文档**：若存在同模块的 `_system-design.md`，作为 API 端点清单和错误码的补充参考

### 2. 提取前端设计文档信息

> 前端设计文档（由 `/ads-front-spec` 产出）聚焦于 UI 交互行为和前端实现细节。按以下顺序提取所有任务生成所需信息。

#### 2.1 从 §1 提取：页面菜单路由规划

| 提取项            | 来源                                             | 用途                                                              |
| ----------------- | ------------------------------------------------ | ----------------------------------------------------------------- |
| 页面清单          | §1.1 页面清单表 → 页面名 + 路由 + UserStory 关联 | 生成路由配置任务 + 页面组件任务（Phase 3~8）                      |
| 关键交互说明      | §1.2 关键交互说明                                | 生成组件交互细节任务（CTCT 自动回填/状态标签/操作按钮动态渲染等） |
| 前端 API 调用约定 | §1.3 前端 API 调用约定                           | 生成 API 模块任务 + 错误处理任务（Phase 2）                       |

#### 2.2 从 §2 提取：总体布局

| 提取项       | 来源        | 用途                        |
| ------------ | ----------- | --------------------------- |
| 页面布局结构 | §2 总体布局 | 生成布局组件任务（Phase 2） |

#### 2.3 从 §3~§N 提取：核心功能区域

> 前端设计文档的每个核心功能区域章节对应一个页面或业务操作。

| 提取项       | 来源                                   | 用途                                       |
| ------------ | -------------------------------------- | ------------------------------------------ |
| 页面 UI 规格 | 每个功能区域章节的 UI 描述             | 生成页面组件 + 子组件任务                  |
| 交互行为     | 用户操作流程描述                       | 生成 Hook 任务（表单校验/分页/排产查询等） |
| 数据显示规则 | 表格列、状态标签颜色、操作按钮显示规则 | 生成 StatusTag/ActionButtons 使用说明      |

#### 2.4 从 §用户输入提取：表单与校验

| 提取项       | 来源                                        | 用途                        |
| ------------ | ------------------------------------------- | --------------------------- |
| 表单字段清单 | 每个表单输入控件的字段名/类型/必填/校验规则 | 生成表单组件声明式校验规则 |
| 交互反馈     | CTCT 自动回填/MOQ 警告/提前期拦截           | 生成 Hook 交互逻辑          |

#### 2.5 从 §错误处理提取：错误码映射

| 提取项       | 来源                                                      | 用途                        |
| ------------ | --------------------------------------------------------- | --------------------------- |
| 错误码映射表 | 错误码 → 用户提示文案 → 展示方式（Message/Dialog/字段级） | 生成 `errorHandler.ts` 任务 |
| 错误展示方式 | Message 提示/Dialog 拦截/字段级错误                       | 生成错误处理 Hook           |

#### 2.6 从 §状态管理提取：Store

| 提取项     | 来源                                             | 用途                          |
| ---------- | ------------------------------------------------ | ----------------------------- |
| Store 定义 | Store 名称 + state 字段 + actions + getters/方法 | **每个 Store 独立成一个任务** |
| 初始值     | 前端设计中的默认值/空值定义                      | Store 初始化代码              |

#### 2.7 从 §US→FSD 对齐表提取：故事映射

| 提取项                | 来源                        | 用途               |
| --------------------- | --------------------------- | ------------------ |
| 用户故事→文件路径映射 | US ID → 组件/Store/API 文件 | 验证任务覆盖完整性 |
| 功能条目→文件路径映射 | 功能编号 → 对应文件         | 验证功能覆盖       |

### 3. 执行任务生成工作流

按以下顺序生成任务：

1. **从 §1.1 页面清单提取页面和路由信息**：
   - 确定模块名（kebab-case，如 `sales-forecast`）
   - 确定页面数 ─→ Phase 3~8 每个页面至少一个 Phase
   - 列出所有目标文件路径（组件/Store/API/类型/路由/i18n）

2. **从 §US→FSD 对齐表提取用户故事并按优先级分组**：
   - P1 故事：US-01~US-05, US-09（核心业务流程）
   - P2 故事：US-06~US-08, US-10（辅助功能）
   - 确认故事与页面的映射关系

3. **按前端项目路径 + TDD 顺序组织任务**（详见 §任务生成规则）

4. **生成依赖关系图**

5. **创建并行执行示例**

6. **验证任务完整性**：
   - 所有页面组件都有对应任务
   - 所有 Store 都有对应任务
   - 所有 API 模块都有对应任务
   - 所有类型定义都有对应任务
   - 所有 i18n 语言文件都有对应任务

### 4. 生成 front_tasks.md

使用 `.adspecs/templates/05b-前端任务清单模板.md` 作为结构参考。front_tasks.md 必须包含以下全部章节：

1. **功能名称 + 元数据**（来源前端设计文档 §1）
2. **文件路径速查表**（所有目标文件的绝对路径清单，按前端项目路径组织）
3. **前端编码规范检查清单**（12 条规则，标记每条是否满足）
4. **Phase 1**：项目初始化（npm install + 目录结构 + 路由框架 + request.ts 确认）
5. **Phase 2**：基础设施（类型定义 ×N、API 模块 ×N、错误码映射表、通用组件 ×N、Hooks ×N）
6. **Phase 3+**：每个用户故事一个阶段（P1→P2 顺序），阶段内按 TDD 顺序排列
7. **Final Phase**：集成与收尾（E2E 测试、路由守卫、i18n 文案、代码评审、build 验证）
8. **依赖关系与执行顺序**（阶段依赖 + 并行机会 + TDD 执行顺序）
9. **并行执行示例**（具体到任务 ID 的并行策略）
10. **实现策略**（MVP 范围 = P1 页面，增量交付路径）

---

## 强制性执行后钩子

**在向用户报告完成之前，必须完成此部分。**

检查项目根目录下是否存在 `.adspecs/extensions.yml` 文件。

- 如果不存在，或 `hooks.after_tasks` 下没有注册任何钩子，则跳到《完成报告》。
- 如果存在，读取该文件并查找 `hooks.after_tasks` 键下的条目。
- 如果 YAML 无法解析或无效，则静默跳过钩子检查并继续到《完成报告》。
- 过滤掉 `enabled` 显式为 `false` 的钩子。将没有 `enabled` 字段的钩子默认为启用状态。
- 对于每个剩余的钩子，**不要**尝试解释或评估钩子的 `condition` 表达式：
  - 如果钩子没有 `condition` 字段，或该字段为 null/空，则视为可执行钩子。
  - 如果钩子定义了非空的 `condition`，则跳过该钩子，将条件评估交由 HookExecutor 实现处理。
- 从钩子命令名称构建斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如，`adspecs.git.commit` → `/ads-git-commit`。
- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
  - **强制钩子**（`optional: false`）——**对于每个强制钩子，必须输出 `EXECUTE_COMMAND:`**：

    ```
    ## 扩展钩子

    **自动钩子**：{extension}
    正在执行：`/{command}`
    EXECUTE_COMMAND: {command}
    ```

  - **可选钩子**（`optional: true`）：

    ```
    ## 扩展钩子

    **可选钩子**：{extension}
    命令：`/{command}`
    描述：{description}

    提示：{prompt}
    执行方式：`/{command}`
    ```

## 完成报告

输出生成的 tasks.md 路径及摘要：

- **检测到的技术栈**：`FRONTEND_STACK`（vue / react）及检测来源
- **前端项目根目录**：`FRONTEND_PROJECT_DIR`
- **前端设计文档来源**：使用的 `_前端设计.md` 路径
- **任务总数**：含各阶段分布
- **每个用户故事的任务数量**：含 TDD 测试任务/实现任务分别计数
- **文件覆盖**：类型 ×N, API 模块 ×N, Store ×N, 页面组件 ×N, 子组件 ×N, Hook ×N, 路由 ×1, i18n ×至少2, 工具函数 ×N
- **前端编码规范检查结果**：12 条规则逐条确认通过
- **TDD 就绪确认**：每个故事阶段内 vitest 测试任务均在实现任务之前
- **识别到的并行执行机会**：标注可并行的任务数
- **每个故事的独立测试标准**：从前端设计文档验收条件提取
- **建议的 MVP 范围**：P1 页面（列表/创建编辑/详情/变更单）
- **格式验证**：确认所有任务遵循 `[TaskID] [P?] [TDD?] [Story?] 描述 + 文件路径` 格式

---

## 任务生成规则

### 关键约束

1. **任务必须按用户故事组织**：每个故事独立可测试，支持独立实现
2. **TDD 严格排序**：每个故事阶段内，vitest 测试任务必须在实现任务之前
3. **前端编码规范强制遵守**：每个任务描述必须包含正确的**项目技术栈**命名和路径（按 §技术栈映射表 展开）
4. **文件路径精确**：每个任务必须包含从 `{FRONTEND_PROJECT_DIR}/src/` 开始的完整文件路径
5. **前端设计文档全量覆盖**：所有页面/组件/Store/API/类型/交互都映射到对应任务

### 检查清单格式（必需）

每个任务必须严格遵循以下格式：

```text
- [ ] [TaskID] [P?] [TDD?] [Story?] 包含精确文件路径的描述
```

**格式组成**：

1. **复选框**：始终以 `- [ ]`（markdown 复选框）开头
2. **任务 ID**：全局递增的顺序编号（T001, T002, T003...）
3. **[P] 标记**：仅当任务可并行执行时添加（操作不同文件、不依赖未完成的任务）
4. **[TDD] 标记**：仅当任务是测试任务时添加（Store 单元测试 / 组件测试），**必须在同故事的实现任务之前**
5. **[Story] 标签**：
   - 格式：[US1], [US2], [US3]...（对应前端设计文档 §US→FSD 对齐表中的用户故事编号）
   - Phase 1（项目初始化）：无故事标签
   - Phase 2（基础设施）：无故事标签
   - Phase 3+（用户故事）：**必须**有故事标签
   - Final Phase（集成收尾）：无故事标签
6. **描述**：明确操作 + 精确的文件路径（从 `{FRONTEND_PROJECT_DIR}/src/` 开始）

**正确示例（按 `FRONTEND_STACK` 展开）**：

*Vue 技术栈示例*：

```text
- [ ] T012 [TDD] [US1] 编写 ForecastOrderList 组件渲染测试（列表加载+分页+筛选+状态标签颜色），文件：
      {FRONTEND_PROJECT_DIR}/src/views/sales-forecast/__tests__/ForecastOrderList.spec.ts
- [ ] T013 [US1] 创建 ForecastOrderList 页面组件（<script setup lang="ts"> + el-table/el-pagination/el-tag），文件：
      {FRONTEND_PROJECT_DIR}/src/views/sales-forecast/ForecastOrderList.vue
- [ ] T014 [P] [US1] 创建 forecastOrderApi 接口模块（8 个端点，使用 request.get/post 封装），文件：
      {FRONTEND_PROJECT_DIR}/src/api/sales-forecast/forecastOrder.ts
- [ ] T015 [P] [US1] 创建 useForecastOrderList Store（defineStore setup 语法），文件：
      {FRONTEND_PROJECT_DIR}/src/store/modules/sales-forecast/forecastOrderListStore.ts
```

*React 技术栈示例*：

```text
- [ ] T012 [TDD] [US1] 编写 ForecastOrderList 组件渲染测试（列表加载+分页+筛选+状态标签颜色），文件：
      {FRONTEND_PROJECT_DIR}/src/pages/sales-forecast/__tests__/ForecastOrderList.spec.tsx
- [ ] T013 [US1] 创建 ForecastOrderList 页面组件（函数组件 + ProTable + Tag/Pagination），文件：
      {FRONTEND_PROJECT_DIR}/src/pages/sales-forecast/ForecastOrderList.tsx
- [ ] T014 [P] [US1] 创建 forecastOrderApi 接口模块（8 个端点，使用 request.get/post 封装），文件：
      {FRONTEND_PROJECT_DIR}/src/api/sales-forecast/forecastOrder.ts
- [ ] T015 [P] [US1] 创建 useForecastOrderList Store（Zustand create<State>），文件：
      {FRONTEND_PROJECT_DIR}/src/stores/sales-forecast/forecastOrderListStore.ts
```

**错误示例**：

```text
- ❌ 错误：`- [ ] 创建预测单页面`（缺少 TaskID + 文件路径 + Story 标签）
- ❌ 错误：`T001 [US1] 创建列表页`（缺少复选框 + 精确文件路径）
- ❌ 错误：`- [ ] T001 [US1] 创建页面`（缺少文件路径）
- ❌ 错误：`- [ ] T010 [US1] 实现列表页组件`（故事阶段内未先写 [TDD] 测试，违反 TDD 规则）
- ❌ 错误：`- [ ] T020 [TDD] [US1] 测试列表`（描述模糊，文件路径缺失）
```

### 前端 TDD 任务排序规则（每个用户故事阶段内）

> **关键原则**：`test-driven-development` skill 要求 "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"。前端使用 **vitest + 项目约定的组件测试库** 实现 TDD。

每个用户故事阶段内的任务遵循严格排序：

```
[TDD] Store 单元测试（先写，先失败）  ← 使用 vitest
  ↓
[TDD] 组件渲染测试（先写，先失败）    ← Vue 栈：@vue/test-utils + vitest
                                        React 栈：@testing-library/react + vitest
  ↓
类型定义（interface/enum/types）
  ↓
API 接口模块（HTTP 客户端封装函数）
  ↓
Store 实现（Vue 栈：defineStore；React 栈：Zustand create<State>）
  ↓
通用组件（StatusTag/ActionButtons）
  ↓
页面组件（列表/表单/详情/概览）
  ↓
路由集成（Vue 栈：defineAsyncComponent 懒加载；React 栈：React.lazy + Suspense）
  ↓
i18n 文案（中/英双语）
```

**测试任务粒度**：

- 每个 Store 至少对应 1 个 Store 单元测试 `[TDD]` 任务（正常 + 异常 + 边界）
- 每个页面组件至少对应 1 个组件测试 `[TDD]` 任务（渲染 + 交互 + 错误状态）
- 测试任务标记 `[TDD]`，与 `[P]` 可共存（如不同 Store 的测试可并行编写）

**测试工具链**：

```bash
# Store 单元测试（路径按 FRONTEND_STACK 展开：Vue 栈 store/modules/，React 栈 stores/）
npx vitest run {FRONTEND_PROJECT_DIR}/src/{STORE_DIR}/sales-forecast/__tests__/forecastOrderListStore.spec.ts

# 组件测试（路径按 FRONTEND_STACK 展开：Vue 栈 views/，React 栈 pages/）
npx vitest run {FRONTEND_PROJECT_DIR}/src/{PAGE_DIR}/sales-forecast/__tests__/ForecastOrderList.spec.{EXT}
```

### 任务组织方式

#### 基于用户故事（前端设计 §US→FSD 对齐表）——主要组织方式

每个用户故事按故事优先级（P1 → P2）各占一个阶段：

- P1 页面可以并行开发（不同的页面组件、不同的 Store）
- P2 页面通常可独立于 P1 进行

每个故事阶段内映射以下前端设计元素：

- 该故事涉及的**页面组件**（§1.1 页面清单 → §3~§N 功能区域）
- 该故事涉及的**状态管理 Store**（§状态管理）
- 该故事涉及的**API 模块**（§1.3 调用约定）
- 该故事涉及的**交互逻辑**（§关键交互说明）
- 该故事涉及的**错误处理**（§错误处理映射表）

#### 基于页面与路由（前端设计 §1）

- 每个页面独立成一个或多个组件任务
- 路由配置统一在 Phase 1 创建，Phase 3~8 逐步追加路由条目
- 子组件（表单/弹窗/表格）可在页面任务中一并描述，或独立成任务（复杂时）

#### 基于类型与 API（前端设计 §1.3 + §状态管理）

- **类型定义全部集中在 Phase 2**，所有后续 Phase 依赖之
- 每个 API 模块独立成一个任务（如 `forecastOrderApi.ts` / `forecastChangeOrderApi.ts`）
- 类型与后端 DTO/Ro 对齐，枚举值与后端枚举编码一致

#### 基于状态管理 Store（前端设计 §状态管理）

- 每个 Store 独立成一个任务
- Store 命名跟随前端设计文档的 §状态管理定义
- Store 测试 `[TDD]` 任务在 Store 实现之前

#### 基于通用组件（前端设计 §2 + §组件复用）

- StatusTag、ActionButtons 等全局共享组件放入 Phase 2
- 页面级私有组件（Form/Dialog/Table）放入各自的故事 Phase

### 阶段结构

> 下方为通用阶段模板，`{EXT}` / `{PAGE_DIR}` / `{STORE_DIR}` / `{I18N_DIR}` 均按 §技术栈映射表 展开。

```
Phase 1: 项目初始化
  ├── T001 npm install 依赖就绪（按 FRONTEND_STACK 安装：框架 + UI 库 + 状态管理 + 路由 + i18n + vitest）
  ├── T002 创建模块目录结构（{PAGE_DIR}/api/{STORE_DIR}/types/router/{I18N_DIR} 对应目录）
  ├── T003 [P] 创建模块路由配置文件（N 个页面路由 + meta 权限标记）
  └── T004 [P] 确认 src/utils/request.ts（HTTP 客户端实例 + token 注入 + 错误统一拦截）

Phase 2: 基础设施（阻塞性前置 — 所有页面依赖）
  ├── 类型定义（可并行 [P]）
  │   ├── {entity}.ts（实体接口 + 枚举）
  │   ├── enums.ts（与后端编码一致）
  │   └── api.ts（PaginationRequest<T>/ResponseData<T>/RequestData<T> 泛型）
  ├── API 模块（可并行 [P]）
  │   └── {entity}Api.ts（N 个端点）
  ├── 工具函数 + 通用组件（可并行 [P]）
  │   ├── errorHandler.ts（错误码映射表）
  │   ├── StatusTag{EXT}（通用状态标签）
  │   ├── ActionButtons{EXT}（动态操作按钮组）
  │   └── usePagination.ts（分页管理 Hook）

Phase 3+: 每个用户故事一个阶段（P1→P2 顺序）
  ├── [TDD] Store 单元测试 + 组件渲染测试
  ├── 状态管理 Store 实现
  ├── 页面组件 + 子组件（表单/弹窗/表格）
  └── 模块路由追加

Final Phase: 集成与收尾
  ├── E2E 端到端测试（核心业务流程）
  ├── 路由守卫完善（角色→菜单可见性+路由访问控制）
  ├── i18n 文案（zh-CN + en-US 两种语言）
  ├── 前端编码规范 12 条合规检查
  ├── 性能优化（路由懒加载/图表按需引入/API 防抖/乐观锁重试）
  ├── npm run build 构建验证（类型检查 + 构建 零错误）
  └── npm run lint + npm run format 代码质量验证
```

### 前端 TDD 就绪确认

生成 tasks.md 后，必须确认以下条件：

- [ ] 每个用户故事阶段内，至少 1 个 `[TDD]` 任务排在所有实现任务之前
- [ ] 每个 `[TDD]` 任务描述了明确的测试场景（Store 单元测试 或 组件渲染/交互测试）
- [ ] 测试工具链使用 **vitest**（Store 测试）和**项目约定的组件测试库**（Vue 栈：@vue/test-utils；React 栈：@testing-library/react）
- [ ] 测试任务与实现任务的对应关系清晰（1 个 Store 测试 → 1 个 Store 实现；1 个组件测试 → 1 个页面组件）
- [ ] tasks.md 包含 TDD 执行指南章节（RED→GREEN→REFACTOR，使用 vitest 命令）
- [ ] 任务顺序与 `test-driven-development` skill 的流程一致

### 前端编码规范合规确认

生成 tasks.md 后，必须按 `FRONTEND_STACK` 确认对应检查项（下方列出两栈并列，按实际栈执行对应列）：

**栈无关项（两栈共检）**：

- [ ] 所有类型文件放在 `src/types/` 下
- [ ] 错误处理使用 `errorHandler.ts` 集中管理错误码映射
- [ ] 状态标签颜色遵循设计规范（蓝色进行中/绿色终态/红色驳回/橙色警告/灰色草稿取消）
- [ ] 乐观锁操作描述携带版本号字段和冲突提示
- [ ] i18n 任务覆盖中/英双语
- [ ] lint 任务包含 ESLint + Prettier

**Vue 栈专属项（`FRONTEND_STACK=vue` 时检查）**：

- [ ] 所有组件任务描述包含 `<script setup lang="ts">` 和 `<el-*>` 组件
- [ ] 所有 Store 任务描述包含 `defineStore` setup 语法
- [ ] 所有路由任务使用 `defineAsyncComponent` 懒加载
- [ ] 表单任务使用 `<el-form>` rules 声明式校验
- [ ] build 任务包含 `vue-tsc --build` + `vite build`

**React 栈专属项（`FRONTEND_STACK=react` 时检查）**：

- [ ] 所有组件任务描述为函数组件 + Hooks，使用 Ant Design 6 / ProComponents
- [ ] 所有 Store 任务描述使用 Zustand `create<State>` 语法
- [ ] 所有路由任务使用 `React.lazy` + `Suspense` 懒加载
- [ ] 表单任务使用 ProForm / ModalForm / DrawerForm 标准模板
- [ ] build 任务包含 `tsc --noEmit` + `vite build`

**API 通用项**：

- [ ] 所有 API 任务描述使用项目封装的 HTTP 客户端（非直接 axios/fetch）

---

## 完成标准

- [ ] 已检测并记录 `FRONTEND_STACK`（vue / react）和 `FRONTEND_PROJECT_DIR`
- [ ] tasks.md 已生成，包含所有阶段、TDD 标记、精确前端文件路径
- [ ] 扩展钩子已根据上述《强制性执行后钩子》的规则派发或跳过
- [ ] 所有 12 条前端编码规范已通过合规确认（按栈展开）
- [ ] 所有故事阶段 TDD 就绪（vitest 测试任务在实现任务之前）
- [ ] 已向用户报告完成情况

---

## 参考：前端设计文档章节 → 任务生成速查表

| 前端设计文档章节       | 提取内容                                     | 生成任务类型              | Phase        |
| ---------------------- | -------------------------------------------- | ------------------------- | ------------ |
| §1.1 页面清单          | 7 个页面 + 路由 + UserStory                  | 路由配置 + 页面组件       | Phase 1, 3~8 |
| §1.2 关键交互说明      | CTCT 自动回填/MOQ 警告/状态标签/按钮动态渲染 | Hook + 组件交互细节       | Phase 3~8    |
| §1.3 前端 API 调用约定 | 认证方式/请求格式/错误处理/乐观锁            | API 模块 + errorHandler   | Phase 2      |
| §2 总体布局            | 页面布局结构                                 | 布局组件                  | Phase 2      |
| §3~§N 核心功能区域     | 每个页面的 UI 规格 + 交互流程                | 页面组件 + 子组件 + Store | Phase 3~8    |
| §用户输入              | 表单字段/校验规则/交互反馈                   | 表单组件声明式校验 + Hook | Phase 4, 6   |
| §错误处理              | 错误码→用户提示→展示方式映射表               | errorHandler.ts + i18n    | Phase 2, 9   |
| §状态管理              | Store 名称/state/actions/getters(方法)       | Store 实现                | Phase 3~8    |
| §US→FSD 对齐表         | US ID → 功能 → 组件/Store/API 文件           | 任务完整性验证 + 故事分组 | 全局         |
