Story 3.4: 收集反馈并修复问题

Status: ready-for-dev

Story

作为测试开发者，我想要运行使用文件上传工具的测试并收集反馈，以便发现潜在问题并改进文件上传工具。

Acceptance Criteria

Given Story 3.1 已实现 uploadFileToField() 函数 Given Story 3.2 已完成单元测试（覆盖率 91.66%） Given Story 3.3 已在真实 E2E 测试中验证文件上传工具（场景 1 通过）

When 运行完整的 E2E 测试套件

Then 验收标准如下：

记录所有问题（失败的测试、错误消息、使用体验）
- 从测试运行中收集问题列表
- 记录每个问题的详细错误信息
- 分析问题的根本原因
分类问题：工具 bug vs 使用错误 vs 改进建议
- 工具 bug：文件上传工具本身的缺陷
- 使用错误：测试代码使用不当导致的问题
- 改进建议：可以提升开发体验的优化项
所有标记为"工具 bug"的问题已修复
- 修复文件上传工具的缺陷
- 验证修复后测试通过
- 更新相关文档
测试连续运行 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 时发现：

已知问题（非文件上传工具问题）

Select 工具问题（Epic 1）
- 问题：Select 工具在处理带 * 号的标签（如 "性别 *"、"残疾类型 *"）时出现超时
- 影响：E2E 测试在填写基本信息阶段失败，未到达文件上传步骤
- 分类：非本 Story 问题 - 属于 Epic 1/Epic 2 的遗留问题
- 建议：在 Epic 2 回顾中记录此问题，作为独立修复项

文件上传工具状态

文件上传工具（Story 3.1-3.3）
- Story 3.3 场景 1 "应该成功上传单张照片"：PASS (33.8s)
- 文件路径解析正确
- testId 架构工作正常
- FileSelector Dialog 集成成功
- fixturesDir 参数配置正确

需要进一步验证的场景

由于 E2E 测试在 Select 步骤失败，以下场景需要手动或修复 Select 后验证：

场景 2：多文件上传验证
- 需要验证连续上传多张照片
- 需要验证不同的 testId 选择
场景 3：完整表单提交验证
- 需要验证文件上传后的表单提交
- 需要验证数据保存正确
场景 4：错误处理验证
- 文件不存在错误处理
- 选择器无效错误处理
场景 5：不同文件类型验证
- JPG、PNG、WEBP 等格式支持

问题分类框架

问题类型	定义	处理方式
工具 bug	`uploadFileToField()` 函数本身的缺陷	本 Story 必须修复
使用错误	测试代码使用不当导致的问题	修改测试代码或文档
改进建议	可提升开发体验的优化项	记录到待办或下个 Epic
依赖问题	其他组件（如 Select）的问题	转交相关 Epic 处理

技术分析

uploadFileToField() 函数分析

已验证的功能（Story 3.1-3.3）：

✅ fixtures 路径解析正确
✅ 文件存在性检查正常
✅ setInputFiles() API 调用正确
✅ 错误处理机制完整
✅ testId 选择器支持工作正常
✅ FileSelector Dialog 集成成功

可能需要改进的地方（待验证）：

多文件连续上传稳定性
- 当前仅在 Story 3.3 场景 1 中验证了单文件上传
- 需要验证连续上传多张照片的稳定性
错误场景完整性
- 文件不存在错误已在单元测试中覆盖
- 选择器无效错误需要在真实 E2E 环境中验证
性能和超时配置
- 默认超时 5000ms 是否足够
- 是否需要针对大文件优化

测试验证计划

阶段 1：隔离测试文件上传功能

由于 Select 工具问题阻碍完整测试，建议：

方案 A：创建简化的上传测试

跳过表单填写，直接导航到照片上传区域
专注验证文件上传功能

方案 B：手动测试

在浏览器中手动测试文件上传流程
记录工具的实际表现

阶段 2：修复后验证

运行完整 E2E 测试套件
连续运行 5 次验证稳定性
记录通过率和失败原因

Epic 2 经验应用

Epic 2 的关键发现（必须应用）：

DOM 结构假设必须验证
- 单元测试无法发现真实 DOM 问题
- 必须在真实 E2E 环境中验证
真实 E2E 测试不可替代
- Story 3.2 单元测试覆盖率 91.66%
- 仍然需要 Story 3.3 的 E2E 集成测试
问题分类的重要性
- 区分工具 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 测试收集反馈：

# 完整测试（如果 Select 问题已修复）
cd web && pnpm test:e2e:chromium file-upload-validation

# 快速失败模式（调试）
timeout 60 pnpm test:e2e:chromium file-upload-validation

运行单元测试验证修复：

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 创建完成，待开发执行：

初步反馈收集结果