# 史诗015 - 人才小程序API支持与数据库扩展

## 史诗目标
为人才小程序提供完整的API接口支持并扩展数据库schema，基于现有allin系统移植模块的基础，为残疾人用户提供个人信息管理、考勤记录、就业信息、薪资查询等完整的数据支持。

## 史诗描述

### 现有系统上下文

**当前相关功能：**
- **mini项目**：基础小程序前端，现有登录、注册、个人资料等基础页面
- **API客户端**：已集成auth、user、role、file模块的RPC客户端（api.ts）
- **史诗7,8,9,10成果**：已移植allin系统的7个后端模块和对应UI模块（channel、company、disability_person、order、platform、salary等）
- **史诗012成果**：已为用人方小程序补充了企业用户认证、企业统计、人才扩展等API接口
- **数据库现状**：PostgreSQL数据库包含19个业务表，已支持核心业务数据存储

**数据库分析发现：**
- **人才用户认证缺失**：`users2`表目前只有admin用户和企业用户，缺乏人才用户的认证支持
- **考勤记录管理**：现有`order_person_asset`表支持打卡视频存储，但需要扩展打卡记录查询API
- **薪资信息存储**：`order_person.salary_detail`字段已存在，需要提供薪资查询API
- **就业历史记录**：基于`order_person`表关联`employment_order`表可查询就业历史
- **个人证件管理**：`disabled_person_photo`表已支持照片存储，需要提供证件照片管理API
- **银行卡信息**：`disabled_bank_card`表已存储银行卡信息，需要提供银行卡管理API

**技术栈：**
- 后端：TypeScript、Hono、Zod OpenAPI、TypeORM
- 数据库：PostgreSQL 17
- API通信：基于Hono RPC的API客户端模式
- 测试：Vitest（后端模块使用Vitest）
- 包管理：pnpm workspace

**集成点：**
- 基于史诗7,8,9,10移植的allin系统模块进行扩展
- 基于史诗012的企业用户认证模式，扩展人才用户认证
- 保持现有数据库schema的向后兼容性
- 遵循现有的模块结构和API设计模式

### 增强详情

**新增/变更内容：**
为人才小程序补充6大类API接口，包括：
1. 数据库schema扩展：扩展用户表支持人才用户类型、添加打卡记录相关字段
2. 人才用户认证API：支持人才用户手机号/身份证号/残疾证号密码登录、获取人才用户信息
3. 个人信息查询API：人才基本信息查询、银行卡信息查询、证件照片查询
4. 考勤记录API：打卡记录查询、考勤统计、考勤日历、打卡明细
5. 就业信息API：当前就业状态查询、薪资记录查询、就业历史查询
6. 帮助与支持API：帮助中心查询、协议政策查询、登录日志查询
7. API文档与测试：OpenAPI文档、TypeScript类型定义、单元测试

**只读设计原则：**
遵循与用人方小程序相同的设计原则，人才小程序API以查询功能为主，所有数据修改操作（个人信息更新、银行卡管理、证件照片管理、打卡记录等）由管理员在管理后台统一处理。人才用户仅有的写入操作包括：登录认证、通知标记已读。

**API路径约定：**
所有人才小程序的API路径统一使用 `api/v1/rencai` 前缀，与现有管理后台和用人方小程序API路径做区分。例如：
- 人才用户登录：`POST /api/v1/rencai/auth/login`
- 人才个人信息：`GET /api/v1/rencai/personal/info`
- 考勤记录查询：`GET /api/v1/rencai/attendance/records`
- 就业信息查询：`GET /api/v1/rencai/employment/info`
- 薪资记录查询：`GET /api/v1/rencai/salary/records`

现有管理后台API和用人方小程序API保持不变，新增的人才小程序API使用独立的路由前缀，避免路径冲突。

**成功标准：**
1. 所有补充API功能完整，符合人才小程序需求
2. 数据库schema扩展不影响现有数据操作
3. API与现有allin系统移植模块无缝集成
4. 通过Vitest测试验证，包括单元测试和集成测试
5. 提供完整的OpenAPI文档和TypeScript类型定义

## 故事列表

**API路径约定说明：**
所有新增的人才小程序API必须遵循 `api/v1/rencai` 前缀约定，确保与现有管理后台和用人方小程序API路径隔离。每个故事在实现API接口时需确保路径前缀正确。

**只读设计说明：**
遵循与用人方小程序相同的设计原则，人才小程序API以查询功能为主。所有数据修改操作（个人信息更新、银行卡管理、证件照片管理、打卡记录等）由管理员在管理后台统一处理。人才用户仅有的写入操作包括：登录认证、通知标记已读。

**故事概览：**
本史诗包含12个故事，其中8个为核心故事（015-01到015-03、015-05到015-07、015-09、015-10），3个延期故事（015-04、015-08、015-11），1个冗余故事（015-12）。故事015-04、015-08因打卡功能前端模拟实现而延期。

### 故事015-01：数据库schema扩展
**背景：** 现有数据库表结构缺少支持人才小程序完整功能的关键字段，需要在不影响现有数据的前提下扩展schema。

**任务列表：**
注：数据库迁移脚本将在上线前统一生成，开发阶段通过TypeORM自动同步。
1. 扩展`users2`表的`user_type`枚举，新增`talent`（人才用户）类型
2. 在`users2`表添加`person_id`字段（外键引用`disabled_person.person_id`），建立人才用户关联
3. 更新对应的TypeORM实体定义
4. 验证现有数据不受影响，新增字段可为空

**注：** 打卡相关字段（`checkin_time`、`checkout_time`、`checkin_status`）暂不添加。打卡功能目前为前端模拟实现，待后续确定接口逻辑后再考虑数据库扩展。

**验收标准：**
- [x] `users2`表的`user_type`枚举成功扩展，新增`talent`类型
- [x] `users2`表成功添加`person_id`字段，现有admin用户和企业用户的该字段值为NULL
- [x] TypeORM实体定义更新完成
- [x] 现有业务功能不受影响，测试通过
**状态：** ✅ 完成 (2025-12-24)

### 故事015-02：人才用户认证API扩展
**背景：** 现有auth-module支持管理员用户和企业用户认证，需要扩展以支持人才用户身份证号/残疾证号密码登录和人才信息关联。

**任务列表：**
1. 扩展auth-module，添加人才用户身份证号/残疾证号密码登录接口
2. 添加人才用户退出登录接口
3. 添加获取人才用户信息接口，包含关联的人才详情（从`disabled_person`表获取）
4. 基于`users2`表的`person_id`字段验证人才用户权限
5. 更新认证中间件，支持人才用户身份识别
6. 编写单元测试和集成测试

- [x] 人才用户可使用身份证号/残疾证号和密码成功登录
- [x] 人才用户登录后可获取包含人才详情的用户信息
- [x] 人才用户可成功退出登录
- [x] 认证中间件正确识别人才用户身份
- [x] 人才用户权限验证逻辑正确
- [x] 所有新增接口通过单元测试和集成测试（16/16通过）
- [x] API文档完整，包含OpenAPI定义和TypeScript类型

**状态：** ✅ 完成 (2025-12-25)

### 故事015-03：个人信息管理API
**背景：** 人才用户需要查看个人信息，包括基本信息、银行卡信息、证件照片等。所有个人信息由管理员在管理后台统一维护，人才小程序只提供查询功能。

**任务列表：**
1. **个人信息查询API**（disability-module扩展）：
   - 基于`disabled_person`表查询人才基本信息
   - 接口返回：姓名、性别、年龄、身份证号、残疾证号、残疾类型、联系电话、联系地址等

2. **银行卡信息查询API**（disability-module扩展）：
   - 基于`disabled_bank_card`表查询人才银行卡信息
   - 接口返回：银行名称、卡号（脱敏）、卡类型、是否默认等

3. **证件照片查询API**（disability-module扩展）：
   - 基于`disabled_person_photo`表查询人才证件照片
   - 接口返回：照片类型（身份证、残疾证、体检报告、征信报告等）、文件信息

4. 编写单元测试和集成测试

**验收标准：**
- [x] 个人信息查询接口返回正确的人才基本信息
- [x] 银行卡信息查询接口返回银行卡信息（卡号脱敏处理）
- [x] 证件照片查询接口返回证件照片信息
- [x] 所有接口验证用户权限，确保用户只能查询自己的数据
- [x] 所有接口通过单元测试和集成测试（11/11通过）
**状态：** ✅ 完成 (2025-12-25)

### 故事015-04：考勤记录API（P2 - 延期，打卡功能前端模拟）
**背景：** 人才用户需要查看考勤记录、考勤统计和打卡明细。当前打卡功能为前端模拟实现，待后续确定真实打卡接口逻辑后再实现后端API。

**任务列表：**
1. **考勤记录查询API**（order-module扩展）：
   - 基于`order_person`表查询个人的打卡记录
   - 支持按月份查询，返回该月的所有打卡记录
   - 接口返回：日期、上班打卡时间、下班打卡时间、打卡状态

2. **考勤统计API**（order-module扩展）：
   - 基于`order_person`表统计个人的考勤数据
   - 接口返回：出勤率、正常出勤天数、迟到次数、早退次数、缺勤次数

3. **考勤日历API**（order-module扩展）：
   - 生成考勤日历视图，标记已打卡日期和打卡状态
   - 支持月份切换，返回该月的日历数据

4. **打卡明细API**（order-module扩展）：
   - 查询详细的打卡记录，包含每天的打卡详情
   - 支持分页查询，按日期倒序排列

5. **打卡视频查询API**（order-module扩展）：
   - 基于`order_person_asset`表查询个人的打卡视频
   - 支持按日期查询打卡视频记录

6. 添加数据库索引优化查询性能
7. 编写单元测试和集成测试

**验收标准：**
- [ ] 考勤记录查询接口返回正确的打卡记录，支持按月查询
- [ ] 考勤统计接口返回正确的考勤统计数据
- [ ] 考勤日历接口返回日历视图数据，正确标记打卡状态
- [ ] 打卡明细接口返回详细的打卡记录，支持分页
- [ ] 打卡视频查询接口返回个人的打卡视频记录
- [ ] 查询性能优化，添加必要的数据索引
- [ ] 所有接口通过单元测试和集成测试

### 故事015-05：就业信息API
**背景：** 人才用户需要查看当前就业状态、薪资记录和就业历史，基于`order_person`表和`employment_order`表进行查询。

**任务列表：**
1. **当前就业状态查询API**（order-module扩展）：
   - 基于`order_person`表查询个人当前的工作状态
   - 接口返回：企业名称、岗位名称、入职日期、工作状态、订单编号、薪资水平
   - 关联`employment_order`表获取企业信息

2. **薪资记录查询API**（order-module扩展）：
   - 基于`order_person.salary_detail`字段查询历史薪资记录
   - 支持按月份查询，返回薪资发放记录
   - 接口返回：月份、发放日期、薪资金额、薪资明细

3. **就业历史查询API**（order-module扩展）：
   - 基于`order_person`表查询个人的就业历史
   - 按时间倒序排列，返回所有历史就业记录
   - 接口返回：企业名称、岗位名称、入职日期、离职日期、工作状态

4. **薪资视频查询API**（order-module扩展）：
   - 基于`order_person_asset`表查询个人的薪资相关视频（工资视频、个税视频）
   - 支持按月份查询薪资视频

5. 添加数据库索引优化查询性能
6. 编写单元测试和集成测试

**验收标准：**
- [ ] 当前就业状态查询接口返回正确的当前工作信息
- [ ] 薪资记录查询接口返回历史薪资记录，支持按月查询
- [ ] 就业历史查询接口返回个人的就业历史记录
- [ ] 薪资视频查询接口返回薪资相关视频记录
- [ ] 查询性能优化，添加必要的数据索引
- [ ] 所有接口通过单元测试和集成测试

### 故事015-06：帮助与支持API
**背景：** 人才用户需要查看帮助文档、用户协议、隐私政策等内容。所有账号安全设置和个人信息修改由管理员在管理后台统一维护。

**任务列表：**
1. **帮助中心查询API**：
   - 帮助中心内容查询接口，提供使用指南和常见问题解答

2. **协议政策查询API**：
   - 用户协议查询接口
   - 隐私政策查询接口

3. **登录日志查询API**（auth-module扩展）：
   - 查询个人的登录日志记录，支持分页
   - 接口返回：登录时间、登录设备、登录IP等

4. 编写单元测试和集成测试

**验收标准：**
- [ ] 帮助中心查询接口返回帮助文档内容
- [ ] 协议政策查询接口返回用户协议和隐私政策
- [ ] 登录日志查询接口返回个人的登录日志记录
- [ ] 所有接口通过单元测试和集成测试

### 故事015-07：通知与消息API
**背景：** 人才用户需要接收系统通知和消息，包括薪资发放通知、考勤异常通知、系统公告等。

**任务列表：**
1. **通知列表查询API**（创建通知模块或扩展现有模块）：
   - 查询个人的通知列表，支持分页
   - 接口返回：通知标题、通知内容、通知时间、通知类型、已读状态

2. **通知详情查询API**：
   - 查询单条通知的详细信息

3. **通知标记已读API**：
   - 标记单条通知为已读
   - 批量标记通知为已读

4. **未读通知数查询API**：
   - 查询个人的未读通知数量

5. **消息推送集成**：
   - 集成小程序消息推送能力，实时推送重要通知
   - 薪资发放时自动推送通知
   - 考勤异常时自动推送通知

6. 编写单元测试和集成测试

**验收标准：**
- [ ] 通知列表查询接口返回个人的通知列表，支持分页
- [ ] 通知详情查询接口返回通知的详细信息
- [ ] 通知标记已读接口支持单条和批量标记已读
- [ ] 未读通知数查询接口返回正确的未读通知数量
- [ ] 消息推送集成，重要通知实时推送到小程序
- [ ] 所有接口通过单元测试和集成测试

### 故事015-08：打卡状态查询API（P2 - 延期，打卡功能前端模拟）
**背景：** 人才用户需要查询当天的打卡状态和历史打卡记录。当前打卡功能为前端模拟实现，待后续确定真实打卡接口逻辑后再实现后端API。

**任务列表：**
1. **当天打卡状态查询API**（order-module扩展）：
   - 查询当天的打卡状态：是否已打卡、打卡时间、打卡类型（上班/下班）
   - 接口返回：打卡状态、打卡时间、打卡结果（正常、迟到、早退等）

2. **打卡异常记录查询API**（order-module扩展）：
   - 查询个人的打卡异常记录：迟到、早退、缺勤等
   - 支持按月份查询异常记录
   - 接口返回：异常日期、异常类型、异常说明（如有）

3. **打卡提醒查询API**（order-module扩展）：
   - 查询打卡提醒设置（如管理员配置的提醒规则）
   - 接口返回：提醒时间、提醒类型等

4. 编写单元测试和集成测试

**验收标准：**
- [ ] 当天打卡状态查询接口返回正确的打卡状态信息
- [ ] 打卡异常记录查询接口返回打卡异常记录
- [ ] 打卡提醒查询接口返回打卡提醒设置信息
- [ ] 所有接口通过单元测试和集成测试

### 故事015-09：数据统计与报表API
**背景：** 人才用户需要查看个人数据统计和报表，包括薪资统计、工作统计等。出勤统计依赖打卡数据，当前打卡功能为前端模拟实现，出勤统计相关API可延期实现。

**任务列表：**
1. **个人出勤统计API**（order-module扩展，可选）：
   - 月度出勤统计：当月出勤天数、出勤率、异常次数
   - 年度出勤统计：年度出勤汇总
   - 出勤趋势分析：月度出勤趋势图表数据
   - **注：** 依赖打卡数据，当前打卡功能为前端模拟实现，可延期实现

2. **个人薪资统计API**（order-module扩展）：
   - 月度薪资统计：当月薪资、历史薪资对比
   - 年度薪资统计：年度薪资总额、平均月薪
   - 薪资趋势分析：月度薪资趋势图表数据

3. **个人工作统计API**（order-module扩展）：
   - 工作时长统计：日均工作时长、月度总工时
   - 工作绩效统计：如需要，可扩展绩效相关统计

4. **统计报表导出**：
   - 支持导出个人统计报表（Excel、PDF格式）
   - 月度报表导出接口
   - 年度报表导出接口

5. 编写单元测试和集成测试

**验收标准：**
- [ ] 个人出勤统计接口返回出勤统计数据
- [ ] 个人薪资统计接口返回薪资统计数据
- [ ] 个人工作统计接口返回工作统计数据
- [ ] 统计报表导出接口支持导出Excel和PDF格式报表
- [ ] 所有接口通过单元测试和集成测试

### 故事015-10：路由路径规范与API客户端
**背景：** 确保所有人才小程序API遵循统一的路径规范，并为前端提供完整的TypeScript API客户端。

**任务列表：**
1. **路由路径规范修复**：
   - 确保所有人才小程序API使用`/api/v1/rencai`前缀
   - 模块包内路由定义不应包含API前缀，前缀应在server包注册时统一添加
   - 修复不符合规范的路由路径

2. **API客户端生成**：
   - 基于OpenAPI文档生成TypeScript API客户端
   - 确保前端可安全使用API客户端类型
   - 提供完整的类型定义和接口文档

3. **错误处理统一**：
   - 统一所有人才小程序API的错误响应格式
   - 提供标准化的错误码和错误信息

4. **API文档完善**：
   - 确保所有接口有完整的OpenAPI文档注释
   - 生成可视化的API文档页面

5. **集成测试更新**：
   - 更新集成测试验证路由路径正确性
   - 测试API客户端与后端接口的集成

**验收标准：**
- [ ] 所有人才小程序API路由路径符合`/api/v1/rencai`前缀约定
- [ ] 模块包内路由定义不包含API前缀，server包正确添加前缀
- [ ] TypeScript API客户端生成完成，前端可安全使用
- [ ] 错误响应格式统一，提供标准化的错误处理
- [ ] OpenAPI文档完整，包含所有接口的文档注释
- [ ] 集成测试通过，验证路由路径和API客户端正确性

### 故事015-11：高级功能与优化（P2 - 后期优化）
**背景：** 人才小程序的高级功能，包括生物识别登录、智能打卡提醒、数据分析洞察等，不是当前MVP必需功能，可延期到后期优化阶段实现。

**优先级说明：** P2优先级，非当前MVP必需功能。可在基本功能稳定后，根据用户反馈逐步添加高级功能。

**任务列表：**
1. （延期）生物识别登录：支持指纹、人脸识别登录
2. （延期）智能打卡提醒：基于位置和时间的智能打卡提醒
3. （延期）数据分析洞察：个人工作表现数据分析与建议
4. （延期）社交功能：人才社区、经验分享等社交功能
5. （延期）职业发展：培训课程、技能提升等职业发展功能

**验收标准：**
- [ ] （延期）生物识别登录功能完整
- [ ] （延期）智能打卡提醒功能准确
- [ ] （延期）数据分析洞察功能有价值
- [ ] （延期）社交功能体验良好
- [ ] （延期）职业发展功能实用

### 故事015-12：API文档与测试完善（冗余 - 基础设施已覆盖）
**背景：** 项目使用`@hono/zod-openapi`实现OpenAPI文档自动生成，在路由定义时通过Zod Schema添加OpenAPI元数据，文档在server包中自动聚合。各故事已包含测试要求（单元测试≥80%，集成测试≥60%），无需专门的故事进行文档和测试完善。

**冗余说明：**
1. **OpenAPI文档**：使用`@hono/zod-openapi`自动生成，路由定义时通过`.openapi()`方法添加文档元数据
2. **TypeScript类型**：自动从Zod Schema生成，供前端使用
3. **单元测试/集成测试**：每个故事都有明确的测试要求和覆盖率标准
4. **API性能测试**：可在相关故事中实现（如故事015-04的考勤查询性能测试）
5. **模块README**：可在各故事的任务列表中包含文档更新

**建议：** 此故事作为基础设施任务已由各故事分别覆盖，无需单独实现。保持各故事的文档和测试要求即可。

### 故事015-13：人才用户手机号登录支持 🆕
**状态**: ✅ Ready for Review
**优先级**: P1 - 用户体验改进（强烈建议）

**背景：** 当前人才用户登录仅支持身份证号/残疾证号,用户反馈使用不方便,希望支持手机号登录,提升登录体验。

**用户价值：**
- 手机号更容易记忆,不需要翻看证件
- 手机号输入更快捷,提升用户体验
- 符合主流APP登录习惯(手机号+密码)

**技术方案：**
- 扩展`UserService.getTalentUserByIdentifier`方法,支持手机号查找
- 手机号查找优先级:先通过`users2.phone`查找,失败后继续身份证号/残疾证号查找
- 使用现有`users2`表的`phone`字段(无需数据库变更)
- 保持向后兼容,身份证号/残疾证号登录仍然可用

**任务列表：**
1. **扩展登录服务方法** (UserService)：
   - 修改`getTalentUserByIdentifier`方法,添加手机号查找逻辑
   - 先通过`phone`字段在`users2`表查找`userType='talent'`的用户
   - 如果手机号查找失败,继续原有的身份证号/残疾证号查找逻辑
   - 确保包含关联查询(person, roles, avatarFile)

2. **更新Schema和API文档**：
   - 更新`TalentLoginSchema`的identifier字段描述为"手机号、身份证号或残疾证号"
   - 更新OpenAPI文档的example和description
   - 更新登录路由的错误提示消息

3. **优化错误提示**：
   - 统一错误消息为"账号或密码错误"(安全考虑)
   - 更新登录路由的错误响应

4. **编写测试**：
   - 添加手机号登录成功的测试用例
   - 添加手机号不存在导致登录失败的测试用例
   - 回归测试:验证身份证号/残疾证号登录仍然正常
   - 测试手机号+密码正确但用户类型不是talent的场景
   - 确保所有现有测试仍然通过

**数据完整性要求：**
- **重要**: 手机号登录依赖于`users2.phone`字段有值
- 管理员创建人才用户时必须填写手机号
- 建议从`disabled_person.phone`同步到`users2.phone`

**数据迁移建议：**
```sql
-- 从disabled_person表同步手机号到users2表
UPDATE users2 u
SET phone = dp.phone
FROM disabled_person dp
WHERE u.person_id = dp.id
  AND u.phone IS NULL
  AND dp.phone IS NOT NULL;
```

**验收标准：**
- [x] 人才用户可使用手机号和密码成功登录
- [x] 手机号登录验证逻辑正确,通过users2表的phone字段查找用户
- [x] 现有的身份证号/残疾证号登录方式仍然正常工作
- [x] 登录错误提示友好,统一为"账号或密码错误"
- [x] API文档更新,包含手机号登录的说明
- [x] 所有测试通过(单元测试和集成测试)

**详细设计文档**: [docs/stories/015.013.story.md](../stories/015.013.story.md)

## 史诗进度

**当前状态：** 史诗执行阶段，3个核心故事已完成，5个核心故事待实现。

**故事完成状态：**
- [x] **故事015-01**：数据库schema扩展 - **已完成** ✅（打卡字段延期）
- [x] **故事015-02**：人才用户认证API扩展 - **已完成** ✅
- [x] **故事015-03**：个人信息管理API - **已完成** ✅
- [ ] **故事015-04**：考勤记录API - **P2 - 延期**（打卡功能前端模拟）
- [ ] **故事015-05**：就业信息API - **待实现**
- [ ] **故事015-06**：帮助与支持API - **待实现**
- [ ] **故事015-07**：通知与消息API - **待实现**
- [ ] **故事015-08**：打卡状态查询API - **P2 - 延期**（打卡功能前端模拟）
- [ ] **故事015-09**：数据统计与报表API - **待实现**（出勤统计可选）
- [ ] **故事015-10**：路由路径规范与API客户端 - **待实现**
- [ ] **故事015-11**：高级功能与优化 - **P2 - 延期**（后期优化）
- [ ] **故事015-12**：API文档与测试完善 - **冗余**（基础设施已覆盖）
- [x] **故事015-13**：人才用户手机号登录支持 - **Ready for Review** ✅ 🆕

**总体进度：** 4/13 故事完成（31%）
**MVP进度：** 4/9 核心故事完成（44%，排除015-04、015-08、015-11延期和015-12冗余）

**最近更新：** 2025-12-26 - 故事015.013已完成：人才用户手机号登录支持,扩展UserService.getTalentUserByIdentifier方法支持手机号优先查找,更新API文档和错误提示,18个集成测试全部通过。2025-12-26 - 故事015.013已创建：人才用户手机号登录支持,允许人才用户使用手机号/身份证号/残疾证号登录,提升用户体验。2025-12-25 - 故事015-03已完成：个人信息查询API、银行卡信息查询API（卡号脱敏）、证件照片查询API、所有11个集成测试通过。2025-12-25 - 故事015-02已完成：人才用户认证API、JWT登录、退出登录、获取用户信息、认证中间件、所有16个测试通过。2025-12-24 - 故事015-01已完成：UserType枚举扩展、personId字段添加、TypeORM实体和Schema更新、测试通过。

---

## 兼容性要求

- [ ] 现有数据库schema变化保持向后兼容
- [ ] 现有API接口不受影响，功能正常
- [ ] 新增字段可为空，不影响现有数据
- [ ] 枚举扩展保留原有枚举值，确保兼容
- [ ] 现有业务逻辑不受影响
- [ ] 性能影响最小化，不影响现有功能响应速度

## 风险缓解

**主要风险：**
1. **数据库schema变更风险**：新增字段和枚举扩展可能影响现有数据操作和查询
2. **API集成风险**：新API可能影响现有模块的稳定性
3. **性能风险**：实时统计查询可能影响数据库性能
4. **兼容性风险**：新增功能可能影响现有系统集成

**缓解措施：**
1. **数据库变更分步实施**：
   - 先扩展`user_type`枚举，不影响现有用户类型
   - `users2`表添加可为空的`person_id`字段，现有用户不受影响
   - `order_person`表添加可为空的打卡字段，现有记录不受影响
2. **逐步集成**：每个故事独立实现和测试，分阶段集成验证
3. **性能优化**：
   - 实时统计查询添加适当的数据库索引
   - 考虑使用物化视图缓存高频统计结果
   - 大数据量查询添加分页和查询条件优化
4. **兼容性保障**：
   - 保持现有API接口不变
   - 新增功能通过新接口提供
   - 充分测试现有功能回归

**回滚计划：**
1. 如果新增功能导致严重问题，可临时禁用新增API路由
2. 数据库schema变更支持可逆回滚：
   - `user_type`枚举扩展：新增的枚举值不影响原有数据，可安全保留
   - `person_id`字段：如需要可删除该字段，人才用户可暂时通过其他方式关联
   - 打卡字段：如需要可删除该字段，不影响核心业务数据
3. 数据库迁移脚本将在上线前统一生成，开发阶段通过TypeORM自动同步
4. API客户端变更可通过版本控制回退到上一个稳定版本

## 完成定义

- [ ] 所有10个核心故事完成（排除015-11延期和015-12冗余），验收标准全部满足
- [ ] 数据库schema扩展完成，不影响现有数据
- [ ] 所有补充API功能完整，符合人才小程序需求
- [ ] API与现有allin系统移植模块无缝集成
- [ ] 通过Vitest测试验证，单元测试和集成测试覆盖率达标
- [ ] 提供完整的OpenAPI文档和TypeScript类型定义
- [ ] 性能测试通过，查询响应时间符合要求
- [ ] 代码符合项目编码规范，通过代码审查

## 依赖关系

- 依赖史诗7,8,9,10移植的API模块作为基础
- 依赖史诗012的企业用户认证模式，扩展人才用户认证
- 依赖现有数据库schema，在基础上进行扩展
- 故事015-01（数据库schema扩展）是其他故事的基础依赖
- 故事015-12（API文档与测试）作为基础设施任务已由各故事分别覆盖
- 史诗后续（人才小程序功能实现）依赖本史诗完成

## 测试策略

1. **单元测试**：对每个新增API接口、服务函数、工具函数进行Vitest单元测试
2. **集成测试**：测试API与数据库的集成，验证数据操作正确性
3. **性能测试**：验证实时统计查询的性能，确保响应时间符合要求
4. **兼容性测试**：验证新增功能不影响现有API接口
5. **回归测试**：确保现有业务功能不受影响
6. **数据库schema变更测试**：验证数据库schema变更的正确性和兼容性

## 执行顺序建议

1. **先完成故事015-01**：数据库schema扩展是基础，其他故事依赖（打卡字段延期）
2. **然后完成故事015-02**：人才用户认证API扩展，提供登录基础
3. **故事015-03**：个人信息管理API，提供基本信息查询
4. **故事015-05**：就业信息API，核心功能实现
5. **故事015-06和015-07**：帮助与支持API和通知与消息API，完善用户体验
6. **故事015-09**：数据统计与报表API（出勤统计可选），增强功能
7. **故事015-10**：路由路径规范与API客户端，确保架构规范
8. **故事015-04、015-08**：考勤记录API和打卡状态查询API（P2延期，打卡功能前端模拟）
9. **故事015-11**：高级功能与优化（P2优先级，后期优化）
10. **故事015-12**：API文档与测试完善（冗余，基础设施已覆盖）
11. **按模块分组**：同一模块的扩展建议由同一开发者完成，确保一致性

---

**故事经理交接说明：**

请为这个人才小程序API支持史诗开发详细用户故事。关键考虑：

- 这是对现有allin系统移植模块的API扩展，技术栈：TypeScript、Hono、Zod OpenAPI、TypeORM、PostgreSQL
- 集成点：史诗7,8,9,10移植的allin系统API模块（channel、company、disability_person、order、platform、salary等）
- 集成点：史诗012的企业用户认证模式，扩展人才用户认证
- 现有模式：遵循现有模块的API设计模式、数据库schema模式
- 关键兼容要求：不影响现有API接口，数据库schema变化保持向后兼容
- 每个故事必须验证现有功能保持完整

史诗应在保持系统兼容性的同时，为人才用户提供完整的API支持，为后续人才小程序功能实现奠定基础。