mini-starter/_bmad-output/implementation-artifacts/13-17-disability-person-form-optimization.md

Story 13.17: 残疾人管理表单优化

Status: done

Story

作为系统管理员， 我希望残疾人管理表单能够自动解析身份证号和残疾证号信息，并支持动态添加多个联系电话， 以减少数据录入工作量和提高数据准确性。

Acceptance Criteria

AC1: 身份证号自动解析功能

1. 当用户输入18位身份证号后，系统自动解析性别
   • 第17位为奇数 → 性别自动填充为"男"
   • 第17位为偶数 → 性别自动填充为"女"
2. 当用户输入18位身份证号后，系统自动解析出生日期
   • 从第7-14位提取出生日期（YYYYMMDD格式）
   • 自动填充到"出生日期"字段
3. 解析后用户可以手动修改解析结果
4. 当身份证号不满足18位时，不触发自动解析
5. 性别和出生日期字段在已填充后仍可手动修改

AC2: 残疾证号自动解析功能

1. 残疾证号格式为 [残疾类别代码][序列号][残疾等级代码]
   • 残疾类别代码: 视力/听力/言语/肢体/智力/精神/多重
   • 残疾等级代码: 一级/二级/三级/四级
2. 当用户输入残疾证号后，系统自动解析并填充残疾类别和等级
   • 示例: 视力残疾123456一级 → 残疾类别填充"视力残疾"，等级填充"一级"
3. 解析后用户可以手动修改解析结果
4. 当残疾证号无法匹配标准格式时，不触发自动解析
5. 残疾类别和等级字段在已填充后仍可手动修改

AC3: 联系电话字段改造

1. 将原有的"联系电话"字段改为"本人手机号"
2. 添加"监护人手机号"字段，支持动态添加多个（最多5个）
3. 本人和监护人手机号都支持手机号格式验证
4. 监护人手机号可添加/删除
5. 数据库schema需要相应调整（保留原有phone字段作为本人手机号，新增guardian_phones表）

AC4: 用户体验

1. 自动解析时有视觉反馈（如短暂高亮或提示信息）
2. 解析失败时不会影响用户继续输入
3. 表单提交时所有必填字段验证正常

Tasks / Subtasks

• [x] Task 1: 身份证号自动解析实现 (AC: #1, #4)

  • Subtask 1.1: 创建身份证解析工具函数（parseIdCard函数）
  • Subtask 1.2: 在DisabilityPersonManagement组件中添加身份证号变化监听
  • Subtask 1.3: 实现性别和出生日期自动填充逻辑
  • Subtask 1.4: 确保用户可手动修改解析结果

• [x] Task 2: 残疾证号自动解析实现 (AC: #2, #5)

  • Subtask 2.1: 创建残疾证号解析工具函数（parseDisabilityId函数）
  • Subtask 2.2: 在DisabilityPersonManagement组件中添加残疾证号变化监听
  • Subtask 2.3: 实现残疾类别和等级自动填充逻辑
  • Subtask 2.4: 处理解析失败的情况

• [x] Task 3: 联系电话字段改造 (AC: #3)

  • Subtask 3.1: 修改数据库schema（保留phone字段，新增guardian_phones表）
  • Subtask 3.2: 更新Zod schema定义
  • Subtask 3.3: 修改DisabilityPersonManagement组件表单UI
  • Subtask 3.4: 实现监护人手机号动态添加/删除功能
  • Subtask 3.5: 添加手机号格式验证

• [x] Task 4: 单元测试 (AC: #1, #2, #3)

  • Subtask 4.1: 测试身份证号解析功能（有效/无效身份证号）
  • Subtask 4.2: 测试残疾证号解析功能
  • Subtask 4.3: 测试监护人手机号增删改功能

• [x] Task 5: 集成测试和验证

  • Subtask 5.1: 手动测试表单完整流程（通过 Playwright MCP E2E 测试验证）
  • Subtask 5.2: 验证数据保存和读取正确性

Dev Notes

技术实现要点

身份证解析规则

• 18位身份证号: 第7-14位为出生日期(YYYYMMDD)，第17位为性别代码(奇数=男，偶数=女)
• 15位身份证号: 第7-12位为出生日期(YYMMDD)，第15位为性别代码

残疾证号解析规则

• 残疾证号通常包含残疾类别关键字，需要通过正则表达式匹配
• 示例格式: [类别]残疾[序列号][等级] 或 [类别][序列号][等级]
• 类别关键词: 视力/听力/言语/肢体/智力/精神/多重
• 等级关键词: 一级/二级/三级/四级

联系电话数据结构

// 新增监护人手机号实体
interface GuardianPhone {
  id?: number;
  personId: number;
  phone: string;
  relationship: string; // 监护人关系（可选）
  isPrimary: number; // 是否主要联系人: 1-是，0-否
}

相关文件路径

前端组件

• /mnt/code/188-179-template-6/allin-packages/disability-person-management-ui/src/components/DisabilityPersonManagement.tsx
  • 需要添加身份证号和残疾证号变化监听
  • 需要修改联系电话UI为本人手机号+监护人手机号

Schema定义

• /mnt/code/188-179-template-6/allin-packages/disability-module/src/schemas/disabled-person.schema.ts
  • 需要添加监护人手机号相关的schema定义

数据库实体

• /mnt/code/188-179-template-6/allin-packages/disability-module/src/entities/disabled-person.entity.ts
  • phone字段保留作为本人手机号
  • 需要新增GuardianPhone实体

Project Structure Notes

• 本Story属于Epic 13（跨端数据同步测试），但实际是功能优化Story
• 遵循monorepo结构，修改位于allin-packages下
• 使用react-hook-form进行表单管理，使用zod进行验证
• 表单变化监听使用useEffect配合watch方法

References

• [Source: /mnt/code/188-179-template-6/allin-packages/disability-person-management-ui/src/components/DisabilityPersonManagement.tsx]
• [Source: /mnt/code/188-179-template-6/allin-packages/disability-module/src/schemas/disabled-person.schema.ts]
• [Source: /mnt/code/188-179-template-6/allin-packages/disability-module/src/entities/disabled-person.entity.ts]
• [Source: /mnt/code/188-179-template-6/CLAUDE.md - 项目开发环境说明]
• [Source: /mnt/code/188-179-template-6/_bmad-output/project-context.md - 项目上下文]

Dev Agent Record

Agent Model Used

claude-opus-4-5-20251101

Debug Log References

Completion Notes List

File List

前端组件

• allin-packages/disability-person-management-ui/src/utils/idCardParser.ts - 身份证解析工具函数
• allin-packages/disability-person-management-ui/src/utils/disabilityIdParser.ts - 残疾证号解析工具函数
• allin-packages/disability-person-management-ui/src/components/DisabilityPersonManagement.tsx - 添加身份证号和残疾证号自动解析功能
• allin-packages/disability-person-management-ui/src/components/GuardianPhoneManagement.tsx - 监护人电话管理组件

前端测试

• allin-packages/disability-person-management-ui/tests/utils/idCardParser.test.ts - 身份证解析单元测试（20个测试用例）
• allin-packages/disability-person-management-ui/tests/utils/disabilityIdParser.test.ts - 残疾证号解析单元测试（22个测试用例）

后端实体

• allin-packages/disability-module/src/entities/disabled-person-guardian-phone.entity.ts - 监护人电话实体
• allin-packages/disability-module/src/entities/disabled-person.entity.ts - 添加监护人电话关系

后端Schema

• allin-packages/disability-module/src/schemas/disabled-person.schema.ts - 添加监护人电话相关schema定义

服务器配置（CRITICAL FIX）

• packages/server/src/index.ts - 修复 DisabledPersonGuardianPhone entity 未注册到 TypeORM 的问题