mini-starter/docs/prd/epic-015-talent-mini-program-api-support.md

史诗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）暂不添加。打卡功能目前为前端模拟实现，待后续确定接口逻辑后再考虑数据库扩展。

验收标准：

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

故事015-02：人才用户认证API扩展

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

任务列表：

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

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

验收标准：

• 个人信息查询接口返回正确的人才基本信息
• 银行卡信息查询接口返回银行卡信息（卡号脱敏处理）
• 证件照片查询接口返回证件照片信息
• 所有接口验证用户权限，确保用户只能查询自己的数据
• 所有接口通过单元测试和集成测试（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

数据迁移建议：

-- 从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;

验收标准：

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

详细设计文档: docs/stories/015.013.story.md

史诗进度

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

故事完成状态：

• 故事015-01：数据库schema扩展 - 已完成 ✅（打卡字段延期）
• 故事015-02：人才用户认证API扩展 - 已完成 ✅
• 故事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文档与测试完善 - 冗余（基础设施已覆盖）
• 故事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支持，为后续人才小程序功能实现奠定基础。