mini-starter/docs/prd/epic-009-system-test-optimization.md

Epic 009: 系统测试需求优化

概述

本史诗旨在优化系统测试过程中的用户体验和功能完整性，针对平台管理、薪资管理、残疾人个人管理、订单管理和公司管理等多个模块进行改进，以提升测试效率和系统可用性。

业务目标

1. 简化测试流程，减少不必要的必填项
2. 修复已知的功能缺陷
3. 优化用户界面和交互体验
4. 确保各模块功能可正常测试

范围

• 平台管理模块的区域选择优化
• 平台管理模块的邮箱输入优化
• 残疾人个人管理模块的多项优化
• 订单管理模块的日期选择和功能测试优化
• 公司管理模块的公司创建优化

成功标准

1. 所有优化需求按计划完成
2. 测试流程简化，必填项减少30%以上
3. 所有修复的功能通过测试验证
4. 用户反馈满意度提升

用户故事

平台管理模块

故事 009-01: 区域选择优化

作为 系统管理员 我希望 在薪资管理中添加薪资时，区域选择无需精确到区县 以便 简化操作流程，提高工作效率

验收标准:

• 区域选择组件支持只选择到市级
• 区县字段不再设为必选项
• 现有数据兼容性保持

技术说明:

• 页面路径：平台管理 > 薪资管理 > 添加薪资 > 区域选择
• 修改区域选择组件的验证规则

平台管理模块

故事 009-02: 邮箱输入优化

作为 平台管理员 我希望 邮箱字段改为非必要输入项 以便 在不需要邮箱的场景下快速完成平台相关操作

验收标准:

• 所有平台管理相关页面的邮箱字段改为非必填
• 表单验证规则更新（添加中文错误提示）
• 后端API支持邮箱为空（空字符串自动转换为undefined）

技术说明:

• 页面路径：平台管理 > 创建平台/编辑平台 > 联系邮箱字段
• 文件位置：
  • 前端：allin-packages/platform-management-ui/src/components/PlatformManagement.tsx
  • 后端：allin-packages/platform-module/src/schemas/platform.schema.ts

• 技术方案：

  1. 修改Zod schema，添加中文错误提示：

     contactEmail: z.string({
     error: '请输入联系邮箱'
     }).email({
     message: '请输入有效的邮箱地址'
     }).max(100, {
     message: '邮箱地址不能超过100个字符'
     }).optional()
     .or(z.literal(''))  // 允许空字符串
     .transform(val => val === '' ? undefined : val)  // 将空字符串转为undefined
     

  2. 前端表单默认值从''改为undefined

  3. 统一创建和更新DTO的验证规则

• 测试要求：

  • 验证空字符串自动转换为undefined
  • 验证中文错误提示显示正确
  • 验证邮箱格式验证正常工作

实施状态: ✅ 已完成 (2025-12-10) 实施详情:

• 前端表单优化：更新默认值、修复React警告、使用RPC类型推断
• 后端schema验证：添加完整中文错误提示、空字符串处理
• 数据库兼容性验证：确认contact_email字段可为空
• 测试覆盖：15个单元测试 + 4个集成测试，所有测试通过
• 回归测试：平台管理UI包20个测试 + 平台模块33个测试通过

残疾人个人管理模块

故事 009-03: 照片上传优化

作为 残疾人信息管理员 我希望 取消照片上传的各种限制 以便 更灵活地上传残疾人照片

验收标准:

• 取消最多5张照片的限制
• 取消必须选择照片类型的限制
• 取消指定格式的限制（支持常见图片格式）
• 取消10MB大小限制
• 照片上传功能正常可用

技术说明:

• 页面路径：残疾人个人管理 > 新增残疾人 > 照片上传
• 修改文件上传组件的配置

故事 009-04: 银行卡管理优化

作为 残疾人信息管理员 我希望 优化银行卡管理功能 以便 更便捷地管理残疾人的银行卡信息

验收标准:

• 银行名称改为选项式，支持用户自行添加（参考省份选择逻辑）
• 修复银行卡照片无法上传的问题
• 增加银行卡类型选择项（一类卡/二类卡）
• 仅保留"公司名字"为必填项，其他字段设为非必填

技术说明:

• 页面路径：残疾人个人管理 > 新增残疾人 > 银行卡管理 > 添加银行卡
• 需要修改银行选择组件、照片上传功能和表单验证

故事 009-05: 基本信息优化

作为 残疾人信息管理员 我希望 在基本信息中增加"具体残疾部位和情况"字段 以便 更详细地记录残疾人的具体情况

验收标准:

• 在基本信息表单中添加"具体残疾部位和情况"字段
• 该字段为非必填项
• 数据存储和展示功能正常

技术说明:

• 页面路径：残疾人个人管理 > 新增残疾人 > 基本信息填写
• 需要更新数据库表、API和前端表单

故事 009-06: 回访记录优化

作为 残疾人信息管理员 我希望 优化回访记录功能 以便 更全面地记录回访情况

验收标准:

• 在回访类型中增加"微信回访"选项
• "创建"按钮点击功能正常（已修复）

技术说明:

• 页面路径：残疾人个人管理 > 新增残疾人 > 回访记录管理 > 添加回访记录
• 需要更新回访类型枚举和前端选项

订单管理模块

故事 009-07: 日期选择优化

作为 订单管理员 我希望 预计开始日期选择无需精确到时间 以便 简化订单创建流程

验收标准:

• 预计开始日期选择器仅保留日期选择
• 时间选择功能移除
• 现有数据兼容性保持

技术说明:

• 页面路径：订单管理 > 创建订单
• 修改日期选择器组件配置

实施状态: ✅ 已完成 (2025-12-10) 实施详情:

• 前端表单优化：type="datetime-local" 改为 type="date"，移除时间处理逻辑
• 前端schema验证：使用正则表达式验证YYYY-MM-DD格式，添加中文错误提示
• 后端兼容性验证：确认 z.coerce.date() 能正确解析YYYY-MM-DD格式
• 数据库兼容性：expectedStartDate 字段已经是 date 类型，无需修改
• 测试更新：更新集成测试中的日期格式，所有测试通过
• 文件修改：
  • allin-packages/order-management-ui/src/components/OrderForm.tsx
  • allin-packages/order-management-ui/tests/integration/order.integration.test.tsx

公司管理模块

故事 009-08: 公司创建优化

作为 系统管理员 我希望 创建公司时仅"公司名字"为必填项 以便 快速创建公司信息

验收标准:

• 创建公司表单中仅"公司名字"为必填
• 其他所有字段（含平台）均设为非必填
• 表单验证规则更新

技术说明:

• 页面路径：公司管理 > 创建公司
• 需要更新前端表单验证和后端DTO验证

实施状态: ✅ 已完成 (2025-12-10) 实施详情:

• 后端schema验证：修改CreateCompanySchema，仅companyName为必填，其他字段改为可选，添加中文错误提示，使用Zod transform将空字符串转换为undefined
• 前端表单优化：更新表单默认值，所有可选字段标记为"（可选）"，使用RPC类型推断而非直接导入schema类型
• 测试覆盖：公司管理UI包23个测试 + 公司模块17个测试全部通过
• 额外优化：修复测试中的DOM查询问题，确保类型安全

技术考虑

1. 数据库变更需要兼容现有数据
2. 前端组件修改需要考虑用户体验一致性
3. API接口变更需要保持向后兼容
4. 表单验证规则的更新需要全面测试
5. 中文错误提示需要统一格式和语言
6. 可选字段的空字符串处理需要统一方案（使用Zod transform转换为undefined）
7. 前端表单默认值需要与schema验证规则保持一致

依赖关系

1. 各模块的优化相对独立，可并行开发

风险与缓解

1. 风险: 数据库变更可能导致现有数据问题 缓解: 充分测试数据迁移脚本，确保数据兼容性
2. 风险: 表单验证规则变更可能影响其他功能 缓解: 全面测试相关功能，确保不影响现有业务
3. 风险: 组件修改可能引入新的bug 缓解: 加强单元测试和集成测试
4. 风险: 中文错误提示不一致或翻译错误 缓解: 统一错误提示格式，进行语言审查
5. 风险: 空字符串处理逻辑错误导致数据异常 缓解: 充分测试空字符串转换逻辑，确保与数据库兼容
6. 风险: 前端默认值与后端验证规则不一致 缓解: 同步更新前端表单默认值和后端schema验证

验收测试计划

1. 功能测试：验证每个优化需求的功能完整性
2. 回归测试：确保现有功能不受影响
3. 性能测试：验证优化后的性能表现
4. 用户体验测试：收集用户反馈
5. 验证测试：测试中文错误提示显示正确性
6. 边界测试：测试空字符串转换和可选字段行为
7. 兼容性测试：验证前后端验证规则一致性

时间估算

• 总工作量：约15-20人天
• 预计完成时间：2-3周

优先级

高 - 这些优化直接影响测试效率和系统可用性

---

史诗创建时间: 2025-12-09 最后更新: 2025-12-10 状态: 进行中 (故事009-02、009-07、009-08已完成，其他故事待实施)

更新记录:

• 2025-12-10: 修正故事009-02为平台管理模块（原误写为薪资管理模块）
• 2025-12-10: 更新平台管理模块schema，添加中文错误提示和空字符串处理
• 2025-12-10: 更新技术考虑、风险与缓解、验收测试计划
• 2025-12-10: 故事009-02实施完成，更新验收标准和实施详情
• 2025-12-10: 故事009-08实施完成，公司创建优化完成
• 2025-12-10: 故事009-07实施完成，订单管理日期选择优化完成