# 史诗012 - 用人方小程序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等）
- **数据库现状**：PostgreSQL数据库包含19个业务表，已支持核心业务数据存储

**数据库分析发现：**
- **企业用户认证缺失**：`users2`表只有admin用户，缺乏企业用户与`employer_company`表的关联
- **视频管理基础存在**：`order_person_asset`表已支持文件关联，但`asset_type`枚举需要扩展以支持工资视频、个税视频、打卡视频、工作视频等类型
- **数据统计需要实时计算**：无专门统计表，需要基于`disabled_person`、`employment_order`、`order_person`等表实时计算
- **年龄统计字段缺失**：`disabled_person`表只有`age`字段，缺乏`birth_date`字段用于准确年龄统计
- **个人征信信息存储**：通过`disabled_bank_card.file_id`关联`files`表存储个人征信截图
- **企业统计可基于现有表**：`employer_company`、`employment_order`、`order_person`表已包含必要关联关系

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

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

### 增强详情

**新增/变更内容：**
补充用人方小程序所需的9大类API接口，包括：
1. 数据库schema扩展：添加`birth_date`字段、扩展`asset_type`枚举、添加`company_id`关联字段
2. 企业用户认证API：支持企业用户手机号密码登录、获取企业用户信息
3. 企业统计API：企业概览统计、企业维度人才统计
4. 人才扩展API：企业专用人才列表查询、企业专用人才详情查询、工作历史查询、薪资历史查询、个人征信信息查询、视频关联查询
5. 订单统计API：打卡数据统计、视频统计、企业维度订单查询
6. 数据统计API：残疾类型分布、性别分布、年龄分布、户籍分布、在职状态统计、薪资分布
7. 视频管理API：视频分类管理、企业维度视频查询（个人维度已在故事012-03实现）、批量下载功能
8. 系统设置API：账号信息管理、安全设置、消息通知设置（P2 - 延期，后期优化）
9. API文档与测试：OpenAPI文档、TypeScript类型定义、单元测试（冗余 - 基础设施已覆盖）

**API路径约定：**
所有用人方小程序的API路径统一使用 `api/v1/yongren` 前缀，与现有管理后台的API路径做区分。例如：
- 企业用户登录：`POST /api/v1/yongren/auth/login`
- 企业概览统计：`GET /api/v1/yongren/company/overview`
- 企业专用人才列表：`GET /api/v1/yongren/disability-person`
- 企业专用人才详情：`GET /api/v1/yongren/disability-person/{id}`
- 人才工作历史：`GET /api/v1/yongren/disability-person/{id}/work-history`

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

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

## 故事列表

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

**故事概览：**
本史诗包含14个故事，其中12个为核心故事（012-01到012-05、012-08到012-15），1个延期故事（012-06），1个冗余故事（012-07）。核心故事已实现11个，剩余1个待实现。

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

**任务列表：**

注：数据库迁移脚本将在上线前统一生成，开发阶段通过TypeORM自动同步。
1. 在`disabled_person`表添加可为空的`birth_date`字段（DATE类型），用于准确年龄统计
2. 扩展`order_person_asset`表的`asset_type`枚举，新增视频类型：`salary_video`（工资视频）、`tax_video`（个税视频）、`checkin_video`（打卡视频）、`work_video`（工作视频）
3. 在`users2`表添加可为空的`company_id`字段（外键引用`employer_company.company_id`），建立企业用户关联
4. 更新对应的TypeORM实体定义
5. 验证现有数据不受影响，新增字段可为空

**验收标准：**
- [x] `disabled_person`表成功添加`birth_date`字段，现有记录该字段值为NULL
- [x] `order_person_asset`表的`asset_type`枚举扩展完成，新增视频类型枚举值
- [x] `users2`表成功添加`company_id`字段，现有admin用户的该字段值为NULL
- [x] TypeORM实体定义更新完成
- [x] 现有业务功能不受影响，测试通过（故事012.001已实现）

### 故事012-02：企业用户认证API扩展
**背景：** 现有auth-module仅支持管理员用户认证，需要扩展以支持企业用户手机号密码登录和企业信息关联。

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

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

### 故事012-03：企业统计与人才扩展API
**背景：** 企业需要查看概览统计和人才详细信息，现有company-module和disability-module需要扩展聚合查询接口。

**任务列表：**
1. **企业统计API**（company-module扩展）：
   - 基于`employer_company`、`employment_order`、`order_person`表实时计算企业概览统计
   - 接口返回：在职人员数、进行中订单数、已完成订单数、累计订单数
   - 企业维度人才统计：分配人才列表、人才状态分布

2. **人才扩展API**（disability-module扩展）：
   - 工作历史查询：基于`order_person`表查询个人的历史工作记录（关联`employment_order`表）
   - 薪资历史查询：基于`order_person.salary_detail`字段和`order`表查询历史薪资记录
   - 个人征信信息查询：基于`disabled_bank_card.file_id`关联`files`表获取征信截图信息
   - 视频关联查询：基于`order_person_asset`表查询关联的视频文件（按扩展的asset_type分类）

3. 添加适当的数据库索引优化查询性能
4. 编写单元测试和集成测试

**验收标准：**
- [x] 企业概览统计接口返回正确的在职人员数、订单数等数据
- [x] 企业维度人才统计接口返回分配人才列表和状态分布
- [x] 人才工作历史查询接口返回个人的历史工作记录
- [x] 人才薪资历史查询接口返回历史薪资记录
- [x] 个人征信信息查询接口返回征信截图信息
- [x] 视频关联查询接口返回按类型分类的关联视频列表
- [x] 查询性能优化，添加必要的数据索引
- [x] 所有接口通过单元测试和集成测试

### 故事012-04：订单统计与数据统计API
**背景：** 企业需要订单管理数据统计和整体数据可视化统计，需要扩展order-module和创建统计模块。

**任务列表：**
1. **订单统计API**（order-module扩展）：
   - 打卡数据统计：基于`order_person_asset`表（asset_type为`checkin_video`）统计打卡视频数量
   - 视频统计：按视频类型（工资、个税、打卡、工作）分类统计
   - 企业维度订单查询：支持按企业ID过滤订单列表，包含订单状态、人员关联等详细信息

2. **数据统计API**（创建统计模块或扩展现有模块）：
   - 残疾类型分布：基于`disabled_person.disability_type`统计
   - 性别分布：基于`disabled_person.gender`统计
   - 年龄分布：基于新增的`birth_date`字段计算年龄分组（18-25、26-35、36-45、46+）
   - 户籍分布：基于`disabled_person.household_province`和`household_city`统计
   - 在职状态统计：基于`disabled_person.job_status`统计
   - 薪资分布：基于`order_person.salary_detail`统计薪资范围分布

3. 优化实时统计查询性能，添加汇总视图或物化视图（如需要）
4. 编写单元测试和集成测试

**验收标准：**
- [x] 订单打卡数据统计接口返回正确的打卡视频数量
- [x] 订单视频统计接口按类型分类返回统计结果
- [x] 企业维度订单查询接口支持按企业ID过滤，返回完整订单信息
- [x] 所有数据统计接口返回正确的统计结果
- [x] 年龄统计基于`birth_date`字段准确计算
- [x] 统计查询性能良好，大数据量下响应时间可接受
- [x] 所有接口通过单元测试和集成测试

### 故事012-05：视频管理API扩展
**背景：** 企业需要管理各类工作视频，视频作为订单附件存储在`order_person_asset`表中（关联`files`表）。个人维度视频查询已在故事012-03中实现（`GET /disability-person/{id}/videos`），本故事主要实现企业维度视频查询和批量下载功能。

**技术说明：** 视频作为订单人员资产（`order_person_asset`表）存储，`asset_type`枚举已扩展支持：`salary_video`（工资视频）、`tax_video`（个税视频）、`checkin_video`（打卡视频）、`work_video`（工作视频）。不需要修改file-module，视频文件通过`file_id`关联`files`表。

**任务列表：**
1. **企业维度视频查询API**（在order-module或company-module中实现）：
   - 基于企业ID查询关联的所有视频（通过`employment_order`→`order_person`→`order_person_asset`关联链）
   - 支持按`asset_type`视频类型过滤查询
   - 支持分页和排序（按上传时间、视频类型等）

2. **批量下载功能**：
   - 支持按企业维度批量下载视频文件（返回文件URL列表或生成临时打包文件）
   - 支持按个人维度批量下载个人关联的视频
   - 实现批量下载接口，支持选择多个视频文件下载

3. **视频状态管理增强**：
   - 在`order_person_asset`表添加`status`字段（枚举：`pending`待审核、`verified`已验证、`rejected`已拒绝）
   - 添加视频审核状态查询和更新接口（如需要）

4. **性能优化**：
   - 添加企业维度视频查询的数据库索引优化
   - 优化批量下载查询性能

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

**验收标准：**
- [x] 企业维度视频查询接口返回企业关联的所有视频，支持按视频类型过滤
- [x] 批量下载功能支持按企业或个人维度下载多个视频文件（返回文件URL列表）
- [x] 视频状态管理功能完整（如实现状态字段）
- [x] 视频查询性能优化，添加必要的数据索引
- [x] 所有接口通过单元测试和集成测试

### 故事012-06：系统设置API（P2 - 后期优化）
**背景：** 企业用户账号信息在管理后台配置，用户无需自助修改手机号、密码等。登录设备管理、登录日志查询、消息通知设置等功能不是当前用人方小程序MVP必需功能，可延期到后期优化阶段实现。

**优先级说明：** P2优先级，非当前MVP必需功能。企业账号由管理员在管理后台创建和维护，用户使用固定账号登录。安全设置和消息通知功能可在后续版本中根据用户反馈逐步添加。

**任务列表：**
1. （延期）添加企业用户专属的设置接口：
   - 账号信息管理：修改手机号、密码等
   - 安全设置：登录设备管理、登录日志查询
   - 消息通知设置：订单状态通知、人才分配通知等开关设置

2. （延期）创建或扩展现有的设置模块
3. （延期）实现设置数据的持久化存储
4. （延期）添加设置变更的历史记录
5. （延期）编写单元测试和集成测试

**验收标准：**
- [ ] （延期）账号信息管理接口支持修改手机号、密码等
- [ ] （延期）安全设置接口提供登录设备管理和登录日志查询
- [ ] （延期）消息通知设置接口支持各类通知的开关控制
- [ ] （延期）设置数据正确持久化存储
- [ ] （延期）设置变更历史记录完整
- [ ] （延期）所有接口通过单元测试和集成测试

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

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

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

### 故事012-08：路由路径规范修复（已完成）
**背景：** 故事012-02和012-03实现的企业用户认证API、企业统计与人才扩展API中，路由路径在模块包内包含了`/api/v1/yongren`前缀，违反了架构规范。根据项目标准，模块包内路由定义不应包含API前缀，前缀应在server包注册时统一添加。

**任务列表：**
1. 修复企业用户认证API路由路径：移除auth模块中`enterprise-login.route.ts`、`enterprise-logout.route.ts`、`enterprise-me.route.ts`中的`/api/v1/yongren`前缀
2. 修复企业统计API路由路径：移除`company-statistics.route.ts`中的`/api/v1/yongren`前缀
3. 修复人才扩展API路由路径：移除`person-extension.route.ts`中的`/api/v1/yongren`前缀
4. 验证server包中的路由注册正确添加`/api/v1/yongren`前缀
5. 更新集成测试，验证路由路径正确性
6. 确保遵循模块包内不需要basepath的架构规范

**验收标准：**
- [x] 企业用户认证API路由路径移除`/api/v1/yongren`前缀，改为`/auth/login`、`/auth/logout`、`/auth/me`
- [x] 企业统计API路由路径移除`/api/v1/yongren`前缀，改为`/company/overview`和`/company/{id}/talents`
- [x] 人才扩展API路由路径移除`/api/v1/yongren`前缀，改为`/disability-person/{id}/*`格式
- [x] server包中的路由注册正确使用`api.route('/api/v1/yongren/...', ...)`
- [x] 所有集成测试通过，验证路由路径正确性
- [x] 遵循模块包内不需要basepath的架构规范

### 故事012-09：管理后台企业用户配置表单扩展
**背景：** 故事012-01已在`users2`表添加`company_id`字段支持企业用户关联，但管理后台的用户管理表单中缺少配置用户所属企业的交互界面。需要扩展user-management-ui包，在用户创建和编辑表单中添加企业选择字段，支持管理员为用户分配企业关联。

**任务列表：**
1. **获取企业列表API集成**：
   - 调研现有企业列表API端点（company-module）
   - 在user-management-ui中创建企业列表查询hook
   - 实现企业数据格式化用于下拉选择框
2. **扩展用户创建表单**：
   - 在user-management-ui的创建表单中添加企业选择字段
   - 使用Select组件实现企业下拉选择
   - 添加表单验证，企业ID必须为数字或NULL
   - 确保companyId字段正确传递给创建用户API
3. **扩展用户编辑表单**：
   - 在编辑表单中添加企业选择字段
   - 初始化表单时加载当前用户的companyId值
   - 确保更新用户API正确接收companyId字段
4. **扩展用户列表显示**：
   - 在用户列表表格中添加"关联企业"列
   - 显示企业名称（如企业信息不可用则显示企业ID）
   - 确保分页和筛选功能不受影响
5. **测试与验证**：
   - 编写单元测试验证企业选择字段功能
   - 编写集成测试验证表单提交和数据显示
   - 运行现有测试确保无回归
   - 测试企业选择字段的清空功能

**验收标准：**
- [x] 用户创建表单中包含企业选择字段（下拉选择框），可选值为系统中的企业列表
- [x] 用户编辑表单中包含企业选择字段，显示当前用户关联的企业并可修改
- [x] 用户列表显示中可查看用户关联的企业信息
- [x] 企业选择字段支持清空（设置为NULL），表示用户不关联任何企业
- [x] 表单验证正确，企业ID必须为有效的企业ID或NULL
- [x] 所有现有功能不受影响，测试通过

### 故事012-10：近期分配人才查询API
**背景：** 企业用户需要查看近期分配的人才（最近30天入职），以便快速了解最新的人力资源动态，及时跟进新员工的管理和培养。

**任务列表：**
1. **近期分配人才查询API开发**（company-module扩展）：
   - 创建近期分配人才查询路由：`company-recent-allocations.route.ts`，路径为`/api/v1/yongren/company/allocations/recent`
   - 在`company.service.ts`中添加`getRecentAllocations`方法，基于`order_person`表关联`employment_order`和`disabled_person`表查询近期分配人才
   - 查询逻辑：筛选`order_person.join_date`在最近30天内，且`order_person.work_status = 'working'`的记录
   - 支持limit参数（可选，默认5条），按`join_date`降序排列
   - 验证企业用户权限：用户只能查询自己企业（`employment_order.company_id`匹配用户`company_id`）的数据
   - 添加数据库索引优化查询性能（`order_person.join_date`、`order_person.work_status`等字段索引）
   - 创建相应的Zod Schema验证：`RecentAllocationsSchema`

2. **API路由集成和认证中间件配置**：
   - 在`company-statistics.route.ts`或新建路由文件中集成近期分配人才查询路由
   - 配置企业用户认证中间件（使用故事012.002实现的`enterpriseAuthMiddleware`）
   - 验证接口需要企业用户权限（通过`company_id`验证）
   - 确保API路径前缀符合约定：`/api/v1/yongren/`
   - 统一错误处理，使用标准错误响应格式

3. **数据库性能优化**：
   - 分析查询性能，识别需要添加索引的字段
   - 在相关表上添加索引：`order_person.join_date`、`order_person.work_status`、`employment_order.company_id`
   - 考虑添加复合索引优化多表关联查询（`order_person.order_id` + `join_date`）
   - 验证索引效果，确保查询响应时间符合要求（< 200ms）

4. **集成测试开发**：
   - 在公司模块集成测试中新增测试用例：`company-recent-allocations.integration.test.ts`
   - 测试近期分配人才查询接口的各种场景：有数据、无数据、不同limit参数
   - 测试企业用户权限验证：非企业用户无法访问接口
   - 测试不同企业用户只能访问自己企业的数据
   - 测试错误场景：无效的参数等
   - 确保测试覆盖率≥60%（集成测试要求）

5. **API文档完善**：
   - 为新增接口添加OpenAPI文档注释
   - 生成TypeScript类型定义文件，供前端使用
   - 更新模块的README文档，说明新增的近期分配人才查询功能
   - 验证所有接口的OpenAPI文档生成正确

**验收标准：**
- [x] 近期分配人才查询接口返回正确的近期分配人才列表（默认最近30天）
- [x] 接口支持可选的limit参数控制返回记录数
- [x] 返回数据包含人才基本信息：姓名、入职日期、订单名称、工作状态
- [x] 企业用户只能访问自己关联企业的数据
- [x] 查询性能优化，添加必要的数据库索引
- [x] 接口通过单元测试和集成测试
- [x] API文档完善，包含OpenAPI文档注释

### 故事012-11：企业专用人才管理API
**背景：** 当前用人方小程序使用通用人才API接口（`/api/v1/disability`），该接口返回所有人才数据，未按企业过滤。而企业专用API（`/api/v1/yongren/disability-person`）只包含扩展接口（工作历史、薪资历史、征信信息、视频关联），缺少基础的人才列表和详情接口。需要补充企业专用的人才列表和详情API，确保企业用户只能访问自己企业的人才数据。

**任务列表：**
1. **企业专用人才列表API开发**（disability-module扩展）：
   - 在`person-extension.route.ts`中添加企业专用人才列表路由：`GET /`，路径为`/api/v1/yongren/disability-person`
   - 在`disabled-person.service.ts`中添加`findAllForCompany`方法，基于`order_person`表关联`employment_order`和`disabled_person`表查询企业人才
   - 查询逻辑：筛选`order_person`表中关联到该企业（`employment_order.company_id`匹配用户`company_id`）的残疾人员工
   - 支持搜索（姓名、残疾证号）、筛选（残疾类型、状态）、分页等参数
   - 验证企业用户权限：用户只能查询自己企业（`employment_order.company_id`匹配用户`company_id`）的数据
   - 添加数据库索引优化查询性能（`order_person.person_id`、`employment_order.company_id`等字段索引）
   - 创建相应的Zod Schema验证：`CompanyPersonListSchema`

2. **企业专用人才详情API开发**（disability-module扩展）：
   - 在`person-extension.route.ts`中添加企业专用人才详情路由：`GET /{id}`，路径为`/api/v1/yongren/disability-person/{id}`
   - 在`disabled-person.service.ts`中添加`findOneForCompany`方法，基于`order_person`表关联验证人员是否属于该企业
   - 查询逻辑：验证人员ID是否通过`order_person`表关联到该企业（使用现有的`validatePersonBelongsToCompany`方法）
   - 返回人员完整信息（包含关联的银行卡片、照片、备注、访问记录等）
   - 验证企业用户权限：用户只能访问自己企业的人员数据

3. **API路由集成和认证中间件配置**：
   - 在`person-extension.route.ts`中集成企业专用人才列表和详情路由
   - 配置企业用户认证中间件（使用故事012.002实现的`enterpriseAuthMiddleware`）
   - 验证接口需要企业用户权限（通过`company_id`验证）
   - 确保API路径前缀符合约定：`/api/v1/yongren/disability-person`
   - 统一错误处理，使用标准错误响应格式
   - 更新server包中的路由注册（`enterpriseDisabilityApiRoutes`已存在，无需修改）

4. **数据库性能优化**：
   - 分析查询性能，识别需要添加索引的字段
   - 在相关表上添加索引：`order_person.person_id`、`order_person.order_id`、`employment_order.company_id`
   - 考虑添加复合索引优化多表关联查询（`employment_order.company_id` + `order_person.person_id`）
   - 验证索引效果，确保查询响应时间符合要求（< 200ms）

5. **集成测试开发**：
   - 在残疾人模块集成测试中新增测试用例：`person-extension.integration.test.ts`（扩展现有测试）
   - 测试企业专用人才列表接口的各种场景：有数据、无数据、搜索、筛选、分页
   - 测试企业专用人才详情接口：正常访问、人员不存在、人员不属于该企业
   - 测试企业用户权限验证：非企业用户无法访问接口
   - 测试不同企业用户只能访问自己企业的数据
   - 测试错误场景：无效的参数等
   - 确保测试覆盖率≥60%（集成测试要求）

6. **API文档完善**：
   - 为新增接口添加OpenAPI文档注释
   - 生成TypeScript类型定义文件，供前端使用
   - 更新模块的README文档，说明新增的企业专用人才管理功能
   - 验证所有接口的OpenAPI文档生成正确

**验收标准：**
- [x] 企业专用人才列表接口返回正确的企业人才列表，支持搜索、筛选、分页
- [x] 企业专用人才详情接口返回人员完整信息
- [x] 企业用户只能访问自己关联企业的人员数据
- [x] 查询性能优化，添加必要的数据库索引
- [x] 接口通过单元测试和集成测试
- [x] API文档完善，包含OpenAPI文档注释
- [ ] 前端mini项目可无缝切换到企业专用API接口（前端集成在后续故事中实现）

### 故事012-12：补充企业专用人才列表API的出生日期和薪资字段
**背景：** 在企业专用人才列表API（`findAllForCompany`方法）的实现中，当前SELECT语句缺少`birth_date`和`salary_detail`字段，导致用人方小程序的人才列表页无法正确显示年龄和薪资信息。虽然数据库schema已在故事012-01中扩展了`disabled_person.birth_date`字段，`order_person.salary_detail`字段也已存在，但API响应中未包含这些字段。

**任务列表：**
1. **更新SELECT语句和字段映射**（disability-module扩展）：
   - 在`disabled-person.service.ts`的`findAllForCompany`方法中，更新SELECT语句包含缺失的字段：
     - 添加`person.birth_date`字段，用于计算年龄
     - 添加`op.salary_detail`字段，用于显示薪资信息
   - 更新查询结果映射，确保`birthDate`和`salaryDetail`字段正确包含在返回数据中
   - 验证字段别名与TypeORM实体定义一致

2. **更新Schema验证和类型定义**：
   - 更新`CompanyPersonListSchema`Zod Schema，添加`birthDate`和`salaryDetail`字段验证
   - 更新相应的TypeScript接口类型定义，确保类型安全
   - 验证字段可为空，兼容现有数据

3. **前端数据映射更新**：
   - 在用人方小程序前端（人才管理UI包）中更新字段映射逻辑：
     - 使用`birthDate`字段计算年龄（如字段不存在或为null则显示"未知岁"）
     - 使用`salaryDetail`字段显示薪资（如字段不存在或为0则显示"待定"）
   - 更新人才列表卡片组件，正确显示年龄和薪资信息

4. **集成测试更新**：
   - 在`person-extension.integration.test.ts`中更新测试用例
   - 验证API响应包含`birthDate`和`salaryDetail`字段
   - 测试边界条件：字段为空、字段为null的情况
   - 确保测试覆盖率≥60%

5. **数据库查询性能验证**：
   - 验证添加新字段后查询性能不受影响（< 200ms）
   - 确保现有索引仍然有效
   - 如有需要，添加`birth_date`字段的索引优化年龄相关查询

**验收标准：**
- [x] 企业专用人才列表API响应包含`birthDate`和`salaryDetail`字段
- [x] 前端人才列表页正确显示年龄（基于`birthDate`计算）和薪资信息
- [x] 字段可为空，兼容现有数据（无`birthDate`或`salaryDetail`的记录）
- [x] 查询性能不受影响，响应时间<200ms
- [x] 集成测试覆盖新增字段的各种场景
- [x] API文档更新，包含新增字段说明

### 故事012-13：工作状态统一优化 - 基于order_person.work_status的长期方案
**背景：** 在当前的企业专用人才API中，工作状态筛选存在数据类型不匹配问题：前端传递中文状态（"在职"、"待入职"、"离职"），Schema验证为字符串，但数据库`disabled_person.job_status`字段为smallint类型（0-未在职，1-已在职）。短期修复通过状态映射解决了基本筛选功能，但"待入职"和"离职"都映射到0，无法精确区分。本故事实施长期理想方案：使用`order_person.work_status`字段（enum类型：'not_working'、'pre_working'、'working'、'resigned'）作为统一的工作状态源，解决状态不一致问题。

**技术优势分析：**
1. **语义准确性**：`order_person.work_status`直接记录人员在订单中的工作状态，更准确反映业务实际
2. **状态完整性**：已有完整的4个状态值，覆盖前端所需的3个状态（'pre_working'→"待入职"、'working'→"在职"、'resigned'→"离职"）
3. **类型一致性**：enum类型与Schema验证类型匹配，无需复杂映射
4. **已有基础设施**：`WorkStatus`枚举、`WorkStatusLabels`中文映射已存在，可直接使用

**关键挑战：**
1. **关联查询复杂性**：需要从`order_person`表获取最新工作状态（一人可能有多条记录）
2. **状态转换逻辑**：`WorkStatus`枚举值（'working'）需要转换为前端期望的中文状态（"在职"）
3. **性能影响**：关联查询可能影响性能，需要优化索引

**任务列表：**

1. **查询逻辑重构**（disability-module扩展）：
   - 在`disabled-person.service.ts`的`findAllForCompany`方法中，修改查询逻辑：
     - 使用`order_person.work_status`而不是`disabled_person.job_status`作为工作状态源
     - 获取人员最新的`order_person`记录（按`join_date`降序）来确定当前工作状态
     - 在SELECT语句中添加`MAX(op.work_status)`或通过子查询获取最新状态
   - 更新结果映射逻辑，将`WorkStatus`枚举值转换为中文状态
     - 'working' → "在职"
     - 'pre_working' → "待入职"
     - 'resigned' → "离职"
     - 'not_working' → "未就业"（作为后备状态）

2. **筛选条件优化**：
   - 修改`jobStatus`筛选逻辑，直接使用`order_person.work_status`进行过滤
   - 支持前端中文状态到`WorkStatus`枚举值的映射：
     - "在职" → 'working'
     - "待入职" → 'pre_working'
     - "离职" → 'resigned'
   - 更新Schema验证，明确状态映射关系

3. **人才详情API统一**：
   - 在`findOneForCompany`方法中，同样使用`order_person.work_status`作为工作状态源
   - 获取人员最新的订单关联记录，确定当前工作状态
   - 保持与人才列表API一致的状态转换逻辑

4. **数据库性能优化**：
   - 分析现有索引：`order_person`表已有`['personId', 'workStatus']`、`['joinDate']`等索引
   - 考虑添加复合索引优化最新状态查询：`['personId', 'joinDate', 'workStatus']`
   - 验证查询性能，确保响应时间<200ms

5. **Schema和类型更新**：
   - 更新`CompanyPersonListQuerySchema`，明确状态筛选选项和映射关系
   - 更新`CompanyPersonListSchema`和`CompanyPersonDetailSchema`，使用一致的枚举类型
   - 生成准确的TypeScript类型定义，确保前端类型安全

6. **前端状态显示统一**：
   - 更新人才管理UI包中的状态显示逻辑，使用新的状态值
   - 确保人才列表页、人才详情页的状态标签显示一致
   - 更新状态筛选组件的选项说明

7. **集成测试全面覆盖**：
   - 在`person-extension.integration.test.ts`中新增测试用例，覆盖所有状态场景
   - 测试状态筛选的精确性："待入职"和"离职"筛选应返回不同结果
   - 测试边界条件：无订单关联的人员状态（显示"未就业"或空值）
   - 测试性能：大数据量下的状态查询性能
   - 确保测试覆盖率≥60%

8. **兼容性保障**：
   - 验证现有数据迁移：所有已有关联订单的人员应有正确的`work_status`值
   - 对于无订单关联的人员，提供合理的默认状态（空值或'not_working'）
   - 确保企业统计中的在职状态分布统计仍能正常工作

**验收标准：**
- [ ] 人才列表API的"在职"筛选精确返回`work_status='working'`的人员
- [ ] 人才列表API的"待入职"筛选精确返回`work_status='pre_working'`的人员
- [ ] 人才列表API的"离职"筛选精确返回`work_status='resigned'`的人员
- [ ] 人才详情页工作状态显示准确，基于最新的`order_person.work_status`
- [ ] 状态映射完整：前端中文状态、Schema验证、数据库枚举值保持一致
- [ ] 查询性能优化，添加必要的数据库索引，响应时间<200ms
- [ ] 集成测试全面覆盖所有状态场景，测试覆盖率≥60%
- [ ] API文档更新，包含完整的状态映射说明
- [ ] 现有功能不受影响，企业统计等依赖工作状态的功能仍能正常工作

**技术决策说明：**

选择`order_person.work_status`而不是扩展`disabled_person.job_status`的原因：
1. **业务逻辑更准确**：工作状态本质是人员在订单中的状态，不是人员的固有属性
2. **状态历史可追溯**：`order_person`表记录了状态变化历史，`disabled_person.job_status`只是当前快照
3. **已有完善设施**：`WorkStatus`枚举体系完整，有对应的中文映射和业务描述
4. **减少数据冗余**：避免在`disabled_person`和`order_person`表中维护相同状态信息

**回滚保障：**
1. 保持`disabled_person.job_status`字段不变，作为备用状态源
2. 实施过程中可分阶段验证，确保每一步都可回退
3. 完整的测试覆盖，确保任何问题都能及时发现

### 故事012-14：重构订单模块路由，分离通用订单API和企业专用订单API
**背景：** 在当前的订单模块实现中，`orderRoutes`实例混合了通用CRUD路由（使用`authMiddleware`）和企业专用路由（使用`enterpriseAuthMiddleware`），导致前端UI包使用`orderRoutes`类型创建企业专用API客户端时，会包含通用CRUD路由，存在权限泄露风险。本故事基于auth-module的正确模式（分离`authRoutes`和`enterpriseAuthRoutes`），重构订单模块路由，实现清晰的职责分离。

**问题分析：**
1. **当前状态**：`order-custom.routes.ts`文件混合了12个通用CRUD路由和6个企业专用路由
2. **风险**：前端使用`orderRoutes`类型时包含企业专用路由，存在权限泄露风险
3. **正确参考**：auth-module已正确分离`authRoutes`（通用）和`enterpriseAuthRoutes`（企业专用）

**任务列表：**
1. **路由重构**：在`order-module/src/routes/index.ts`中创建独立的`enterpriseOrderRoutes`实例，只包含企业专用路由
2. **职责分离**：确保`orderRoutes`实例只包含通用CRUD路由，移除企业专用路由
3. **类型导出**：导出两个路由实例：`orderRoutes`（通用）和`enterpriseOrderRoutes`（企业专用）
4. **server包更新**：更新server包中的路由注册，确保企业专用订单API使用正确的`enterpriseOrderRoutes`
5. **前端类型更新**：更新故事011.004中的API客户端示例，使用`enterpriseOrderRoutes`类型
6. **测试更新**：更新集成测试验证路由分离和权限控制

**验收标准：**
- [x] `orderRoutes`实例只包含通用CRUD路由，使用`authMiddleware`中间件
- [x] `enterpriseOrderRoutes`实例包含所有企业专用路由，使用`enterpriseAuthMiddleware`中间件
- [x] 前端UI包可安全使用`enterpriseOrderRoutes`类型创建企业专用API客户端
- [x] 现有功能不受影响：管理后台订单功能（通用API）和企业用户小程序功能（企业专用API）继续正常工作
- [x] 路由类型定义正确导出，确保类型安全
- [x] 集成测试验证路由分离的正确性和权限控制

**技术决策说明：**
选择路由分离而非混合模式的原因：
1. **职责清晰**：通用API服务于管理后台，企业专用API服务于用人方小程序，两者权限模型不同
2. **类型安全**：前端UI包需要精确的类型定义，避免意外访问不合适的路由
3. **架构一致**：遵循auth-module的成功模式，保持项目架构一致性
4. **权限控制**：确保企业用户只能访问企业专用API，管理员可访问通用API

**兼容性保障：**
1. 保持现有API路径不变：通用API使用`/api/v1/order`，企业专用API使用`/api/v1/yongren/order`
2. 现有客户端无需修改路径，只需更新类型引用
3. 分阶段实施，验证每一步的向后兼容性

### 故事012-15：数据统计API安全修复与路由集成
**背景：** 在故事012.004已实现的数据统计API中存在安全漏洞和路由集成缺失问题：1) statistics-module和order-module的企业统计API接受`companyId`查询参数，允许覆盖认证用户的企业ID，违反企业数据隔离安全要求；2) statistics-module路由未在server包中注册，导致API端点实际不可用；3) server包未导出`EnterpriseStatisticsRoutes`类型，前端无法获得类型安全的API客户端。本故事修复这些安全和技术债务问题。

**问题分析：**
1. **安全漏洞**：统计API允许通过查询参数覆盖企业ID，违反"企业ID强制从认证用户的JWT token中获取"的安全要求（故事012.004第158-162行）
2. **路由缺失**：`@d8d/allin-statistics-module`已实现但未在server包注册，前端无法访问`/api/v1/yongren/statistics`路径
3. **类型缺失**：server包未导出`EnterpriseStatisticsRoutes`类型，影响前端类型安全
4. **文档不准确**：故事011.005中的API描述在安全要求和集成状态方面不准确

**任务列表：**
1. **修复statistics-module安全漏洞**：移除所有统计API的`companyId`查询参数，强制从认证token获取企业ID
2. **修复order-module企业统计API安全漏洞**：同样移除打卡统计、视频统计、企业订单查询中的`companyId`参数
3. **server包集成**：添加`@d8d/allin-statistics-module`依赖，注册`/api/v1/yongren/statistics`路由，导出`EnterpriseStatisticsRoutes`类型
4. **文档更新**：更新故事011.005文档，修正API规范中的安全要求和集成状态描述
5. **测试验证**：确保所有修复通过集成测试，验证企业数据隔离安全性

**验收标准：**
- [x] statistics-module所有统计API不再接受`companyId`查询参数，企业ID强制从认证用户的JWT token中获取
- [x] order-module企业统计API同样移除`companyId`查询参数，强制从认证token获取企业ID
- [x] statistics-module路由正确注册到server包，路径前缀为`/api/v1/yongren/statistics`
- [x] server包添加`@d8d/allin-statistics-module`依赖，并导出`EnterpriseStatisticsRoutes`类型
- [x] 更新故事011.005文档，修正API规范中不准确的安全要求和集成状态描述
- [x] 所有修复通过集成测试验证，确保企业数据隔离安全要求满足

**安全原则：**
1. **最小权限原则**：企业用户只能访问自己关联的企业数据
2. **安全默认原则**：默认拒绝，必须显式授权
3. **防御性编程**：验证所有输入，包括认证上下文
4. **向后兼容**：修复不应破坏现有API契约（响应格式不变）

**企业数据隔离实现：**
- 所有企业专用API使用`enterpriseAuthMiddleware`中间件验证
- 企业ID从JWT token的`company_id`字段获取，添加到context
- 统计查询通过`employment_order`→`order_person`→`disabled_person`关联链过滤
- 服务层验证查询结果的企业ID与用户企业ID匹配

## 史诗进度

**当前状态**：史诗核心功能基本完成，13个核心故事中12个已实现（012-01到012-05、012-08到012-12、012-14、012-15），为企业用户管理功能提供了完整的API支持。故事012-12已补充企业专用人才列表API的出生日期和薪资字段，解决人才列表页年龄和薪资显示问题。故事012-14已解决订单模块路由混合问题，实现通用订单API和企业专用订单API的清晰分离。故事012-15解决数据统计API安全漏洞和路由集成问题。新增故事012-13解决工作状态数据一致性问题，采用基于`order_person.work_status`的长期优化方案。故事012-06（系统设置API）延期至后期优化阶段，故事012-07（API文档与测试完善）作为基础设施任务已由各故事分别覆盖。

**故事完成状态**：
- [x] **故事012-01**：数据库schema扩展 - **已完成**（故事012.001已实现）
- [x] **故事012-02**：企业用户认证API扩展 - **已完成**（故事012.002已实现）
- [x] **故事012-03**：企业统计与人才扩展API - **已完成**（故事012.003已实现）
- [x] **故事012-08**：路由路径规范修复 - **已完成**（故事012.008已实现）
- [x] **故事012-04**：订单统计与数据统计API - **已完成**（故事012.004已实现）
- [x] **故事012-05**：视频管理API扩展 - **已完成**（故事012.005已实现）
- [x] **故事012-09**：管理后台企业用户配置表单扩展 - **已完成**（故事012.009已实现）
- [x] **故事012-10**：近期分配人才查询API - **已完成**（故事012.010已实现）
- [x] **故事012-11**：企业专用人才管理API - **已完成**（故事012.011已实现）
- [x] **故事012-12**：补充企业专用人才列表API的出生日期和薪资字段 - **已完成**
- [ ] **故事012-13**：工作状态统一优化 - 基于order_person.work_status的长期方案 - **待实现**
- [x] **故事012-14**：重构订单模块路由，分离通用订单API和企业专用订单API - **已完成**（故事012.014已实现）
- [x] **故事012-15**：数据统计API安全修复与路由集成 - **已完成**
- [ ] **故事012-06**：系统设置API - **P2 - 延期**（后期优化）
- [ ] **故事012-07**：API文档与测试完善 - **冗余**（基础设施已覆盖）

**总体进度**：12/15 故事完成（80%）
**MVP进度**：12/13 核心故事完成（92%，排除012-06延期和012-07冗余，包含012-13、012-14、012-15）

**最近更新**：2025-12-23 - 添加故事012-15（数据统计API安全修复与路由集成）：修复statistics-module和order-module企业统计API的安全漏洞（移除`companyId`查询参数），完成server包路由注册和类型导出，确保企业数据隔离安全性。2025-12-21 - 故事012-14完成：重构订单模块路由，分离通用订单API和企业专用订单API，解决路由混合导致的权限泄露风险，确保前端UI包的类型安全。2025-12-21 - 添加故事012-14（重构订单模块路由）：实现通用订单API和企业专用订单API的清晰分离，解决路由混合导致的权限泄露风险，确保前端UI包的类型安全。2025-12-20 - 添加故事012-13（工作状态统一优化）：采用基于`order_person.work_status`的长期优化方案，解决前端中文状态、Schema验证、数据库类型不匹配问题，实现"在职"、"待入职"、"离职"状态的精确筛选和显示。2025-12-20 - 故事012-12完成：企业专用人才列表API的出生日期和薪资字段已补充，人才列表页年龄和薪资显示问题已解决。2025-12-20 - 添加故事012-12（补充企业专用人才列表API的出生日期和薪资字段）以解决人才列表页年龄和薪资显示"未知岁"和"待定"的问题。2025-12-19 - 故事011.003企业专用API使用修复：人才详情页已改为使用enterpriseDisabilityClient企业专用API，确保企业用户数据安全隔离。2025-12-18 - 故事012.011完成，企业专用人才管理API已实现。2025-12-18 - 故事012.010完成，近期分配人才查询API已实现。2025-12-18 - 故事012.009完成，管理后台企业用户配置表单扩展已实现。2025-12-18 - 添加故事012-09（管理后台企业用户配置表单扩展）以解决管理后台用户表单缺失企业选择字段的问题。2025-12-17 - 故事012.005完成，视频管理API扩展已实现。史诗012核心功能全部完成。故事012.004完成，订单统计与数据统计API已实现。史诗012故事优先级调整：故事012-08标记为已完成；故事012-06调整为P2延期（系统设置API）；故事012-07标记为冗余（API文档与测试完善）；故事012-05重新设计（基于order_person_asset实体）。故事012.003完成，企业统计与人才扩展API已实现；故事012.008创建并完成，路由路径规范修复。

---

## 兼容性要求

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

## 风险缓解

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

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

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

## 完成定义

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

## 依赖关系

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

## 测试策略

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

## 执行顺序建议

1. **先完成故事012-01**：数据库schema扩展是基础，其他故事依赖（已完成）
2. **然后完成故事012-02、012-03、012-08**：企业用户认证、统计、路由规范修复（已完成）
3. **故事012-04和012-05已完成**：订单统计与数据统计API、视频管理API扩展已全部实现
4. **故事012-09已完成**：管理后台企业用户配置表单扩展已实现
5. **故事012-10已完成**：近期分配人才查询API已实现
6. **故事012-11已完成**：企业专用人才管理API已实现
7. **故事012-12已完成**：补充企业专用人才列表API的出生日期和薪资字段已实现
8. **新增故事012-13**：工作状态统一优化 - 基于order_person.work_status的长期方案（待实现）
9. **故事012-14已完成**：重构订单模块路由，分离通用订单API和企业专用订单API
10. **故事012-15已完成**：数据统计API安全修复与路由集成（已完成）
11. **延期故事012-06**：系统设置API（P2优先级，后期优化）
12. **基础设施故事012-07**：API文档与测试完善（冗余，基础设施已覆盖）
13. **按模块分组**：同一模块的扩展建议由同一开发者完成，确保一致性

---

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

请为这个API补充史诗开发详细用户故事。关键考虑：

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

史诗应在保持系统兼容性的同时，为企业用户管理功能提供完整的API支持，为史诗011（用人方小程序功能实现）奠定基础。