# 05-验收清单（AC Matrix）

> **implement 与 deliver 的唯一验收 SSOT**。`01-需求分析报告.md` 仅为业务概述，**不**承担完整验收职责。  
> 每条 AC 须从 `source/PRD.md` **逐条抽取**（禁止仅从 01 摘要归纳）。

## 清单状态

- **定义状态**：未定义（AI 从 PRD 填表后改为 `已定义`）
- **签收状态**：未签收（交付前改为 `已签收`）

## ⛔ 格式强制约束（AI 必须遵守）

> **禁止自创表格结构**，必须严格使用下方「验收项」表格模板。  
> **禁止修改列名、列数或列顺序**，必须保持完全一致。

### 表格列定义（必须包含全部 9 列，缺一不可）

| 列名 | 说明 | 取值范围 |
|------|------|----------|
| **ID** | 全局唯一标识 | `AC-01`、`AC-02`、`AC-03-V`（两位数字起，不足补零；visual 变体加 `-V` 后缀） |
| **PRD 出处** | 需求来源 | `PRD-001`、`PRD-005,PRD-011` 等 PRD 原子 ID（**必填，必须引用 PRD-XXX ID**，支持逗号分隔多条；章节号仅作辅助标注） |
| **验收标准（可测试）** | 可观测断言 | DOM 顺序、完整 toast/tooltip 文案、E2E 路径、截图基线对比（**必填，禁止占位符**） |
| **预期结果** | 成功/失败判定 | 写明操作后的可判定结果：成功标准 + 失败/边界标准（**必填，禁止占位符**） |
| **对应证据** | 可复核留证 | 截图路径、Network 请求、测试文件、E2E 断言等（**必填**；签收前须为真实路径） |
| **测试类型** | 测试层级组合 | `unit` \| `component` \| `e2e` \| `visual` \| `manual`（可组合如 `unit+e2e`） |
| **优先级** | 业务重要性 | `P0`（交付阻断）\| `P1` \| `P2`（**至少 1 条 P0**） |
| **映射（spec/tasks）** | 任务关联 | 初始值 `待映射`，propose 后改为 `[AC-XX]` 引用 |
| **验收状态** | 验收进度 | 初始值 `待验收`，deliver 前 P0 改为 `已验收` 或 `验收不通过` |

### 禁止事项（违反将导致 gate 失败）

- ❌ 禁止使用「序号」「验收项」「验收方式」「状态」等非标准列名
- ❌ 禁止将「测试类型」填写为「手动测试」等中文，必须用 `manual`
- ❌ 禁止省略「预期结果」「对应证据」「映射（spec/tasks）」列或「PRD 出处」列
- ❌ 禁止使用多层嵌套表格（如「1.1」「1.2」子表格），所有 AC 必须在主表平铺
- ❌ 禁止在表格中留空占位符 `（填写）`，必须填入实际内容
- ❌ 禁止修改列标题的精确文本，如「验收标准（可测试）」不得改为「验收标准」
- ❌ 禁止省略「预期结果」或「对应证据」列（旧 7 列格式将导致 gate 失败）

## 五层 AC 模型（gate 强制）

在「验收标准（可测试）」列**前缀**标注：`[业务]`、`[UI]`、`[交互]`、`[数据]`、`[技术]`（不改 9 列表格）。

| 标签 | 要点 | 禁止 |
|------|------|------|
| `[业务]` | 业务规则、状态变更 | 不可测试空话 |
| `[UI]` | 结构/布局/样式；visual 基线 diff≤2% | 「页面展示正常」 |
| `[交互]` | loading、防重复、toast、失败恢复 | 仅「点击保存成功」 |
| `[数据]` | GET/POST + 字段映射 + 枚举 + null→`--` | 「调用接口成功」 |
| `[技术]` | lint/单测/TS | — |

**[交互] 推荐**：`操作：点击保存；前置：表单合法；过程：button loading、禁止重复提交；成功：toast「保存成功」；异常：接口失败恢复按钮`

**[数据] 推荐**：`GET /order/detail；入参 orderId；refund_status→refundStatus；0/1/2；null 展示 --`

**UI 保真五维**（P0 `[UI]` 并集 ≥3/5）：结构 · 布局 · 样式 · 状态 · 动效

## 填写规则

1. **ID**：`AC-01`、`AC-02`… 全局唯一；visual 变体加 `-V` 后缀如 `AC-02-V`。
2. **验收标准**：必须可观测（DOM 顺序、完整 toast/tooltip 文案、E2E 路径、**截图基线对比**等）；含 PRD 原型图时须写 `source/.../image_N.png` 或 `visual-baseline/xxx.png` 与 `diff≤2%`。
3. **预期结果**：必须写清**成功标准**与**失败/边界标准**，示例：
   - 成功：列表出现 ≥1 条且筛选条件与输入一致；toast 展示「保存成功」
   - 失败：无结果时展示空态文案「暂无数据」；接口非 200 时展示错误提示且不渲染脏数据
4. **对应证据**：必须写明证据类型与获取位置，示例：
   - 截图：`playwright-pic/<模块>/<变更>/AC-01-列表.png`
   - 网络：`Network GET /api/xxx status=200，response.total≥1`
   - 自动化：`e2e/foo.spec.ts` 中断言 `expect(page.getByText('保存成功'))`
   - 生成阶段可写**计划证据**；签收前 P0 须替换为**真实路径**
5. **UI 面 P0 强制句式（通用，不写死业务）**：凡涉及页面/弹窗/列表/详情/导入导出的 P0，验收标准**必须**同时写清：
   - **壳层**：`独立页` / `Tab` / `弹窗(Modal)` / `Drawer` 等（禁止只写「可打开」）
   - **交互原语**：`双击编辑` / `行内编辑` / `Tab 切换` / `预览→确认` 等可测步骤
   - 含接口路径时仍须写壳层，避免「接口对了、壳层做错」仍被签收
   - **禁止交互方式歧义**：P0 UI AC 验收标准**禁止**出现"行内/弹窗"、"Tab/抽屉"、"独立页/弹窗"等二选一表述。须与 PRD/演示代码一致，写明唯一交互方式
6. **测试类型**：`unit` | `component` | `e2e` | `visual` | `manual`（可组合，如 `unit+e2e+visual`）。**PRD source 含 `.png` 原型图时，至少 1 条 P0/P1 `visual` AC**（禁止仅用 P2 visual 应付）。
7. **优先级**：`P0`（交付阻断）/ `P1` / `P2`。
8. **映射**：propose 后在 `openspec/changes/<change>/tasks.md` 或 `spec.md` 中引用 `[AC-XX]`；**tasks 须有「演示模块迁移」段，与 design 映射表一行一任务**。
9. **Intentional 偏差**：与 PRD 有意不一致时，必须同步记入 `03-待确认问题清单.md` 并在下文登记。

## 验收项（必须使用此表格格式）

> **🤖 AI 生成指引（生成时必须删除本段）**：
> 1. **保留完整 9 列表头**：列名、顺序、数量不得修改
> 2. **删除下方示例行**：从 PRD 逐条抽取并填入实际验收项
> 3. **「PRD 出处」必填**：精确章节号（如 `PRD §1.2.3`），禁止 `（填写）` 占位符
> 4. **「验收标准」「预期结果」「对应证据」必填**：可观测的具体内容，禁止 `（填写）` 占位符
> 5. **「PRD 出处」必须引用 PRD 原子 ID**：如 `PRD-005` 或 `PRD-005,PRD-011`，禁止仅写章节号（如 `PRD §1.2.3`）。AI 须对照 `.prd-review-atoms.json` 中 domain=frontend 的原子逐条抽取，确保每条前端原子至少被一条 AC 引用。
> 6. **ID 递增**：从 `AC-01` 开始，每个 ID 全局唯一
> 7. **⚠️ 格式自检（生成后必须执行）**：
>    - [ ] 表格恰好 9 列？数一数表头的 `|` 分隔符
>    - [ ] 列名精确匹配：`ID` | `PRD 出处` | `验收标准（可测试）` | `预期结果` | `对应证据` | `测试类型` | `优先级` | `映射（spec/tasks）` | `验收状态`
>    - [ ] 每行以 `| AC-XX |` 开头（XX 为两位数字）？
>    - [ ] 每条 AC 的「预期结果」「对应证据」均已填写？
>    - [ ] 优先级列包含至少 1 个 `P0`？
>    - [ ] `定义状态` 已标记为 `已定义`？
>    - [ ] 无 `（填写）` 占位符？
> 8. **⚠️ 禁止格式（gate 将失败）**：
>    - ❌ 7 列旧格式（缺少「预期结果」「对应证据」）→ `ac-expected-evidence-quality` 失败
>    - ❌ 5 列格式 `| AC-ID | 优先级 | 验收标准 | 签收状态 | 验收备注 |` → gate 无法识别 P0
>    - ❌ 6 列格式 `| AC-ID | 优先级 | ... | 验收状态 | 签收状态 |` → gate 无法识别 P0
>    - ❌ 列名 `AC-ID`（必须用 `ID`）
>    - ❌ 列名 `签收状态`（必须用 `验收状态`）
>    - ❌ 列名 `验收备注`（不是标准列）
> 9. **格式验证**：生成后运行 `npx sdd-flow-kit gate --expect docs-closed --run-id <runId>` 验证，不通过则立即修复格式后重试

| ID | PRD 出处 | 验收标准（可测试） | 预期结果 | 对应证据 | 测试类型 | 优先级 | 映射（spec/tasks） | 验收状态 |
|----|---------|-------------------|---------|---------|---------|--------|-------------------|---------|
| AC-01 | PRD-001 | [业务] 订单详情页存在退款入口 | 成功：入口可见可点；失败：无入口或置灰无说明 | `e2e/order.spec.ts` | e2e | P0 | 待映射 | 待验收 |
| AC-02 | PRD-005 | [交互] 壳层=弹窗内 Tab；切换「导入/导入历史」；历史行「查看详情」打开明细（非独立路由页） | 成功：Tab 切换后内容区切换且无独立路由跳转；失败：点击后 404 或新开页 | `e2e/import.spec.ts` 断言 Tab 文案 | e2e | P0 | 待映射 | 待验收 |
| AC-02-V | PRD-005 | [UI] 列表页 table列顺序与基线 `source/.../image_1.png` 一致（spacing/字体/icon；diff≤2%） | 成功：像素 diff≤2%；失败：diff 超标或基线缺失 | `e2e/visual.spec.ts` toHaveScreenshot | visual+e2e | P1 | e2e/*.spec.ts | 待验收 |
| AC-03 | PRD-012 | [数据] GET /order/detail；入参 orderId；refund_status→refundStatus；0/1/2 枚举；null 展示 -- | 成功：字段与枚举正确；失败：脏数据或 null 未处理 | `src/.../order.mapper.test.ts` | unit | P0 | 待映射 | 待验收 |
| AC-04 | PRD-001 | [技术] 新增组件通过 eslint 与 TypeScript 检查 | 成功：lint/type 无 error；失败：有阻断级告警 | `npm run lint` 日志 | unit | P1 | 待映射 | 待验收 |

## Intentional 偏差登记

| AC-ID | 偏差说明（相对 PRD） | 确认来源（03 条目或用户原话） |
|-------|---------------------|------------------------------|
| （无则留空） | | |

## 签收检查（deliver 前人工/AI 勾选）

- [ ] 全部 P0 行的「验收状态」已改为 `已验收`
- [ ] 每条 P0 的「对应证据」已更新为**真实**截图/测试/日志路径（非计划占位）
- [ ] 每条 P0 在 `tasks.md` 或 `spec.md` 中有 `[AC-XX]` 映射且对应测试已通过
- [ ] Intentional 偏差已记入 `03` 且上表已登记
- [ ] 已将「签收状态」改为 `已签收`