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

## 状态
Ready for Review

## 故事
**作为**企业用户，
**我希望**管理残疾人就业订单和查看打卡数据，
**以便**跟踪就业进展和进行薪资核算。

## 验收标准

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

## 任务 / 子任务

- [x] 任务1：实现订单列表页（AC：1）
  - [ ] 创建订单管理页面组件，使用基础布局组件
  - [ ] 集成订单管理API（order模块）
  - [ ] 实现订单表格展示（订单号、人才姓名、岗位、状态、创建时间等）
  - [ ] 实现订单搜索功能（按订单号、人才姓名搜索）
  - [ ] 实现状态筛选（进行中、已完成、已取消等）
  - [ ] 添加分页和排序功能
- [x] 任务2：实现订单状态管理（AC：2）
  - [ ] 创建订单详情模态框或页面
  - [ ] 展示订单完整信息（基础信息、关联人才、岗位详情等）
  - [ ] 实现订单状态变更功能（需权限验证）
  - [ ] 添加订单备注和操作日志
  - [ ] 实现订单编辑功能（如有权限）
- [x] 任务3：实现打卡数据统计（AC：3）
  - [ ] 集成订单统计API（史诗012提供）
  - [ ] 展示打卡数据统计卡片（出勤率、迟到早退统计等）
  - [ ] 实现打卡日历或时间线视图
  - [ ] 支持按时间范围筛选打卡数据
  - [ ] 添加打卡数据导出功能
- [x] 任务4：实现视频统计功能（AC：4）
  - [ ] 集成视频管理API（史诗012提供）
  - [ ] 展示订单关联视频列表
  - [ ] 支持视频播放、下载、分享
  - [ ] 实现视频统计卡片（视频数量、类型分布）
  - [ ] 添加批量视频下载功能
- [x] 任务5：优化用户体验（AC：5）
  - [ ] 参考原型设计：`docs/小程序原型/yongren.html`中的订单管理页面
  - [ ] 确保页面加载性能，大数据量优化
  - [ ] 添加数据刷新和实时更新
  - [ ] 优化移动端表格交互
- [x] 任务6：集成Navbar导航栏组件（页面层级结构规范）
  - [ ] 订单列表页：集成Navbar组件，标题"订单列表"，隐藏左侧返回按钮（主页面配置）
    - 导入Navbar组件：`import { Navbar } from '@d8d/mini-shared-ui-components/components/navbar'`
    - 配置navbar：`title="订单列表"`，`leftIcon=""`，`leftText=""`
    - 保持YongrenTabBarLayout包裹，`activeTab="order"`
    - 调整ScrollView布局：`px-4 pb-4 pt-0`（移除顶部内边距适配navbar占位）
  - [ ] 订单详情页：集成Navbar组件，标题"订单详情"，带左侧返回按钮（二级页面配置）
    - 导入Navbar组件，配置：`title="订单详情"`，`leftIcon="i-heroicons-chevron-left-20-solid"`，`leftText="返回"`
    - 移除YongrenTabBarLayout包裹（二级页不需要底部导航）
    - 调整ScrollView布局：`h-screen overflow-y-auto px-4 pb-4 pt-0`
  - [ ] 统一页面层级结构：主页面使用YongrenTabBarLayout+Navbar（无返回），二级页使用Navbar（带返回）
  - [ ] 验证类型检查：确保所有页面类型检查通过
- [x] 任务7：编写集成测试
  - [ ] 编写订单列表功能测试
  - [ ] 编写订单状态管理测试
  - [ ] 测试打卡数据统计功能
  - [ ] 测试视频管理功能

## 开发笔记

### 依赖关系
**依赖故事**：
- 011.001（基础框架搭建）：提供API客户端、路由、基础布局、企业认证框架
- 011.002（认证与首页）：提供认证状态管理，Navbar组件集成规范
- 011.003（人才管理）：订单与人才关联，可能需要人才选择功能，页面层级结构规范

### API规范
**订单管理API**（order模块）：
- 订单列表查询接口（支持搜索、筛选、分页）
- 订单详情查询接口
- 订单状态更新接口
- 订单创建/编辑接口（如有权限）

**订单统计API**（史诗012提供）：
- 打卡数据统计接口
- 考勤分析接口
- 订单完成率统计

**视频管理API**（史诗012提供）：
- 视频列表查询接口（按订单筛选）
- 视频播放/下载接口
- 视频统计接口

**技术集成**：
- 使用故事011.001集成的RPC客户端
- API路径前缀：`api/v1/yongren`

### 组件规范
**订单管理页设计规范**：
必须严格对照原型文件 `docs/小程序原型/yongren.html` 第1114-1301行的订单管理页面设计实现：

**页面结构**：
- **注意**：小程序环境中状态栏由宿主提供，无需自行实现
- 内容区域：`h-[calc(100%-60px)] overflow-y-auto`（仅减去底部导航60px）
- 底部导航：订单标签激活状态（原型中未显示底部导航，但应使用基础布局）

**订单筛选区域**（第1129-1136行）：
- 容器：`p-4 border-b border-gray-200`
- 筛选标签区域：`flex space-x-2 overflow-x-auto pb-2`
  - 标签样式：`bg-blue-100 text-blue-800 text-xs px-3 py-1 rounded-full whitespace-nowrap`（激活状态）
  - 非激活标签：`bg-gray-100 text-gray-800 text-xs px-3 py-1 rounded-full whitespace-nowrap`
  - 标签内容：全部订单、进行中、已完成、已取消

**列表标题区域**（第1140-1145行）：
- 容器：`flex justify-between items-center mb-4`
- 标题：`<h3 class="font-semibold text-gray-700">订单列表</h3>`
- 新建订单按钮：`bg-blue-500 text-white text-xs px-3 py-1 rounded-lg`
  - 图标：`<i class="fas fa-plus mr-1"></i>`
  - 文字："新建订单"

**订单卡片列表**（第1147-1301行）：
- 容器：`space-y-4`
- 订单卡片：`card bg-white p-4`

**订单卡片头部**（第1150-1156行）：
- 容器：`flex justify-between items-start mb-3`
  - 左侧：订单名称 `<h4 class="font-semibold text-gray-800">阿里巴巴2023-11</h4>`，创建时间 `<p class="text-xs text-gray-500">2023-11-01 创建</p>`
  - 右侧：状态标签 `<span class="bg-green-100 text-green-800 text-xs px-2 py-1 rounded-full">进行中</span>`

**订单信息网格**（第1157-1174行）：
- 容器：`grid grid-cols-2 gap-3 text-sm mb-3`
- 每个字段：标签 `<p class="text-gray-500">预计人数</p>`，值 `<p class="text-gray-800">30人</p>`
- 字段包括：预计人数、实际人数、开始日期、预计结束日期

**打卡数据统计网格**（第1176-1192行）：
- 容器：`grid grid-cols-3 gap-2 mb-3`
- 统计卡片：`bg-blue-50 rounded-lg p-2 text-center`（三种颜色：blue-50, green-50, purple-50）
  - 标题：`<p class="text-xs text-gray-600">本月打卡</p>`
  - 数值：`<p class="text-sm font-bold text-gray-800">24/30</p>`
  - 百分比：`<p class="text-xs text-gray-500">80%</p>`
- 统计类型：本月打卡、工资视频、个税视频

**操作按钮区域**（第1193-1200行）：
- 容器：`flex justify-between text-sm`
  - 查看详情按钮：`text-blue-500`，图标 `<i class="fas fa-eye mr-1"></i>`，文字"查看详情"
  - 下载视频按钮：`text-gray-500`，图标 `<i class="fas fa-download mr-1"></i>`，文字"下载视频"

**订单详情设计规范**：
原型文件中没有单独的订单详情页面，需要基于人才详情页面（页面4）的设计风格创建：

**设计原则**：
- 遵循人才详情页的卡片式布局和信息分组方式
- 使用相同的颜色系统、字体大小和间距规范
- 保持一致的交互模式（返回列表、操作按钮等）

**建议页面结构**：
1. **顶部信息区域**：类似人才详情页，显示订单名称、状态、创建时间等关键信息
2. **基本信息卡片**：订单编号、创建时间、预计人数、实际人数、时间范围等
3. **关联人才卡片**：显示订单关联的人才列表（可点击跳转人才详情）
4. **打卡记录卡片**：按月显示打卡统计，支持查看详细打卡记录
5. **视频资料卡片**：分类显示关联视频（工资视频、个税视频等），支持播放下载
6. **操作区域**：状态变更、添加备注、下载报告等操作按钮

**样式参考**：
- 卡片样式：使用 `.card bg-white p-4 mb-4`
- 标题样式：`<h3 class="font-semibold text-gray-700 mb-3">`
- 字段布局：`grid grid-cols-2 gap-3 text-sm` 或 `space-y-3 text-sm`
- 状态标签：复用现有标签样式（绿色-进行中、蓝色-已完成等）

**UI组件使用**：
- **基础组件来源**（现在来自独立的UI包）：
  - `YongrenTabBarLayout` - 从`@d8d/yongren-shared-ui/components/YongrenTabBarLayout`导入（底部导航布局组件，主页面必须使用，订单标签激活状态）
  - `Navbar` - 从`@d8d/mini-shared-ui-components/components/navbar`导入（顶部导航栏组件，所有页面必须使用）
  - `PageContainer` - 从`@d8d/mini-shared-ui-components/components/page-container`导入（页面容器组件）
- **页面层级结构规范**：
  - **主页面**（订单列表页）：使用`YongrenTabBarLayout` + `Navbar`组合
    - Navbar配置：`title="订单列表"`，`leftIcon=""`，`leftText=""`（无返回按钮）
    - ScrollView布局：`px-4 pb-4 pt-0`（移除顶部内边距适配navbar占位）
  - **二级页面**（订单详情页）：仅使用`Navbar`（移除YongrenTabBarLayout包裹）
    - Navbar配置：`title="订单详情"`，`leftIcon="i-heroicons-chevron-left-20-solid"`，`leftText="返回"`（带返回按钮）
    - ScrollView布局：`h-screen overflow-y-auto px-4 pb-4 pt-0`
- **独立开发小程序UI组件**：基于原型文件独立设计开发订单管理相关UI组件
- **复用现有基础组件**：复用mini项目中已有的基础UI组件（表格、统计卡片等），根据原型设计调整样式
- **注意**：史诗011针对mini小程序，UI组件应独立设计，而非复用管理后台的`@d8d/allin-*`系列UI包

### 文件位置
**当前架构（已按mini-ui-packages拆分）**：

**订单管理UI包**：
- **包名称**：`@d8d/yongren-order-management-ui`（位于`mini-ui-packages/yongren-order-management-ui/`）
- **主要页面组件**：
  - `src/pages/OrderList/OrderList.tsx` - 订单列表页面组件
    - 使用`YongrenTabBarLayout`布局，`activeTab="order"`
    - 集成`Navbar`组件，标题"订单列表"，隐藏左侧返回按钮（主页面）
    - 使用`ScrollView`作为内容容器，布局`px-4 pb-4 pt-0`适配navbar占位
    - 路由路径：`pages/yongren/order/list`
  - `src/pages/OrderDetail/OrderDetail.tsx` - 订单详情页面组件
    - 集成`Navbar`组件，标题"订单详情"，带左侧返回按钮（二级页面）
    - 移除`YongrenTabBarLayout`包裹（二级页不需要底部导航）
    - 使用`ScrollView`作为内容容器，布局`h-screen overflow-y-auto px-4 pb-4 pt-0`
    - 路由路径：`pages/yongren/order/detail`
- **依赖的UI包**：
  - **布局组件**：
    - `@d8d/yongren-shared-ui/components/YongrenTabBarLayout` - 底部导航布局组件（主页面使用）
    - `@d8d/mini-shared-ui-components/components/navbar` - 顶部导航栏组件（所有页面使用）
    - `@d8d/mini-shared-ui-components/components/page-container` - 页面容器组件
  - **业务模块**：
    - `@d8d/allin-order-module` - 订单管理模块类型定义

**桥接文件位置**（在mini项目中）：
- `mini/src/pages/yongren/order/list/index.tsx` - 订单列表页面桥接文件
  - 从`@d8d/yongren-order-management-ui`导入`OrderList`组件
  - 路由路径：`pages/yongren/order/list`
- `mini/src/pages/yongren/order/detail/index.tsx` - 订单详情页面桥接文件
  - 从`@d8d/yongren-order-management-ui`导入`OrderDetail`组件
  - 路由路径：`pages/yongren/order/detail`

### 数据模型
基于史诗012扩展的数据库schema：
- `order_person_asset`表的`asset_type`枚举已扩展视频类型 [来源：docs/stories/012.001.story.md#数据模型]
  - 新增视频类型：`salary_video`、`tax_video`、`checkin_video`、`work_video`
- 订单与人才、企业、岗位的多重关联关系

### 技术约束
- **数据权限**：企业只能查看和管理自己的订单
- **状态流转**：订单状态变更需符合业务流程规则
- **性能考虑**：打卡数据可能量大，需分页或懒加载
- **视频处理**：视频播放需考虑格式兼容性和加载性能
- **页面结构**：主页面必须使用YongrenTabBarLayout+Navbar（无返回按钮），二级页必须使用Navbar（带返回按钮，移除YongrenTabBarLayout包裹），遵循统一的页面层级结构规范
- **布局渲染**：Taro小程序中View容器内的Text组件默认内联显示，需要使用`flex flex-col`强制垂直排列，确保布局符合原型设计

### 测试要求
**测试框架**：Jest + Testing Library
**关键测试场景**：
1. **订单列表测试**：
   - 搜索筛选功能测试
   - 分页排序测试
   - 表格渲染性能测试
2. **订单管理测试**：
   - 订单状态变更流程测试
   - 权限验证测试
   - 数据一致性测试
3. **打卡统计测试**：
   - 数据统计准确性测试
   - 时间范围筛选测试
   - 数据导出功能测试
4. **视频管理测试**：
   - 视频列表展示测试
   - 视频播放功能测试
   - 批量操作测试
5. **页面结构测试**：
   - Navbar组件集成测试（主页面无返回，二级页带返回）
   - 页面层级结构验证（主页面使用YongrenTabBarLayout，二级页移除）
   - 类型检查验证

## 变更日志
| 日期 | 版本 | 描述 | 作者 |
|------|------|------|------|
| 2025-12-17 | 1.0 | 初始创建（订单管理故事） | Bob（Scrum Master） |
| 2025-12-20 | 1.1 | 更新Navbar集成规范，添加页面层级结构，反映mini-ui-packages架构 | Claude Code |
| 2025-12-20 | 1.2 | 实施订单管理功能：订单列表页、订单详情页、打卡统计、视频统计、集成测试 | James (Developer) |

## 开发代理记录
*此部分由开发代理在实施过程中填充*

**文档更新记录 (2025-12-20)**：
- 根据史诗011最新实现，更新Navbar组件集成规范
- 添加任务6：集成Navbar导航栏组件（页面层级结构规范）
- 更新UI组件使用规范，反映mini-ui-packages拆分后的架构
- 更新技术约束，添加页面结构要求
- 更新测试要求，添加页面结构测试场景
- 统一所有用人小程序页面的Navbar集成标准

## QA结果
*来自QA代理对已完成故事实施的QA审查结果*