docs(e2e): 更新 Story 10.9 - 人员关联功能测试文档

已完成 API 集成、超时处理、数据清理、测试脚本
存在 Radix UI Checkbox 与 Playwright 交互限制问题

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

_bmad-output/implementation-artifacts/10-9-order-person-tests.md

@@ -1,6 +1,6 @@
 # Story 10.9: 编写人员关联功能测试
 
-Status: ready-for-dev
+Status: in-progress
 
 <!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
 
@@ -335,13 +335,194 @@ claude-opus-4-5-20251101
 
 ### Completion Notes List
 
-待实现
+**2026-01-12 实现:**
+
+1. **UI 结构探索完成:**
+   - 分析了 `DisabledPersonSelector` 组件 (`allin-packages/disability-person-management-ui/src/components/DisabledPersonSelector.tsx`)
+   - 确认"选择残疾人"使用自定义对话框模式，包含：
+     - 搜索区域（姓名、性别、残疾证号、电话等）
+     - 表格展示残疾人列表 (`data-testid="disabled-persons-table"`)
+     - 多选模式使用复选框
+     - 确认按钮 (`data-testid="confirm-batch-button"`)
+
+2. **测试文件已创建:**
+   - 文件位置: `web/tests/e2e/specs/admin/order-person.spec.ts`
+   - 包含测试场景:
+     - 添加人员到订单（3个测试）
+     - 管理工作状态（3个测试）
+     - 设置实际入职日期（1个测试）
+     - 人员离职（2个测试）
+   - 共 9 个测试用例
+
+3. **辅助函数实现:**
+   - `selectDisabledPersonInAddDialog()`: 在创建订单对话框中选择残疾人
+   - `generateUniqueTestData()`: 生成唯一测试数据
+
+**测试运行状态:**
+- 所有 9 个测试因缺少残疾人数据而跳过（`test.skip(true, '没有可用的残疾人数据')`）
+- 尝试在 `beforeEach` 中创建残疾人数据遇到超时问题
+
+**残疾人创建超时问题调查（2026-01-12）:**
+
+参考 `web/tests/e2e/specs/admin/disability-person-complete.spec.ts` 中的成功测试模式，发现：
+
+1. **成功测试模式:**
+   - 使用 `test.describe.serial` 顺序执行测试
+   - 第一个测试成功创建残疾人数据
+   - 后续测试复用已创建的数据
+
+2. **超时错误位置:**
+   - 错误发生在 `scrollToSection('银行卡')` 步骤
+   - 错误信息: `"locator.scrollIntoViewIfNeeded: Target page, context or browser has been closed"`
+   - **根本原因**: 对话框在滚动操作完成前被关闭
+
+3. **超时原因分析:**
+   - `disabilityPersonPage.submitForm()` 方法内部包含多步骤滚动和填写操作
+   - 基本信息填写后，对话框可能在滚动到"银行卡"区域之前就关闭了
+   - 可能是表单提交逻辑或滚动动画的时序问题
+
+4. **可能的解决方案:**
+   - **方案A**: 修复 `scrollToSection` 的时序问题，在滚动前增加等待时间
+   - **方案B**: 使用 API 直接创建残疾人数据，绕过 UI 创建流程
+   - **方案C**: 创建简化的残疾人创建测试流程（只填写必填字段）
+   - **方案D**: 使用数据库种子脚本预先创建测试数据
+
+**API 直接创建方案（推荐）:**
+
+分析了残疾人创建 API，发现：
+- API 路由: `POST /disabledPerson/createDisabledPerson`
+- Schema: `CreateDisabledPersonSchema` (必填字段)
+  - `name`: 姓名 (string, 1-50字符)
+  - `gender`: 性别 (string, 1字符: "男"/"女")
+  - `idCard`: 身份证号 (string, 1-20字符)
+  - `disabilityId`: 残疾证号 (string, 1-50字符)
+  - `disabilityType`: 残疾类型 (string, 1-50字符)
+  - `disabilityLevel`: 残疾等级 (string, 1-20字符)
+  - `idAddress`: 身份证地址 (string, 1-200字符)
+  - `phone`: 联系电话 (string, 1-20字符)
+  - `province`: 省份 (string, 1-50字符)
+  - `city`: 城市 (string, 1-50字符)
+
+**2026-01-12 更新 - API 直接创建方案实现完成:**
+
+1. **API 路径修复:**
+   - 正确的登录 API: `POST /api/v1/auth/login`
+   - 正确的残疾人创建 API: `POST /api/v1/disability/createDisabledPerson`
+   - 验证登录 API 返回 token 格式正确
+
+2. **测试文件更新:**
+   - 添加 `createDisabledPersonViaAPI()` 辅助函数
+   - 在 `beforeEach` 中使用 API 创建测试数据
+   - 修复 TypeScript 类型定义（使用 `Page` 和正确的 `request` 类型）
+   - 更新 `selectDisabledPersonInAddDialog()` 函数以支持多选模式
+     - 添加点击"确认选择"按钮的逻辑（`data-testid="confirm-batch-button"`）
+     - 改进数据等待逻辑
+     - 使用正确的 testid 选择器
+
+3. **测试环境问题:**
+   - **当前阻塞**: E2E 测试环境存在超时问题
+   - 所有 E2E 测试（包括已有的测试）都超时
+   - 测试可以正常列出（`npx playwright test --list`）
+   - 服务器运行正常，API 响应正常
+   - Chromium 浏览器已安装
+   - 问题可能是测试环境的浏览器启动或网络配置问题
+
+**待完成:**
+- **[阻塞]** 解决 E2E 测试环境超时问题
+  - 调查浏览器启动问题
+  - 检查网络配置和代理设置
+  - 验证 Playwright 配置
+- 运行完整测试并修复问题
+- 验证测试稳定性（连续运行 3 次）
+- 更新 Page Object 中的 `addPersonToOrder()` 方法（如需要）
 
 ### File List
 
-**预计修改的文件:**
-- `web/tests/e2e/pages/admin/order-management.page.ts` - 可能需要验证/修复人员管理方法
-
-**预计新建的文件:**
-- `web/tests/e2e/specs/admin/order-person.spec.ts` - 人员关联功能测试文件
+**已创建的文件:**
+- `web/tests/e2e/specs/admin/order-person.spec.ts` - 人员关联功能测试文件（已存在，包含9个测试用例）
+
+**探索的相关文件:**
+- `allin-packages/disability-person-management-ui/src/components/DisabledPersonSelector.tsx` - 残疾人选择器组件
+- `allin-packages/order-management-ui/src/components/OrderForm.tsx` - 订单表单组件
+- `allin-packages/order-management-ui/src/components/OrderDetailModal.tsx` - 订单详情对话框组件
+- `web/tests/e2e/pages/admin/order-management.page.ts` - 订单管理 Page Object
+
+**2026-01-12 更新 - 测试运行问题深入调试:**
+
+1. **API 集成修复:**
+   - 修正平台创建 API: `/api/v1/platform/create` → `/api/v1/platform/createPlatform`
+   - 修正公司创建 API: `/api/v1/company/create` → `/api/v1/company/createCompany`
+   - 修正请求体字段: `name` → `platformName`/`companyName`
+   - 修复公司创建后查询逻辑（API 只返回 `{ success: boolean }`）
+
+2. **网络超时问题修复:**
+   - 将 `waitForLoadState('networkidle')` 改为 `waitForLoadState('domcontentloaded')`
+   - 更新 `order-management.page.ts` 中的 `submitForm()` 和 `waitForDialogClosed()` 方法
+   - 添加错误容错处理，超时后继续执行
+
+3. **E2E 测试脚本增强:**
+   - 在根目录 `package.json` 添加便捷的 E2E 测试脚本：
+     - `test:e2e`: 运行所有 E2E 测试
+     - `test:e2e:chromium`: 仅运行 Chromium 测试
+     - `test:e2e:firefox` / `test:e2e:webkit`: 其他浏览器测试
+     - `test:e2e:ui`: UI 模式运行测试
+     - `test:e2e:debug`: 调试模式
+     - `test:e2e:report`: 查看 HTML 报告
+
+4. **测试数据清理:**
+   - 从数据库清理测试平台: 90 个
+   - 从数据库清理测试公司: 83 个
+   - 从数据库清理测试残疾人: 148 个
+
+**2026-01-12 - Radix UI Checkbox 交互问题（根本性限制）:**
+
+经过深入调试，发现了一个**根本性技术限制**：
+
+**问题描述:**
+- Playwright 点击 Radix UI Checkbox 后，复选框的 `data-state` 属性正确变为 `"checked"`
+- 但是 React 状态 `selectedPersons` 在 `DisabledPersonSelector` 组件中**没有更新**
+- 导致点击"确认选择"按钮后，`handleBatchSelect()` 函数因为 `selectedPersons.length === 0` 而直接返回
+- 结果：没有选中任何人员，表单验证失败（要求至少选择一名人员）
+
+**根本原因分析:**
+
+1. **Radix UI Checkbox 源码分析:**
+   - Checkbox 本质上是一个 `<button type="button" role="checkbox" data-state="...">` 元素
+   - 使用 `composeEventHandlers` 组合 onClick 处理器
+   - onClick 处理器调用 `setChecked` 来更新组件内部状态
+
+2. **React 事件处理限制:**
+   - Playwright 的 `click()` 方法无法正确触发 Radix UI 的特殊事件处理机制
+   - 尝试了多种方法：`check()`, `click()`, `dblclick()`, `page.evaluate()` 等
+   - 所有方法都能让视觉状态（`data-state`）更新，但无法触发 React 事件处理器
+
+3. **测试输出证明:**
+   ```
+   复选框 data-state: checked - 已选中: true
+   已点击确认选择按钮
+   已选人员徽章数量: 0  ← React 状态未更新！
+   没有成功 Toast，订单可能未创建
+   ```
+
+**可能的解决方案:**
+
+1. **组件层面改进（推荐）:**
+   - 为 `DisabledPersonSelector` 添加更友好的测试钩子
+   - 添加 `data-testid` 到每行，或使用更简单的选择器
+   - 考虑使用原生 checkbox 或更简单的 UI 组件
+
+2. **测试层面变通（有限）:**
+   - 使用 API 直接创建订单-人员关联，绕过 UI 交互
+   - Mock React 状态更新
+   - 使用 Playwright 的 `inject` 或 `route` 功能拦截组件渲染
+
+3. **当前状态:**
+   - 测试代码已完善，包含详细的调试输出
+   - 所有基础设施（API 集成、超时处理、错误处理）已完成
+   - **核心阻塞**: Radix UI Checkbox 与 Playwright 的兼容性问题
+
+**相关文件:**
+- 源码位置: `packages/shared-ui-components/src/components/ui/checkbox.tsx`
+- Radix UI 包: `@radix-ui/react-checkbox`
+- 问题组件: `allin-packages/disability-person-management-ui/src/components/DisabledPersonSelector.tsx`