mini-starter/docs/prd/epic-011-employer-mini-program-implementation.md

史诗011 - 用人方小程序功能实现

史诗目标

在mini项目中完整实现用人方小程序的所有页面功能，基于史诗7,8,9,10已移植的API模块基础，为企业用户提供残疾人就业管理的完整解决方案。

状态更新（2025-12-24）

• 依赖状态：史诗012完成5/6核心故事（83%），MVP API就绪
• 启动建议：史诗011可以立即开始开发
• 调整说明：故事011.006需调整企业设置页功能实现（系统设置API延期至P2优先级），故事011.007使用 mini-charts 包重构数据统计图表
• 故事拆分：史诗拆分为7个故事，便于逐步开发和测试
• 整体进度：故事011.001已完成，故事011.002已完成，故事011.003已完成，故事011.004已完成（订单管理功能完整实现），故事011.005已完成（数据统计功能完整实现，布局渲染优化），故事011.006未开始
• 故事011.001完成情况：基础框架搭建完成，包含API客户端集成、路由配置、布局组件、企业认证框架，所有测试通过，现有功能适配为企业用户使用
• 故事011.002完成情况：登录页面UI更新完成（严格对照原型设计），首页仪表板实现完整，认证状态管理增强（自动token刷新），集成测试通过（23个测试），已集成Navbar导航栏组件，统一页面层级结构
• 故事011.003完成情况：人才管理功能完整实现，包含人才列表页（搜索、筛选、分页）、人才详情页（基本信息、工作信息、薪资信息）、薪资历史记录、个人征信文件管理，严格对照原型设计实现，多模块API集成验证通过，已集成Navbar导航栏组件，区分主页面和二级页的不同配置（主页面使用YongrenTabBarLayout+Navbar无返回，二级页使用Navbar带返回按钮）
• 故事011.004完成情况：订单管理功能完整实现，包含订单列表页（搜索、筛选、分页）、订单详情页（仅查看功能）、打卡日历视图、时间范围筛选、打卡数据导出、视频播放/下载/分享、批量视频下载、企业专用订单API客户端集成（enterpriseOrderClient）、RPC类型推断实现、Navbar导航栏组件集成、Taro适配优化，通过类型检查，故事状态为Ready for Review
• 故事011.005完成情况：数据统计功能完整实现，包含6个统计图表（残疾类型、性别、年龄、户籍、在职状态、薪资分布）、4个统计卡片（在职人数、平均薪资、在职率、新增人数）、Taro原生Picker日期选择器、布局渲染优化（所有View容器添加flex flex-col确保正确垂直排列）、图表标题间距优化（使用mt-3实现正确间距）、性能优化（懒加载、数据缓存、React.memo），严格对照原型设计实现，通过类型检查，故事状态为Ready for Review
• 故事011.006完成情况：视频与系统管理功能尚未开始，故事状态为Draft，依赖系统设置API延期（P2优先级），需调整实现计划
• 故事011.007完成情况：使用 mini-charts 包重构数据统计图表尚未开始，故事状态为Draft，依赖史诗016（mini-charts 包）和故事011.005
• 导航栏集成状态：所有用人小程序页面已完成Navbar组件集成，建立统一的页面层级结构规范，主页面使用YongrenTabBarLayout+Navbar（无返回按钮），二级页面使用Navbar（带返回按钮，移除YongrenTabBarLayout包裹），已验证类型检查通过
• 布局渲染优化状态：所有用人小程序页面已完成Taro小程序布局优化，确保View容器内的Text组件正确垂直排列，避免内联显示导致的布局问题

史诗描述

现有系统上下文

当前相关功能：

• mini项目：基础小程序前端，已改造登录、个人资料页面为企业用户使用（注册功能由管理员管理）
• API客户端：已集成auth、user、role、file模块的RPC客户端（api.ts）
• 史诗7,8,9,10成果：已移植allin系统的7个后端模块和对应UI模块（channel、company、disability_person、order、platform、salary等）
• 原型设计：docs/小程序原型/yongren.html 提供了完整的8个页面原型设计

技术栈：

• 前端：TypeScript、React、Hono RPC客户端、Tailwind CSS
• 测试：Jest（mini项目使用Jest，其他包使用Vitest）
• API通信：基于Hono RPC的API客户端模式
• 包管理：pnpm workspace

集成点：

• 需要将史诗7,8,9,10移植的allin系统模块API客户端集成到mini项目
• 依赖史诗012（API补充与数据库扩展）提供完整的用人方小程序API支持
• 基于已有RPC客户端模式扩展新的API客户端，使用api/v1/yongren路径前缀
• UI组件开发：基于原型文件独立开发小程序UI组件，复用现有小程序通用组件（如登录注册组件），只修改样式，保持核心逻辑不变
• 遵循mini项目现有的页面结构和路由配置

史诗012完成状态更新（2025-12-17）：

• ✅ 完成情况：5/6核心故事完成（83%），MVP就绪
• ✅ 已完成的API：数据库schema、企业用户认证、企业统计、人才扩展、订单统计、数据统计、视频管理
• ⚠️ 延期API：系统设置API（P2优先级，非MVP必需）
• 📊 进度：史诗011可以立即开始，但故事011.006需调整系统设置相关功能实现计划

增强详情

新增/变更内容： 在mini项目中实现用人方小程序的8个核心页面，包括：

1. 登录页 - 企业用户手机号密码登录
2. 首页/看板 - 企业概览、人才分配、数据卡片
3. 人才列表页 - 人才搜索、筛选、分页展示
4. 人才详情页 - 个人信息、工作历史、薪资、视频管理
5. 数据统计页 - 可视化图表、残疾类型分布、性别年龄分布等
6. 订单管理页 - 订单列表、状态管理、打卡数据统计
7. 企业设置页 - 企业信息、账号管理、安全设置
8. 视频查看下载页 - 企业/个人维度的视频管理

页面功能基于：

• docs/小程序原型/yongren.html 完整原型设计
• 史诗7,8,9,10移植的API模块提供数据支持
• 缺失的API接口进行增补实现

集成方式：

1. API客户端集成：基于现有api.ts模式，新增allin系统模块的RPC客户端
2. UI组件开发：基于原型文件独立开发小程序UI组件，复用现有小程序通用组件（如登录注册组件），只修改样式，保持核心逻辑不变。注意：史诗011针对mini小程序，UI组件应独立设计，而非复用管理后台的@d8d/allin-*系列UI包
3. 导航栏组件集成：所有页面统一集成Navbar导航栏组件，建立页面层级结构规范：主页面使用YongrenTabBarLayout+Navbar（无返回按钮），二级页面使用Navbar（带返回按钮，移除YongrenTabBarLayout包裹）
4. 页面结构：遵循mini项目现有的页面目录结构（src/pages/），适配导航栏占位布局
5. 路由配置：使用现有的路由配置模式

成功标准：

1. 8个页面功能完整实现，符合原型设计要求
2. 与史诗7,8,9,10移植的API模块无缝集成
3. 保持mini项目现有功能的完整性（登录、注册、个人资料等）
4. 通过Jest测试验证，包括组件测试和集成测试
5. 遵循项目编码规范和UI组件使用规范

故事列表

故事011.001：基础框架搭建

背景： 史诗012已完成5/6核心故事（83%），MVP API就绪。需要将史诗7,8,9,10移植的API模块及史诗012补充的API集成到mini项目的RPC客户端中，建立用人方小程序的基础技术框架。注：系统设置API为P2优先级延期功能。

任务列表：

1. 分析史诗7,8,9,10移植的API模块及史诗012补充的API，确定需要集成的RPC客户端
2. 扩展mini/src/api.ts，新增allin系统模块的RPC客户端，包括史诗012补充的API接口
3. 配置用人方小程序的路由结构，支持页面导航
4. 创建基础布局组件（状态栏、底部导航、页面容器），参考原型设计docs/小程序原型/yongren.html
5. 建立企业用户认证框架，支持后续登录页面集成
6. 编写基础测试，验证现有功能不受影响

验收标准：

• allin系统模块及史诗012补充API的RPC客户端成功集成到mini/src/api.ts
• 用人方小程序的路由结构配置完成，支持页面导航
• 基础布局组件（状态栏、底部导航、页面容器）可用并符合移动端设计
• 企业用户认证框架就绪，支持后续登录页面集成
• 现有mini项目功能不受影响

故事011.002：认证与首页实现

背景： 依赖故事011.001完成的基础框架和史诗012提供的企业用户认证API、企业统计API，实现企业用户登录功能和首页/看板页面。

任务列表：

1. 实现登录页面功能，支持企业用户手机号密码登录
2. 完善认证状态管理（token存储、验证、自动刷新）
3. 实现首页/看板页面，展示企业概览数据（在职人员统计、分配人才列表等）
4. 集成企业统计API，实现数据卡片和人才列表组件
5. 集成Navbar导航栏组件，建立统一的页面层级结构（主页面使用YongrenTabBarLayout+Navbar无返回按钮）
6. 优化用户体验，确保页面设计符合原型标准
7. 编写集成测试，验证登录和首页功能

验收标准：

• 登录页面功能完整，支持企业用户手机号密码登录
• 登录状态管理正常，token存储和验证可靠
• 首页/看板页面展示企业概览数据（在职人员统计、分配人才列表等）
• 页面设计符合原型标准，移动端体验良好，已集成Navbar导航栏组件
• 与基础框架（故事011.001）无缝集成，建立统一的页面层级结构规范

故事011.003：人才管理功能实现

背景： 依赖故事011.001-011.002完成的基础，以及史诗012提供的人才扩展API，实现人才管理功能。

任务列表：

1. 实现人才列表页，支持按姓名、残疾证号搜索，按状态、残疾类型筛选和分页展示
2. 实现人才详情页，展示完整信息（基本信息、工作信息、薪资信息等）
3. 集成薪资管理API，实现薪资历史记录查看功能
4. 集成文件管理API，实现个人征信文件预览和下载
5. 集成Navbar导航栏组件，区分主页面和二级页配置（列表页使用YongrenTabBarLayout+Navbar无返回，详情页使用Navbar带返回按钮）
6. 优化大数据量列表性能和页面间导航
7. 编写集成测试，验证人才管理功能

验收标准：

• 人才列表页功能完整，支持按姓名、残疾证号搜索
• 人才列表支持按状态、残疾类型筛选和分页展示
• 人才详情页展示完整信息（基本信息、工作信息、薪资信息等）
• 支持查看薪资历史记录和个人征信文件
• 页面设计符合原型标准，与基础框架无缝集成，已集成Navbar导航栏组件并建立页面层级结构规范（主页面使用YongrenTabBarLayout+Navbar无返回，二级页使用Navbar带返回按钮）

故事011.004：订单管理功能实现

背景： 依赖故事011.001-011.003完成的基础，以及史诗012提供的订单统计API、视频管理API，实现订单管理功能。

任务列表：

1. 实现订单管理页，展示订单列表，支持状态筛选和搜索
2. 实现订单状态管理（查看、编辑、状态变更）
3. 实现打卡数据统计功能，显示考勤记录
4. 实现视频统计功能，关联订单的视频资料可查看
5. 优化页面加载性能和大数据量处理
6. 编写集成测试，验证订单管理功能

验收标准：

• 订单管理页展示订单列表，支持状态筛选和搜索
• 支持订单状态管理（查看、编辑、状态变更）（查看功能已实现，编辑和状态变更在管理后台执行）
• 打卡数据统计功能完整，显示考勤记录（包含打卡日历视图、时间范围筛选、数据导出）
• 视频统计功能正常，关联订单的视频资料可查看（支持播放、下载、分享和批量下载）
• 页面设计符合原型标准，与系统其他部分无缝集成（已严格对照原型设计实现，已集成Navbar导航栏组件，建立页面层级结构规范）

故事011.005：数据统计功能实现

背景： 依赖故事011.001-011.004完成的基础，以及史诗012提供的数据统计API，实现数据可视化功能。

任务列表：

1. 实现数据统计页，展示完整的统计图表集合
2. 实现残疾类型分布图表，数据准确显示
3. 实现性别分布、年龄分布、户籍省份分布图表
4. 支持数据筛选（时间范围、部门等）和图表交互
5. 优化图表加载性能和移动端显示
6. 编写集成测试，验证数据统计功能

验收标准：

• 数据统计页展示完整的统计图表集合
• 残疾类型分布图表正确显示，数据准确
• 性别分布、年龄分布、户籍省份分布图表功能正常
• 支持数据筛选（时间范围、部门等）和图表交互
• 页面设计符合原型标准，图表加载性能良好

故事011.006：视频与系统管理功能实现

背景： 依赖故事011.001-011.005完成的基础，以及史诗012提供的视频管理API，实现视频管理和企业设置功能。注：系统设置API为P2优先级延期功能，企业设置页高级功能需相应调整实现计划。

任务列表：

1. 实现视频查看下载页，支持企业维度和个人维度的视频管理
2. 实现视频操作功能（播放、下载、分享、批量下载）
3. 实现企业设置页面基础功能（企业信息展示）
4. 处理系统设置API延期，标记账号管理、安全设置等高级功能为"后期优化"
5. 优化视频播放体验和大文件处理性能
6. 编写集成测试，验证视频与系统管理功能

验收标准：

• 视频查看下载页功能完整，支持企业维度和个人维度的视频管理
• 视频支持播放、下载、分享、批量下载功能
• 企业设置页面基础功能可用（企业信息展示）
• 账号管理、安全设置等高级功能标记为"后期优化"（因系统设置API延期）
• 页面设计符合原型标准，与系统其他部分无缝集成

故事011.007：使用 mini-charts 包重构数据统计图表

背景： 依赖故事011.005完成的数据统计功能和史诗016提供的 mini-charts 图表组件包，使用专业的图表组件替换现有的纯CSS实现，提升数据可视化体验和交互功能。

任务列表：

1. 分析 mini-charts 包的可用组件和API（ColumnChart、PieChart、LineChart 等）
2. 重构残疾类型分布图表，使用 ColumnChart 组件替换纯CSS实现
3. 重构性别分布图表，使用 ColumnChart 组件替换纯CSS实现
4. 重构年龄分布图表，使用 PieChart 组件替换纯CSS实现
5. 重构户籍省份分布图表，使用横向 ColumnChart 组件替换纯CSS实现
6. 重构在职状态统计图表，使用 PieChart（环形图）组件替换纯CSS实现
7. 重构薪资分布图表，使用横向 ColumnChart 组件替换纯CSS实现
8. 验证性能优化和用户体验（懒加载、数据缓存、tooltip 交互）
9. 编写集成测试和文档更新

验收标准：

• 数据统计页使用 mini-charts 包的图表组件替换所有纯CSS实现
• 残疾类型分布使用 ColumnChart 组件显示
• 性别分布使用 ColumnChart 组件显示
• 年龄分布使用 PieChart 组件显示
• 户籍省份分布使用横向 ColumnChart 组件显示
• 在职状态统计使用 PieChart（环形图）组件显示
• 薪资分布使用横向 ColumnChart 组件显示
• 图表支持 tooltip 交互，显示详细数据
• 保持现有的性能优化（懒加载、数据缓存）
• 通过类型检查和测试验证

依赖关系：

• 依赖故事011.005（数据统计功能实现）
• 依赖史诗016（mini-charts 包）- 已完成 016.001-016.009 故事

兼容性要求

• 现有mini项目功能适配为企业用户使用（登录、个人资料页面已改造，注册功能由管理员管理）
• 遵循现有api.ts RPC客户端模式，新增客户端与原有客户端兼容
• 使用一致的UI组件库，保持界面风格统一
• 保持路由结构的统一性，新增路由不影响现有路由
• 数据库schema变化保持向后兼容
• 性能影响最小化，不影响现有功能响应速度

风险缓解

主要风险：

1. 数据库schema变更风险：新增字段和枚举扩展可能影响现有数据操作和查询
2. API集成可能影响现有功能稳定性
3. UI组件复用可能存在兼容性问题
4. 数据统计图表性能可能影响页面加载速度

缓解措施：

1. 数据库变更分步实施：
   • 先添加可为空的birth_date字段，不影响现有记录
   • 扩展asset_type枚举时保留原有枚举值，确保向后兼容
   • users2表添加可为空的company_id字段，现有admin用户不受影响
2. 逐步集成：每个API模块独立集成，分阶段测试验证
3. 组件测试：对复用的UI组件进行充分测试，确保兼容性
4. 性能优化：数据统计图表采用懒加载和分页，优化大数据量展示；实时统计查询添加适当的数据库索引
5. 回滚计划：保持原有api.ts不变，新增独立客户端文件，便于回滚

回滚计划：

1. 如果新增功能导致严重问题，可临时移除新增路由，恢复原有功能
2. API客户端变更可通过版本控制回退到上一个稳定版本
3. 数据库schema变更支持可逆回滚：
   • birth_date字段：如需要可删除该字段，不影响核心业务数据
   • asset_type枚举扩展：新增的枚举值不影响原有数据，可安全保留
   • company_id字段：如需要可删除该字段，企业用户可暂时通过其他方式关联
4. 保留完整的数据迁移脚本，支持向前和向后迁移

完成定义

• 所有7个故事完成，验收标准全部满足
• 8个页面功能完整，符合原型设计要求
• API集成测试通过，包括正常流程和异常情况测试
• 现有功能回归测试通过，确保无功能退化
• 代码符合项目编码规范，通过代码审查
• 文档更新完成，包括API接口文档和用户操作手册
• 性能测试通过，页面加载时间在可接受范围内
• 移动端适配良好，主流设备测试通过

依赖关系

• 依赖史诗7,8,9,10移植的API模块和UI组件包
• 依赖史诗012（API补充与数据库扩展）：提供企业用户认证、企业统计、人才扩展、订单统计、数据统计、视频管理等API接口（5/6核心故事完成，系统设置API延期至P2优先级）
• 依赖现有mini项目的基础框架和构建配置
• 依赖数据库schema与移植模块保持一致（通过史诗012扩展）
• 需要测试环境支持，包括API服务和数据库

史诗012依赖状态（2025-12-22验证）：

• ✅ 已就绪：数据库schema、企业用户认证、企业统计、人才扩展、订单统计、数据统计、视频管理
• ⚠️ 延期：系统设置API（P2，非MVP必需）
• 🚀 启动建议：史诗011可以立即开始，故事011.006需调整系统设置相关功能实现

状态更新日志

日期	更新内容	更新人
2025-12-22	初始状态更新，故事011.001-011.004已完成	Claude Code
2025-12-24	故事011.005完成：数据统计功能完整实现，布局渲染优化，日期选择器改进	Claude Code
2025-12-24	添加故事011.007：使用 mini-charts 包重构数据统计图表	Claude Code

测试策略

1. 单元测试：对新增组件和工具函数进行Jest单元测试
2. 集成测试：测试API客户端与后端服务的集成
3. UI测试：对页面交互和用户体验进行测试
4. 性能测试：验证数据统计页面的加载和渲染性能
5. 兼容性测试：测试不同设备和浏览器的兼容性
6. 回归测试：确保现有功能不受影响

---

故事经理交接说明：

请为这个已有项目开发详细用户故事。关键考虑：

• 这是对现有mini项目的增强，技术栈：TypeScript、React、Hono RPC、Tailwind CSS，测试使用Jest
• 集成点：史诗7,8,9,10移植的allin系统API模块（channel、company、disability_person、order、platform、salary等）
• 现有模式：遵循mini项目现有的api.ts RPC客户端模式、页面结构和路由配置
• 关键兼容要求：不影响现有登录、注册、个人资料等功能，保持系统完整性
• 每个故事必须验证现有功能保持完整

史诗应在保持系统完整性的同时，为企业用户提供完整的残疾人就业管理功能，实现docs/小程序原型/yongren.html中的完整页面功能。