✨ feat(form-helper): 创建表单辅助工具开发文档

- 新增 Story 4.1 开发文档，定义 `fillMultiStepForm` 和 `scrollToSection` 函数需求
- 包含完整的验收标准、任务分解和开发注意事项
- 集成 Epic 2-3 的成功经验，强调“先验证再扩展”策略
- 提供详细的类型定义、函数签名和测试场景设计

_bmad-output/implementation-artifacts/4-1-form-helper-tool.md

@@ -0,0 +1,126 @@
+# Story 4.1: 开发表单辅助工具函数
+
+Status: ready-for-dev
+
+## Story
+
+作为测试开发者，
+我想要使用 `fillMultiStepForm()` 和 `scrollToSection()` 函数，
+以便测试多步骤表单和滚动操作。
+
+## Acceptance Criteria
+
+1. **fillMultiStepForm 函数实现** - 函数签名：`fillMultiStepForm(page, steps): Promise<void>`，支持分步填写表单
+2. **scrollToSection 函数实现** - 滚动到特定区域，等待目标区域可见
+3. **类型定义完整** - FormStep 接口、FieldTypes 类型、FormHelperOptions 配置
+4. **错误处理** - 使用 E2ETestError 和 ErrorContext
+5. **JSDoc 完整** - 包含 @param、@throws、@example
+
+
+## Tasks / Subtasks
+
+- [ ] **Task 1: 实现 fillMultiStepForm 函数** (AC: #1)
+  - [ ] Subtask 1.1: 定义 FormStep 接口和 FieldTypes 类型
+  - [ ] Subtask 1.2: 实现步骤遍历和字段填充逻辑
+  - [ ] Subtask 1.3: 支持文本字段、选择器、日期字段
+  - [ ] Subtask 1.4: 集成现有工具（selectRadixOption、uploadFileToField）
+
+- [ ] **Task 2: 实现 scrollToSection 函数** (AC: #2)
+  - [ ] Subtask 2.1: 通过 sectionName 定位区域
+  - [ ] Subtask 2.2: 使用 scrollIntoViewIfNeeded() 滚动
+  - [ ] Subtask 2.3: 等待目标区域可见
+
+- [ ] **Task 3: 定义类型和配置** (AC: #3)
+- [ ] **Task 4: 实现错误处理** (AC: #4)
+- [ ] **Task 5: 添加 JSDoc 文档** (AC: #5)
+- [ ] **Task 6: 更新主导出文件
+
+## Dev Notes
+
+### Epic 4 背景与目标
+
+**Epic 4: 表单工具开发与验证**
+
+遵循 Epic 2 和 Epic 3 的成功模式：工具开发 → 真实 E2E 测试验证 → 稳定性验证
+
+**当前进度：**
+- Epic 1: ✅ 已完成（类型定义、错误处理、Select 工具）
+- Epic 2: ✅ 已完成（Select 工具 E2E 验证）
+- Epic 3: ✅ 已完成（文件上传工具 + 稳定性验证）
+- Epic 4: 🔄 本 Epic - 表单工具开发与验证
+
+### Epic 2-3 成功模式经验
+
+1. **"先验证再扩展"策略** - Epic 2/3 都遵循此模式并成功
+2. **DOM 结构假设必须验证** - 单元测试无法发现真实 DOM 问题
+3. **稳定性验证标准** - Epic 3 证明 6 次连续运行足够
+
+### 架构文档参考
+
+**核心函数签名：**
+fillMultiStepForm(page: Page, steps: FormStep[]): Promise<void>
+scrollToSection(page: Page, sectionName: string): Promise<void>
+
+**类型定义设计：**
+export interface FormStep { name: string; fields: FormField[]; }
+export interface FormField { selector: string; type: FieldType; value: string | string[]; }
+export type FieldType = "text" | "select" | "select-async" | "date" | "file" | "checkbox" | "radio";
+export interface FormHelperOptions extends BaseOptions { stepDelay?: number; clearBeforeFill?: boolean; }
+
+
+### 与现有工具的集成
+
+复用已实现的工具：
+- selectRadixOption / selectRadixOptionAsync - Select 工具
+- uploadFileToField - 文件上传
+- selectCascade - 级联选择（Epic 3 创建）
+
+### 测试场景设计
+
+**残疾人管理表单场景：**
+await fillMultiStepForm(page, [{ name: "基本信息", fields: [{ selector: "name", type: "text", value: "测试用户" }] }]);
+await scrollToSection(page, "照片");
+
+### Epic 2-3 常见陷阱避免
+
+1. DOM 结构假设必须验证 - 使用真实 E2E 测试
+2. 避免硬编码超时 - 使用 Playwright auto-waiting
+3. 精确文本匹配 - 使用 :text-is() 或 { exact: true }
+
+### 参考文档
+
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-4-Story-4.1]
+- [Source: _bmad-output/planning-artifacts/architecture.md]
+- [Source: _bmad-output/implementation-artifacts/epic-2-retrospective.md]
+- [Source: _bmad-output/implementation-artifacts/epic-3-retrospective.md]
+
+## Dev Agent Record
+
+### Agent Model Used
+
+claude-opus-4-5-20251101
+
+### Completion Notes List
+
+**创建日期:** 2026-01-11
+
+**Story 分析完成:**
+- ✅ 加载并分析了 Epic 4 完整需求
+- ✅ 分析了 Epic 2-3 成功模式经验
+- ✅ 提取了架构文档中的设计要求
+- ✅ 定义了类型和函数签名
+- ✅ 提供了实现示例和错误处理模式
+
+**可以进入开发阶段 (Story 4.1 → ready-for-dev)**
+
+### File List
+
+**待创建文件:**
+1. packages/e2e-test-utils/src/form-helper.ts - 表单辅助工具实现
+2. packages/e2e-test-utils/tests/unit/form-helper.test.ts - 单元测试（Story 4.2）
+3. packages/e2e-test-utils/src/index.ts - 更新主导出
+
+---
+
+**Story 状态:** ✅ ready-for-dev
+**准备日期:** 2026-01-11