docs(planning): 重组 Epic 结构 - 应用"先验证再扩展"策略

基于 Epic 1 和 Epic 2 的成功经验，将原 Epic 3（扩展工具集）拆分为独立的 Epic，
每个工具类别都遵循"开发 → E2E 验证 → 稳定性验证"的完整模式。

**变更内容：**
- Epic 3: 文件上传工具开发与验证（原 Epic 2.5 提升）
- Epic 4: 表单工具开发与验证（原 Epic 3 部分内容独立）
- Epic 5: 列表和对话框工具开发与验证（原 Epic 3 部分内容独立）
- Epic 6: 完整验证（残疾人管理）- 原编号不变
- Epic 7: 文档与开发者体验 - 原编号不变

**关键改进：**
- 每个工具都有独立的开发、验证、稳定性测试流程
- 优先解决文件上传测试超时阻塞问题（Epic 3）
- 清晰的 Epic 间依赖关系

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

_bmad-output/implementation-artifacts/sprint-status.yaml

@@ -1,4 +1,4 @@
-# generated: 2026-01-08
+# generated: 2026-01-10
 # project: 188-179-template-6
 # project_key: 188-179-template-6
 # tracking_system: file-system
@@ -33,7 +33,7 @@
 # - SM typically creates next story after previous one is 'done' to incorporate learnings
 # - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended)
 
-generated: 2026-01-09T18:59:00Z
+generated: 2026-01-10T08:00:00Z
 project: 188-179-template-6
 project_key: 188-179-template-6
 tracking_system: file-system
@@ -50,49 +50,79 @@ development_status:
   1-6-select-unit-tests: done
   epic-1-retrospective: done
 
-  # Epic 2: 在现有 E2E 测试中验证 Select 工具 (新 Epic - 来自回顾会议)
+  # Epic 2: 在现有 E2E 测试中验证 Select 工具
   # 详情参见: _bmad-output/implementation-artifacts/epic-2-retrospective.md
   epic-2: done
   2-1-install-e2e-utils: done
   2-2-rewrite-static-select: done
   2-3-rewrite-async-select: done
-  2-4-run-tests-collect-feedback: done  # 完成 - 修复了 listbox 依赖、超时配置、下拉框关闭逻辑
+  2-4-run-tests-collect-feedback: done
   2-5-fix-found-issues: done
-  # 2-6-stability-verification: skipped - 已充分验证，跳过稳定性测试
   epic-2-retrospective: done
 
-  # Epic 3 (原 Epic 2): 扩展工具集（文件上传、表单、列表、对话框）
-  # 状态: paused - Epic 2 已完成，但建议先完成技术改进（ESLint、文档、测试策略）
-  # 技术改进行动项参见: _bmad-output/implementation-artifacts/epic-2-retrospective.md
-  epic-3: paused
-  3-1-file-upload-tool: backlog
-  3-2-form-helper-tool: backlog
-  3-3-dynamic-list-tool: backlog
-  3-4-dialog-tool: backlog
-  3-5-update-export-fixtures: backlog
-  3-6-extended-unit-tests: backlog
+  # Epic 3: 文件上传工具开发与验证
+  # 目标: 遵循"先验证再扩展"策略，优先开发文件上传工具，解决当前测试超时阻塞问题
+  # 模式: 工具开发 → 真实 E2E 测试验证 → 问题修复 → 稳定性验证
+  epic-3: backlog
+  3-1-file-upload-tool: backlog          # 开发文件上传工具函数
+  3-2-upload-unit-tests: backlog         # 编写文件上传工具的单元测试
+  3-3-upload-e2e-integration: backlog    # 在 web/tests/e2e 中验证文件上传工具
+  3-4-collect-feedback-fix: backlog      # 收集反馈并修复问题
+  3-5-upload-stability-test: backlog     # 文件上传稳定性验证 (10次连续运行)
   epic-3-retrospective: optional
 
-  # Epic 4 (原 Epic 3): 在残疾人管理中验证工具包
-  # 状态: 暂停 - 等待 Epic 2 验证完成
-  epic-4: paused
-  4-1-photo-upload-test: backlog
-  4-2-bank-card-test: backlog
-  4-3-remark-visit-test: backlog
-  4-4-complete-flow-test: backlog
-  4-5-stability-test: backlog
+  # Epic 4: 表单工具开发与验证
+  # 模式: 工具开发 → 真实 E2E 测试验证 → 稳定性验证
+  epic-4: backlog
+  4-1-form-helper-tool: backlog          # 开发表单辅助工具函数
+  4-2-form-unit-tests: backlog           # 编写表单工具的单元测试
+  4-3-form-e2e-integration: backlog      # 在 web/tests/e2e 中验证表单工具
+  4-4-form-stability-test: backlog       # 表单稳定性验证
   epic-4-retrospective: optional
 
-  # Epic 5 (原 Epic 4): 完善文档与开发者体验
+  # Epic 5: 列表和对话框工具开发与验证
+  # 模式: 工具开发 → 真实 E2E 测试验证 → 稳定性验证
   epic-5: backlog
-  5-1-improve-readme-docs: backlog
+  5-1-dynamic-list-tool: backlog         # 开发动态列表工具函数
+  5-2-dialog-tool: backlog               # 开发对话框操作函数
+  5-3-list-dialog-unit-tests: backlog    # 编写列表和对话框的单元测试
+  5-4-list-dialog-e2e-integration: backlog  # 在 web/tests/e2e 中验证
+  5-5-list-dialog-stability-test: backlog   # 稳定性验证
   epic-5-retrospective: optional
 
-# 回顾会议行动项 (2026-01-09):
+  # Epic 6: 完整验证（残疾人管理）
+  # 状态: backlog - 等待所有工具开发和验证完成
+  epic-6: backlog
+  6-1-complete-flow-test: backlog
+  6-2-stability-test: backlog
+  epic-6-retrospective: optional
+
+  # Epic 7: 完善文档与开发者体验
+  epic-7: backlog
+  7-1-improve-readme-docs: backlog
+  7-2-vscode-snippets: backlog
+  epic-7-retrospective: optional
+
+# Epic 重新编号说明 (2026-01-10):
+# =====================================
+# 基于 Epic 1 和 Epic 2 的成功经验，采用"先验证再扩展"策略
+# 每个工具都遵循: 工具开发 → E2E 验证 → 稳定性验证
+#
+# Epic 1: Select 工具开发 ✅
+# Epic 2: Select 工具验证 ✅
+# Epic 3: 文件上传工具开发与验证 🆕
+#   - 解决当前测试超时阻塞问题
+# Epic 4: 表单工具开发与验证 🆕
+# Epic 5: 列表和对话框工具开发与验证 🆕
+# Epic 6: 完整验证（残疾人管理）
+# Epic 7: 文档与开发者体验
+
+# 技术改进完成状态 (2026-01-10):
+# ================================
 # - HIGH: 配置 ESLint 规则捕获常见问题 ✅
 # - HIGH: 更新架构文档记录 TypeScript + Playwright 陷阱 ✅
-# - HIGH: 创建新的 Epic 2（在现有 E2E 测试中验证 Select 工具）✅
-# - HIGH: 更新 Epic 编号（2→3, 3→4, 4→5）✅
-# - MEDIUM: 创建开发者自查清单
-# - MEDIUM: 更新代码审查检查清单
-# 详情参见: _bmad-output/implementation-artifacts/epic-1-retrospective.md
+# - HIGH: 创建开发者自查清单 ✅
+# 详情参见:
+#   - packages/e2e-test-utils/eslint.config.js
+#   - _bmad-output/planning-artifacts/architecture.md (新增 TypeScript+Playwright 陷阱部分)
+#   - packages/e2e-test-utils/docs/DEVELOPER_CHECKLIST.md

_bmad-output/planning-artifacts/epics.md

@@ -292,16 +292,27 @@ Error: Radix Select 等待超时
 |--------|------|------|
 | FR1-FR6 | Epic 1 | Radix UI Select 测试支持（静态和异步） |
 | FR25-FR32 | Epic 1 | 包基础设施（package.json、类型定义、配置） |
-| FR7-FR24, FR46-FR50 | Epic 3 | 扩展工具集（文件上传、表单、列表、对话框、可扩展性） |
-| FR41-FR45 | Epic 2 & 4 | 质量与稳定性（Select 验证、全面验证、稳定性测试） |
-| FR33-FR40 | Epic 5 | 文档与开发者体验（README、示例、迁移指南） |
-
-**Epic 规划变更说明（2026-01-09）：**
+| FR7-FR10 | Epic 3 | 文件上传测试支持（文件上传工具与验证） |
+| FR11-FR15 | Epic 4 | 表单交互测试支持（表单工具与验证） |
+| FR16-FR24 | Epic 5 | 列表和对话框测试支持（列表和对话框工具与验证） |
+| FR41-FR45 | Epic 2, 3, 4, 5, 6 | 质量与稳定性（各工具验证、全面验证、稳定性测试） |
+| FR33-FR40 | Epic 7 | 文档与开发者体验（README、示例、迁移指南） |
+| FR46-FR50 | Epic 3, 4, 5 | 可扩展性（各工具的配置和扩展支持） |
+
+**Epic 规划变更说明（2026-01-10）：**
 - Epic 1: ✅ 已完成（Select 工具基础框架）
-- Epic 2: 🆕 新增（在现有 E2E 测试中验证 Select 工具）
-- Epic 3: 原 Epic 2（扩展工具集）
-- Epic 4: 原 Epic 3（全面验证工具包）
-- Epic 5: 原 Epic 4（完善文档与开发者体验）
+- Epic 2: ✅ 已完成（在现有 E2E 测试中验证 Select 工具）
+- Epic 3: 🆕 文件上传工具开发与验证（遵循 Epic 2 成功模式）
+- Epic 4: 🆕 表单工具开发与验证（遵循 Epic 2 成功模式）
+- Epic 5: 🆕 列表和对话框工具开发与验证（遵循 Epic 2 成功模式）
+- Epic 6: 完整验证（残疾人管理）
+- Epic 7: 文档与开发者体验
+
+**"先验证再扩展"策略：**
+基于 Epic 2 的成功经验，每个工具都遵循"开发 → E2E 验证 → 稳定性验证"的模式：
+- Epic 3: 文件上传工具（优先解决当前测试超时问题）
+- Epic 4: 表单工具
+- Epic 5: 列表和对话框工具
 
 ## Epic List
 
@@ -309,6 +320,8 @@ Error: Radix Select 等待超时
 
 **目标：** 测试开发者可以安装 `@d8d/e2e-test-utils` 包，立即使用 Select 工具测试 Radix UI Select 组件（最常用、最关键的测试场景）。
 
+**状态:** ✅ Done
+
 **交付物：**
 - 完整的包结构和配置（package.json, tsconfig.json, vitest.config.ts）
 - `selectRadixOption()` 和 `selectRadixOptionAsync()` 函数
@@ -319,77 +332,111 @@ Error: Radix Select 等待超时
 
 **FRs covered:** FR1-FR6, FR25-FR32
 
-**用户价值：**
-- 可以安装并立即使用 Select 工具
-- 无需深入了解 Radix UI DOM 结构
-- 自动处理时序问题
-- 清晰的错误提示
+---
+
+### Epic 2: 在现有 E2E 测试中验证 Select 工具
+
+**目标：** 在 `web/tests/e2e/` 的残疾人管理测试中使用 Select 工具，验证工具在真实场景中的可用性和稳定性。
+
+**状态:** ✅ Done
+
+**交付物：**
+- Select 工具在残疾人管理测试中的实际应用
+- 5 处静态 Select 迁移（残疾类型、等级等）
+- 2 处异步 Select 迁移（省份、城市）
+- DOM 结构问题修复（listbox → option）
+
+**FRs covered:** FR41-FR45 (部分)
+
+**关键经验：**
+- DOM 结构假设必须验证
+- 真实 E2E 测试不可替代
+- "先验证再扩展"策略有效
 
 ---
 
-### Epic 2: 扩展工具集（文件上传、表单、列表、对话框）
+### Epic 3: 文件上传工具开发与验证
+
+**目标：** 遵循 Epic 2 成功模式，开发文件上传工具并在真实 E2E 测试中验证，解决当前测试超时阻塞问题。
 
-**目标：** 测试开发者可以使用完整的 6 个核心工具函数，覆盖所有常见 E2E 测试场景。
+**状态:** 🆕 Backlog
+
+**模式：** 工具开发 → 真实 E2E 测试验证 → 问题修复 → 稳定性验证
+
+**交付物：**
+- `uploadFileToField()` 文件上传工具
+- 单元测试（Vitest）
+- 在残疾人管理测试中验证（至少 3 处文件上传）
+- 稳定性验证（10次连续运行）
+
+**FRs covered:** FR7-FR10, FR46-FR50 (部分), FR41-FR45 (部分)
+
+---
+
+### Epic 4: 表单工具开发与验证
+
+**目标：** 开发表单辅助工具并在真实 E2E 测试中验证。
+
+**状态:** Backlog (等待 Epic 3 完成)
+
+**模式：** 工具开发 → 真实 E2E 测试验证 → 稳定性验证
 
 **交付物：**
-- `uploadFileToField()` - 文件上传工具
 - `fillMultiStepForm()`, `scrollToSection()` - 表单辅助工具
-- `addDynamicListItem()`, `deleteDynamicListItem()` - 动态列表工具
-- `handleDialog()`, `waitForDialogClosed()`, `cancelDialog()` - 对话框工具
-- Fixtures 目录结构示例
 - 单元测试
+- 在残疾人管理测试中验证
+- 稳定性验证
+
+**FRs covered:** FR11-FR15, FR46-FR50 (部分), FR41-FR45 (部分)
+
+---
 
-**FRs covered:** FR7-FR24, FR46-FR50
+### Epic 5: 列表和对话框工具开发与验证
+
+**目标：** 开发动态列表和对话框工具并在真实 E2E 测试中验证。
+
+**状态:** Backlog (等待 Epic 4 完成)
+
+**模式：** 工具开发 → 真实 E2E 测试验证 → 稳定性验证
+
+**交付物：**
+- `addDynamicListItem()`, `deleteDynamicListItem()` - 动态列表工具
+- `handleDialog()`, `waitForDialogClosed()` - 对话框工具
+- 单元测试
+- 在残疾人管理测试中验证
+- 稳定性验证
 
-**用户价值：**
-- 完整的工具集覆盖所有常见测试场景
-- 统一的 API 设计和错误处理
-- 支持可配置和扩展
+**FRs covered:** FR16-FR24, FR46-FR50 (部分), FR41-FR45 (部分)
 
 ---
 
-### Epic 3: 在残疾人管理中验证工具包
+### Epic 6: 完整验证（残疾人管理）
+
+**目标：** 工具包在真实的残疾人管理 E2E 测试中完整验证，证明所有工具函数可用且稳定。
 
-**目标：** 工具包在真实的残疾人管理 E2E 测试中验证，证明工具函数可用且稳定，提供完整的参考示例。
+**状态:** Backlog (等待 Epic 5 完成)
 
 **交付物：**
-- 残疾人管理 E2E 测试（使用工具函数）
-- 照片上传功能测试
-- 银行卡管理功能测试
-- 备注功能测试
-- 回访功能测试
-- 完整流程测试
+- 残疾人管理完整流程测试（使用所有工具）
 - 稳定性验证（20次连续运行 100% 通过）
 
 **FRs covered:** FR38, FR41-FR45
 
-**用户价值：**
-- 验证工具包的可用性和稳定性
-- 提供完整的参考示例
-- 证明工具包符合性能标准
-
 ---
 
-### Epic 4: 完善文档与开发者体验
+### Epic 7: 完善文档与开发者体验
 
 **目标：** 测试开发者可以在 30 分钟内上手使用工具包，有完整的文档、示例和迁移指南。
 
+**状态:** Backlog (等待 Epic 6 完成)
+
 **交付物：**
 - 完整的 README（安装、快速入门、API 文档）
-- 每个工具函数的详细使用示例
-- 迁移指南（从现有测试代码到工具函数）
-- 常见问题和解决方案
-- 残疾人管理测试作为完整示例
-- JSDoc 完整注释
+- VS Code snippets
+- 迁移指南
 
 **FRs covered:** FR33-FR40
 
-**用户价值：**
-- 快速上手（30 分钟内编写第一个测试）
-- 清晰的文档和示例
-- 降低学习曲线
-- 便于团队采用
-
 ---
 
 ## Epic 1: 测试工具包基础框架与 Select 支持
@@ -655,17 +702,40 @@ Error: Radix Select 等待超时
 - 9/10 次通过 = 90% 稳定性，需要分析失败原因 ⚠️
 - < 9/10 次通过 = 稳定性不足，需要修复 ❌
 
+**Epic 2 状态:** ✅ Done
+**回顾文档:** `_bmad-output/implementation-artifacts/epic-2-retrospective.md`
+
 ---
 
-## Epic 3: 扩展工具集（文件上传、表单、列表、对话框）
+## Epic 3: 文件上传工具开发与验证
+
+**目标：** 遵循 Epic 2 的成功模式，开发文件上传工具并在 `web/tests/e2e/` 的真实测试中验证，解决当前测试超时阻塞问题。
+
+**背景：**
+- Epic 1 和 Epic 2 已证明"先验证再扩展"策略的有效性
+- 当前残疾人管理测试在文件上传阶段超时（60秒），阻塞了完整验证
+- 优先开发文件上传工具，解决当前阻塞问题
+
+**范围：**
+- ✅ 开发文件上传工具 `uploadFileToField()`
+- ✅ 编写单元测试（Vitest）
+- ✅ 在 `web/tests/e2e/` 中验证工具
+- ✅ 收集反馈并修复问题
+- ✅ 稳定性验证（10次连续运行）
+
+**模式：** 工具开发 → 真实 E2E 测试验证 → 问题修复 → 稳定性验证
 
-**目标：** 测试开发者可以使用完整的 6 个核心工具函数，覆盖所有常见 E2E 测试场景。
+**依赖：**
+- Epic 1: ✅ 已完成（类型定义、错误处理、基础设施）
 
-**说明：** 本 Epic 原 Epic 2，已在 Epic 2 完成后重新编号。
+**验收标准：**
+1. 文件上传工具在至少 3 处真实 E2E 测试中使用
+2. 所有测试连续运行 10 次，100% 通过率
+3. 测试超时问题已解决
 
 ---
 
-### Story 3.1: 实现文件上传工具
+### Story 3.1: 开发文件上传工具函数
 
 作为测试开发者，
 我想要使用 `uploadFileToField()` 函数上传文件，
@@ -680,10 +750,146 @@ Error: Radix Select 等待超时
 **And** 支持相对路径（相对于 fixtures 目录）
 **And** 错误时提供清晰消息（文件路径、选择器、失败原因）
 **And** 操作在 5 秒内完成（NFR9）
+**And** 配置对象继承 `BaseOptions`
+
+**函数签名：**
+```typescript
+export async function uploadFileToField(
+  page: Page,
+  selector: string,
+  fileName: string,
+  options?: FileUploadOptions
+): Promise<void>
+
+export interface FileUploadOptions extends BaseOptions {
+  /** fixtures 目录路径，默认为 'tests/fixtures' */
+  fixturesDir?: string;
+  /** 是否等待上传完成，默认为 true */
+  waitForUpload?: boolean;
+}
+```
+
+**参考架构决策：**
+- 遵循 `docs/standards/e2e-radix-testing.md` 中的文件上传规范
+- 使用 `DEFAULT_TIMEOUTS` 常量定义超时
+- 错误处理使用 `E2ETestError` 和 `ErrorContext`
 
 ---
 
-### Story 3.2: 实现表单辅助工具
+### Story 3.2: 编写文件上传单元测试
+
+作为测试开发者，
+我想要文件上传工具有充分的单元测试，
+以便确保函数的正确性和稳定性。
+
+**验收标准：**
+
+**Given** 文件上传工具函数已实现
+**When** 创建 `tests/unit/file-upload.test.ts`
+**Then** 测试覆盖率 ≥ 80%（NFR29）
+**And** 测试用例包括：成功上传、文件不存在、选择器无效、超时
+**And** 使用 Vitest 运行测试
+**And** 所有测试通过
+
+**⚠️ Epic 2 关键经验应用：**
+- 单元测试无法发现真实 DOM 问题，但可验证基本逻辑
+- 必须添加集成测试使用真实 Playwright API
+- 使用 Playwright Page mock 验证文件上传逻辑
+
+---
+
+### Story 3.3: 在 web/tests/e2e 中验证文件上传工具
+
+作为测试开发者，
+我想要在 `web/tests/e2e/` 的残疾人管理测试中使用文件上传工具，
+以便验证工具在真实场景中的可用性。
+
+**验收标准：**
+
+**Given** 文件上传工具和单元测试已完成
+**When** 在 `web/tests/e2e/specs/admin/disability-person-complete.spec.ts` 中使用工具
+**Then** 至少迁移 3 处文件上传操作（身份证照片、残疾证照片）
+**And** 移除原有的自定义文件上传方法
+**And** 测试在真实浏览器中通过
+**And** 无测试超时问题
+
+**验证场景：**
+- 身份证照片上传（正面、反面）
+- 残疾证照片上传
+- 个人照片上传（如果有）
+
+**参考 Epic 2.2-2.3 的迁移模式：**
+- 渐进式迁移：先迁移部分测试
+- 保留原有方法作为 TODO 备份
+- 验证通过后再完全替换
+
+---
+
+### Story 3.4: 收集反馈并修复问题
+
+作为测试开发者，
+我想要运行使用文件上传工具的测试并收集反馈，
+以便发现潜在问题并改进工具。
+
+**验收标准：**
+
+**Given** 文件上传工具已在真实测试中使用
+**When** 运行完整的 E2E 测试套件
+**Then** 记录所有问题（失败的测试、错误消息、使用体验）
+**Then** 分类问题：工具 bug vs 使用错误 vs 改进建议
+**And** 所有标记为"工具 bug"的问题已修复
+**And** 测试连续运行 5 次通过
+**And** 无 flaky 失败
+
+**优先级：**
+- HIGH: 影响测试结果的问题（如上传失败、超时）
+- MEDIUM: 影响开发体验的问题（如错误消息不清晰）
+- LOW: 优化建议（如性能改进）
+
+---
+
+### Story 3.5: 文件上传稳定性验证
+
+作为测试开发者，
+我想要验证文件上传工具的稳定性，
+以便确保工具可以可靠地使用。
+
+**验收标准：**
+
+**Given** 所有问题已修复
+**When** 连续运行文件上传相关测试 10 次
+**Then** 所有测试 100% 通过
+**And** 无超时失败
+**And** 平均执行时间 ≤ 5 秒/文件
+
+**测试场景：**
+- `pnpm test:e2e:chromium disability-person-complete.spec.ts` 运行 10 次
+- 重点验证文件上传相关步骤
+
+**成功标准：**
+- 10/10 次通过 = 100% 稳定性 ✅
+- 9/10 次通过 = 90% 稳定性，需要分析失败原因 ⚠️
+- < 9/10 次通过 = 稳定性不足，需要修复 ❌
+
+**Epic 3 回顾：**
+- 如果 100% 通过，可以进入 Epic 4
+- 如果 < 100%，需要分析并修复问题后再验证
+
+---
+
+## Epic 4: 表单工具开发与验证
+
+**目标：** 开发表单辅助工具并在 `web/tests/e2e/` 的真实测试中验证。
+
+**说明：** 遵循 Epic 2 和 Epic 3 的成功模式。
+
+**依赖：** Epic 3 完成
+
+**模式：** 工具开发 → 真实 E2E 测试验证 → 稳定性验证
+
+---
+
+### Story 4.1: 开发表单辅助工具函数
 
 作为测试开发者，
 我想要使用 `fillMultiStepForm()` 和 `scrollToSection()` 函数，
@@ -700,157 +906,158 @@ Error: Radix Select 等待超时
 
 ---
 
-### Story 3.3: 实现动态列表工具
+### Story 4.2: 编写表单工具单元测试
 
 作为测试开发者，
-我想要使用 `addDynamicListItem()` 和 `deleteDynamicListItem()` 函数，
-以便测试银行卡管理、备注管理等动态列表功能。
+我想要表单工具有充分的单元测试，
+以便确保函数的正确性和稳定性。
 
 **验收标准：**
 
-**Given** 类型定义已存在
-**When** 实现 `src/dynamic-list.ts` 中的动态列表函数
-**Then** `addDynamicListItem(page, itemType, data)` 添加新列表项
-**And** `deleteDynamicListItem(page, itemType, index)` 删除指定索引的项
-**And** 支持不同类型列表项（银行卡、备注等）
-**And** 验证列表状态变化
-**And** 处理异步更新场景
+**Given** 表单辅助工具函数已实现
+**When** 创建 `tests/unit/form-helper.test.ts`
+**Then** 测试覆盖率 ≥ 80%（NFR29）
+**And** 测试用例包括：成功填写、滚动操作、验证错误等
+**And** 使用 Vitest 运行测试
+**And** 所有测试通过
 
 ---
 
-### Story 3.4: 实现对话框操作工具
+### Story 4.3: 在 web/tests/e2e 中验证表单工具
 
 作为测试开发者，
-我想要使用 `handleDialog()`, `waitForDialogClosed()`, `cancelDialog()` 函数，
-以便统一操作 Radix UI Dialog。
+我想要在残疾人管理测试中使用表单辅助工具，
+以便验证工具在真实场景中的可用性。
 
 **验收标准：**
 
-**Given** 类型定义已存在
-**When** 实现 `src/dialog.ts` 中的对话框操作函数
-**Then** `handleDialog(page, action)` 支持 confirm/cancel/close 操作
-**And** `waitForDialogClosed(page)` 等待对话框完全关闭
-**And** `cancelDialog(page)` 提供取消操作的快捷方式
-**And** 理解 Radix UI Dialog 的 DOM 结构（`role="dialog"`）
-**And** 等待对话框关闭后再继续后续操作
+**Given** 表单工具和单元测试已完成
+**When** 在残疾人管理测试中使用工具
+**Then** 验证多步骤表单填写
+**And** 验证滚动操作
+**And** 测试在真实浏览器中通过
 
 ---
 
-### Story 3.5: 更新主导出和 Fixtures 示例
+### Story 4.4: 表单稳定性验证
 
 作为测试开发者，
-我想要可以导入所有新增的工具函数，
-并参考 Fixtures 目录结构示例。
+我想要验证表单工具的稳定性，
+以便确保工具可以可靠地使用。
 
 **验收标准：**
 
-**Given** 所有扩展工具函数已实现
-**When** 更新 `src/index.ts` 和创建 Fixtures 目录示例
-**Then** `index.ts` 导出所有新函数（uploadFileToField, fillMultiStepForm 等）
-**And** 创建 `tests/fixtures/` 目录结构示例
-**And** Fixtures 包含 `images/` 和 `documents/` 子目录
-**And** 提供示例测试文件（sample-id-card.jpg 等）
-**And** 所有函数有完整的 JSDoc 注释
+**Given** 所有问题已修复
+**When** 连续运行表单相关测试 10 次
+**Then** 所有测试 100% 通过
 
 ---
 
-### Story 3.6: 扩展工具集单元测试
+## Epic 5: 列表和对话框工具开发与验证
 
-作为测试开发者，
-我想要所有扩展工具函数有充分的单元测试，
-以便确保函数的正确性和稳定性。
+**目标：** 开发动态列表和对话框工具并在 `web/tests/e2e/` 的真实测试中验证。
 
-**验收标准：**
+**说明：** 遵循 Epic 2-4 的成功模式。
 
-**Given** 扩展工具函数已实现
-**When** 创建 `tests/unit/` 下的测试文件
-**Then** 测试覆盖率 ≥ 80%（NFR29）
-**And** 测试文件包括：file-upload.test.ts, form-helper.test.ts, dynamic-list.test.ts, dialog.test.ts
-**And** 每个函数的成功和失败场景都有测试
-**And** 使用 Vitest 运行，所有测试通过
+**依赖：** Epic 4 完成
+
+**模式：** 工具开发 → 真实 E2E 测试验证 → 稳定性验证
 
 ---
 
-## Epic 4: 在残疾人管理中验证工具包
+### Story 5.1: 开发动态列表和对话框工具函数
 
-**目标：** 工具包在真实的残疾人管理 E2E 测试中验证，证明工具函数可用且稳定，提供完整的参考示例。
+作为测试开发者，
+我想要使用 `addDynamicListItem()`、`deleteDynamicListItem()` 和对话框工具，
+以便测试银行卡管理、备注管理等动态列表功能。
 
-**说明：** 本 Epic 原 Epic 3，已在 Epic 2 完成后重新编号。
+**验收标准：**
 
-**注意：** 原 Epic 3 的范围需要调整，因为 Epic 2 已涵盖 Select 工具的验证。
+**Given** 类型定义已存在
+**When** 实现 `src/dynamic-list.ts` 和 `src/dialog.ts` 中的函数
+**Then** `addDynamicListItem(page, itemType, data)` 添加新列表项
+**And** `deleteDynamicListItem(page, itemType, index)` 删除指定索引的项
+**And** `handleDialog(page, action)` 支持 confirm/cancel/close 操作
+**And** `waitForDialogClosed(page)` 等待对话框完全关闭
+**And** 支持不同类型列表项（银行卡、备注等）
 
 ---
 
-### Story 4.2: 照片上传功能测试（使用现有测试）
+### Story 5.2: 编写列表和对话框单元测试
 
 作为测试开发者，
-我想要在现有的残疾人管理 E2E 测试中使用文件上传工具，
-以便验证 `uploadFileToField()` 的可用性。
+我想要列表和对话框工具有充分的单元测试，
+以便确保函数的正确性和稳定性。
 
 **验收标准：**
 
-**Given** Epic 3 已完成，文件上传工具已实现
-**When** 在 `web/tests/e2e/specs/admin/disability-person-complete.spec.ts` 中使用 `uploadFileToField()`
-**Then** 上传身份证照片（正面、反面）
-**And** 上传残疾证照片
-**And** 验证文件上传成功
-**And** 测试使用 `web/tests/e2e/fixtures/images/` 中的示例文件
+**Given** 列表和对话框工具函数已实现
+**When** 创建 `tests/unit/dynamic-list.test.ts` 和 `dialog.test.ts`
+**Then** 测试覆盖率 ≥ 80%（NFR29）
+**And** 测试用例包括：添加、删除、打开/关闭对话框等
+**And** 使用 Vitest 运行测试
+**And** 所有测试通过
 
 ---
 
-### Story 4.3: 银行卡管理功能测试（使用现有测试）
+### Story 5.3: 在 web/tests/e2e 中验证列表和对话框工具
 
 作为测试开发者，
-我想要在现有的残疾人管理 E2E 测试中使用动态列表和对话框工具，
-以便验证这些工具的可用性。
+我想要在残疾人管理测试中使用列表和对话框工具，
+以便验证工具在真实场景中的可用性。
 
 **验收标准：**
 
-**Given** Epic 3 已完成，对话框和动态列表工具已实现
-**When** 在现有测试中使用 `handleDialog()`, `addDynamicListItem()`, `deleteDynamicListItem()`
-**Then** 打开添加银行卡对话框
-**And** 填写银行卡信息（银行名称、卡号、持卡人）
-**And** 添加银行卡到列表
-**And** 验证列表状态变化
+**Given** 列表和对话框工具及单元测试已完成
+**When** 在残疾人管理测试中使用工具
+**Then** 验证银行卡管理（添加、删除）
+**And** 验证备注管理
+**And** 测试在真实浏览器中通过
 
 ---
 
-### Story 4.4: 备注和回访功能测试（使用现有测试）
+### Story 5.4: 列表和对话框稳定性验证
 
 作为测试开发者，
-我想要在现有的残疾人管理 E2E 测试中使用表单辅助工具，
-以便验证表单工具的综合使用。
+我想要验证列表和对话框工具的稳定性，
+以便确保工具可以可靠地使用。
 
 **验收标准：**
 
-**Given** Epic 3 已完成，表单辅助工具已实现
-**When** 在现有测试中使用 `fillMultiStepForm()`, `scrollToSection()`
-**Then** 填写备注表单
-**And** 滚动到回访区域
-**And** 添加备注到列表
-**And** 验证表单提交和列表更新
+**Given** 所有问题已修复
+**When** 连续运行列表和对话框相关测试 10 次
+**Then** 所有测试 100% 通过
+
+---
+
+## Epic 6: 完整验证（残疾人管理）
+
+**目标：** 工具包在真实的残疾人管理 E2E 测试中完整验证，证明所有工具函数可用且稳定。
+
+**依赖：** Epic 5 完成
 
 ---
 
-### Story 4.5: 完整流程验证
+### Story 6.1: 完整流程测试
 
 作为测试开发者，
-我想要在现有的完整流程测试中使用所有工具，
+我想要在残疾人管理完整流程测试中使用所有工具，
 以便演示所有工具函数的综合使用。
 
 **验收标准：**
 
-**Given** Epic 2-4 的所有工具已在部分测试中验证
+**Given** Epic 1-5 的所有工具已实现并验证
 **When** 确保 `disability-person-complete.spec.ts` 使用所有工具
 **Then** 基本信息：使用 `selectRadixOption` 和 `selectRadixOptionAsync`
-**And** 照片上传：使用 `uploadFileToField`
-**And** 银行卡管理：使用 `handleDialog`, `addDynamicListItem`, `deleteDynamicListItem`
-**And** 备注添加：使用 `fillMultiStepForm`, `scrollToSection`, `addDynamicListItem`
+**And** 照片上传：使用 `uploadFileToField` (来自 Epic 3)
+**And** 表单操作：使用 `fillMultiStepForm`, `scrollToSection` (来自 Epic 4)
+**And** 银行卡管理：使用 `handleDialog`, `addDynamicListItem`, `deleteDynamicListItem` (来自 Epic 5)
+**And** 备注添加：使用 `addDynamicListItem` (来自 Epic 5)
 **And** 所有测试通过
 
 ---
 
-### Story 4.6: 稳定性测试（使用现有测试）
+### Story 6.2: 稳定性测试
 
 作为测试开发者，
 我想要有稳定性测试验证工具包的可靠性，
@@ -859,7 +1066,7 @@ Error: Radix Select 等待超时
 **验收标准：**
 
 **Given** 完整流程测试已编写
-**When** 创建 `tests/stability/repeat-run.spec.ts`
+**When** 创建稳定性测试或运行现有测试 20 次
 **Then** 测试连续运行 20 次完整流程
 **And** 验证 100% 通过率（NFR1）
 **And** 测试执行时间符合性能标准（NFR8-NFR11）
@@ -868,15 +1075,15 @@ Error: Radix Select 等待超时
 
 ---
 
-## Epic 5: 完善文档与开发者体验
+## Epic 7: 完善文档与开发者体验
 
 **目标：** 测试开发者可以在 30 分钟内上手使用工具包，有完整的文档、示例和迁移指南。
 
-**说明：** 本 Epic 原 Epic 4，已在 Epic 2 完成后重新编号。
+**依赖：** Epic 6 完成
 
 ---
 
-### Story 5.1: 完善 README、API 文档和示例
+### Story 7.1: 完善 README、API 文档和示例
 
 作为测试开发者，
 我想要有完整的 README 和 API 文档，
@@ -884,7 +1091,7 @@ Error: Radix Select 等待超时
 
 **验收标准：**
 
-**Given** Epic 1-4 的所有功能已实现
+**Given** Epic 1-6 的所有功能已实现
 **When** 完善 `README.md` 和 API 文档
 **Then** README 包含：项目简介、安装说明、快速入门、API 文档
 **And** 每个工具函数都有完整的使用示例
@@ -894,4 +1101,21 @@ Error: Radix Select 等待超时
 **And** 残疾人管理测试作为完整示例
 **And** 所有函数有完整的 JSDoc 注释
 
+---
+
+### Story 7.2: VS Code Snippets 和开发体验
+
+作为测试开发者，
+我想要有 VS Code 代码片段，
+以便加速测试开发。
+
+**验收标准：**
+
+**Given** README 和 API 文档已完成
+**When** 创建 VS Code snippets 配置
+**Then** 提供常用代码片段（selectRadixOption, uploadFileToField 等）
+**And** 片段有清晰的触发词和描述
+**And** 文档说明如何安装和使用 snippets
+**And** 开发者可以在 30 分钟内使用工具包编写第一个测试
+