mini-starter/_bmad-output/implementation-artifacts/13-13-order-stats-fix.md

Story 13.13: 修复企业小程序订单统计字段显示问题

Status: ready-for-dev

元数据

• Epic: Epic 13 - 跨端数据同步测试
• 状态: ready-for-dev
• 优先级: P0 (高优先级 Bug 修复)
• 故事点: 5

用户故事

作为企业管理员， 我在企业小程序的订单列表中查看订单卡片时， 我希望看到准确的订单统计数据（实际人数、本月打卡、工资视频、个税视频）， 以便了解订单执行情况和人员合规状态。

问题背景

当前问题： 企业小程序订单卡片中的统计字段显示为 0：

• 实际人数：正确（从 orderPersons 数组长度计算）
• 本月打卡：显示为 0/0 0%（硬编码）
• 工资视频：显示为 0/0 0%（硬编码）
• 个税视频：显示为 0/0 0%（硬编码）

根本原因： 前端 OrderList.tsx 文件中硬编码了统计值为 0，未调用后端统计 API。

影响范围： 企业用户无法通过小程序了解订单执行情况和人员合规状态，影响业务决策。

验收标准

AC 1: 修复订单卡片统计字段硬编码问题

Given 企业小程序订单列表页面 When 页面加载订单数据时 Then 应该从后端 API 获取实际统计数据 And "实际人数"应显示订单实际关联的残疾人人数（当前已正确） And "本月打卡"应显示实际的打卡统计数据 And "工资视频"应显示实际的工资视频统计数据 And "个税视频"应显示实际的个税视频统计数据

AC 2: 本月打卡统计字段正确显示

Given 订单卡片显示本月打卡统计 When 查看统计数据时 Then 应显示格式：实际打卡数/订单总人数 百分比 And 数据来源：order_person_asset 表，asset_type='checkin_video' And 统计本月内该订单关联人员的打卡视频数量 Example: 24/30 80% 表示 30 人中有 24 人已打卡

AC 3: 工资视频统计字段正确显示

Given 订单卡片显示工资视频统计 When 查看统计数据时 Then 应显示格式：实际视频数/订单总人数 百分比 And 数据来源：order_person_asset 表，asset_type='salary_video' And 统计本月内该订单关联人员的工资确认视频数量 Example: 22/24 92% 表示 24 人中有 22 人已上传工资视频

AC 4: 个税视频统计字段正确显示

Given 订单卡片显示个税视频统计 When 查看统计数据时 Then 应显示格式：实际视频数/订单总人数 百分比 And 数据来源：order_person_asset 表，asset_type='tax_video' And 统计本月内该订单关联人员的个税确认视频数量 Example: 20/24 83% 表示 24 人中有 20 人已上传个税视频

AC 5: E2E 测试验证修复效果

Given 企业小程序订单列表测试 When 运行 E2E 测试时 Then 应验证订单卡片统计字段正确显示 And 应验证数据从 API 获取而非硬编码 And 应验证百分比计算正确

任务

任务 0: 分析现有代码和数据结构

• 分析 OrderList.tsx 当前的数据转换逻辑
• 确认后端 API 是否已提供订单统计数据接口
• 确认 order_person_asset 表结构和字段
• 设计前端调用统计 API 的方案

任务 1: 后端 API 开发（如需要）

• 检查是否存在订单统计 API 端点
• 如不存在，创建 /api/company-orders/{orderId}/stats 端点
• 返回统计数据：实际人数、本月打卡、工资视频、个税视频
• 添加 API Schema 定义

任务 2: 前端代码修复

• 修改 OrderList.tsx 的数据转换逻辑
• 移除硬编码的统计值（line 85-87）
• 调用后端统计 API 获取实际数据
• 处理 API 错误和加载状态

任务 3: 准备 Page Object

• 在 enterprise-mini.page.ts 中添加订单统计相关方法：
  • getOrderCardStats(orderId: number)
  • expectOrderStatsField(fieldName: string, expected: any)

任务 4: 创建 E2E 测试文件

• 创建 web/tests/e2e/specs/cross-platform/order-stats-fix.spec.ts

任务 5: 实现 AC1 修复验证测试

• 测试：验证订单卡片统计字段不再显示为 0
• 测试：验证数据从 API 获取
• 测试：验证加载状态显示正确

任务 6: 实现 AC2-AC4 统计字段验证测试

• 测试：验证本月打卡统计正确性
• 测试：验证工资视频统计正确性
• 测试：验证个税视频统计正确性
• 测试：验证百分比计算正确

任务 7: 跨端数据一致性验证

• 后台添加人员到订单 → 验证小程序实际人数更新
• 后台添加打卡视频 → 验证小程序本月打卡统计更新
• 后台添加工资视频 → 验证小程序工资视频统计更新
• 后台添加个税视频 → 验证小程序个税视频统计更新

任务 8: 集成测试与稳定性验证

• 测试：订单列表加载多个订单的统计性能
• 测试：无统计数据时的显示状态
• 稳定性验证：连续运行 10 次，100% 通过

Dev Notes

Epic 13 背景和依赖

Epic 13: 跨端数据同步测试 (Epic E)

• 目标: 验证后台操作后小程序端的数据同步，覆盖完整的业务流程
• 业务分组: Epic E（跨端数据同步测试）
• 背景: 真实用户旅程跨越管理后台和小程序，需要验证数据同步的正确性和时效性
• 依赖:
  • Epic 10: 已完成（订单管理 E2E 测试）
  • Epic 12: 已完成（小程序登录测试）

订单统计字段业务含义

根据 PRD 文档（_bmad-output/planning-artifacts/prd.md），订单统计字段定义如下：

字段	业务含义	数据来源	计算逻辑	显示格式
实际人数	当前订单实际关联的残疾人人数	order_person 表	统计 order_id 等于当前订单 ID 的记录数量	XX人
本月打卡	本月内残疾人上下班打卡的视频记录数量统计	order_person_asset 表，asset_type='checkin_video'	统计本月内该订单关联人员的打卡视频数量	24/30 80%
工资视频	残疾人每月薪资确认视频，用于合规证明和薪资发放记录	order_person_asset 表，asset_type='salary_video'	统计本月内该订单关联人员的工资确认视频数量	22/24 92%
个税视频	残疾人每月个税确认视频，用于税务合规证明	order_person_asset 表，asset_type='tax_video'	统计本月内该订单关联人员的个税确认视频数量	20/24 83%

相关文件

前端文件（需修复）：

• mini-ui-packages/yongren-order-management-ui/src/pages/OrderList/OrderList.tsx

  • Line 85-87: 硬编码的统计值

    checkinStats: { current: 0, total: orderPersonsCount, percentage: 0 },
    salaryVideoStats: { current: 0, total: orderPersonsCount, percentage: 0 },
    taxVideoStats: { current: 0, total: orderPersonsCount, percentage: 0 }
    

后端 API 相关（需检查/创建）：

• allin-packages/company-order-module/src/routes/company-order.routes.ts
• allin-packages/company-order-module/src/services/company-order.service.ts
• allin-packages/company-order-module/src/schemas/company-order.schema.ts

E2E 测试文件（需创建）：

• web/tests/e2e/specs/cross-platform/order-stats-fix.spec.ts
• web/tests/e2e/pages/mini/enterprise-mini.page.ts

API 设计建议

端点设计：

GET /api/company-orders/{orderId}/stats

响应格式：

interface OrderStatsResponse {
  orderId: number;
  actualPeople: number;
  checkinStats: {
    current: number;
    total: number;
    percentage: number;
  };
  salaryVideoStats: {
    current: number;
    total: number;
    percentage: number;
  };
  taxVideoStats: {
    current: number;
    total: number;
    percentage: number;
  };
}

查询参数（可选）：

• year: 年份（默认当前年）
• month: 月份（默认当前月）

前端修复方案

当前代码问题：

// Line 65-88: 数据转换时硬编码统计值
const transformedOrders = (data.data || []).map((order: OrderData) => {
  const orderPersonsCount = order.orderPersons?.length || 0
  // ...
  return {
    // ...
    checkinStats: { current: 0, total: orderPersonsCount, percentage: 0 },
    salaryVideoStats: { current: 0, total: orderPersonsCount, percentage: 0 },
    taxVideoStats: { current: 0, total: orderPersonsCount, percentage: 0 }
  }
})

修复方案：

1. 在 enterpriseOrderClient 中添加统计 API 调用方法
2. 使用 useQuery 或并行请求获取每个订单的统计数据
3. 合并订单数据和统计数据

测试开发流程（Playwright MCP 持续验证）

本 Story 采用 Playwright MCP 持续验证的测试开发流程：

1. 即时验证: 在开发过程中立即使用 Playwright MCP 验证
2. 持续反馈: 每完成一个功能模块立即验证
3. 减少返工: 早期发现问题可以减少后期返工成本

参考文档

PRD 文档：

• _bmad-output/planning-artifacts/prd.md - 订单统计字段业务定义

架构文档：

• _bmad-output/planning-artifacts/architecture.md - 技术栈和架构决策

相关 Story 文档：

• 13-12-statistics-page-validation.md - 数据统计页修复经验参考
• 12-4-enterprise-mini-page-object.md - 企业小程序 Page Object
• 12-5-enterprise-mini-login.md - 企业小程序登录测试

Dev Agent Record

Agent Model Used

Created by create-story workflow

Debug Log References

Implementation phase - no debug yet

Completion Notes List

File List

待创建的文件：

• _bmad-output/implementation-artifacts/13-13-order-stats-fix.md - Story 文档
• web/tests/e2e/specs/cross-platform/order-stats-fix.spec.ts - E2E 测试文件

待修改的文件：

• _bmad-output/planning-artifacts/epics.md - 添加 Story 13.13
• mini-ui-packages/yongren-order-management-ui/src/pages/OrderList/OrderList.tsx - 修复硬编码统计值
• allin-packages/company-order-module/src/routes/company-order.routes.ts - 添加统计 API（如需要）
• web/tests/e2e/pages/mini/enterprise-mini.page.ts - Page Object 扩展

Change Log

• 2026-01-15: Story 13.13 创建完成
  • 订单统计字段显示修复需求
  • 5 个验收标准（AC）
  • 8 个任务（包含分析、后端 API、前端修复、E2E 测试）
  • 状态：ready-for-dev