# Story 009.005: 基本信息优化

## Status
Ready for Review

## Story
**As a** 残疾人信息管理员
**I want** 在基本信息中增加"具体残疾部位和情况"字段
**so that** 更详细地记录残疾人的具体情况

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

## Tasks / Subtasks
- [ ] 修改残疾人实体，添加具体残疾部位和情况字段 (AC: 1, 2, 3)
  - [ ] 修改 `allin-packages/disability-module/src/entities/disabled-person.entity.ts`，添加 `specificDisability` 字段
  - [ ] 字段类型：`varchar(500)`，可为空，注释：具体残疾部位和情况
- [ ] 修改残疾人Schema验证规则 (AC: 1, 2, 3)
  - [ ] 修改 `allin-packages/disability-module/src/schemas/disabled-person.schema.ts`
  - [ ] 在 `BaseDisabledPersonSchema` 中添加 `specificDisability` 字段，设为可选
  - [ ] 在 `DisabledPersonSchema` 中添加 `specificDisability` 字段，设为可选
  - [ ] 在 `CreateDisabledPersonSchema` 中添加 `specificDisability` 字段，设为可选
  - [ ] 在 `UpdateDisabledPersonSchema` 中添加 `specificDisability` 字段，设为可选
  - [ ] 添加中文错误提示：最大长度500字符
- [ ] 修改前端残疾人管理表单 (AC: 1, 2, 3)
  - [ ] 修改 `allin-packages/disability-person-management-ui/src/components/DisabilityPersonManagement.tsx`
  - [ ] 在创建表单默认值中添加 `specificDisability: ''`
  - [ ] 在表单字段网格中添加"具体残疾部位和情况"字段
  - [ ] 使用 `Textarea` 组件，支持多行输入
  - [ ] 字段标签为"具体残疾部位和情况（可选）"
  - [ ] 确保更新表单也包含该字段
- [ ] 更新数据库实体（TypeORM自动同步） (AC: 3)
  - [ ] 修改实体文件后，TypeORM会自动同步数据库结构
  - [ ] 无需手动创建迁移脚本（开发阶段）
- [ ] 添加测试覆盖 (AC: 1, 2, 3)
  - [ ] 更新残疾人模块集成测试，验证新字段功能
  - [ ] 更新残疾人管理UI包集成测试，验证表单字段显示和验证
  - [ ] 测试空值、有效值和边界值（500字符限制）

## Dev Notes

### 技术栈信息 [Source: architecture/tech-stack.md]
- 运行时：Node.js 20.18.3
- 框架：Hono 4.8.5（Web框架和API路由，RPC类型安全）
- 前端框架：React 19.1.0
- 数据库：PostgreSQL 17（通过TypeORM）
- ORM：TypeORM 0.3.25
- 样式：Tailwind CSS 4.1.11
- 状态管理：React Query 5.83.0

### 项目结构信息 [Source: architecture/source-tree.md]
- 残疾人管理模块：`allin-packages/disability-module/`
  - 实体：`src/entities/disabled-person.entity.ts`
  - Schema：`src/schemas/disabled-person.schema.ts`
  - 服务：`src/services/`
  - 路由：`src/routes/`
- 残疾人个人管理UI包：`allin-packages/disability-person-management-ui/`
  - 组件：`src/components/DisabilityPersonManagement.tsx`
  - API客户端：`src/api/disabilityClient.ts`
  - 测试：`tests/integration/`

### 后端模块包规范 [Source: architecture/backend-module-package-standards.md]
- 包命名规范：`@d8d/allin-disability-module`
- 目录结构规范：
  - `src/entities/` - 实体定义
  - `src/schemas/` - 验证Schema
  - `src/services/` - 服务层
  - `src/routes/` - 路由层
  - `tests/integration/` - 集成测试
- Schema验证要求：使用 `@hono/zod-openapi`，添加中文错误提示

### UI包开发规范 [Source: architecture/ui-package-standards.md]
- 包命名规范：`@d8d/allin-disability-person-management-ui`
- 组件开发规范：
  - 使用RPC推断类型，而不是直接导入schema类型
  - 为关键交互元素添加 `data-testid` 属性
  - 使用条件渲染两个独立的Form组件（创建和更新）
  - 表单字段使用网格布局：`grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4`
- 测试规范：
  - 测试文件位置：`tests/integration/`
  - 使用 `data-testid` 进行元素查询
  - 避免使用 `getByText()` 查找可能重复的文本元素

### 编码标准 [Source: architecture/coding-standards.md]
- 测试框架：Vitest + Testing Library + hono/testing
- 测试位置：`tests/` 文件夹与源码并列
- 覆盖率目标：核心业务逻辑 > 80%
- 关键集成规则：
  - 确保现有API兼容性
  - 使用测试数据库，避免污染生产数据
  - 测试各种错误场景和边界条件

### 数据模型变更指导
- 字段名称：`specific_disability`（数据库），`specificDisability`（代码）
- 字段类型：`VARCHAR(500)`，可为空
- 字段注释：具体残疾部位和情况
- 位置：添加到 `disabled_person` 表
- 兼容性：新字段必须可为空，不影响现有数据
- **数据库同步**：开发阶段使用TypeORM自动同步，无需手动创建迁移脚本

### 表单字段设计
- 组件类型：`Textarea`（多行文本输入）
- 标签："具体残疾部位和情况（可选）"
- 占位符："请输入具体残疾部位和情况，最多500字符"
- 验证规则：最大长度500字符，中文错误提示
- 布局：与其他基本信息字段在同一网格布局中

### 测试要求
- 单元测试：验证Schema验证规则
- 集成测试：验证API端点对新字段的支持
- UI测试：验证表单字段显示、输入和验证
- 边界测试：测试500字符限制
- 兼容性测试：验证现有数据不受影响

### Testing
- **测试文件位置**：
  - 后端：`allin-packages/disability-module/tests/integration/disability.integration.test.ts`
  - 前端：`allin-packages/disability-person-management-ui/tests/integration/disability-person.integration.test.tsx`
- **测试标准**：
  - 使用Vitest作为测试框架
  - 集成测试验证完整工作流
  - 测试覆盖率 > 80%
  - 使用 `data-testid` 进行元素查询
  - 测试边界条件和错误场景
- **测试框架和模式**：
  - 后端：hono/testing + Vitest
  - 前端：Testing Library + Vitest
  - E2E：Playwright（如果需要）
- **特定测试要求**：
  - 验证新字段在创建、更新、查询操作中正常工作
  - 验证字段为非必填项
  - 验证500字符长度限制
  - 验证现有数据兼容性

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-12-10 | 1.0 | 初始故事创建 | Bob (Scrum Master) |

## Dev Agent Record

### Agent Model Used
Claude 3.5 Sonnet (d8d-model)

### Debug Log References
- 实体修改：`allin-packages/disability-module/src/entities/disabled-person.entity.ts`
- Schema验证规则更新：`allin-packages/disability-module/src/schemas/disabled-person.schema.ts`
- 前端表单更新：`allin-packages/disability-person-management-ui/src/components/DisabilityPersonManagement.tsx`
- 集成测试更新：`allin-packages/disability-module/tests/integration/disability.integration.test.ts`
- UI集成测试更新：`allin-packages/disability-person-management-ui/tests/integration/disability-person.integration.test.tsx`

### Completion Notes List
1. ✅ 修改残疾人实体，添加 `specificDisability` 字段（varchar(500)，可为空）
2. ✅ 更新所有Schema验证规则（BaseDisabledPersonSchema, DisabledPersonSchema, CreateDisabledPersonSchema, UpdateDisabledPersonSchema）
3. ✅ 前端表单添加Textarea组件，标签为"具体残疾部位和情况（可选）"，支持多行输入
4. ✅ 数据库实体更新完成（TypeORM自动同步）
5. ✅ 添加完整的测试覆盖：
   - 后端集成测试：验证空值、有效值、边界值（500字符限制）
   - UI集成测试：验证表单字段显示、输入和验证
6. ✅ 查看详情模态框添加新字段显示

### File List
**创建/修改的文件：**
1. `allin-packages/disability-module/src/entities/disabled-person.entity.ts` - 添加 `specificDisability` 字段
2. `allin-packages/disability-module/src/schemas/disabled-person.schema.ts` - 更新所有Schema验证规则
3. `allin-packages/disability-person-management-ui/src/components/DisabilityPersonManagement.tsx` - 添加前端表单字段
4. `allin-packages/disability-module/tests/integration/disability.integration.test.ts` - 添加后端集成测试
5. `allin-packages/disability-person-management-ui/tests/integration/disability-person.integration.test.tsx` - 添加UI集成测试

**影响的文件：**
1. `allin-packages/disability-module/src/routes/` - 所有使用DisabledPerson实体的路由
2. `allin-packages/disability-module/src/services/` - 所有使用DisabledPerson实体的服务

## QA Results
