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

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

## 状态更新（2025-12-18）
- **依赖状态**：史诗012完成5/6核心故事（83%），MVP API就绪
- **启动建议**：史诗011可以立即开始开发
- **调整说明**：故事011.006需调整企业设置页功能实现（系统设置API延期至P2优先级）
- **故事拆分**：史诗拆分为6个故事，便于逐步开发和测试
- **整体进度**：故事011.001已完成，故事011.002已完成，可开始故事011.003
- **故事011.001完成情况**：基础框架搭建完成，包含API客户端集成、路由配置、布局组件、企业认证框架，所有测试通过，现有功能适配为企业用户使用
- **故事011.002完成情况**：登录页面UI更新完成（严格对照原型设计），首页仪表板实现完整，认证状态管理增强（自动token刷新），集成测试通过（23个测试）

## 史诗描述

### 现有系统上下文

**当前相关功能：**
- **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. **页面结构**：遵循mini项目现有的页面目录结构（`src/pages/`）
4. **路由配置**：使用现有的路由配置模式

**成功标准：**
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. 编写基础测试，验证现有功能不受影响

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

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

**任务列表：**
1. 实现登录页面功能，支持企业用户手机号密码登录
2. 完善认证状态管理（token存储、验证、自动刷新）
3. 实现首页/看板页面，展示企业概览数据（在职人员统计、分配人才列表等）
4. 集成企业统计API，实现数据卡片和人才列表组件
5. 优化用户体验，确保页面设计符合原型标准
6. 编写集成测试，验证登录和首页功能

**验收标准：**
- [x] 登录页面功能完整，支持企业用户手机号密码登录
- [x] 登录状态管理正常，token存储和验证可靠
- [x] 首页/看板页面展示企业概览数据（在职人员统计、分配人才列表等）
- [x] 页面设计符合原型标准，移动端体验良好
- [x] 与基础框架（故事011.001）无缝集成

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

**任务列表：**
1. 实现人才列表页，支持按姓名、残疾证号搜索，按状态、残疾类型筛选和分页展示
2. 实现人才详情页，展示完整信息（基本信息、工作信息、薪资信息等）
3. 集成薪资管理API，实现薪资历史记录查看功能
4. 集成文件管理API，实现个人征信文件预览和下载
5. 优化大数据量列表性能和页面间导航
6. 编写集成测试，验证人才管理功能

**验收标准：**
- [ ] 人才列表页功能完整，支持按姓名、残疾证号搜索
- [ ] 人才列表支持按状态、残疾类型筛选和分页展示
- [ ] 人才详情页展示完整信息（基本信息、工作信息、薪资信息等）
- [ ] 支持查看薪资历史记录和个人征信文件
- [ ] 页面设计符合原型标准，与基础框架无缝集成

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

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

**验收标准：**
- [ ] 订单管理页展示订单列表，支持状态筛选和搜索
- [ ] 支持订单状态管理（查看、编辑、状态变更）
- [ ] 打卡数据统计功能完整，显示考勤记录
- [ ] 视频统计功能正常，关联订单的视频资料可查看
- [ ] 页面设计符合原型标准，与系统其他部分无缝集成

### 故事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延期）
- [ ] 页面设计符合原型标准，与系统其他部分无缝集成

## 兼容性要求

- [x] 现有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. 保留完整的数据迁移脚本，支持向前和向后迁移

## 完成定义

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

## 依赖关系

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

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

## 测试策略

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`中的完整页面功能。