docs(story-008.006): 优化残疾人个人管理UI故事任务

- 移除冗余的前端Zod Schema创建任务
- 移除独立的表单类型定义任务
- 移除包装组件任务（AreaSelectField、EnumSelectField）
- 添加任务调整说明，参考故事008.005经验
- 标注具体参考文件路径，便于开发参考
- 保留多步骤表单状态管理的合理架构

基于故事008.005的开发经验，简化开发任务，避免重复工作。

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

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

docs/stories/008.006.transplant-disability-person-management-ui.story.md

@@ -0,0 +1,328 @@
+# Story 008.006: 移植残疾人个人管理UI（disability_person → @d8d/allin-disability-person-management-ui）
+
+## Status
+Draft
+
+## Story
+**As a** 开发者，
+**I want** 将disability_person管理页面从allin_system-master/client移植为独立UI包@d8d/allin-disability-person-management-ui，完成技术栈转换并集成文件上传、区域选择器组件和枚举常量，
+**so that** 我们可以将Allin系统的残疾人个人管理UI模块集成到当前项目中，遵循现有的UI包结构和编码标准，并正确集成文件上传、区域选择器和枚举常量功能。
+
+## Acceptance Criteria
+1. 创建`allin-packages/disability-person-management-ui`目录结构
+2. 完成组件转换：复杂表单、照片上传、备注管理组件
+3. **文件上传集成**：与`@d8d/file-management-ui`集成
+4. **区域包集成**：集成`@d8d/area-management-ui`的区域选择器组件用于残疾人详细地址管理（省份→城市→区县三级联动）
+5. **枚举常量集成**：使用`@d8d/allin-enums`包中的枚举
+6. 完成API客户端转换：复杂API调用链（使用rpcClient + ClientManager模式）
+7. 完成状态管理转换：多步骤表单状态
+8. 完成表单转换：复杂验证逻辑（包含区域选择验证）
+9. 配置package.json：多依赖管理（包含`@d8d/area-management-ui`）
+10. 编写组件测试：覆盖所有复杂场景（包含区域选择功能测试）
+11. 通过类型检查和基本测试验证
+
+## Tasks / Subtasks
+- [ ] 任务1：创建残疾人个人管理UI包基础结构 (AC: 1, 9)
+  - [ ] 创建目录结构：`allin-packages/disability-person-management-ui/`
+    - **目标目录**：`allin-packages/disability-person-management-ui/`
+    - **参考结构**：`allin-packages/platform-management-ui/`目录结构
+  - [ ] 创建package.json：配置包名、依赖、脚本
+    - **目标文件**：`allin-packages/disability-person-management-ui/package.json`
+    - **包名**：`@d8d/allin-disability-person-management-ui`
+    - **依赖**：`@d8d/allin-disability-module`、`@d8d/area-management-ui`、`@d8d/file-management-ui`、`@d8d/allin-enums`、`@d8d/shared-ui-components`、`@tanstack/react-query`、`react-hook-form`、`zod`
+    - **参考文件**：`allin-packages/platform-management-ui/package.json`
+  - [ ] 创建TypeScript配置：`tsconfig.json`
+    - **目标文件**：`allin-packages/disability-person-management-ui/tsconfig.json`
+    - **参考文件**：`allin-packages/platform-management-ui/tsconfig.json`
+  - [ ] 创建测试配置：`vitest.config.ts`
+    - **目标文件**：`allin-packages/disability-person-management-ui/vitest.config.ts`
+    - **参考文件**：`allin-packages/platform-management-ui/vitest.config.ts`
+  - [ ] 创建主入口文件：`src/index.ts`
+    - **目标文件**：`allin-packages/disability-person-management-ui/src/index.ts`
+    - **参考文件**：`allin-packages/platform-management-ui/src/index.ts`
+
+- [ ] 任务2：分析源系统文件并创建API客户端 (AC: 6)
+  - [ ] 分析源系统残疾人个人管理页面：`allin_system-master/client/app/admin/dashboard/disability_person/page.tsx`
+    - **源文件**：`allin_system-master/client/app/admin/dashboard/disability_person/page.tsx`
+    - **查看要点**：数据结构、API调用方式、表单字段、照片上传逻辑、备注管理
+  - [ ] 查看残疾人模块RPC路由定义：`allin-packages/disability-module/src/routes/disabled-person-custom.routes.ts`
+    - **路由文件**：`allin-packages/disability-module/src/routes/disabled-person-custom.routes.ts`
+    - **查看要点**：路由路径、请求方法、Schema定义
+  - [ ] 查看残疾人模块集成测试：`allin-packages/disability-module/tests/integration/disability.integration.test.ts`
+    - **测试文件**：`allin-packages/disability-module/tests/integration/disability.integration.test.ts`
+    - **查看要点**：API调用方式、请求参数、响应格式、错误处理
+  - [ ] 查看残疾人模块Schema定义：`allin-packages/disability-module/src/schemas/disabled-person.schema.ts`
+    - **源文件**：`allin-packages/disability-module/src/schemas/disabled-person.schema.ts`
+    - **查看要点**：`CreateDisabledPersonSchema`、`UpdateDisabledPersonSchema`、字段定义、验证规则（仅用于了解字段结构，不直接导入）
+  - [ ] **创建API客户端**：`src/api/disabilityClient.ts`
+    - **目标文件**：`allin-packages/disability-person-management-ui/src/api/disabilityClient.ts`
+    - **重要原则**：使用ClientManager单例模式管理RPC客户端生命周期
+    - **类型推导**：使用`InferRequestType`和`InferResponseType`从RPC客户端推导类型
+    - **参考模式**：参考现有UI包的API客户端模式
+      - `allin-packages/platform-management-ui/src/api/platformClient.ts` - 平台管理UI API客户端
+      - `allin-packages/platform-management-ui/src/api/types.ts` - 平台管理UI类型定义
+      - `allin-packages/disability-management-ui/src/api/disabilityClient.ts` - 残疾人管理UI API客户端（最新实现）
+
+- [ ] 任务3：实现文件上传集成 (AC: 3)
+  - [ ] 分析源系统照片上传逻辑：`allin_system-master/client/app/admin/dashboard/disability_person/AddDisabledPersonModal.tsx`
+    - **源文件**：`allin_system-master/client/app/admin/dashboard/disability_person/AddDisabledPersonModal.tsx`
+    - **查看要点**：照片上传组件、文件处理逻辑、预览功能
+  - [ ] 查看文件管理UI包组件：`packages/file-management-ui/src/components/FileSelector.tsx`
+    - **组件文件**：`packages/file-management-ui/src/components/FileSelector.tsx`
+    - **查看要点**：组件API、事件处理、文件类型限制
+  - [ ] 创建照片上传组件：`src/components/PhotoUploadField.tsx`
+    - **目标文件**：`allin-packages/disability-person-management-ui/src/components/PhotoUploadField.tsx`
+    - **功能**：集成`FileSelector`组件，支持照片上传、预览、删除
+    - **参考文件**：`packages/file-management-ui/src/components/FileSelector.tsx`
+  - [ ] 集成照片上传到表单：在残疾人个人表单中添加照片上传字段
+    - **字段**：`photoFileId`（文件ID字段）
+    - **表单集成**：使用`PhotoUploadField`组件，表单接收`fileId`参数
+  - [ ] 创建照片预览组件：`src/components/PhotoPreview.tsx`
+    - **目标文件**：`allin-packages/disability-person-management-ui/src/components/PhotoPreview.tsx`
+    - **功能**：使用`FilePreview`组件显示照片
+    - **参考文件**：`packages/file-management-ui/src/components/FilePreview.tsx`
+
+- [ ] 任务4：实现区域选择器集成 (AC: 4)
+  - [ ] 查看区域管理UI包组件：`packages/area-management-ui/src/components/AreaSelect.tsx`
+    - **组件文件**：`packages/area-management-ui/src/components/AreaSelect.tsx`
+    - **查看要点**：组件API、三级联动逻辑、数据格式
+  - [ ] 集成区域选择器到表单：在残疾人个人表单中添加区域选择字段
+    - **字段**：`provinceId`、`cityId`、`districtId`
+    - **表单集成**：直接使用`AreaSelect`组件，支持三级联动
+  - [ ] 实现区域数据转换：将源系统的字符串省份城市转换为区域ID
+    - **数据加载时**：区域ID → 区域名称显示
+    - **数据提交时**：区域ID → 后端API
+
+- [ ] 任务5：实现枚举常量集成 (AC: 5)
+  - [ ] 查看Allin枚举包：`allin-packages/enums/src/index.ts`
+    - **枚举文件**：`allin-packages/enums/src/index.ts`
+    - **查看要点**：残疾人相关枚举定义（性别、残疾类型、残疾等级等）
+  - [ ] 集成枚举选择器到表单：在残疾人个人表单中添加枚举选择字段
+    - **字段**：`gender`、`disabilityType`、`disabilityLevel`等
+    - **表单集成**：使用Select组件，从枚举包获取选项
+
+- [ ] 任务6：实现复杂表单组件 (AC: 2, 7, 8)
+  - [ ] 创建残疾人个人管理主组件：`src/components/DisabilityPersonManagement.tsx`
+    - **目标文件**：`allin-packages/disability-person-management-ui/src/components/DisabilityPersonManagement.tsx`
+    - **功能**：主管理组件，包含表格、搜索、创建、编辑功能
+    - **参考文件**：`allin-packages/platform-management-ui/src/components/PlatformManagement.tsx`
+  - [ ] 创建残疾人个人表单组件：`src/components/DisabilityPersonForm.tsx`
+    - **目标文件**：`allin-packages/disability-person-management-ui/src/components/DisabilityPersonForm.tsx`
+    - **功能**：复杂表单组件，集成照片上传、区域选择、枚举选择
+    - **参考模式**：必须使用条件渲染两个独立的Form组件（创建和编辑）
+  - [ ] 创建备注管理组件：`src/components/RemarkManagement.tsx`
+    - **目标文件**：`allin-packages/disability-person-management-ui/src/components/RemarkManagement.tsx`
+    - **功能**：残疾人备注管理，支持添加、编辑、删除备注
+  - [ ] 创建多步骤表单状态管理：使用React状态管理多步骤表单流程
+    - **步骤**：基本信息 → 照片上传 → 区域选择 → 备注管理
+    - **状态管理**：使用React Context或useReducer管理多步骤状态
+
+- [ ] 任务7：编写集成测试 (AC: 10)
+  - [ ] 创建主测试文件：`tests/integration/disability-person.integration.test.tsx`
+    - **目标文件**：`allin-packages/disability-person-management-ui/tests/integration/disability-person.integration.test.tsx`
+    - **参考文件**：`allin-packages/platform-management-ui/tests/integration/platform.integration.test.tsx`
+  - [ ] 实现完整CRUD流程测试：创建残疾人个人 → 查询列表 → 更新 → 删除
+    - **测试场景**：创建残疾人个人记录 → 查询残疾人个人列表 → 更新记录 → 删除记录
+    - **测试ID**：为关键交互元素添加`data-testid`属性，避免使用文本查找
+  - [ ] 实现文件上传集成测试：验证照片上传功能
+    - **测试场景**：照片上传组件集成，文件选择、预览、删除功能
+    - **验证点**：文件ID正确传递，表单验证正常工作
+  - [ ] 实现区域选择器集成测试：验证区域选择功能
+    - **测试场景**：区域选择器组件集成，三级联动功能
+    - **验证点**：区域ID正确传递，表单验证正常工作
+  - [ ] 实现枚举选择器集成测试：验证枚举选择功能
+    - **测试场景**：枚举选择器组件集成，选项加载和选择
+    - **验证点**：枚举值正确传递，表单验证正常工作
+  - [ ] 实现表单验证测试：验证必填字段、身份证号唯一性等
+    - **测试场景**：必填字段验证、身份证号格式验证、身份证号唯一性验证
+    - **参考模式**：残疾人模块集成测试中的验证逻辑
+  - [ ] 实现错误处理测试：API错误、网络错误、验证错误
+    - **测试场景**：API错误、网络错误、表单验证错误
+    - **参考模式**：平台管理集成测试中的错误处理
+
+- [ ] 任务8：验证和测试 (AC: 11)
+  - [ ] 运行`pnpm typecheck`确保无类型错误
+  - [ ] 运行`pnpm test`确保所有集成测试通过
+  - [ ] 验证文件上传组件集成正常工作
+  - [ ] 验证区域选择器组件集成正常工作
+  - [ ] 验证枚举选择器组件集成正常工作
+  - [ ] 验证表单验证和错误处理功能
+  - [ ] 验证组件导出和类型定义正确
+
+## Dev Notes
+
+### 从前一个故事学到的关键经验（故事008.005）：
+1. **Schema设计一致性验证**：必须查看后端模块的集成测试和路由定义来确保Schema设计正确，不能仅凭前端使用场景假设。
+2. **API路径一致性验证**：必须根据后端实际路由设计前端API调用，不能假设为标准CRUD模式。
+3. **测试精度优化**：在测试中使用test ID比文本查找更精确可靠。
+4. **类型推导优化**：遵循现有UI包的模式，使用正确的RPC类型推导语法。
+5. **表单组件模式规范**：必须使用条件渲染两个独立的Form组件，避免在单个Form组件上动态切换props。
+6. **简化开发任务**：移除冗余的Schema创建、类型定义和包装组件任务，直接使用后端Schema和现有组件
+
+### 任务调整说明
+根据故事008.005的UI包开发规范和经验，对原任务进行了优化：
+1. **移除前端Zod Schema创建**：直接使用后端模块的Schema进行表单验证，避免重复定义
+2. **移除独立的表单类型定义**：使用RPC推断类型（`InferRequestType`和`InferResponseType`），无需创建独立的类型文件
+3. **移除包装组件任务**：直接使用`AreaSelect`组件和Select组件，无需额外包装组件
+4. **保留多步骤表单状态管理**：对于多步骤表单，使用React Context管理状态是合理的架构设计
+5. **优化组件结构**：将表格、表单、模态框功能集成到主组件中，简化结构
+
+### 类型推导最佳实践（基于史诗008经验总结）：
+1. **必须使用RPC推断类型**：使用`InferRequestType`和`InferResponseType`从RPC客户端推导类型，而不是直接导入schema类型。
+2. **避免Date/string类型不匹配**：后端Schema中的Date类型在前端可能是string，直接导入会导致类型错误。
+3. **参考现有UI包模式**：参考现有UI包的类型定义模式，确保一致性。
+   - `allin-packages/platform-management-ui/src/api/types.ts` - 平台管理UI类型定义
+   - `allin-packages/disability-management-ui/src/api/types.ts` - 残疾人管理UI类型定义（最新实现）
+4. **Schema仅用于验证**：前端Zod Schema仅用于表单验证，类型定义必须从RPC客户端推导。
+5. **正确处理混合路由**：当模块使用自定义路由与CRUD路由混合时，必须通过查看后端模块集成测试确认正确的路由结构。
+
+### 技术栈规范 [Source: docs/architecture/ui-package-standards.md]
+- **包结构规范**：标准目录结构，包含components、api、hooks、types目录
+- **RPC客户端实现规范**：必须使用ClientManager单例模式管理RPC客户端生命周期
+- **组件开发规范**：使用@d8d/shared-ui-components组件库，React Query进行状态管理
+- **类型定义规范**：使用RPC推断类型，避免重新定义类型
+- **测试规范**：集成测试、组件测试、单元测试分层结构
+- **表单组件模式规范**：必须使用条件渲染两个独立的Form组件，避免在单个Form组件上动态切换props
+
+### 项目结构信息 [Source: docs/architecture/source-tree.md]
+- **UI包位置**：`allin-packages/disability-person-management-ui/`（Allin系统专属包目录）
+- **参考实现**：
+  - `allin-packages/platform-management-ui/`（已完成的平台管理UI包）
+  - `allin-packages/channel-management-ui/`（已完成的渠道管理UI包）
+  - `allin-packages/company-management-ui/`（已完成的公司管理UI包）
+  - `allin-packages/salary-management-ui/`（已完成的薪资管理UI包）
+  - `allin-packages/disability-management-ui/`（已完成的残疾人管理UI包）
+- **后端模块**：`allin-packages/disability-module/`（对应的后端模块）
+- **区域管理UI包**：`packages/area-management-ui/`（需要集成的区域选择器组件）
+- **文件管理UI包**：`packages/file-management-ui/`（需要集成的文件上传组件）
+- **枚举常量包**：`allin-packages/enums/`（需要使用的枚举常量）
+
+### 源系统文件路径
+- **需要移植的源文件**：
+  - `allin_system-master/client/app/admin/dashboard/disability_person/page.tsx`
+  - `allin_system-master/client/app/admin/dashboard/disability_person/AddDisabledPersonModal.tsx`
+  - `allin_system-master/client/app/admin/dashboard/disability_person/DisabledPersonDetailModal.tsx`
+  - `allin_system-master/client/app/admin/dashboard/disability_person/disabilityPersonService.ts`
+  - `allin_system-master/client/app/admin/dashboard/disability_person/constant.ts`
+- **需要对照参考的文件**：
+  - `allin-packages/platform-management-ui/src/components/PlatformManagement.tsx`
+  - `allin-packages/platform-management-ui/src/api/platformClient.ts`
+  - `allin-packages/platform-management-ui/src/api/types.ts`
+  - `allin-packages/platform-management-ui/tests/integration/platform.integration.test.tsx`
+  - `allin-packages/company-management-ui/src/components/CompanyManagement.tsx`
+  - `allin-packages/company-management-ui/src/api/companyClient.ts`
+  - `allin-packages/company-management-ui/src/types/index.ts`
+- **区域选择器组件文件**：
+  - `packages/area-management-ui/src/components/AreaSelect.tsx`
+  - `packages/area-management-ui/src/api/areaClient.ts`
+- **文件上传组件文件**：
+  - `packages/file-management-ui/src/components/FileSelector.tsx`
+  - `packages/file-management-ui/src/components/FilePreview.tsx`
+  - `packages/file-management-ui/src/api/fileClient.ts`
+- **枚举常量文件**：
+  - `allin-packages/enums/src/index.ts`
+
+### 残疾人模块RPC API调用信息（基于集成测试和路由定义）
+- **RPC客户端调用方式**（来自`allin-packages/disability-module/tests/integration/disability.integration.test.ts`和`allin-packages/disability-module/src/routes/disabled-person-custom.routes.ts`）：
+  - `disabilityClientManager.get().createDisabledPerson.$post({ json: personData })` - 创建残疾人记录
+  - `disabilityClientManager.get().updateDisabledPerson.$post({ json: personData })` - 更新残疾人记录
+  - `disabilityClientManager.get().deleteDisabledPerson.$post({ json: { id } })` - 删除残疾人记录
+  - `disabilityClientManager.get().getDisabledPersonList.$get({ query: { page, pageSize, filters, sortBy, sortOrder } })` - 获取残疾人列表（分页）
+  - `disabilityClientManager.get().getDisabledPersonById.$get({ query: { id } })` - 获取残疾人详情
+
+- **API路径映射**（来自`allin-packages/disability-module/src/routes/disabled-person-custom.routes.ts`）：
+  - `POST /createDisabledPerson` → `disabilityClientManager.get().createDisabledPerson.$post`
+  - `POST /updateDisabledPerson` → `disabilityClientManager.get().updateDisabledPerson.$post`
+  - `POST /deleteDisabledPerson` → `disabilityClientManager.get().deleteDisabledPerson.$post`
+  - `GET /getDisabledPersonList` → `disabilityClientManager.get().getDisabledPersonList.$get`
+  - `GET /getDisabledPersonById` → `disabilityClientManager.get().getDisabledPersonById.$get`
+
+- **残疾人数据字段**（来自`allin-packages/disability-module/src/schemas/disabled-person.schema.ts`）：
+  - `name: string` - 姓名
+  - `gender: string` - 性别
+  - `idCard: string` - 身份证号
+  - `disabilityId: string` - 残疾证号
+  - `disabilityType: string` - 残疾类型
+  - `disabilityLevel: string` - 残疾等级
+  - `idAddress: string` - 身份证地址
+  - `phone: string` - 联系电话
+  - `province: string` - 省份
+  - `city: string` - 城市
+  - **注意**：源系统使用字符串省份城市，需要转换为区域ID格式
+
+### 文件上传集成方案
+- **组件使用**：导入`FileSelector`和`FilePreview`组件从`@d8d/file-management-ui`
+- **数据转换**：将源系统的文件上传转换为文件ID管理
+  - 表单提交时：文件ID → 后端API
+  - 数据显示时：文件ID → 文件预览显示
+- **照片上传**：使用`FileSelector`组件限制文件类型为图片
+- **表单集成**：在残疾人个人表单中集成照片上传字段，替换原有的文件上传逻辑
+
+### 区域选择器集成方案
+- **组件使用**：导入`AreaSelect`组件从`@d8d/area-management-ui`
+- **数据转换**：将源系统的字符串省份城市转换为区域ID
+  - 表单提交时：区域ID → 后端API
+  - 数据显示时：区域ID → 区域名称显示
+- **三级联动**：使用`AreaSelect`组件内置的省份→城市→区县三级联动功能
+- **表单集成**：在残疾人个人表单中集成区域选择器，替换原有的省份、城市选择逻辑
+- **数据格式**：`AreaSelect`组件返回`{ provinceId?, cityId?, districtId? }`格式
+- **验证集成**：残疾人Schema中的区域字段验证与`AreaSelect`组件集成
+
+### 枚举常量集成方案
+- **枚举使用**：导入枚举常量从`@d8d/allin-enums`
+- **枚举类型**：性别、残疾类型、残疾等级等
+- **组件集成**：创建通用枚举选择器组件，根据枚举类型动态加载选项
+- **表单集成**：在残疾人个人表单中集成枚举选择器，替换原有的硬编码选项
+
+### 表单验证要求
+- **必填字段**：姓名、性别、身份证号、残疾证号、残疾类型、残疾等级、联系电话
+- **身份证号验证**：格式验证、唯一性验证（后端验证）
+- **联系电话验证**：手机号格式验证
+- **区域验证**：省份和城市必须选择
+- **照片验证**：文件类型验证（仅限图片）、文件大小限制
+
+### Testing
+**测试标准**：
+- **测试框架**：Vitest + Testing Library
+- **测试位置**：
+  - 集成测试：`tests/integration/disability-person.integration.test.tsx`
+- **测试覆盖要求**：
+  - 完整CRUD流程测试
+  - 文件上传集成测试
+  - 区域选择器集成测试
+  - 枚举选择器集成测试
+  - 表单验证测试（必填字段、身份证号格式、联系电话格式）
+  - 错误处理测试（API错误、验证错误）
+- **测试模式**：参考现有UI包的集成测试模式
+
+**测试策略**：
+- 使用`data-testid`进行元素定位，避免文本查找
+- 模拟完整的用户交互流程
+- 验证文件上传组件的集成和数据转换
+- 验证区域选择器的集成和数据转换
+- 验证枚举选择器的集成和数据转换
+- 测试表单验证和错误提示
+- 覆盖各种错误场景
+
+## Change Log
+| Date | Version | Description | Author |
+|------|---------|-------------|--------|
+| 2025-12-03 | 1.0 | 初始创建故事008.006 | Scrum Master Bob |
+
+## Dev Agent Record
+*This section is populated by the development agent during implementation*
+
+### Agent Model Used
+*To be filled by dev agent*
+
+### Debug Log References
+*To be filled by dev agent*
+
+### Completion Notes List
+*To be filled by dev agent*
+
+### File List
+*To be filled by dev agent*
+
+## QA Results
+*Results from QA Agent QA review of the completed story implementation*