docs: 完成 Epic 1 回顾及技术改进

- 添加 Epic 1 回顾会议文档（epic-1-retrospective.md）
- 重新排列 Epic 顺序：Epic 2 验证现有工具 -> Epic 3 扩展工具集
- 配置 ESLint 规则捕获常见代码问题（冗余 null 检查、空 catch、未使用变量）
- 更新架构文档添加 TypeScript + Playwright 常见陷阱
- 创建新 Epic 2：在现有 E2E 测试中验证 Select 工具

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/epic-1-retrospective.md

@@ -0,0 +1,401 @@
+# Epic 1 Retrospective: 测试工具包基础框架与 Select 支持
+
+**会议日期:** 2026-01-09
+**Epic 状态:** ✅ Done
+**参与人员:** Root (Project Lead), Bob (Scrum Master), Alice (Product Owner), Charlie (Senior Dev), Dana (QA Engineer), Elena (Junior Dev)
+
+## 会议概览
+
+**Epic 1 目标:** 测试开发者可以安装 `@d8d/e2e-test-utils` 包，立即使用 Select 工具测试 Radix UI Select 组件。
+
+**交付成果:**
+- 完成故事: 6/6 (100%)
+- 单元测试: 37/37 通过 (100%)
+- 测试覆盖率: 93.65% Statements, 88.09% Branches
+- 类型检查: ✅ 通过
+
+**会议目的:**
+1. 学习 Epic 1 的执行经验
+2. 为下一个 Epic 的成功做准备
+
+## 成功经验 ✅
+
+### 1. 代码审查流程有效
+
+代码审查在 Epic 1 中发挥了关键作用：
+
+| 故事 | 审查问题 | HIGH | MEDIUM | LOW | 状态 |
+|------|---------|------|--------|-----|------|
+| 1.1 | 9 | 3 | 3 | 2 | 全部修复 |
+| 1.2 | 4 | 1 | 2 | 1 | 全部修复 |
+| 1.3 | 8 | 2 | 6 | 0 | 全部修复 |
+| 1.4 | 7 | 2 | 5 | 0 | 全部修复 |
+| 1.5 | 6 | 0 | 4 | 2 | 全部修复 |
+| 1.6 | 5 | 0 | 4 | 1 | 全部修复 |
+| **总计** | **39** | **8** | **24** | **7** | **100% 修复** |
+
+**关键发现:**
+- HIGH 级问题从 Story 1.1-1.4 的 8 个降至 Story 1.5-1.6 的 0 个
+- 所有问题无一遗漏，全部得到修复
+- 团队从审查中学习并应用到下一个故事
+
+**Charlie (Senior Dev):** "Story 1.3 的审查发现的问题尤其关键。如果我们没有发现 `:has-text()` 会部分匹配的问题，测试可能会在错误选项上通过，导致严重的假阳性 bug。"
+
+### 2. 持续改进模式
+
+从前一个故事的经验传递到下一个故事：
+
+| 经验来源 | 应用故事 | 内容 |
+|---------|---------|------|
+| Story 1.3 审查 | Story 1.4 | DOM 类型问题处理、精确文本匹配 |
+| Story 1.4 实现 | Story 1.6 | 单元测试 Mock 策略、重试机制测试 |
+| Story 1.6 测试 | Bug 修复 | 发现并修复网络空闲等待超时配置 bug |
+
+**Elena (Junior Dev):** "Charlie 在 Story 1.3 的审查后让我把每个内部函数都加上完整的 JSDoc。虽然一开始觉得麻烦，但后来写 Story 1.4 的测试时发现这些文档真的很有帮助。"
+
+### 3. 测试质量提升
+
+测试覆盖率从 Story 1.1 的基础占位测试提升到 Story 1.6 的优秀覆盖率：
+
+- **Statements:** 93.65% (目标: ≥80%)
+- **Branches:** 88.09% (目标: ≥80%)
+- **Functions:** 100% (目标: ≥80%)
+- **Lines:** 93.65% (目标: ≥80%)
+
+**Dana (QA Engineer):** "Story 1.6 更有意思——我们在写单元测试的过程中发现了一个实际的 bug：`selectRadixOptionAsync` 的网络空闲等待超时配置不对。这证明代码审查和测试是互补的。"
+
+### 4. 类型系统基础扎实
+
+Epic 1 建立的类型系统为后续开发奠定了基础：
+
+- `BaseOptions` - 所有配置对象的基类
+- `ErrorContext` - 结构化错误信息
+- `E2ETestError` - 统一的错误处理
+- `AsyncSelectOptions`, `FileUploadOptions`, `FormStepOptions`, `DialogOptions` - 特定选项类型
+
+**Charlie (Senior Dev):** "我们在 Epic 1 建立的类型系统是一个很大的胜利。`BaseOptions` 作为所有配置对象的基类、`E2ETestError` 提供结构化错误信息，这些设计模式在后续故事中持续复用，减少了重复代码。"
+
+---
+
+**[第一部分完 - 会议概览和成功经验]**
+
+## 挑战和问题分析 ⚠️
+
+### 1. 重复出现的审查问题
+
+代码审查发现的 39 个问题中，有相当一部分是重复出现的：
+
+| 问题类型 | 出现次数 | 可预防？ | 预防方法 |
+|---------|---------|----------|----------|
+| 冗余 null 检查 | 5+ | ✅ 是 | ESLint 规则 |
+| 缺少 JSDoc | 8+ | ✅ 是 | ESLint 规则 |
+| 空 catch 块 | 4+ | ✅ 是 | ESLint 规则 |
+| DOM 类型问题 | 1 | ✅ 是 | 架构文档 |
+| 文本选择器精确性 | 1 | ✅ 是 | 编码规范 |
+
+**Dana (QA Engineer):** "这 18+ 个重复问题占总数的近一半。如果能通过工具或文档预防，就能节省约 8 小时的修复时间。"
+
+**成本分析:**
+- 每个问题平均修复时间：25 分钟
+- 18 个可预防问题 × 25 分钟 = **7.5 小时**
+- **预防优于治疗：** 配置 ESLint 规则只需 2 小时，一次性解决问题
+
+### 2. TypeScript + Playwright DOM 类型问题
+
+**Elena (Junior Dev):** "Story 1.3 的 DOM 类型问题真的让我很困惑。`page.evaluate()` 在 TypeScript 中总是报错，我花了很长时间才找到 `page.locator().allTextContents()` 这个解决方案。"
+
+**问题详情:**
+- 使用 `page.evaluate()` 获取文本内容会触发 TypeScript DOM 类型错误
+- Playwright 的类型定义与浏览器 DOM 环境不完全兼容
+
+**解决方案:**
+```typescript
+// ❌ 不推荐 - TypeScript 类型问题
+const text = await page.evaluate(el => el.textContent, element);
+
+// ✅ 推荐 - 使用 Playwright API
+const text = await element.textContent();
+// 或
+const texts = await page.locator(selector).allTextContents();
+```
+
+**Charlie (Senior Dev):** "我应该在架构文档中注明这一点，而不是让你自己去摸索。"
+
+### 3. 精确文本匹配问题
+
+**问题:** 使用 `:has-text()` 选择器会进行部分匹配，可能导致误选错误选项。
+
+**Story 1.3 发现的案例:**
+- 期望选择 "广东省"
+- 实际选择了 "广东省xx市"（因为包含 "广东省"）
+
+**解决方案:**
+```typescript
+// ❌ 部分匹配 - 可能误选
+page.locator(`.option:has-text("广东省")`)
+
+// ✅ 精确匹配 - 只匹配完全相等的文本
+page.locator(`.option:text-is("广东省")`)
+```
+
+**影响:** 如果没有在代码审查中发现，测试可能会在错误选项上通过，导致假阳性 bug。
+
+### 4. 网络空闲等待超时配置 Bug
+
+**Story 1.6 单元测试中发现:**
+
+```typescript
+// ❌ Bug - 网络空闲等待使用了默认的 networkIdle 超时
+await page.waitForLoadState('networkidle', { timeout: DEFAULT_TIMEOUTS.networkIdle });
+
+// ✅ 修复 - 使用用户自定义的 timeout
+await page.waitForLoadState('networkidle', { timeout: options.timeout ?? DEFAULT_TIMEOUTS.async });
+```
+
+**Dana (QA Engineer):** "这证明代码审查和测试是互补的。审查可以发现问题，但单元测试能在实际执行中暴露隐藏的 bug。"
+
+### 5. Epic 规划问题（Root 发现）
+
+**问题 1: Epic 顺序错误**
+
+原规划顺序:
+- Epic 1: ✅ Select 工具（已完成）
+- Epic 2: 扩展工具集（文件上传、表单等）
+- Epic 3: 在残疾人管理中验证工具包
+- Epic 4: 完善文档
+
+**Root (Project Lead):** "为什么先扩展更多工具，而不是先验证现有工具？如果我们现在构建的工具不能用，Epic 2 会浪费大量时间。"
+
+**正确顺序:**
+- Epic 1: ✅ Select 工具（已完成）
+- **Epic 2 (新):** **在现有 E2E 测试中验证 Select 工具**
+- Epic 3 (原 Epic 2): 扩展工具集
+- Epic 4 (原 Epic 3): 全面验证
+- Epic 5 (原 Epic 4): 完善文档
+
+**问题 2: 重复建设而非复用**
+
+原 Epic 3 Story 3.1 计划创建 `tests/test-app/` **独立测试应用**，而不是使用现有的 `web/tests/e2e/`。
+
+**Root (Project Lead):** "现有的 web 目录已经有 E2E 测试了。为什么要另外创建一个 test-app？直接在现有测试中使用工具包更高效。"
+
+**Alice (Product Owner):** "这个修正更符合敏捷原则——利用现有资源，而不是重复建设。"
+
+**Charlie (Senior Dev):** "而且从测试角度看，在真实的残疾人管理测试中使用 Select 工具更能发现实际问题。"
+
+---
+
+**[第二部分完 - 挑战和问题分析]**
+
+## 行动项 📋
+
+### 优先级 HIGH
+
+#### 1. 配置 ESLint 规则捕获常见问题
+
+**负责人:** Charlie
+**预计时间:** 2 小时
+
+**需要配置的规则:**
+```javascript
+// .eslintrc.js
+{
+  rules: {
+    // 捕获冗余的 null 检查
+    'no-constant-binary-expression': 'error',
+
+    // 捕获未使用的变量
+    'no-unused-vars': 'error',
+
+    // 捕获空 catch 块
+    'no-empty': ['error', { allowEmptyCatch: false }],
+
+    // 首选 const
+    'prefer-const': 'error'
+  }
+}
+```
+
+**预期收益:** 自动捕获约 50% 的重复审查问题
+
+#### 2. 更新架构文档记录 TypeScript + Playwright 陷阱
+
+**负责人:** Charlie
+**预计时间:** 1 小时
+
+**文档位置:** `_bmad-output/planning-artifacts/architecture.md`
+
+**需要添加的内容:**
+- TypeScript DOM 类型问题及解决方案
+- 精确文本匹配选择器规范
+- 常见陷阱和最佳实践
+
+#### 3. 创建新的 Epic 2
+
+**负责人:** Bob (Scrum Master)
+**预计时间:** 1 小时
+
+**Epic 2: 在现有 E2E 测试中验证 Select 工具**
+
+**包含的故事:**
+| 故事 | 内容 | 预计时间 |
+|------|------|----------|
+| 2.1 | 在 web 目录安装 `@d8d/e2e-test-utils` | 0.5h |
+| 2.2 | 使用 `selectRadixOption` 重写残疾类型选择测试 | 1h |
+| 2.3 | 使用 `selectRadixOptionAsync` 重写省份/城市选择测试 | 1.5h |
+| 2.4 | 运行测试并收集问题和改进建议 | 1h |
+| 2.5 | 修复发现的问题（如有） | 取决于发现 |
+| 2.6 | 稳定性验证（连续 10 次，100% 通过） | 0.5h |
+
+**预计总工作量:** 4-6 小时 + 修复时间
+
+#### 4. 更新 Epic 编号
+
+**负责人:** Bob (Scrum Master)
+**预计时间:** 0.5 小时
+
+**变更:**
+- 原 Epic 2 → Epic 3
+- 原 Epic 3 → Epic 4
+- 原 Epic 4 → Epic 5
+
+### 优先级 MEDIUM
+
+#### 5. 创建开发者自查清单
+
+**负责人:** Elena
+**预计时间:** 1 小时
+
+**清单内容:**
+- [ ] 所有导出函数都有完整的 JSDoc
+- [ ] 内部函数使用 `@internal` 标记
+- [ ] 错误处理使用 `E2ETestError` 而非原生 `Error`
+- [ ] 文本选择器使用 `:text-is()` 而非 `:has-text()`
+- [ ] 配置对象继承 `BaseOptions`
+- [ ] 超时值使用 `DEFAULT_TIMEOUTS` 常量
+
+#### 6. 更新代码审查检查清单
+
+**负责人:** Charlie
+**预计时间:** 0.5 小时
+
+**添加检查点:**
+- 检查是否复用现有基础设施而非创建新应用
+- 验证是否遵循"先验证再扩展"原则
+
+#### 7. 更新 Epic 规划模板
+
+**负责人:** Bob (Scrum Master)
+**预计时间:** 0.5 小时
+
+**添加指导原则:**
+- 鼓励先验证 MVP 再扩展功能
+- 优先复用现有资源而非重复建设
+- 每个功能完成后应有验证环节
+
+### 优先级 LOW
+
+#### 8. 在 Epic 2 开始前完成技术改进
+
+**前置条件:** 行动项 1-3 必须在启动新 Epic 2 之前完成
+
+---
+
+## Epic 规划修正 🔄
+
+### 修正后的 Epic 顺序
+
+| Epic | 内容 | 状态 |
+|------|------|------|
+| **Epic 1** | Select 工具基础框架 | ✅ Done |
+| **Epic 2 (新)** | **在现有 E2E 测试中验证 Select 工具** | 🆕 To Be Created |
+| **Epic 3** | 扩展工具集（文件上传、表单、列表、对话框）| ⏸️ Pending |
+| **Epic 4** | 全面验证工具包 | ⏸️ Pending |
+| **Epic 5** | 完善文档与开发者体验 | ⏸️ Pending |
+
+### 新 Epic 2 详细规划
+
+**Epic 2: 在现有 E2E 测试中验证 Select 工具**
+
+**目标:**
+- 在 `web/tests/e2e/` 的现有残疾人管理测试中使用 Select 工具
+- 验证工具在真实场景中的可用性和稳定性
+- 收集实际使用反馈，为后续工具设计提供指导
+
+**范围:**
+- ✅ 使用现有 `web/tests/e2e/` 测试基础设施
+- ✅ 使用现有的残疾人管理测试场景
+- ❌ 不创建新的 test-app
+- ❌ 不添加新功能（仅验证现有功能）
+
+**验收标准:**
+1. Select 工具在至少 2 个真实 E2E 测试场景中使用
+2. 所有测试连续运行 10 次，100% 通过率
+3. 发现的问题已记录并修复（或列入待办）
+4. 收集的使用反馈已整理
+
+---
+
+## 关键决策 🎯
+
+### 决策 1: 重新排列 Epic 顺序
+
+**原顺序:** 构建 → 扩展 → 验证
+**新顺序:** 构建 → **验证 → 扩展 → 全面验证
+
+**理由:**
+1. **更快反馈** - 不用等所有工具做完再验证
+2. **降低风险** - 如果 Select 工具有问题，只修这一个工具
+3. **更好决策** - 验证后的经验可以指导后续工具设计
+4. **更小批次** - 每个 Epic 都是可独立交付的价值
+
+### 决策 2: 使用现有基础设施
+
+**原计划:** 创建 `tests/test-app/` 独立测试应用
+**新计划:** 使用现有 `web/tests/e2e/` 测试
+
+**理由:**
+1. **更快启动** - 无需搭建新应用
+2. **更真实** - 在实际业务场景中测试
+3. **更易维护** - 只有一个测试套件
+4. **更早发现** - 直接在现有测试中发现问题
+
+### 决策 3: 技术改进先行
+
+**计划:** 在启动新 Epic 2 之前完成技术改进（ESLint 配置、文档更新）
+
+**理由:**
+1. **预防胜于治疗** - 节费 2 小时配置，节省 7.5 小时修复
+2. **一次性投资，持续受益** - 改进将惠及所有后续 Epic
+3. **建立标准** - 为团队建立清晰的编码规范
+
+---
+
+## 总结 📝
+
+**Epic 1 状态:** ✅ **Done**
+
+**关键成果:**
+- ✅ Select 工具函数完整实现
+- ✅ 93.65% 测试覆盖率
+- ✅ 37/37 单元测试通过
+- ✅ 类型检查通过
+- ✅ 所有代码审查问题已修复
+
+**关键经验:**
+1. 代码审查流程有效，但应与预防措施结合
+2. 从前一个故事学习并应用到下一个故事效果显著
+3. 在真实场景中验证比构建更多功能更优先
+4. 利用现有基础设施比重复建设更高效
+
+**下一步:**
+1. ✅ Epic 1 完成并归档
+2. 🆕 创建新 Epic 2（验证现有工具）
+3. 🔧 完成技术改进（ESLint、文档）
+4. ⏸️ 原 Epic 2-4 暂停，等待验证结果
+
+**Bob (Scrum Master):** "这是一次非常成功的回顾会议。Root 的洞察帮助我们发现了 Epic 规划中的关键问题，避免在错误的方向上投入更多时间。感谢所有人的坦诚分享。"
+
+---
+
+**[文档完]**

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

@@ -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-08
+generated: 2026-01-09
 project: 188-179-template-6
 project_key: 188-179-template-6
 tracking_system: file-system
@@ -41,36 +41,57 @@ story_location: _bmad-output/implementation-artifacts
 
 development_status:
   # Epic 1: 测试工具包基础框架与 Select 支持
-  epic-1: in-progress
+  epic-1: done
   1-1-create-package-structure: done
   1-2-implement-types-errors: done
   1-3-static-select-tool: done
   1-4-async-select-tool: done
   1-5-main-export-docs: done
   1-6-select-unit-tests: done
-  epic-1-retrospective: optional
+  epic-1-retrospective: done
 
-  # Epic 2: 扩展工具集（文件上传、表单、列表、对话框）
+  # Epic 2: 在现有 E2E 测试中验证 Select 工具 (新 Epic - 来自回顾会议)
+  # 详情参见: _bmad-output/implementation-artifacts/epic-1-retrospective.md
   epic-2: backlog
-  2-1-file-upload-tool: backlog
-  2-2-form-helper-tool: backlog
-  2-3-dynamic-list-tool: backlog
-  2-4-dialog-tool: backlog
-  2-5-update-export-fixtures: backlog
-  2-6-extended-unit-tests: backlog
+  2-1-install-e2e-utils: backlog
+  2-2-rewrite-static-select: backlog
+  2-3-rewrite-async-select: backlog
+  2-4-run-tests-collect-feedback: backlog
+  2-5-fix-found-issues: backlog
+  2-6-stability-verification: backlog
   epic-2-retrospective: optional
 
-  # Epic 3: 在残疾人管理中验证工具包
-  epic-3: backlog
-  3-1-test-app-infrastructure: backlog
-  3-2-photo-upload-test: backlog
-  3-3-bank-card-test: backlog
-  3-4-remark-visit-test: backlog
-  3-5-complete-flow-test: backlog
-  3-6-stability-test: backlog
+  # Epic 3 (原 Epic 2): 扩展工具集（文件上传、表单、列表、对话框）
+  # 状态: 暂停 - 等待 Epic 2 验证完成
+  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-retrospective: optional
 
-  # Epic 4: 完善文档与开发者体验
-  epic-4: backlog
-  4-1-improve-readme-docs: backlog
+  # 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-retrospective: optional
+
+  # Epic 5 (原 Epic 4): 完善文档与开发者体验
+  epic-5: backlog
+  5-1-improve-readme-docs: backlog
+  epic-5-retrospective: optional
+
+# 回顾会议行动项 (2026-01-09):
+# - 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

_bmad-output/planning-artifacts/architecture.md

@@ -523,6 +523,93 @@ await page.waitForTimeout(5000);
 
 ---
 
+## TypeScript + Playwright 常见陷阱
+
+> 本部分记录从 Epic 1 回顾中总结的 TypeScript + Playwright 陷阱和最佳实践。
+> 参见: _bmad-output/implementation-artifacts/epic-1-retrospective.md
+
+### 陷阱 1: DOM 类型问题
+
+**问题：** 使用 `page.evaluate()` 获取文本内容会触发 TypeScript DOM 类型错误。
+
+**原因：** Playwright 的类型定义与浏览器 DOM 环境不完全兼容，`page.evaluate()` 中的类型推断可能出现问题。
+
+**解决方案：** 使用 Playwright API 而非 `page.evaluate()`：
+
+```typescript
+// ❌ 不推荐 - TypeScript 类型问题
+const text = await page.evaluate(el => el.textContent, element);
+
+// ✅ 推荐 - 使用 Playwright API
+const text = await element.textContent();
+
+// ✅ 推荐 - 使用 locator 获取多个文本
+const texts = await page.locator(selector).allTextContents();
+```
+
+### 陷阱 2: 精确文本匹配
+
+**问题：** 使用 `:has-text()` 选择器会进行部分匹配，可能导致误选错误选项。
+
+**案例：** 期望选择 "广东省"，实际选择了 "广东省xx市"（因为包含 "广东省"）。
+
+**解决方案：** 使用 `:text-is()` 进行精确匹配：
+
+```typescript
+// ❌ 部分匹配 - 可能误选
+page.locator(`.option:has-text("广东省")`)
+
+// ✅ 精确匹配 - 只匹配完全相等的文本
+page.locator(`.option:text-is("广东省")`)
+```
+
+**影响：** 如果没有在代码审查中发现，测试可能会在错误选项上通过，导致假阳性 bug。
+
+### 陷阱 3: 网络空闲等待超时配置
+
+**问题：** 网络空闲等待使用了固定的 `networkIdle` 超时，而非用户自定义的超时值。
+
+**案例（Story 1.6 单元测试中发现）：**
+
+```typescript
+// ❌ Bug - 网络空闲等待使用了默认的 networkIdle 超时
+await page.waitForLoadState('networkidle', { timeout: DEFAULT_TIMEOUTS.networkIdle });
+
+// ✅ 修复 - 使用用户自定义的 timeout
+await page.waitForLoadState('networkidle', { timeout: options.timeout ?? DEFAULT_TIMEOUTS.async });
+```
+
+**经验：** 任何使用超时的 Playwright API 都应该尊重用户的自定义配置。
+
+### 陷阱 4: 选择器策略优先级
+
+**问题：** 直接使用文本选择器可能失败，因为 Radix UI 的 DOM 结构会随版本变化。
+
+**解决方案：** 按优先级使用选择器策略：
+
+```typescript
+const SELECTOR_STRATEGIES = [
+  findByTestId,      // 1. data-testid - 最稳定
+  findByAria,        // 2. aria-label + role - 无障碍属性
+  findByText,        // 3. text content - 兜底方案
+] as const;
+```
+
+### 实现检查清单
+
+基于 Epic 1 的经验，所有开发者应遵循以下检查清单：
+
+- [ ] 所有导出函数都有完整的 JSDoc（@param, @returns, @throws, @example）
+- [ ] 内部函数使用 `@internal` 标记
+- [ ] 错误处理使用 `E2ETestError` 而非原生 `Error`
+- [ ] 文本选择器使用 `:text-is()` 而非 `:has-text()`
+- [ ] 配置对象继承 `BaseOptions`
+- [ ] 超时值使用 `DEFAULT_TIMEOUTS` 常量
+- [ ] 避免使用 `page.evaluate()` 处理 DOM 操作
+- [ ] 网络空闲等待使用用户自定义的超时值
+
+---
+
 ## Project Structure & Boundaries
 
 ### Complete Project Directory Structure

_bmad-output/planning-artifacts/epics.md

@@ -291,11 +291,17 @@ Error: Radix Select 等待超时
 | FR 范围 | Epic | 描述 |
 |--------|------|------|
 | FR1-FR6 | Epic 1 | Radix UI Select 测试支持（静态和异步） |
-| FR7-FR24 | Epic 2 | 扩展工具集（文件上传、表单、列表、对话框） |
 | FR25-FR32 | Epic 1 | 包基础设施（package.json、类型定义、配置） |
-| FR33-FR40 | Epic 4 | 文档与开发者体验（README、示例、迁移指南） |
-| FR41-FR45 | Epic 3 | 质量与稳定性（残疾人管理验证、稳定性测试） |
-| FR46-FR50 | Epic 2 | 可扩展性设计（配置对象、版本升级兼容） |
+| FR7-FR24, FR46-FR50 | Epic 3 | 扩展工具集（文件上传、表单、列表、对话框、可扩展性） |
+| FR41-FR45 | Epic 2 & 4 | 质量与稳定性（Select 验证、全面验证、稳定性测试） |
+| FR33-FR40 | Epic 5 | 文档与开发者体验（README、示例、迁移指南） |
+
+**Epic 规划变更说明（2026-01-09）：**
+- Epic 1: ✅ 已完成（Select 工具基础框架）
+- Epic 2: 🆕 新增（在现有 E2E 测试中验证 Select 工具）
+- Epic 3: 原 Epic 2（扩展工具集）
+- Epic 4: 原 Epic 3（全面验证工具包）
+- Epic 5: 原 Epic 4（完善文档与开发者体验）
 
 ## Epic List
 
@@ -495,13 +501,171 @@ Error: Radix Select 等待超时
 
 ---
 
-## Epic 2: 扩展工具集（文件上传、表单、列表、对话框）
+## Epic 2: 在现有 E2E 测试中验证 Select 工具
+
+**目标：** 在 `web/tests/e2e/` 的现有残疾人管理测试中使用 Select 工具，验证工具在真实场景中的可用性和稳定性，收集实际使用反馈，为后续工具设计提供指导。
+
+**背景：** Epic 1 已完成 Select 工具的开发和单元测试，但尚未在真实 E2E 测试场景中验证。通过在现有测试中使用这些工具，我们可以：
+1. 验证工具在实际业务场景中的可用性
+2. 发现并修复潜在问题
+3. 收集使用体验反馈，改进 API 设计
+4. 为后续工具开发建立信心和经验
+
+**范围：**
+- ✅ 使用现有 `web/tests/e2e/` 测试基础设施
+- ✅ 使用现有的残疾人管理测试场景
+- ✅ 替换 Page Object 中现有的 Select 操作
+- ❌ 不创建新的测试应用
+- ❌ 不添加新功能（仅验证现有功能）
+
+**依赖：**
+- Epic 1: ✅ 已完成（Select 工具已开发）
+
+**验收标准：**
+1. Select 工具在至少 2 个真实 E2E 测试场景中使用
+2. 所有测试连续运行 10 次，100% 通过率
+3. 发现的问题已记录并修复（或列入待办）
+4. 收集的使用反馈已整理
+
+---
+
+### Story 2.1: 在 web 目录安装 @d8d/e2e-test-utils
+
+作为测试开发者，
+我想要在 web 目录安装 `@d8d/e2e-test-utils` 包，
+以便在 E2E 测试中使用 Select 工具。
+
+**验收标准：**
+
+**Given** Epic 1 已完成，`@d8d/e2e-test-utils` 包已构建
+**When** 在 `web/package.json` 中添加 workspace 依赖
+**Then** 可以在 `web/tests/e2e/` 中导入 Select 工具
+**And** TypeScript 类型检查通过
+**And** 运行时无依赖错误
+
+**实现要点：**
+- 使用 `pnpm add -D @d8d/e2e-test-utils@workspace:*` 安装
+- 验证 `web/tests/e2e/` 中可以导入：`import { selectRadixOption } from '@d8d/e2e-test-utils'`
+
+---
+
+### Story 2.2: 使用 selectRadixOption 重写残疾类型选择
+
+作为测试开发者，
+我想要使用 `selectRadixOption()` 替换 Page Object 中的 Select 操作，
+以便验证工具在静态 Select 场景中的可用性。
+
+**验收标准：**
+
+**Given** @d8d/e2e-test-utils 已安装
+**When** 修改 `web/tests/e2e/pages/admin/disability-person.page.ts`
+**Then** `fillBasicForm()` 中的残疾类型选择使用 `selectRadixOption()`
+**And** `fillBasicForm()` 中的残疾等级选择使用 `selectRadixOption()`
+**And** 移除原有的 `selectRadixOption()` 方法
+**And** 测试通过，功能正常
+
+**验证场景：**
+- 残疾类型：视力残疾、听力残疾、肢体残疾、言语残疾等（静态选项）
+- 残疾等级：一级、二级、三级、四级（静态选项）
+
+---
+
+### Story 2.3: 使用 selectRadixOptionAsync 重写省份/城市选择
+
+作为测试开发者，
+我想要使用 `selectRadixOptionAsync()` 处理异步加载的 Select，
+以便验证工具在异步 Select 场景中的可用性。
+
+**验收标准：**
+
+**Given** @d8d/e2e-test-utils 已安装
+**When** 修改 `web/tests/e2e/pages/admin/disability-person.page.ts`
+**Then** `fillBasicForm()` 中的省份选择使用 `selectRadixOptionAsync()`
+**And** `fillBasicForm()` 中的城市选择使用 `selectRadixOptionAsync()`
+**And** 移除 `waitForTimeout(500)` 等待城市加载的 hack
+**And** 测试通过，功能正常
+
+**验证场景：**
+- 省份选择（异步加载选项）
+- 城市选择（根据省份动态加载）
+
+**配置要点：**
+- 使用 `waitForOption: true` 等待选项加载
+- 使用合理的超时配置（5-10 秒）
+
+---
+
+### Story 2.4: 运行测试并收集问题和改进建议
+
+作为测试开发者，
+我想要运行使用新工具的测试并收集反馈，
+以便发现潜在问题并改进工具。
+
+**验收标准：**
+1. 运行 `web/tests/e2e/specs/admin/disability-person-complete.spec.ts`
+2. 记录所有问题（包括失败的测试、错误消息、使用体验）
+3. 分类问题：工具 bug vs 使用错误 vs 改进建议
+4. 整理成问题清单
+
+**关注点：**
+- 工具是否按预期工作？
+- 错误消息是否清晰？
+- API 是否简洁易用？
+- 是否有性能问题？
+
+---
+
+### Story 2.5: 修复发现的问题
+
+作为测试开发者，
+我想要修复 Story 2.4 中发现的问题，
+以便工具可以正常使用。
+
+**验收标准：**
+- 所有标记为"工具 bug"的问题已修复
+- 所有测试通过
+- 修复已记录到 story 文件
+
+**优先级：**
+- HIGH: 影响测试结果的问题（如选择失败、超时）
+- MEDIUM: 影响开发体验的问题（如错误消息不清晰）
+- LOW: 优化建议（如性能改进）
+
+---
+
+### Story 2.6: 稳定性验证
+
+作为测试开发者，
+我想要验证测试的稳定性，
+以便确保工具可以可靠地使用。
+
+**验收标准：**
+
+**Given** 所有问题已修复
+**When** 连续运行测试 10 次
+**Then** 所有测试 100% 通过
+**And** 无 flaky 失败
+**And** 平均执行时间 < 5 分钟
+
+**测试场景：**
+- `pnpm test:e2e:chromium disability-person-complete.spec.ts` 运行 10 次
+
+**成功标准：**
+- 10/10 次通过 = 100% 稳定性 ✅
+- 9/10 次通过 = 90% 稳定性，需要分析失败原因 ⚠️
+- < 9/10 次通过 = 稳定性不足，需要修复 ❌
+
+---
+
+## Epic 3: 扩展工具集（文件上传、表单、列表、对话框）
 
 **目标：** 测试开发者可以使用完整的 6 个核心工具函数，覆盖所有常见 E2E 测试场景。
 
+**说明：** 本 Epic 原 Epic 2，已在 Epic 2 完成后重新编号。
+
 ---
 
-### Story 2.1: 实现文件上传工具
+### Story 3.1: 实现文件上传工具
 
 作为测试开发者，
 我想要使用 `uploadFileToField()` 函数上传文件，
@@ -519,7 +683,7 @@ Error: Radix Select 等待超时
 
 ---
 
-### Story 2.2: 实现表单辅助工具
+### Story 3.2: 实现表单辅助工具
 
 作为测试开发者，
 我想要使用 `fillMultiStepForm()` 和 `scrollToSection()` 函数，
@@ -536,7 +700,7 @@ Error: Radix Select 等待超时
 
 ---
 
-### Story 2.3: 实现动态列表工具
+### Story 3.3: 实现动态列表工具
 
 作为测试开发者，
 我想要使用 `addDynamicListItem()` 和 `deleteDynamicListItem()` 函数，
@@ -554,7 +718,7 @@ Error: Radix Select 等待超时
 
 ---
 
-### Story 2.4: 实现对话框操作工具
+### Story 3.4: 实现对话框操作工具
 
 作为测试开发者，
 我想要使用 `handleDialog()`, `waitForDialogClosed()`, `cancelDialog()` 函数，
@@ -572,7 +736,7 @@ Error: Radix Select 等待超时
 
 ---
 
-### Story 2.5: 更新主导出和 Fixtures 示例
+### Story 3.5: 更新主导出和 Fixtures 示例
 
 作为测试开发者，
 我想要可以导入所有新增的工具函数，
@@ -590,7 +754,7 @@ Error: Radix Select 等待超时
 
 ---
 
-### Story 2.6: 扩展工具集单元测试
+### Story 3.6: 扩展工具集单元测试
 
 作为测试开发者，
 我想要所有扩展工具函数有充分的单元测试，
@@ -607,102 +771,86 @@ Error: Radix Select 等待超时
 
 ---
 
-## Epic 3: 在残疾人管理中验证工具包
+## Epic 4: 在残疾人管理中验证工具包
 
 **目标：** 工具包在真实的残疾人管理 E2E 测试中验证，证明工具函数可用且稳定，提供完整的参考示例。
 
----
+**说明：** 本 Epic 原 Epic 3，已在 Epic 2 完成后重新编号。
 
-### Story 3.1: 创建测试应用和集成测试基础设施
-
-作为测试开发者，
-我想要有一个独立的测试应用来验证工具函数，
-以便在真实环境中测试工具包的集成。
-
-**验收标准：**
-
-**Given** Epic 1-2 的工具函数已实现
-**When** 创建 `tests/test-app/` 独立测试应用
-**Then** 测试应用使用 Vite + React
-**And** 包含 Radix UI 组件页面（Select、Dialog、File Upload、Form、Dynamic List）
-**And** Playwright 配置自动启动测试应用服务器
-**And** 可以通过 `pnpm test` 运行集成测试
+**注意：** 原 Epic 3 的范围需要调整，因为 Epic 2 已涵盖 Select 工具的验证。
 
 ---
 
-### Story 3.2: 照片上传功能测试
+### Story 4.2: 照片上传功能测试（使用现有测试）
 
 作为测试开发者，
-我想要使用工具函数测试残疾人管理的照片上传功能，
-以便验证文件上传工具的可用性。
+我想要在现有的残疾人管理 E2E 测试中使用文件上传工具，
+以便验证 `uploadFileToField()` 的可用性。
 
 **验收标准：**
 
-**Given** 测试基础设施已创建
-**When** 编写照片上传 E2E 测试
-**Then** 使用 `uploadFileToField()` 上传身份证照片
-**And** 使用 `uploadFileToField()` 上传残疾证照片
+**Given** Epic 3 已完成，文件上传工具已实现
+**When** 在 `web/tests/e2e/specs/admin/disability-person-complete.spec.ts` 中使用 `uploadFileToField()`
+**Then** 上传身份证照片（正面、反面）
+**And** 上传残疾证照片
 **And** 验证文件上传成功
-**And** 测试覆盖多文件上传场景
-**And** 测试使用 fixtures 中的示例文件
+**And** 测试使用 `web/tests/e2e/fixtures/images/` 中的示例文件
 
 ---
 
-### Story 3.3: 银行卡管理功能测试
+### Story 4.3: 银行卡管理功能测试（使用现有测试）
 
 作为测试开发者，
-我想要使用工具函数测试残疾人管理的银行卡管理功能，
-以便验证动态列表和对话框工具的可用性。
+我想要在现有的残疾人管理 E2E 测试中使用动态列表和对话框工具，
+以便验证这些工具的可用性。
 
 **验收标准：**
 
-**Given** 测试基础设施已创建
-**When** 编写银行卡管理 E2E 测试
-**Then** 使用 `handleDialog()` 打开添加银行卡对话框
+**Given** Epic 3 已完成，对话框和动态列表工具已实现
+**When** 在现有测试中使用 `handleDialog()`, `addDynamicListItem()`, `deleteDynamicListItem()`
+**Then** 打开添加银行卡对话框
 **And** 填写银行卡信息（银行名称、卡号、持卡人）
-**And** 使用 `addDynamicListItem()` 添加银行卡
-**And** 使用 `deleteDynamicListItem()` 删除银行卡
+**And** 添加银行卡到列表
 **And** 验证列表状态变化
 
 ---
 
-### Story 3.4: 备注和回访功能测试
+### Story 4.4: 备注和回访功能测试（使用现有测试）
 
 作为测试开发者，
-我想要使用工具函数测试残疾人管理的备注和回访功能，
-以便验证表单和动态列表工具的综合使用。
+我想要在现有的残疾人管理 E2E 测试中使用表单辅助工具，
+以便验证表单工具的综合使用。
 
 **验收标准：**
 
-**Given** 测试基础设施已创建
-**When** 编写备注和回访 E2E 测试
-**Then** 使用 `fillMultiStepForm()` 填写备注表单
-**And** 使用 `scrollToSection()` 滚动到回访区域
-**And** 使用 `addDynamicListItem()` 添加备注
+**Given** Epic 3 已完成，表单辅助工具已实现
+**When** 在现有测试中使用 `fillMultiStepForm()`, `scrollToSection()`
+**Then** 填写备注表单
+**And** 滚动到回访区域
+**And** 添加备注到列表
 **And** 验证表单提交和列表更新
 
 ---
 
-### Story 3.5: 完整流程测试
+### Story 4.5: 完整流程验证
 
 作为测试开发者，
-我想要有一个完整的残疾人管理流程测试，
+我想要在现有的完整流程测试中使用所有工具，
 以便演示所有工具函数的综合使用。
 
 **验收标准：**
 
-**Given** 各功能测试已完成
-**When** 编写完整流程 E2E 测试
-**Then** 测试包含：基本信息填写（使用 `selectRadixOption` 选择静态和异步 Select）
-**And** 照片上传（使用 `uploadFileToField`）
-**And** 银行卡管理（使用 `handleDialog`, `addDynamicListItem`）
-**And** 备注添加（使用 `fillMultiStepForm`）
-**And** 表单提交和验证
-**And** 演示与 Page Object 模式的集成
+**Given** Epic 2-4 的所有工具已在部分测试中验证
+**When** 确保 `disability-person-complete.spec.ts` 使用所有工具
+**Then** 基本信息：使用 `selectRadixOption` 和 `selectRadixOptionAsync`
+**And** 照片上传：使用 `uploadFileToField`
+**And** 银行卡管理：使用 `handleDialog`, `addDynamicListItem`, `deleteDynamicListItem`
+**And** 备注添加：使用 `fillMultiStepForm`, `scrollToSection`, `addDynamicListItem`
+**And** 所有测试通过
 
 ---
 
-### Story 3.6: 稳定性测试
+### Story 4.6: 稳定性测试（使用现有测试）
 
 作为测试开发者，
 我想要有稳定性测试验证工具包的可靠性，
@@ -720,13 +868,15 @@ Error: Radix Select 等待超时
 
 ---
 
-## Epic 4: 完善文档与开发者体验
+## Epic 5: 完善文档与开发者体验
 
 **目标：** 测试开发者可以在 30 分钟内上手使用工具包，有完整的文档、示例和迁移指南。
 
+**说明：** 本 Epic 原 Epic 4，已在 Epic 2 完成后重新编号。
+
 ---
 
-### Story 4.1: 完善 README、API 文档和示例
+### Story 5.1: 完善 README、API 文档和示例
 
 作为测试开发者，
 我想要有完整的 README 和 API 文档，
@@ -734,7 +884,7 @@ Error: Radix Select 等待超时
 
 **验收标准：**
 
-**Given** Epic 1-3 的所有功能已实现
+**Given** Epic 1-4 的所有功能已实现
 **When** 完善 `README.md` 和 API 文档
 **Then** README 包含：项目简介、安装说明、快速入门、API 文档
 **And** 每个工具函数都有完整的使用示例

packages/e2e-test-utils/eslint.config.js

@@ -0,0 +1,99 @@
+import js from '@eslint/js';
+import typescriptEslint from '@typescript-eslint/eslint-plugin';
+import typescriptParser from '@typescript-eslint/parser';
+import globals from 'globals';
+
+/**
+ * ESLint 配置 for @d8d/e2e-test-utils
+ *
+ * 此配置捕获常见代码问题，包括：
+ * - 冗余的 null 检查
+ * - 未使用的变量
+ * - 空 catch 块
+ * - 首选 const 而非 let
+ *
+ * 参见: _bmad-output/implementation-artifacts/epic-1-retrospective.md
+ */
+/** @type {import('eslint').Linter.Config[]} */
+const config = [
+  // 基础配置
+  {
+    files: ['**/*.{js,ts}'],
+    ignores: [
+      'dist/**',
+      'node_modules/**',
+      '*.config.js',
+      '*.config.ts',
+      'coverage/**',
+    ],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      parser: typescriptParser,
+      parserOptions: {
+        project: './tsconfig.json',
+      },
+      globals: {
+        ...globals.node,
+        ...globals.es2021,
+      },
+    },
+    plugins: {
+      '@typescript-eslint': typescriptEslint,
+    },
+    rules: {
+      // 基础 ESLint 规则
+      ...js.configs.recommended.rules,
+
+      // TypeScript 规则
+      '@typescript-eslint/no-unused-vars': ['error', {
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+        caughtErrorsIgnorePattern: '^_',
+      }],
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/no-non-null-assertion': 'warn',
+
+      // 捕获冗余的 null 检查 (来自 Epic 1 回顾)
+      'no-constant-binary-expression': 'error',
+
+      // 捕获空 catch 块 (来自 Epic 1 回顾)
+      'no-empty': ['error', { allowEmptyCatch: false }],
+
+      // 首选 const (来自 Epic 1 回顾)
+      'prefer-const': 'error',
+
+      // 其他有用的规则
+      'no-console': 'off', // 测试工具可能需要 console.debug
+      'no-undef': 'off', // TypeScript 已经处理了未定义变量
+      'no-unused-vars': 'off', // 使用 TypeScript 的版本
+    },
+  },
+
+  // 测试环境配置 (Vitest)
+  {
+    files: ['tests/**/*.test.ts', 'tests/**/*.spec.ts'],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...vitestGlobals,
+      },
+    },
+  },
+];
+
+// Vitest 全局变量
+const vitestGlobals = {
+  describe: 'readonly',
+  it: 'readonly',
+  test: 'readonly',
+  expect: 'readonly',
+  beforeEach: 'readonly',
+  afterEach: 'readonly',
+  beforeAll: 'readonly',
+  afterAll: 'readonly',
+  vi: 'readonly',
+};
+
+export default config;

packages/e2e-test-utils/package.json

@@ -20,12 +20,18 @@
     "test": "vitest",
     "test:unit": "vitest run",
     "test:coverage": "vitest --coverage",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
   },
   "peerDependencies": {
     "@playwright/test": "^1.40.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@typescript-eslint/eslint-plugin": "^8.21.0",
+    "@typescript-eslint/parser": "^8.21.0",
+    "globals": "^15.14.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
     "@vitest/coverage-v8": "^3.2.4"

pnpm-lock.yaml

@@ -4415,9 +4415,21 @@ importers:
         specifier: ^1.40.0
         version: 1.55.0
     devDependencies:
+      '@eslint/js':
+        specifier: ^9.18.0
+        version: 9.38.0
+      '@typescript-eslint/eslint-plugin':
+        specifier: ^8.21.0
+        version: 8.46.2(@typescript-eslint/parser@8.46.2(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3))(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/parser':
+        specifier: ^8.21.0
+        version: 8.46.2(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3)
       '@vitest/coverage-v8':
         specifier: ^3.2.4
         version: 3.2.4(vitest@3.2.4(@types/debug@4.1.12)(@types/node@24.9.1)(happy-dom@18.0.1)(jiti@2.6.1)(jsdom@26.1.0)(lightningcss@1.30.2)(sass@1.93.2)(stylus@0.64.0)(terser@5.44.0)(tsx@4.20.6)(yaml@2.8.1))
+      globals:
+        specifier: ^15.14.0
+        version: 15.15.0
       typescript:
         specifier: ^5.8.3
         version: 5.9.3