mini-starter/docs/stories/005.014.order-export.story.md

Story 5.14: 管理后台订单数据导出功能

Status

Draft

Story

As a 系统管理员 I want 能够在管理后台的订单管理页面导出订单数据为xlsx格式 so that 进行数据分析和报表制作

Acceptance Criteria

• 在订单管理页面添加"导出Excel"按钮
• 支持按当前筛选条件导出订单数据
• 导出的xlsx文件包含完整的订单信息（包含乘客快照信息）
• 支持批量导出所有订单数据
• 导出的文件格式规范，包含表头和格式
• 支持导出进度显示和下载提示
• 处理大量数据时的性能优化
• 导出文件命名规范，包含时间戳

Tasks / Subtasks

• 前端实现订单导出功能 (AC: 1, 2, 3, 4, 5, 6, 8)
  • 在Orders.tsx页面添加"导出Excel"按钮
  • 实现导出处理函数，收集当前筛选条件
  • 使用现有xlsx库生成Excel文件
  • 实现导出进度显示和下载提示
  • 处理大量数据时的分页查询和性能优化
  • 实现文件命名规范，包含时间戳
• 后端支持订单数据查询 (AC: 2, 3, 4, 7)
  • 利用现有通用CRUD API支持大pageSize查询
  • 确保API支持JSON格式筛选条件
  • 验证订单数据字段完整性
• 测试订单导出功能 (AC: 1-8)
  • 编写单元测试验证导出功能
  • 编写集成测试验证数据完整性
  • 编写E2E测试验证完整导出流程

Dev Notes

技术栈信息

[Source: architecture/tech-stack.md#现有技术栈维护]

• 前端框架: Taro + React (小程序), React + Vite (Web管理后台)
• 状态管理: React Query 5.83.0
• UI组件库: shadcn/ui + Tailwind CSS 4.1.11
• Excel库: 已安装的xlsx库

项目结构信息

[Source: architecture/source-tree.md#实际项目结构]

• 管理后台页面位置: web/src/client/admin/pages/Orders.tsx
• API客户端位置: web/src/client/api.ts
• 订单API路径: packages/server/src/api/admin/orders/index.ts

订单数据结构

[Source: docs/prd/epic-005-travel-service-core.md#实际可导出数据字段] 可导出数据字段:

• 订单编号: id
• 用户信息: user.username, user.phone
• 路线信息: route.name, route.description
• 乘客数量: passengerCount
• 订单金额: totalAmount
• 订单状态: status (待支付、待出发、行程中、已完成、已取消)
• 支付状态: paymentStatus (待支付、支付中、已支付、支付失败、已退款、已关闭)
• 创建时间: createdAt
• 更新时间: updatedAt
• 乘客快照信息: passengerSnapshots (包含姓名、证件类型、证件号码等)

通用CRUD规范

[Source: architecture/generic-crud-standards.md#核心组件]

• 订单查询API: 使用现有通用CRUD API，支持分页、筛选和关联查询
• 筛选条件: 支持JSON格式筛选条件，包含状态、支付状态等
• 分页查询: 支持大pageSize参数获取所有数据

管理后台开发规范

[Source: architecture/admin-dashboard-standards.md#页面开发规范]

• 页面结构: 遵循标准管理后台页面结构
• 按钮使用: 使用shadcn/ui Button组件
• 状态管理: 使用React Query进行数据获取和缓存
• 用户体验: 实现导出进度显示和错误处理

技术实现方案

[Source: docs/prd/epic-005-travel-service-core.md#技术实现方案]

• 前端实现: 使用已安装的 xlsx 库生成Excel文件
• 后端支持: 利用现有的通用CRUD API，支持JSON格式筛选条件
• 文件生成: 前端生成Excel文件，避免服务器压力
• 性能优化: 使用现有API的pageSize参数支持大量数据查询

前端实现细节

[Source: docs/prd/epic-005-travel-service-core.md#前端实现细节]

// 订单导出功能实现 - 基于实际Orders.tsx页面结构
const handleExportOrders = async () => {
  try {
    // 1. 显示导出进度
    setExporting(true);

    // 2. 获取当前页面筛选条件（基于现有filters和searchParams）
    const exportFilters = {
      status: filters.status,
      paymentStatus: filters.paymentStatus,
      search: searchParams.search,
      pageSize: 10000 // 使用大pageSize获取所有数据
    };

    // 3. 调用API获取订单数据
    // 4. 使用xlsx库生成Excel文件
    // 5. 创建下载链接并触发下载
    // 6. 隐藏导出进度
  } catch (error) {
    // 错误处理
  } finally {
    setExporting(false);
  }
};

测试

测试标准

[Source: architecture/coding-standards.md#增强特定标准]

• 测试框架: Vitest + Testing Library + Playwright
• 测试位置: 统一在 tests/ 目录中，按类型分层组织
• 覆盖率目标: 核心业务逻辑 > 80%

测试要求

• 单元测试: 验证导出函数逻辑和Excel生成
• 集成测试: 验证API调用和数据完整性
• E2E测试: 验证完整导出流程和用户体验

测试文件位置

• 单元测试: web/tests/unit/client/admin/pages/Orders.test.tsx
• 集成测试: web/tests/integration/client/admin/pages/Orders.test.tsx
• E2E测试: tests/e2e/admin/order-export.spec.ts

Change Log

Date	Version	Description	Author
2025-10-25	1.0	创建故事文档	Bob (Scrum Master)

Dev Agent Record

Agent Model Used

Claude Sonnet 4.5

Debug Log References

• 检查订单管理页面结构
• 实现前端订单导出功能
• 验证后端API支持
• 编写测试用例
• 运行完整测试验证

Completion Notes List

• ✅ 前端实现订单导出功能，包含导出按钮、进度显示、筛选条件收集
• ✅ 后端API支持大pageSize查询（10000条记录）
• ✅ 包含完整的订单信息导出：订单编号、用户信息、路线信息、乘客数量、订单金额、状态、时间戳
• ✅ 特别包含乘客快照信息导出，显示每个乘客的姓名、证件类型、证件号码和手机号
• ✅ 实现文件命名规范，包含时间戳
• ✅ 编写完整的集成测试用例，覆盖成功、空数据、错误、筛选条件等场景
• ✅ 支持按当前筛选条件导出数据

File List

• 修改文件:
  • web/src/client/admin/pages/Orders.tsx - 添加导出功能
  • packages/server/src/modules/orders/order.schema.ts - 更新pageSize限制
  • web/tests/integration/client/admin/orders.test.tsx - 添加导出功能测试

Status

Ready for Review

QA Results