Головна сторінка Огляд Довідка
Реєстрація Увійти
188-template-179
/
mini-starter
відгалужено від 155-template-138/mini-starter
2
0
Відгалуження 0
Файли
Дерево: 10eda70f80
Гілки Теги
mini-starter
/
_bmad-output
/
implementation-artifacts
/
13-14-order-detail-stats-fix.md

13-14-order-detail-stats-fix.md 14 KB
Історія Запис

Story 13.14: 修复企业小程序订单详情页统计数据问题

Status: done

元数据

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

用户故事

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

问题背景

当前问题： 企业小程序订单详情页中的统计数据显示错误，与订单列表页数据不一致：

页面 本月打卡 工资视频
订单列表页 (Story 13-13 已修复) 1/1 100% 1/1 100%
订单详情页 (当前问题) 12/0 0% 0/0 0%

根本原因分析：

  1. Story 13-13 修复了订单列表页的统计数据，API 正常工作（/company-orders/{id}/stats）
  2. Story 13-11 验证了订单详情页的 UI 结构，但未深入验证统计数据准确性
  3. 订单详情页可能存在以下问题之一：
    • 未调用统计 API，使用硬编码或错误数据源
    • 数据绑定逻辑错误，字段映射不正确
    • API 调用时机或参数错误

影响范围： 企业用户在订单详情页看到错误的统计数据，影响业务决策和用户体验。

验收标准

AC 1: 订单详情页统计数据与列表页一致

Given 企业小程序订单列表页显示正确统计数据 When 点击订单卡片进入订单详情页 Then 详情页的统计数据应与列表页完全一致 And 实际人数应相同 And 本月打卡统计应相同（格式：实际数/总数 百分比） And 工资视频统计应相同 And 个税视频统计应相同

AC 2: 订单详情页调用统计 API

Given 订单详情页加载时 When 页面渲染统计数据区域 Then 应调用后端 /api/company-orders/{orderId}/stats API And 应传递正确的订单 ID 参数 And 应正确解析和显示 API 返回的统计数据

AC 3: 订单详情页统计数据字段正确显示

Given 后端 API 返回正确的统计数据 When 在订单详情页查看统计数据 Then "实际人数"应显示 actualPeople 字段值 And "本月打卡"应显示 checkinStats（current/total percentage） And "工资视频"应显示 salaryVideoStats And "个税视频"应显示 taxVideoStats And 百分比计算应正确（保留整数或指定小数位）

AC 4: 后台添加打卡视频后详情页统计更新

Given 后台为订单人员添加打卡视频 When 在企业小程序打开订单详情页 Then 本月打卡统计应反映最新数据 And 统计数据应在合理时间内更新（缓存时间 ≤ 5 分钟）

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

Given E2E 测试环境 When 运行订单详情页统计测试 Then 应验证详情页与列表页数据一致性 And 应验证 API 调用正确 And 应验证数据绑定逻辑正确 And 应验证跨端数据同步正确

任务 / Subtasks

任务 0: 分析订单详情页数据获取逻辑 (AC: #)

  • 分析订单详情页组件代码（OrderDetail.tsx 或类似文件）
  • 确认当前数据源（是否调用统计 API 或使用硬编码）
  • 确认数据绑定逻辑和字段映射关系
  • 对比列表页和详情页的数据处理差异

任务 1: 修复后端 API 或前端数据绑定 (AC: #)

  • 如果是后端 API 问题：
    • 检查 /company-orders/{id}/stats 端点是否支持详情页调用
    • 确认 API 响应格式与前端期望一致
    • 修复 API 问题（如有）
  • 如果是前端数据绑定问题：
    • 修改订单详情页组件，调用统计 API
    • 正确绑定 API 返回数据到 UI 组件
    • 处理加载状态和错误状态

任务 2: 确保详情页与列表页数据一致 (AC: #)

  • 验证两个页面使用相同的 API 端点
  • 验证两个页面的数据格式化逻辑一致
  • 验证缓存策略不影响数据一致性

任务 3: 创建/更新 Page Object 方法 (AC: #)

  • 在 enterprise-mini.page.ts 中添加/更新方法：
    • getOrderDetailStats(orderId: number) - 获取详情页统计数据
    • expectOrderDetailStatsConsistentWithList(orderId) - 验证详情页与列表页一致
    • expectOrderDetailStatsField(fieldName, expected) - 验证单个字段

任务 4: 创建 E2E 测试文件 (AC: #)

  • 创建 web/tests/e2e/specs/cross-platform/order-detail-stats-fix.spec.ts
  • 实现数据一致性验证测试
  • 实现跨端数据同步验证测试

任务 5: 实现 AC1-AC3 验证测试 (AC: #)

  • 测试：验证详情页与列表页统计数据一致
  • 测试：验证详情页调用统计 API
  • 测试：验证详情页统计数据字段正确显示
  • 测试：验证百分比计算正确

任务 6: 实现 AC4 跨端数据同步测试 (AC: #)

  • 测试：后台添加打卡视频 → 详情页统计更新验证
  • 测试：后台添加工资视频 → 详情页统计更新验证
  • 测试：后台添加个税视频 → 详情页统计更新验证

任务 7: 集成测试与稳定性验证 (AC: #)

  • 测试：验证详情页缓存不影响数据准确性
  • 测试：验证无统计数据时的显示状态
  • 稳定性验证：连续运行 10 次，100% 通过

Dev Notes

Epic 13 背景和依赖

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

  • 目标: 验证后台操作后小程序端的数据同步，覆盖完整的业务流程
  • 业务分组: Epic E（跨端数据同步测试）
  • 背景: 真实用户旅程跨越管理后台和小程序，需要验证数据同步的正确性和时效性
  • 依赖:
    • Epic 10: 已完成（订单管理 E2E 测试）
    • Epic 12: 已完成（小程序登录测试）
    • Story 13-11: 已完成（订单详情页完整性验证）
    • Story 13-13: 已完成（订单列表页统计字段显示修复）

订单统计字段业务含义

根据 Story 13-13 的 PRD 文档，订单统计字段定义如下：

字段 业务含义 数据来源 计算逻辑 显示格式
实际人数 当前订单实际关联的残疾人人数 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/OrderDetail/
    • 或类似路径：OrderDetail.tsx, OrderDetailPage.tsx
  • 订单列表页组件（参考修复）：
    • mini-ui-packages/yongren-order-management-ui/src/pages/OrderList/OrderList.tsx

后端 API（已在 Story 13-13 中实现）：

  • 端点：GET /api/company-orders/{orderId}/stats
  • 文件位置参考：
    • allin-packages/order-module/src/routes/order-custom.routes.ts
    • allin-packages/order-module/src/services/order.service.ts
    • allin-packages/order-module/src/schemas/order.schema.ts

E2E 测试文件（需创建）：

  • web/tests/e2e/specs/cross-platform/order-detail-stats-fix.spec.ts
  • web/tests/e2e/pages/mini/enterprise-mini.page.ts（可能已有部分方法）

API 设计参考（Story 13-13 已实现）

端点：

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

查询参数（可选）：

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

响应格式：

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;
  };
}

前端修复方案参考

Story 13-13 列表页修复经验：

  1. 创建 useOrderStats() hook 用于获取统计数据
  2. 使用 React Query 管理状态和缓存
  3. 在 OrderCard 组件中独立调用 API
  4. 显示 "..." 加载状态，错误时降级到 0/0 0%

详情页修复建议：

  1. 参考 OrderList.tsx 的 useOrderStats() 实现
  2. 在详情页组件中调用相同的 API
  3. 确保字段映射与列表页一致
  4. 使用相同的缓存策略（5 分钟）

订单详情页 URL 参考

/mini/#/mini/pages/yongren/order/detail/index?id={orderId}

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

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

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

参考文档

PRD 文档：

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

架构文档：

  • _bmad-output/planning-artifacts/architecture.md - 技术栈和架构决策
  • _bmad-output/project-context.md - 项目上下文和开发规范

相关 Story 文档：

  • 13-13-order-stats-fix.md - 订单列表页统计修复（参考实现）
  • 13-11-order-detail-validation.md - 订单详情页完整性验证
  • 12-4-enterprise-mini-page-object.md - 企业小程序 Page Object
  • 12-5-enterprise-mini-login.md - 企业小程序登录测试

项目结构说明

前端组件位置：

mini-ui-packages/
└── yongren-order-management-ui/
    ├── src/
    │   ├── pages/
    │   │   ├── OrderList/      # 订单列表页（已修复）
    │   │   │   └── OrderList.tsx
    │   │   └── OrderDetail/    # 订单详情页（需检查）
    │   │       └── OrderDetail.tsx 或类似文件
    │   ├── api/
    │   │   └── types.ts        # API 类型定义
    │   └── hooks/
    │       └── useOrderStats.ts # 可能需要迁移此 hook
    └── package.json

后端 API 位置：

allin-packages/
└── order-module/
    ├── src/
    │   ├── routes/
    │   │   └── order-custom.routes.ts  # 统计 API 路由
    │   ├── services/
    │   │   └── order.service.ts         # 统计服务
    │   └── schemas/
    │       └── order.schema.ts          # API Schema
    └── package.json

Dev Agent Record

Agent Model Used

  • Model: Claude (d8d-model)
  • Date: 2026-01-16

Debug Log References

  • 无需调试日志，修复直接有效

Completion Notes List

  1. 根本原因分析 (任务 0)：

    • 订单列表页 (OrderList.tsx) 使用正确的 /company-orders/:id/stats API
    • 订单详情页 (OrderDetail.tsx) 错误地使用了公司级别的统计 API (/checkin-statistics 和 /video-statistics)
    • 这导致详情页显示的是公司全局统计而非订单特定统计

  2. 修复实现 (任务 1)：

    • 将 fetchOrderStatisticsQuery 函数修改为调用 /company-orders/:id/stats API
    • 添加 actualPeople 字段到 StatisticsData 接口
    • 使用与列表页相同的缓存策略 (5 分钟)
    • 使用相同的 queryKey (['order-stats', orderId]) 确保缓存共享

  3. 数据一致性验证 (任务 2)：

    • 两个页面现在使用相同的 API 端点
    • 数据格式化逻辑一致
    • 缓存策略一致（5 分钟）

  4. Page Object 扩展 (任务 3)：

    • 添加 OrderDetailStats 接口定义
    • 添加 getOrderDetailStats() 方法
    • 添加 expectOrderDetailStatsConsistentWithList() 方法
    • 添加 expectOrderDetailStatsField() 方法

  5. E2E 测试创建 (任务 4-7)：

    • 创建 order-detail-stats-fix.spec.ts 测试文件
    • 实现 AC1-AC5 的所有验收标准测试
    • 包含稳定性验证测试（连续运行 10 次）

File List

修改的文件：

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

    • 修改 fetchOrderStatisticsQuery 函数使用正确的 API 端点
    • 更新 StatisticsData 接口包含 actualPeople 字段
    • 添加缓存策略 (5 分钟) 与列表页保持一致
    • 移除未使用的导入 (CheckinStatisticsResponse, VideoStatisticsResponse)

  • web/tests/e2e/pages/mini/enterprise-mini.page.ts

    • 添加 OrderDetailStats 接口定义
    • 添加 getOrderDetailStats() 方法
    • 添加 expectOrderDetailStatsConsistentWithList() 方法
    • 添加 expectOrderDetailStatsField() 方法

  • _bmad-output/implementation-artifacts/sprint-status.yaml

    • 更新 Story 13-14 状态为 in-progress → review

新创建的文件：

  • web/tests/e2e/specs/cross-platform/order-detail-stats-fix.spec.ts
    • AC1: 验证详情页与列表页统计数据一致
    • AC2: 验证详情页调用统计 API
    • AC3: 验证详情页统计数据字段正确显示
    • AC5: E2E 测试验证修复效果
    • 稳定性测试: 连续运行 10 次

Change Log

  • 2026-01-16: Story 13.14 创建完成
    • 订单详情页统计数据修复需求
    • 5 个验收标准（AC）
    • 7 个任务（包含分析、修复、E2E 测试）
    • 状态：ready-for-dev