|
|
@@ -0,0 +1,149 @@
|
|
|
+# 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#前端实现细节]
|
|
|
+```typescript
|
|
|
+// 订单导出功能实现 - 基于实际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
|
|
|
+
|
|
|
+### Debug Log References
|
|
|
+
|
|
|
+### Completion Notes List
|
|
|
+
|
|
|
+### File List
|
|
|
+
|
|
|
+## QA Results
|
yourname