Главная Обзор Помощь
Регистрация Вход
188-template-179
/
mini-starter
ответвлено от 155-template-138/mini-starter
2
0
Ответвить 0
Файлы
Дерево: 71920364c0
Ветки Метки
mini-starter
/
docs
/
prd
/
epic-015-talent-mini-program-api-support.md

epic-015-talent-mini-program-api-support.md 26 KB
История Исходник

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

故事概览： 本史诗包含12个故事，其中10个为核心故事（015-01到015-10），1个延期故事（015-11），1个冗余故事（015-12）。

故事015-01：数据库schema扩展

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

任务列表： 注：数据库迁移脚本将在上线前统一生成，开发阶段通过TypeORM自动同步。

  1. 扩展users2表的user_type枚举，新增talent（人才用户）类型
  2. 在users2表添加person_id字段（外键引用disabled_person.person_id），建立人才用户关联
  3. 在order_person表添加打卡相关字段：checkin_time（上班打卡时间）、checkout_time（下班打卡时间）、checkin_status（打卡状态：正常、迟到、早退、缺勤）
  4. 更新对应的TypeORM实体定义
  5. 验证现有数据不受影响，新增字段可为空

验收标准：

  • users2表的user_type枚举成功扩展，新增talent类型
  • users2表成功添加person_id字段，现有admin用户和企业用户的该字段值为NULL
  • order_person表成功添加打卡相关字段，现有记录该字段值为NULL
  • TypeORM实体定义更新完成
  • 现有业务功能不受影响，测试通过

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

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

任务列表：

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

验收标准：

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

故事015-03：个人信息管理API

背景： 人才用户需要查看和管理个人信息，包括基本信息、银行卡信息、证件照片等。

任务列表：

  1. 个人信息查询API（disability-module扩展）：

    • 基于disabled_person表查询人才基本信息
    • 接口返回：姓名、性别、年龄、身份证号、残疾证号、残疾类型、联系电话、联系地址等

  2. 个人信息更新API（disability-module扩展）：

    • 支持人才用户更新个人信息（如联系电话、联系地址等）
    • 验证更新权限，确保用户只能更新自己的信息

  3. 银行卡管理API（disability-module扩展）：

    • 基于disabled_bank_card表查询人才银行卡信息
    • 添加银行卡接口（关联files表存储银行卡照片）
    • 设置默认银行卡接口
    • 删除银行卡接口（需验证权限）

  4. 证件照片管理API（disability-module扩展）：

    • 基于disabled_person_photo表查询人才证件照片
    • 添加证件照片接口（身份证、残疾证、体检报告、征信报告等）
    • 删除证件照片接口（需验证权限）

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

验收标准：

  • 个人信息查询接口返回正确的人才基本信息
  • 个人信息更新接口支持更新个人可修改信息
  • 银行卡管理接口支持查询、添加、设置默认、删除银行卡
  • 证件照片管理接口支持查询、添加、删除证件照片
  • 所有接口验证用户权限，确保用户只能操作自己的数据
  • 所有接口通过单元测试和集成测试

故事015-04：考勤记录API

背景： 人才用户需要查看考勤记录、考勤统计和打卡明细，基于order_person表的打卡记录进行查询和统计。

任务列表：

  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（disability-module扩展）：

    • 支持人才用户修改个人信息（联系电话、联系地址等）
    • 添加个人信息修改历史记录

  2. 账号安全设置API（auth-module扩展）：

    • 修改密码接口
    • 登录设备管理接口（查询登录设备、退出设备）
    • 登录日志查询接口

  3. 消息通知设置API（创建或扩展现有模块）：

    • 消息通知开关设置（薪资发放通知、考勤异常通知、系统公告等）
    • 通知偏好设置接口

  4. 帮助与支持API：

    • 帮助中心内容查询接口
    • 用户协议查询接口
    • 隐私政策查询接口
    • 问题反馈接口

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

验收标准：

  • 个人信息修改接口支持修改个人可修改信息
  • 账号安全设置接口支持修改密码、管理登录设备、查询登录日志
  • 消息通知设置接口支持各类通知的开关控制
  • 帮助与支持接口提供帮助中心、用户协议、隐私政策等内容
  • 所有接口通过单元测试和集成测试

故事015-07：通知与消息API

背景： 人才用户需要接收系统通知和消息，包括薪资发放通知、考勤异常通知、系统公告等。

任务列表：

  1. 通知列表查询API（创建通知模块或扩展现有模块）：

    • 查询个人的通知列表，支持分页
    • 接口返回：通知标题、通知内容、通知时间、通知类型、已读状态

  2. 通知详情查询API：

    • 查询单条通知的详细信息

  3. 通知标记已读API：

    • 标记单条通知为已读
    • 批量标记通知为已读

  4. 未读通知数查询API：

    • 查询个人的未读通知数量

  5. 消息推送集成：

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

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

验收标准：

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

故事015-08：远程打卡API

背景： 人才用户需要通过小程序进行远程打卡，记录上班和下班时间。

任务列表：

  1. 远程打卡API（order-module扩展）：

    • 上班打卡接口：记录上班打卡时间
    • 下班打卡接口：记录下班打卡时间
    • 打卡状态验证：验证是否在合理时间内打卡（如上班时间前1小时内打卡）
    • 打卡位置验证：如需要，可集成位置验证

  2. 打卡记录查询API：

    • 查询当天的打卡记录
    • 查询历史打卡记录

  3. 打卡异常处理：

    • 打卡异常记录：迟到、早退、缺勤等异常情况记录
    • 异常打卡说明：允许用户提交异常说明

  4. 打卡提醒功能：

    • 打卡提醒设置接口
    • 定时打卡提醒推送

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

验收标准：

  • 远程打卡接口支持上班和下班打卡
  • 打卡记录查询接口返回打卡记录
  • 打卡异常处理支持异常记录和说明提交
  • 打卡提醒功能支持提醒设置和定时推送
  • 所有接口通过单元测试和集成测试

故事015-09：数据统计与报表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-01：数据库schema扩展 - 待实现
  • 故事015-02：人才用户认证API扩展 - 待实现
  • 故事015-03：个人信息管理API - 待实现
  • 故事015-04：考勤记录API - 待实现
  • 故事015-05：就业信息API - 待实现
  • 故事015-06：系统设置API - 待实现
  • 故事015-07：通知与消息API - 待实现
  • 故事015-08：远程打卡API - 待实现
  • 故事015-09：数据统计与报表API - 待实现
  • 故事015-10：路由路径规范与API客户端 - 待实现
  • 故事015-11：高级功能与优化 - P2 - 延期（后期优化）
  • 故事015-12：API文档与测试完善 - 冗余（基础设施已覆盖）

总体进度： 0/12 故事完成（0%） MVP进度： 0/10 核心故事完成（0%，排除015-11延期和015-12冗余）

最近更新： 2025-12-23 - 史诗015创建：为人才小程序提供完整的API接口支持，包含12个故事，覆盖登录认证、个人信息、考勤记录、就业信息、系统设置等功能。

兼容性要求

  • 现有数据库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-04和015-05：考勤记录API和就业信息API，核心功能实现
  5. 故事015-06和015-07：系统设置API和通知与消息API，完善用户体验
  6. 故事015-08和015-09：远程打卡API和数据统计API，增强功能
  7. 故事015-10：路由路径规范与API客户端，确保架构规范
  8. 故事015-11：高级功能与优化（P2优先级，后期优化）
  9. 故事015-12：API文档与测试完善（冗余，基础设施已覆盖）
  10. 按模块分组：同一模块的扩展建议由同一开发者完成，确保一致性

故事经理交接说明：

请为这个人才小程序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支持，为后续人才小程序功能实现奠定基础。