adspecs 0.1.12

package/skills/adspecs-front-spec/SKILL.md

@@ -0,0 +1,502 @@
+---
+name: "adspecs-front-spec"
+description: "基于 PRD 文件一次性完成前端交互和 UI 行为语义提取，生成面向产品经理和前端开发的功能规格说明书（UI/交互规格）"
+argument-hint: "指定 PRD 文件路径，如 docs/20-prd/crm/sales-forecast/M06-01_销售预测需求规格说明书.md"
+compatibility: "需要 docs/ 目录体系，含 04-前端功能设计模板.md、项目约定文档、ECP 编码规范"
+metadata:
+  author: "qingwen"
+  source: "docs/20-prd/{module-subdir}/{spec文件名}.md"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+**必须** 在继续之前考虑用户输入（如果非空）。
+
+## 路径配置加载
+
+在开始执行之前，先确定输入/输出目录：
+
+1. 检查项目根目录是否存在 `.adspecs/paths.json`
+2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键
+3. 如果不存在或配置键缺失，使用下方表格中的默认值
+
+| 配置键       | 默认值                  | 用途                     |
+| ------------ | ----------------------- | ------------------------ |
+| `prd_dir`    | `docs/20-prd`           | PRD 文件所在目录（输入） |
+| `design_dir` | `docs/30-system-design` | 前端功能设计文档输出目录 |
+
+将解析后的路径分别记为 `PRD_DIR` 和 `DESIGN_DIR`，后续步骤中引用这些变量而非硬编码路径。
+
+## 定位
+
+本 skill 专注于 **UI/交互功能规格** 层面的文档输出，与 `adspecs-prd`（业务需求层面）和 `adspecs-plan`（技术架构层面）形成三层文档体系：
+
+| 对比项   | adspecs-prd                                        | adspecs-front-spec（本 skill）                                      | adspecs-plan                                     |
+| -------- | -------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------ |
+| 输出     | 产品需求说明书（1 个文件）                         | 功能规格说明书（1 个文件）                                          | 系统设计 + SQL（2 个文件）                       |
+| 模板     | `02-产品需求说明书模板.md`                         | `04-前端功能设计模板.md`                                            | `03-系统设计模板.md`                             |
+| 目标读者 | 产品经理、业务方                                   | 产品经理、前端开发、UX 设计师                                       | 开发架构师、后端工程师                           |
+| 核心问题 | **做什么 & 为什么** — 业务需求、用户故事、验收标准 | **怎么用** — 页面路由、布局、交互行为、输入输出、错误处理、状态管理 | **怎么建** — OOA/OOD、类结构、数据模型、接口设计 |
+| 关注点   | 业务场景、用户故事、功能描述、验收标准             | 页面路由规划、界面布局、功能区域交互、表单输入、错误反馈、前端状态  | DO/DTO/VO、类结构、数据模型、接口设计            |
+
+**典型工作流**：
+
+1. 先用 `adspecs-prd` 生成产品需求说明书供业务方确认（做什么）
+2. 再用 `adspecs-front-spec` 生成功能规格说明书供产品和前端确认交互细节（怎么用）
+3. 最后用 `adspecs-plan` 生成技术系统设计文档供开发团队使用（怎么建）
+
+## 角色
+
+你是一位 10 年以上经验的软件交互设计师和需求分析师，精通：
+
+- 从产品需求说明书中提炼 UI 交互行为和用户体验设计
+- Web 应用界面布局设计和交互模式（Element Plus / Ant Design 等企业级组件库）
+- 前端状态管理和数据流设计
+- 本项目的业务域和模块结构（参见 `CLAUDE.md`）
+- 功能规格说明书模板（参见 `.adspecs/templates/04-前端功能设计模板.md`）
+
+## 任务
+
+读取用户指定的 PRD 文件，生成：
+
+1. **功能规格说明书** — 基于 `.adspecs/templates/04-前端功能设计模板.md`（8 部分结构），将需求描述转化为面向产品和前端的 UI/交互功能规格文档
+
+## 输入
+
+- **需求规格说明书**: 用户指定的 PRD 文件（如 `{PRD_DIR}/crm/sales-forecast/M06-01_销售预测需求规格说明书.md`）
+  - 文件通常包含：用户故事（US）、验收场景（Given-When-Then）、业务规则（BR）、功能清单、状态机、权限矩阵、通知机制等
+- **系统设计文档**（可选，推荐）: `{DESIGN_DIR}/{crm|mom}/` 目录下对应的 system-design 文件，提供 API 端点清单、错误码定义、枚举值等
+- **模板文件**:
+  - `.adspecs/templates/04-前端功能设计模板.md` — 功能规格说明书输出模板（8 部分结构：§1 页面菜单路由规划、§2 总体布局、§3~§4 核心功能区域、§5 用户输入、§6 错误处理、§7 状态管理、§8 US→FSD 对齐表）
+- **项目约定**:
+  - `CLAUDE.md` — 项目技术架构、模块结构、前端技术栈（Vue 3 + TypeScript + Element Plus）
+
+## 执行前检查
+
+**检查扩展钩子（规划前）**:
+
+- 检查项目根目录是否存在 `.adspecs/extensions.yml`。
+- 如果存在，读取它并查找 `hooks.before_plan` 下的条目。
+- 如果 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` 不存在，静默跳过。
+
+1. **解析用户输入**：
+   - 如果 `$ARGUMENTS` 是文件路径（以 `docs/` 或 `/` 开头，或以 `.md` 结尾）→ 读取该文件作为需求描述
+   - 如果 `$ARGUMENTS` 是自然语言描述 → 直接使用
+   - 如果 `$ARGUMENTS` 为空 → 使用 **AskUserQuestion** 工具提示用户输入需求描述
+
+2. **加载模板**：
+   - 读取 `.adspecs/templates/04-前端功能设计模板.md`，获取功能规格说明书的完整结构
+   - 如果模板不存在，使用内置的分析结构（见下方"## 工作流程"）
+
+3. **加载项目上下文**（可选）：
+   - 如果 `CLAUDE.md` 存在，读取以了解项目背景
+   - 如果 `docs/{PRD_DIR}/` 下有相关文档，读取以补充需求背景
+
+4. **识别二级模块**：
+   - 扫描 `{ARCH_DIR}/` 目录，查找 `01-*_business_scenarios.md` 或 `01-*_business_architecture.md` 文件（业务功能架构文档，两者命名均可能出现）
+   - 如果找到，读取文件内容，重点关注：
+     - **二、系统模块总览** → **2.2 子模块清单**：获取所有主模块（M00~M{N}）及其下属的二级模块（子模块，编号格式如 M03-01、M03-02、SYS-01 等）
+     - **三、各模块业务场景详述**：获取每个模块的业务场景描述（S-M{XX}-{YY} 系列）
+   - 将需求描述内容与各二级模块的名称、说明、业务场景进行语义匹配，确定需求最匹配的**二级模块编号**（如 M03-02）
+   - 匹配规则：
+     1. **精确匹配**：需求描述中明确提到某个子模块名称或编号 → 直接采用
+     2. **场景匹配**：需求描述的业务场景与某个模块下的场景（S-M{XX}-{YY}）高度吻合 → 采用该子模块编号
+     3. **语义匹配**：需求描述的核心功能与某个子模块的"说明"字段语义相近 → 采用该子模块编号
+     4. **无法匹配**：需求内容与任何二级模块都不匹配 → 使用 AskUserQuestion 让用户从二级模块列表中选择，或标记为"新模块"
+   - 将匹配到的二级模块编号记为 `MODULE_ID`（如 `M03-02`），对应的主模块编号记为 `PARENT_MODULE`（如 `M03`）
+   - 如果架构文档不存在，跳过此步骤，`MODULE_ID` 留空，输出目录不包含模块子目录
+
+5. **确定输出路径**：
+   - 输出根目录：`{OUTPUT_DIR}/`（由路径配置加载阶段解析，默认 `docs/{DESIGN_DIR}/`）
+   - 如果 `MODULE_ID` 已识别（非空）：
+     - 输出子目录：`{OUTPUT_DIR}/{MODULE_ID}/`（如 `docs/{DESIGN_DIR}/M03-02/`）
+     - 如果子目录不存在，自动创建
+   - 如果 `MODULE_ID` 为空（架构文档不存在或无法匹配）：
+     - 直接使用 `{OUTPUT_DIR}/` 作为输出目录（兼容旧行为）
+   - 输出文件名：基于需求描述生成简洁名称，格式 `{short-name}_前端功能设计.md`
+   - 完整输出路径示例：
+     - 有模块：`docs/{DESIGN_DIR}/M03-02/customer-management_前端功能设计.md`
+     - 无模块：`docs/{DESIGN_DIR}/customer-management_前端功能设计.md`
+   - 如果目录下已有同名文件，询问用户是覆盖还是重命名,还是新增版本号格式如下：
+     - 有模块：`docs/{DESIGN_DIR}/M03-02/{MODULE_ID}_{short-name}_前端功能设计_v{version}.md`
+     - 无模块：`docs/{DESIGN_DIR}/{short-name}_前端功能设计_v{version}.md`
+   - 将解析后的路径持久化到 `.adspecs/feature.json`（多功能注册表格式）：
+
+     ```json
+     {
+       "active": "<resolved feature dir>",
+       "frontDesigns": [
+         {
+           "id": "<功能ID>",
+           "directory": "<resolved feature dir>",
+           "filename": "<resolved feature filename>",
+           "name": "<功能名称>",
+           "status": "drafting",
+           "created": "<DATE>"
+         }
+       ]
+     }
+     ```
+
+     **操作方式**:
+     1. 读取现有的 `.adspecs/feature.json`（如存在）
+     2. 将新功能追加到 `frontDesigns` 数组（若 directory 已存在则跳过，避免重复）
+     3. 将 `active` 更新为当前功能目录
+     4. 写入文件（使用 2-space 缩进以保证可读性）
+
+     写入实际的解析后目录路径值（例如 `{OUTPUT_DIR}/003-user-auth`），而非字面字符串 `ADSPECS_FEATURE_DIRECTORY`。
+     这允许下游命令（`/adspecs-front-tasks` 等）通过 `active` 字段定位当前功能目录，而无需依赖 git 分支名称约定。
+
+     **注意**: 不要在功能目录下创建 `feature.json` 文件——所有功能追踪统一在 `.adspecs/feature.json` 中管理。
+
+## 内容裁剪规则
+
+本 skill 关注 **UI/交互功能规格**，裁剪规则如下：
+
+**以下内容应忽略**，不出现在功能规格说明书中：
+
+- 数据库表设计细节（字段类型、索引、约束）
+- 后端事务管理、性能优化方案
+- DO/DTO/VO/Entity 类层次结构
+- MyBatis XML 映射细节
+- 后端 Service 实现逻辑
+- Feign Client / RPC 接口定义
+- Kafka 事件发布/订阅机制
+
+**以下内容应提取并转化**为 UI/交互语言：
+
+| 来源                               | 转化为功能规格说明书的内容                     | 对应模板章节         |
+| ---------------------------------- | ---------------------------------------------- | -------------------- |
+| 功能清单（一级/二级/三级功能编号） | 页面清单（页面 → 路由 → UserStory 映射）       | §1.1 页面清单        |
+| 用户故事验收场景                   | 页面关键交互说明（操作流程、联动逻辑）         | §1.2 关键交互说明    |
+| REST API 端点路径                  | API 调用约定                                   | §1.3 前端API调用约定 |
+| 概览/报表类功能                    | 图表交互定义（技术选型 + 交互行为）            | §1.4 图表交互        |
+| 页面布局描述                       | 总体布局结构图（ASCII 字符画）                 | §2 总体布局          |
+| 功能操作流程（AC 条件）            | 功能区域行为表（触发方式 → 接口 → 行为）       | §3~§4 核心功能区域   |
+| 状态机 / 状态枚举值                | 状态条件表（空/有数据/加载中）+ 状态标签映射表 | §3~§4 核心功能区域   |
+| 字段定义（名称、必填、校验）       | 输入元素表（元素类型/校验规则/行为）           | §5 用户输入区域      |
+| 错误码 / 异常清单                  | 错误处理与用户反馈表（后端错误码 → 前端展示）  | §6 错误处理          |
+| 前端交互状态需求                   | State 变量表（变量名/类型/初始值/用途）        | §7 状态管理          |
+| US 编号 + 验收标准                 | US → FSD 对齐表（US → 涉及交互 → 对应章节）    | §8 US→FSD对齐表      |
+
+## 功能区域拆分规则
+
+模板的 §3 和 §4 标注为"核心功能区域 1/2"，实际使用时需按功能页面拆分，每个主要页面创建一个功能区域章节。**最少 2 个、无上限**，按需增加 §5、§6……用户输入、错误处理、状态管理、US→FSD 对齐表章节编号依次后移。
+
+| 页面类型            | 拆分方式                         | 典型内容                                     |
+| ------------------- | -------------------------------- | -------------------------------------------- |
+| 列表页              | 独立为一个功能区域               | 搜索条件、列表展示、分页、操作按钮、状态标签 |
+| 表单页（新增/编辑） | 独立为一个功能区域               | 表单字段、校验规则、提交行为、取消操作       |
+| 详情页              | 独立为一个功能区域               | 数据展示、状态信息、操作按钮                 |
+| 报表/概览页         | 独立为一个功能区域               | 筛选条件、图表/聚合数据展示、导出            |
+| 弹窗/抽屉           | 合并到所属页面区域，或独立成区域 | 取决于复杂度，简单的合并，复杂的独立         |
+
+**命名规则**：`§N. 核心功能区域 — 【页面名称】`，例如：
+
+- `§3. 核心功能区域 — 预测单列表页`
+- `§4. 核心功能区域 — 预测单创建/编辑页`
+- `§5. 核心功能区域 — 预测单详情页`
+
+## 工作流程
+
+### 步骤 1：读取输入
+
+1. 读取用户指定的 PRD 文件，重点关注：用户故事（US）、验收场景（AC）、功能清单、状态机、权限矩阵、通知机制、业务规则
+2. 如果 `{DESIGN_DIR}/` 下存在对应的 system-design 文件，一并读取，提取：API 端点清单、错误码定义、枚举值
+3. 读取 `CLAUDE.md` 了解项目模块结构、前端技术栈（Vue 3 + TypeScript + Element Plus）
+
+### 步骤 2：读取模板
+
+读取 `.adspecs/templates/04-前端功能设计模板.md`，理解输出的 8 部分结构要求
+
+### 步骤 3：生成功能规格说明书
+
+按照模板的 8 部分结构，将需求内容转化为 UI/交互功能规格文档：
+
+**§1 — 页面菜单路由规划**（skill 核心贡献，从功能清单和验收场景推导）：
+
+- **§1.1 页面清单**：从 PRD 的功能清单（§4.1）提取页面列表，生成路由映射表
+  - 格式：`| 页面 | 路由 | 说明 | UserStory |`
+  - 路由命名使用层级清晰的小写路径（如 `/sales/forecasts`、`/sales/forecasts/:id`）
+  - 每个页面须关联对应的 UserStory 编号
+
+- **§1.2 关键交互说明**：从 PRD 的验收场景（Given-When-Then）和功能详细描述中提取每个页面的交互要点
+  - 每个页面用 1-2 句描述核心交互流程和关键行为
+  - 标注特殊交互行为（如 CTCT 自动回填、状态标签颜色区分、乐观锁冲突提示、二次确认弹窗）
+
+- **§1.3 前端API调用约定**：定义前后端 API 交互的通用约定
+  - 认证方式（如 `Authorization: Bearer {token}`）
+  - 列表查询格式（GET/POST，分页响应结构 `{ total, records, pageIndex, pageRows }`）
+  - 创建/更新格式（POST，成功返回 `{ code: "200", data: {...} }`）
+  - 文件上传格式（POST multipart/form-data）
+  - 错误响应统一格式（`{ code: "3103_xxx_xxx", msg: "...", data: null }`）
+  - 乐观锁机制约定（更新时携带 versionNum，409 冲突时提示用户刷新重试）
+
+- **§1.4 图表交互**：如果功能涉及概览/报表页面（如预测汇总、准确率分析），定义图表交互
+  - 格式：`| 图表 | 技术 | 交互 |`
+  - 技术选型：ECharts Bar（柱状图）、ECharts Line（折线图）、ECharts Pie（饼图）、ECharts Gauge（仪表盘）
+  - 交互描述：点击下钻行为、hover 提示内容、异常标注规则、维度切换行为
+
+**§2 — 总体布局 / 界面结构**：
+
+- 从 PRD 的功能描述和业务流程推导整体页面布局
+- 使用 ASCII 字符画绘制页面布局结构图（参照模板示例格式：`┌─┐└─┘├─┤│`）
+- 标注每个区域的名称和功能定位（如：Header 导航栏、搜索筛选区、数据列表区、分页操作区、侧边导航）
+- 如果功能涉及多个页面（列表页、表单页、详情页、概览页），为每个主要页面分别绘制布局图
+
+**§3~§N — 核心功能区域**（按"功能区域拆分规则"为每个主要页面创建）：
+
+对于 **列表类页面**，使用功能表格式：
+
+| 功能     | 触发方式     | 调用接口                 | 行为描述                       |
+| -------- | ------------ | ------------------------ | ------------------------------ |
+| 列表加载 | 页面加载     | GET /xxx/find-pagination | 调用分页查询接口，展示数据列表 |
+| 搜索筛选 | 点击查询按钮 | GET /xxx/find-pagination | 根据筛选条件重新查询           |
+| 新增     | 点击新增按钮 | —                        | 打开新增表单（新页面/弹窗）    |
+| 编辑     | 点击编辑按钮 | —                        | 回填数据到编辑表单             |
+| 删除     | 点击删除按钮 | GET /xxx/delete          | 二次确认后调用删除接口         |
+
+对于 **详情/展示类页面**，使用状态条件表格式：
+
+| 状态     | 条件         | 显示内容                   |
+| -------- | ------------ | -------------------------- |
+| A 空状态 | 无数据时     | 展示空状态提示 + 引导操作  |
+| B 有数据 | 数据加载成功 | 展示数据详情，列出完整字段 |
+| C 加载中 | 请求进行中   | Loading 骨架屏或 Spinner   |
+
+**§N.1 — 状态标签映射**（如果列表项/详情含状态字段）：
+
+- 从 PRD 的状态机中提取所有状态枚举值
+- 映射为：状态字段值 → 显示文本 → 样式（颜色/Element Tag 类型）
+- 使用前端常用色彩语义：绿色=成功/终态（已全部转单完成/已变更）、红色=失败/驳回、橙色=警告/待处理、蓝色=进行中、灰色=草稿/取消/作废
+
+**§N+1 — 用户输入区域**（表单页面）：
+
+- 从 PRD 的字段定义表（§4.3.1.3 等）和校验规则推导输入元素表
+- 格式：`| 元素 | 类型 | 行为 |`（类型 + 校验规则 + placeholder + 联动逻辑）
+- 输入元素类型使用前端组件名称：文本框、下拉选择框、日期选择器、文件上传、开关、数字输入框、文本域
+- 校验规则使用业务语言描述（如"必填"、"最大 500 字符"、"≥ 当前日期 + 提报提前期"），不使用正则表达式
+- 提交按钮标注 loading 状态和禁用条件（如"提交中禁止重复点击"、"必填字段未填写时禁用"）
+
+**§N+2 — 错误处理与用户反馈**：
+
+- 从系统设计文档的错误码定义（或 PRD 异常场景）转化为前端展示方案
+- 格式：`| 后端错误码 | HTTP | 前端展示 |`（错误码 + HTTP 状态码 + 提示文案 + 展示方式）
+- 展示方式包括：Message 全局提示、Dialog 对话框、表单字段级错误、Notification 通知
+- 提示文案应具体、友好，面向最终用户（如"要求成品入库时间不满足提报提前期要求"而非 "3103_forecast_order_007"）
+- 覆盖常见错误类型：表单校验失败、业务规则冲突、权限不足、网络异常、并发冲突（乐观锁）
+
+**§N+3 — 状态管理**：
+
+- 从前端交互需求推导需要管理的 State 变量
+- 格式：`| State 变量 | 类型 | 初始值 | 用途 |`
+- 变量名使用前端 camelCase 命名惯例
+- 按功能分组：
+  - 数据状态：列表数据（list）、详情数据（detail）、分页信息（pagination）、下拉选项数据
+  - 表单状态：表单数据对象（form）、校验错误信息（errors）、提交中标记（submitting）
+  - UI 状态：加载中标记（loading）、弹窗/抽屉开关（dialogVisible）、搜索条件折叠状态
+  - 选择状态：选中行 keys（selectedRows）、当前 Tab（activeTab）、当前概览维度
+
+**§8 — US → FSD 对齐表**（模板固定最后一节，章节编号随功能区域数量后移）：
+
+- 引用 PRD 中的 US 编号（如 US-01、US-02）
+- 将每条 US 的交互相关验收标准（AC）映射到本 FSD 的具体章节
+- 格式：`| UserStory | 验收标准涉及交互 | 本文章节 |`
+- 确保所有 US 的交互相关 AC 都有对应的功能区域描述，无遗漏
+
+### 步骤 4：保存文件
+
+将生成的功能规格说明书保存到 `30-system-design` 目录下，即 `{DESIGN_DIR}/{module-subdir}/`
+
+### 步骤 5：质量验证
+
+1. **生成检查清单**: 在 `{ADSPECS_FEATURE_DIRECTORY}/checklists/front_spec_checklist.md` 生成检查清单文件，使用本文 `## 质量检查` 章节中的完整项目列表（前端设计文档检查 20 项 + PRD 溯源检查 6 项）
+
+2. **运行验证检查**: 对照每个检查清单项审查生成的功能规格说明书：
+   - 对于每一项，确定其通过或失败
+   - 记录发现的具体问题（引用相关 FSD 章节）
+
+3. **处理验证结果**:
+   - **如果所有项通过**: 将检查清单标记为完成，继续必选执行后钩子部分
+   - **如果有项失败**:
+     1. 列出失败的项和具体问题
+     2. 更新功能规格说明书以处理每个问题
+     3. 重新运行验证直到所有项通过（最多 3 次迭代）
+     4. 如果 3 次迭代后仍然失败，在检查清单备注中记录剩余问题并警告用户
+
+4. **更新检查清单**: 在每次验证迭代后，以当前的通过/失败状态更新检查清单文件（将 `- [ ]` 切换为 `- [x]` 或反之）
+
+## 输出
+
+### 通用输出要求
+
+- 全文使用 UI/交互语言，避免出现 Java 类型、DDD 术语、后端实现细节
+- §1.1 页面清单须为每个页面定义清晰的路由路径
+- §2 页面布局必须使用 ASCII 字符画展示，标注区域名称和功能
+- 每个主要页面（列表/表单/详情/报表）独立为一个核心功能区域章节
+- 功能表中的"调用接口"列使用 REST API 路径（如 `GET /forecast-order/find-pagination`），不使用 Java 方法名
+- 输入元素使用前端组件名称（文本框/下拉框/日期选择器/开关/文件上传），不使用 Java 类型
+- 状态标签样式使用前端常用色彩语义描述（蓝/绿/红/橙/灰 + 对应场景）
+- 状态管理中的变量名使用前端命名惯例（camelCase）
+- 错误处理的提示文案应具体、友好，面向最终用户
+
+## 质量检查
+
+生成文件后，逐项核对以下清单：
+
+### 前端设计文档检查
+
+**模板覆盖**
+
+- [ ] 04 号模板必填部分（§1~§8）全部覆盖
+- [ ] 每个主要页面（列表/表单/详情/报表）独立为一个核心功能区域章节
+- [ ] US → FSD 对齐表覆盖 PRD 中所有 US 的交互相关 AC，无遗漏
+
+**页面路由与布局**
+
+- [ ] §1.1 页面清单为每个页面定义了清晰的路由路径，且关联了 UserStory 编号
+- [ ] §2 总体布局使用 ASCII 字符画，标注了区域名称和功能定位
+- [ ] 路由路径使用层级清晰的小写路径（如 `/sales/forecasts`、`/sales/forecasts/:id`）
+- [ ] 页面清单中的页面覆盖了 PRD 功能清单中所有涉及用户交互的三级功能
+
+**功能区域交互**
+
+- [ ] 列表类页面使用功能表格式（触发方式 → 调用接口 → 行为描述）
+- [ ] 详情/展示类页面使用状态条件表格式（空/有数据/加载中）
+- [ ] 状态标签映射使用前端色彩语义（蓝=进行中/绿=终态/红=驳回/橙=警告/灰=草稿取消）
+- [ ] 功能表"调用接口"列使用 REST API 路径，**不使用 Java 方法名**
+- [ ] 功能表"调用接口"列是否在对应模块的后端设计中存在和接口一致性
+- [ ] 每个功能区域的交互行为可追溯到 PRD 的 US/BR 编号
+
+**输入与校验**
+
+- [ ] 输入元素使用前端组件名称（文本框/下拉选择框/日期选择器/开关/文件上传），**不使用 Java 类型**
+- [ ] 校验规则使用业务语言描述（如"必填"、"最大 500 字符"），**不使用正则表达式**
+- [ ] 提交按钮标注了 loading 状态和禁用条件
+- [ ] 错误处理表中后端错误码映射到前端展示方式（Message/Dialog/字段级/Notification）
+
+**状态管理与规范**
+
+- [ ] 状态管理变量使用 camelCase 命名，按功能分组（数据状态/表单状态/UI 状态/选择状态）
+- [ ] 全文使用 UI/交互语言，**未出现 Java 类型、DDD 术语、后端实现细节**
+- [ ] 错误处理提示文案具体、友好，面向最终用户（非技术错误码原文）
+- [ ] 一级模块名称和编号与 `docs/10-architecture/01-*_business_scenarios.md` 或 `01-*_business_architecture.md` 中对应的模块对齐
+
+### PRD 溯源检查
+
+- [ ] 所有 PRD 功能清单中的三级功能都有对应的页面/功能区域
+- [ ] 所有 PRD 状态机的状态枚举值都有对应的状态标签映射
+- [ ] 所有 PRD 权限矩阵中的功能权限在交互行为中体现了可见性/可操作性控制
+- [ ] 所有 PRD 字段定义表中的必填字段在输入元素表中标注了校验规则
+- [ ] 所有 PRD 异常场景在错误处理表中有对应的前端展示方案
+- [ ] 无 [NEEDS CLARIFICATION] 标记残留
+
+## 必选执行后钩子
+
+**必须在向用户报告完成之前完成本节。**
+
+检查项目根目录是否存在 `.adspecs/extensions.yml`。
+
+- 如果不存在，或 `hooks.after_plan` 下没有注册钩子，跳到完成报告。
+- 如果存在，读取它并查找 `hooks.after_plan` 下的条目。
+- 如果 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~§8 覆盖情况）
+- PRD 中 US/BR 的对齐覆盖率
+- 质量检查通过项数 / 总项数
+- 如有未通过项，列出具体问题和建议修复方向
+
+## 完成标志
+
+- [ ] 功能规格说明书已生成（按 04 号模板 §1~§8 完整覆盖，必填部分无遗漏）
+- [ ] US → FSD 对齐表覆盖所有 PRD 用户故事的交互相关 AC
+- [ ] 质量检查清单已生成并通过验证
+- [ ] 文件已保存到 `{DESIGN_DIR}/{module-subdir}/`
+- [ ] 扩展钩子已根据上述必选执行后钩子规则分发或跳过
+- [ ] 完成报告已呈现给用户
+
+## 触发关键词
+
+`adspecs-front-spec`
+
+### 使用示例
+
+```
+/adspecs-front-spec {PRD_DIR}/crm/sales-forecast/M06-01_销售预测需求规格说明书.md
+```
+
+或直接在对话中指定：
+
+```
+使用 adspecs-front-spec 处理 M06-01_销售预测需求规格说明书.md
+```