mini-starter/docs/prd/epic-012-api-supplement-for-employer-mini-program.md

史诗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接口时需确保路径前缀正确。

故事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. 验证现有数据不受影响，新增字段可为空

验收标准：

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

故事012-02：企业用户认证API扩展

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

任务列表：

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

验收标准：

• 企业用户可使用手机号和密码成功登录
• 企业用户登录后可获取包含企业详情的用户信息
• 企业用户可成功退出登录
• 认证中间件正确识别企业用户身份
• 企业用户权限验证逻辑正确
• 所有新增接口通过单元测试和集成测试
• 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. 编写单元测试和集成测试

验收标准：

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

故事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. 编写单元测试和集成测试

验收标准：

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

故事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. 编写单元测试和集成测试

验收标准：

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

故事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的架构规范

验收标准：

• 企业用户认证API路由路径移除/api/v1/yongren前缀，改为/auth/login、/auth/logout、/auth/me
• 企业统计API路由路径移除/api/v1/yongren前缀，改为/company/overview和/company/{id}/talents
• 人才扩展API路由路径移除/api/v1/yongren前缀，改为/disability-person/{id}/*格式
• server包中的路由注册正确使用api.route('/api/v1/yongren/...', ...)
• 所有集成测试通过，验证路由路径正确性
• 遵循模块包内不需要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. 测试与验证：
   • 编写单元测试验证企业选择字段功能
   • 编写集成测试验证表单提交和数据显示
   • 运行现有测试确保无回归
   • 测试企业选择字段的清空功能

验收标准：

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

故事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文档生成正确

验收标准：

• 近期分配人才查询接口返回正确的近期分配人才列表（默认最近30天）
• 接口支持可选的limit参数控制返回记录数
• 返回数据包含人才基本信息：姓名、入职日期、订单名称、工作状态
• 企业用户只能访问自己关联企业的数据
• 查询性能优化，添加必要的数据库索引
• 接口通过单元测试和集成测试
• 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文档生成正确

验收标准：

• 企业专用人才列表接口返回正确的企业人才列表，支持搜索、筛选、分页
• 企业专用人才详情接口返回人员完整信息
• 企业用户只能访问自己关联企业的人员数据
• 查询性能优化，添加必要的数据库索引
• 接口通过单元测试和集成测试
• 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验证和类型定义：

   • 更新CompanyPersonListSchemaZod 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字段的索引优化年龄相关查询

验收标准：

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

史诗进度

当前状态：史诗全部完成，10个核心故事已全部实现（012-01到012-05、012-08到012-12），为企业用户管理功能提供了完整的API支持。故事012-12已补充企业专用人才列表API的出生日期和薪资字段，解决人才列表页年龄和薪资显示问题。故事012-06（系统设置API）延期至后期优化阶段，故事012-07（API文档与测试完善）作为基础设施任务已由各故事分别覆盖。

故事完成状态：

• 故事012-01：数据库schema扩展 - 已完成（故事012.001已实现）
• 故事012-02：企业用户认证API扩展 - 已完成（故事012.002已实现）
• 故事012-03：企业统计与人才扩展API - 已完成（故事012.003已实现）
• 故事012-08：路由路径规范修复 - 已完成（故事012.008已实现）
• 故事012-04：订单统计与数据统计API - 已完成（故事012.004已实现）
• 故事012-05：视频管理API扩展 - 已完成（故事012.005已实现）
• 故事012-09：管理后台企业用户配置表单扩展 - 已完成（故事012.009已实现）
• 故事012-10：近期分配人才查询API - 已完成（故事012.010已实现）
• 故事012-11：企业专用人才管理API - 已完成（故事012.011已实现）
• 故事012-12：补充企业专用人才列表API的出生日期和薪资字段 - 已完成
• 故事012-06：系统设置API - P2 - 延期（后期优化）
• 故事012-07：API文档与测试完善 - 冗余（基础设施已覆盖）

总体进度：10/10 故事完成（100%） MVP进度：10/10 核心故事完成（100%，排除012-06延期和012-07冗余）

最近更新：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创建并完成，路由路径规范修复。

---

兼容性要求

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

风险缓解

主要风险：

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客户端变更可通过版本控制回退到上一个稳定版本

完成定义

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

依赖关系

• 依赖史诗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-06：系统设置API（P2优先级，后期优化）
8. 基础设施故事012-07：API文档与测试完善（冗余，基础设施已覆盖）
9. 按模块分组：同一模块的扩展建议由同一开发者完成，确保一致性

---

故事经理交接说明：

请为这个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（用人方小程序功能实现）奠定基础。