docs(e2e-test-utils): 创建 Story 3.4 - 收集反馈并修复问题

创建了 Epic 3 的第四个 story 文档，包含：
- 运行 E2E 测试收集反馈的任务清单
- 问题分类框架（工具 bug vs 使用错误 vs 改进建议）
- 初步反馈分析：文件上传工具基本功能正常
- 发现 Select 工具问题（非本 Story 范围）
- 多文件上传和错误场景待验证

更新 sprint-status.yaml:
- Story 3.4 状态: backlog → ready-for-dev

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

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

_bmad-output/implementation-artifacts/3-4-collect-feedback-fix.md

@@ -0,0 +1,330 @@
+# Story 3.4: 收集反馈并修复问题
+
+Status: ready-for-dev
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+作为测试开发者，
+我想要运行使用文件上传工具的测试并收集反馈，
+以便发现潜在问题并改进文件上传工具。
+
+## Acceptance Criteria
+
+**Given** Story 3.1 已实现 `uploadFileToField()` 函数
+**Given** Story 3.2 已完成单元测试（覆盖率 91.66%）
+**Given** Story 3.3 已在真实 E2E 测试中验证文件上传工具（场景 1 通过）
+
+**When** 运行完整的 E2E 测试套件
+
+**Then** 验收标准如下：
+
+1. **记录所有问题（失败的测试、错误消息、使用体验）**
+   - 从测试运行中收集问题列表
+   - 记录每个问题的详细错误信息
+   - 分析问题的根本原因
+
+2. **分类问题：工具 bug vs 使用错误 vs 改进建议**
+   - **工具 bug**：文件上传工具本身的缺陷
+   - **使用错误**：测试代码使用不当导致的问题
+   - **改进建议**：可以提升开发体验的优化项
+
+3. **所有标记为"工具 bug"的问题已修复**
+   - 修复文件上传工具的缺陷
+   - 验证修复后测试通过
+   - 更新相关文档
+
+4. **测试连续运行 5 次通过**
+   - 验证修复后测试稳定性
+   - 无 flaky 失败
+   - 记录测试通过率
+
+## Tasks / Subtasks
+
+- [ ] **Task 1: 运行完整 E2E 测试并收集问题** (AC: #1)
+  - [ ] Subtask 1.1: 运行 `file-upload-validation.spec.ts` 完整测试
+  - [ ] Subtask 1.2: 检查 `test-results/` 目录中的错误报告
+  - [ ] Subtask 1.3: 记录所有测试失败和错误信息
+
+- [ ] **Task 2: 分析并分类问题** (AC: #2)
+  - [ ] Subtask 2.1: 区分文件上传工具问题 vs 其他问题
+  - [ ] Subtask 2.2: 标记工具 bug（需修复）
+  - [ ] Subtask 2.3: 记录使用错误和改进建议
+
+- [ ] **Task 3: 修复文件上传工具的 bug** (AC: #3)
+  - [ ] Subtask 3.1: 修复已识别的工具 bug
+  - [ ] Subtask 3.2: 运行单元测试验证修复
+  - [ ] Subtask 3.3: 运行 E2E 测试验证修复
+
+- [ ] **Task 4: 稳定性验证** (AC: #4)
+  - [ ] Subtask 4.1: 连续运行测试 5 次
+  - [ ] Subtask 4.2: 记录通过率和稳定性指标
+  - [ ] Subtask 4.3: 如有失败，分析并修复
+
+- [ ] **Task 5: 编写测试报告** (AC: #1, #4)
+  - [ ] Subtask 5.1: 记录发现的问题和修复
+  - [ ] Subtask 5.2: 更新 Story 3.1-3.3 的经验教训
+  - [ ] Subtask 5.3: 为 Story 3.5 提供稳定性验证基础
+
+## Dev Notes
+
+### Epic 3 背景与目标
+
+**Epic 3: 文件上传工具开发与验证**
+
+遵循 Epic 2 的成功模式，开发文件上传工具并在真实 E2E 测试中验证，解决当前测试超时阻塞问题。
+
+**模式：** 工具开发 → 真实 E2E 测试验证 → 问题修复 → 稳定性验证
+
+**当前进度：**
+- Story 3.1: ✅ 已完成 - `uploadFileToField()` 函数已实现（含 UI 组件 testId 支持）
+- Story 3.2: ✅ 已完成 - 单元测试（覆盖率 91.66%）
+- Story 3.3: ✅ 已完成 - 在真实 E2E 测试中验证（场景 1 通过）
+- Story 3.4: 🔄 本 Story - 收集反馈并修复问题
+
+### 从测试运行中收集的初步反馈
+
+**测试执行情况（2026-01-10）：**
+
+运行 `file-upload-validation.spec.ts` 时发现：
+
+#### 已知问题（非文件上传工具问题）
+
+1. **Select 工具问题（Epic 1）**
+   - 问题：Select 工具在处理带 `*` 号的标签（如 "性别 *"、"残疾类型 *"）时出现超时
+   - 影响：E2E 测试在填写基本信息阶段失败，未到达文件上传步骤
+   - 分类：**非本 Story 问题** - 属于 Epic 1/Epic 2 的遗留问题
+   - 建议：在 Epic 2 回顾中记录此问题，作为独立修复项
+
+#### 文件上传工具状态
+
+2. **文件上传工具（Story 3.1-3.3）**
+   - Story 3.3 场景 1 "应该成功上传单张照片"：**PASS** (33.8s)
+   - 文件路径解析正确
+   - testId 架构工作正常
+   - FileSelector Dialog 集成成功
+   - fixturesDir 参数配置正确
+
+### 需要进一步验证的场景
+
+由于 E2E 测试在 Select 步骤失败，以下场景需要手动或修复 Select 后验证：
+
+1. **场景 2：多文件上传验证**
+   - 需要验证连续上传多张照片
+   - 需要验证不同的 testId 选择
+
+2. **场景 3：完整表单提交验证**
+   - 需要验证文件上传后的表单提交
+   - 需要验证数据保存正确
+
+3. **场景 4：错误处理验证**
+   - 文件不存在错误处理
+   - 选择器无效错误处理
+
+4. **场景 5：不同文件类型验证**
+   - JPG、PNG、WEBP 等格式支持
+
+### 问题分类框架
+
+| 问题类型 | 定义 | 处理方式 |
+|---------|------|---------|
+| **工具 bug** | `uploadFileToField()` 函数本身的缺陷 | 本 Story 必须修复 |
+| **使用错误** | 测试代码使用不当导致的问题 | 修改测试代码或文档 |
+| **改进建议** | 可提升开发体验的优化项 | 记录到待办或下个 Epic |
+| **依赖问题** | 其他组件（如 Select）的问题 | 转交相关 Epic 处理 |
+
+### 技术分析
+
+#### uploadFileToField() 函数分析
+
+**已验证的功能（Story 3.1-3.3）：**
+- ✅ fixtures 路径解析正确
+- ✅ 文件存在性检查正常
+- ✅ setInputFiles() API 调用正确
+- ✅ 错误处理机制完整
+- ✅ testId 选择器支持工作正常
+- ✅ FileSelector Dialog 集成成功
+
+**可能需要改进的地方（待验证）：**
+1. **多文件连续上传稳定性**
+   - 当前仅在 Story 3.3 场景 1 中验证了单文件上传
+   - 需要验证连续上传多张照片的稳定性
+
+2. **错误场景完整性**
+   - 文件不存在错误已在单元测试中覆盖
+   - 选择器无效错误需要在真实 E2E 环境中验证
+
+3. **性能和超时配置**
+   - 默认超时 5000ms 是否足够
+   - 是否需要针对大文件优化
+
+### 测试验证计划
+
+#### 阶段 1：隔离测试文件上传功能
+
+由于 Select 工具问题阻碍完整测试，建议：
+
+**方案 A：创建简化的上传测试**
+- 跳过表单填写，直接导航到照片上传区域
+- 专注验证文件上传功能
+
+**方案 B：手动测试**
+- 在浏览器中手动测试文件上传流程
+- 记录工具的实际表现
+
+#### 阶段 2：修复后验证
+
+1. 运行完整 E2E 测试套件
+2. 连续运行 5 次验证稳定性
+3. 记录通过率和失败原因
+
+### Epic 2 经验应用
+
+**Epic 2 的关键发现（必须应用）：**
+
+1. **DOM 结构假设必须验证**
+   - 单元测试无法发现真实 DOM 问题
+   - 必须在真实 E2E 环境中验证
+
+2. **真实 E2E 测试不可替代**
+   - Story 3.2 单元测试覆盖率 91.66%
+   - 仍然需要 Story 3.3 的 E2E 集成测试
+
+3. **问题分类的重要性**
+   - 区分工具 bug vs 使用错误
+   - 避免在错误的修复方向浪费时间
+
+### 项目结构说明
+
+**相关文件：**
+```
+packages/e2e-test-utils/
+├── src/
+│   └── file-upload.ts         # 文件上传工具（可能需要修复）
+├── tests/
+│   └── unit/
+│       └── file-upload.test.ts  # 单元测试（验证修复）
+
+web/tests/e2e/
+├── specs/admin/
+│   └── file-upload-validation.spec.ts  # E2E 测试（运行收集反馈）
+├── fixtures/images/
+│   ├── sample-id-card.jpg
+│   └── sample-disability-card.jpg
+└── pages/admin/
+    └── disability-person.page.ts      # Page Object（可能需要修改）
+```
+
+### 运行测试命令
+
+**运行 E2E 测试收集反馈：**
+```bash
+# 完整测试（如果 Select 问题已修复）
+cd web && pnpm test:e2e:chromium file-upload-validation
+
+# 快速失败模式（调试）
+timeout 60 pnpm test:e2e:chromium file-upload-validation
+```
+
+**运行单元测试验证修复：**
+```bash
+cd packages/e2e-test-utils
+pnpm test --testNamePattern "file-upload"
+```
+
+### 参考文档
+
+**架构文档：**
+- `_bmad-output/planning-artifacts/architecture.md` - 错误处理策略、测试标准
+
+**E2E 测试标准：**
+- `docs/standards/e2e-radix-testing.md` - 文件上传测试标准
+
+**Epic 3 完整需求：**
+- `_bmad-output/planning-artifacts/epics.md` - Epic 3 和 Story 3.4 详细需求
+
+**前置 Story 文件：**
+- `_bmad-output/implementation-artifacts/3-1-file-upload-tool.md` - 工具实现
+- `_bmad-output/implementation-artifacts/3-2-upload-unit-tests.md` - 单元测试
+- `_bmad-output/implementation-artifacts/3-3-upload-e2e-integration.md` - E2E 集成测试
+
+**Epic 2 回顾（关键经验）：**
+- `_bmad-output/implementation-artifacts/epic-2-retrospective.md` - 问题分类和修复经验
+
+### Project Structure Notes
+
+**Monorepo 结构对齐：**
+- E2E 测试在 `web/tests/e2e/` 目录
+- 使用 `@d8d/e2e-test-utils` workspace 包
+- 测试 fixtures 位于 `web/tests/fixtures/`
+
+**文件组织：**
+- 测试文件按功能组织在 `specs/admin/` 目录
+- 使用 `.spec.ts` 后缀命名（Playwright 约定）
+- Page Objects 位于 `pages/admin/` 目录
+
+### References
+
+**源文档引用：**
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-3-Story-3.4]
+- [Source: _bmad-output/implementation-artifacts/3-1-file-upload-tool.md] - 工具实现
+- [Source: _bmad-output/implementation-artifacts/3-3-upload-e2e-integration.md] - E2E 集成测试
+
+**Epic 2 经验教训：**
+- [Source: _bmad-output/implementation-artifacts/epic-2-retrospective.md] - 问题分类和修复方法
+
+## Dev Agent Record
+
+### Agent Model Used
+
+Claude Opus 4 (claude-opus-4-5-20251101)
+
+### Debug Log References
+
+### Completion Notes List
+
+_本 Story 创建完成，待开发执行：_
+
+#### 初步反馈收集结果
+
+**测试执行情况（2026-01-10）：**
+1. 运行了 `file-upload-validation.spec.ts`
+2. 发现测试在 Select 步骤失败（非文件上传工具问题）
+3. 文件上传工具在 Story 3.3 场景 1 中已验证通过
+
+#### 已发现的问题分类
+
+| 问题 | 类型 | 状态 |
+|-----|------|------|
+| Select 工具处理带 `*` 标签超时 | 依赖问题（Epic 1） | 转交相关 Epic |
+| 多文件上传稳定性 | 待验证 | 需本 Story 验证 |
+| 错误场景完整性 | 待验证 | 需本 Story 验证 |
+
+#### 下一步行动
+
+1. **优先级 HIGH**：验证多文件上传功能
+   - 由于测试受阻于 Select 问题，可能需要创建简化测试
+   - 或手动验证多文件上传场景
+
+2. **优先级 MEDIUM**：错误场景 E2E 验证
+   - 文件不存在
+   - 选择器无效
+
+3. **优先级 LOW**：性能和优化
+   - 超时配置是否合理
+   - 大文件上传性能
+
+### File List
+
+_本 Story 创建的文件：_
+- `_bmad-output/implementation-artifacts/3-4-collect-feedback-fix.md` - 本 Story 文件
+
+_相关文件（待修改）：_
+- `packages/e2e-test-utils/src/file-upload.ts` - 可能需要修复
+- `web/tests/e2e/specs/admin/file-upload-validation.spec.ts` - E2E 测试
+
+---
+
+**Story 创建日期:** 2026-01-10
+**Story 状态:** ready-for-dev

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

@@ -67,7 +67,7 @@ development_status:
   3-1-file-upload-tool: done             # 开发文件上传工具函数（含 UI 组件架构改进）
   3-2-upload-unit-tests: done             # 编写文件上传工具的单元测试
   3-3-upload-e2e-integration: done       # 在 web/tests/e2e 中验证文件上传工具
-  3-4-collect-feedback-fix: backlog      # 收集反馈并修复问题
+  3-4-collect-feedback-fix: ready-for-dev # 收集反馈并修复问题
   3-5-upload-stability-test: backlog     # 文件上传稳定性验证 (10次连续运行)
   epic-3-retrospective: optional