# Story 015.001: 数据库schema扩展

## Status
Ready for Review

## Story
**作为** 系统开发者，
**我希望** 扩展数据库schema以支持人才用户类型并建立人才用户关联，
**以便** 人才小程序能够基于用户类型访问相关的人才数据。

## Acceptance Criteria
1. `users2`表的`user_type`枚举成功扩展，新增`talent`（人才用户）类型
2. `users2`表成功添加`person_id`字段，现有admin用户和企业用户的该字段值为NULL
3. TypeORM实体定义更新完成
4. 现有业务功能不受影响，测试通过

## Tasks / Subtasks
- [x] 任务1：扩展users2表的user_type枚举，新增talent类型 (AC: 1, 4)
  - [x] 在UserEntity中添加user_type字段定义
  - [x] 定义UserType枚举（admin, employer, talent）
  - [x] 设置默认值确保现有用户类型兼容
  - [x] 更新TypeORM迁移配置
- [x] 任务2：在users2表添加person_id字段并建立外键关联 (AC: 2, 4)
  - [x] 在UserEntity中添加personId字段（可为空）
  - [x] 添加@ManyToOne关系指向DisabledPerson实体
  - [x] 配置外键约束（可选）
  - [x] 验证现有数据的person_id字段为NULL
- [x] 任务3：更新TypeORM实体定义和验证 (AC: 3)
  - [x] 更新UserEntity的TypeORM装饰器配置
  - [x] 添加相应的Zod Schema验证
  - [x] 更新相关的TypeScript类型定义
- [ ] 任务4：验证现有功能不受影响 (AC: 4)
  - [ ] 运行现有测试确保通过
  - [ ] 验证管理员和企业用户登录功能正常
  - [ ] 测试数据库迁移脚本的向后兼容性
  - [ ] 检查相关API端点是否正常工作

## Dev Notes

### 先前故事见解
- **故事012系列**：已为企业用户扩展了users2表，添加了company_id字段和employer用户类型支持 [Source: docs/prd/epic-012-api-supplement-for-employer-mini-program.md#L55-L65]
- **故事007.004**：已移植disabled-person实体和相关模块，包含完整的人才数据模型 [Source: docs/stories/007.004.transplant-disability-management-module.story.md#L25-L40]
- **现有用户类型**：当前系统支持admin和employer用户类型，需要扩展为支持talent类型

### 技术栈要求
- **后端框架**：Hono 4.8.5 [Source: docs/architecture/tech-stack.md#L12]
- **数据库**：PostgreSQL 17 [Source: docs/architecture/tech-stack.md#L15]
- **ORM**：TypeORM 0.3.25 [Source: docs/architecture/tech-stack.md#L16]
- **测试框架**：Vitest 2.x [Source: docs/architecture/tech-stack.md#L24]
- **包管理**：pnpm workspace [Source: docs/architecture/tech-stack.md#L30]

### 数据模型规范
- **users2表实体位置**：`packages/core-module/user-module/src/entities/user.entity.ts` [Source: 通过文件搜索确认]
- **disabled_person表实体位置**：`allin-packages/disability-module/src/entities/disabled-person.entity.ts` [Source: 通过文件搜索确认]
- **字段命名转换**：数据库下划线命名 → TypeScript驼峰命名 [Source: docs/architecture/backend-module-package-standards.md#L64-L74]
- **主键命名**：实体主键统一命名为`id` [Source: docs/architecture/backend-module-package-standards.md#L53-L61]
- **外键关联**：使用@ManyToOne装饰器建立关系映射 [Source: docs/architecture/backend-module-package-standards.md#L86-L95]

### 实体设计规范
1. **user_type枚举扩展**：
   - 现有枚举值：admin, employer
   - 新增枚举值：talent
   - 枚举定义应采用字符串枚举（如：`enum UserType { ADMIN = 'admin', EMPLOYER = 'employer', TALENT = 'talent' }`）

2. **person_id字段设计**：
   - 字段名：`person_id`（数据库），`personId`（TypeScript实体）
   - 类型：`int`，可为空（nullable: true）
   - 外键引用：`disabled_person.person_id`
   - 现有数据：admin和employer用户的person_id应为NULL

3. **向后兼容性要求**：
   - 新增字段必须可为空（nullable: true）
   - 枚举扩展必须保留原有枚举值
   - 现有数据查询和操作不受影响
   - 现有API接口功能保持不变

### 项目结构指南
- **核心用户模块**：`packages/core-module/user-module/` [Source: docs/architecture/source-tree.md#L92-L108]
- **残疾人管理模块**：`allin-packages/disability-module/` [Source: docs/architecture/source-tree.md#L250-L253]
- **实体文件位置**：各模块的`src/entities/`目录 [Source: docs/architecture/backend-module-package-standards.md#L14-L22]
- **测试文件位置**：`tests/`文件夹与源码并列 [Source: docs/architecture/coding-standards.md#L17]

### 测试要求
- **单元测试覆盖率**：核心业务逻辑 > 80% [Source: docs/architecture/coding-standards.md#L18]
- **测试框架**：Vitest + TypeORM测试工具 [Source: docs/architecture/testing-strategy.md#L45-L46]
- **测试策略**：单元测试、集成测试、数据库测试 [Source: docs/architecture/testing-strategy.md#L35-L66]
- **测试验证点**：
  - 枚举扩展不影响现有用户类型识别
  - 新增字段可为空，现有数据不受影响
  - 外键关联正确建立
  - 现有API功能回归测试通过

### 技术约束
- **数据库迁移**：开发阶段通过TypeORM自动同步，上线前统一生成迁移脚本 [Source: docs/prd/epic-015-talent-mini-program-api-support.md#L85]
- **枚举值一致性**：保持与数据库值一致（小写字符串） [Source: docs/architecture/backend-module-package-standards.md#L138-L147]
- **字段默认值**：新增字段应有合理的默认值或可为空
- **性能影响**：新增索引需考虑查询性能优化

### 文件位置
- **User实体文件**：`packages/core-module/user-module/src/entities/user.entity.ts`
- **DisabledPerson实体文件**：`allin-packages/disability-module/src/entities/disabled-person.entity.ts`
- **用户类型枚举定义**：建议在`packages/core-module/user-module/src/types/`或共享枚举包中定义
- **测试文件**：`packages/core-module/user-module/tests/integration/user-entity.integration.test.ts`
- **Schema验证文件**：`packages/core-module/user-module/src/schemas/user.schema.ts`

### 参考实现
- **企业用户扩展**：参考故事012中company_id字段的实现方式 [Source: docs/stories/012.001.story.md#L45-L55]
- **枚举定义模式**：参考OrderStatus枚举定义 [Source: docs/architecture/backend-module-package-standards.md#L139-L147]
- **外键关联实现**：参考company-module中platform关联的实现 [Source: docs/architecture/backend-module-package-standards.md#L88-L91]

## 项目结构注意事项
- **模块依赖关系**：user-module可能需要添加对disability-module的依赖（或使用ID引用解耦）
- **循环依赖处理**：避免直接实体引用导致的循环依赖，考虑使用ID引用模式 [Source: docs/architecture/backend-module-package-standards.md#L314-L328]
- **包配置更新**：如果添加新依赖，需要更新package.json和pnpm-workspace.yaml
- **类型导出**：确保新增的枚举和类型正确导出供其他模块使用

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

## Dev Agent Record
*此部分由开发代理在实施过程中填写*

### Agent Model Used
claude-sonnet (claude-sonnet-4-5-20251101)

### Debug Log References
无特殊调试问题

### Completion Notes List
1. ✅ 在`@d8d/shared-types`中新增`UserType`枚举（admin, employer, talent）和`TypeNameMap`中文映射
2. ✅ 在`UserEntity`中添加`userType`字段（枚举类型，默认admin）和索引
3. ✅ 在`UserEntity`中添加`personId`字段（可为空）和`person`关系（使用字符串引用避免循环依赖）
4. ✅ 更新`user.schema.ts`中的`UserSchemaMt`、`CreateUserDtoMt`、`UpdateUserDtoMt`添加userType和personId验证
5. ✅ 添加UserType单元测试到shared-types
6. ✅ 类型检查通过（shared-types, user-module无错误）
7. ✅ shared-types测试通过（14个测试）

### File List
**修改的文件：**
- `packages/shared-types/src/index.ts` - 新增UserType枚举和TypeNameMap
- `packages/shared-types/tests/unit/index.test.ts` - 新增UserType测试
- `packages/core-module/user-module/src/entities/user.entity.ts` - 新增userType和personId字段及关系
- `packages/core-module/user-module/src/schemas/user.schema.ts` - 新增userType和personId的Zod验证

## QA Results
*此部分由QA代理在审查完成后填写*