# Story 5.7: 订单信息查看（管理后台）

## Status
Approved

## Story
**As a** 系统管理员
**I want** 能够查看所有订单信息和状态
**so that** 监控订单流程和处理异常订单

## Acceptance Criteria
1. 支持查看所有订单列表
2. 支持按订单状态筛选（待支付、待出发、行程中、已完成、已取消）
3. 显示订单详细信息（用户信息、路线信息、乘客信息、金额、状态）
4. 支持订单状态统计和报表

## Tasks / Subtasks
- [x] 创建订单相关基础文件 (前置任务)
  - [x] 创建订单实体 `packages/server/src/modules/orders/order.entity.ts`
  - [x] 创建订单Zod Schema `packages/server/src/modules/orders/order.schema.ts`
  - [x] 创建共享类型 `packages/server/src/share/order.types.ts`

- [x] 创建管理后台订单API路由 (AC: 1, 2, 3, 4)
  - [x] 使用通用CRUD规范创建管理后台订单API
  - [x] 实现订单列表查询（支持分页、搜索、状态筛选）
  - [x] 实现订单详情查询（包含关联的用户、路线、乘客信息）
  - [x] 实现订单状态统计API
- [x] 编写管理后台订单API集成测试 (AC: 1, 2, 3, 4)
  - [x] 编写订单列表API集成测试
  - [x] 编写订单状态筛选功能集成测试
  - [x] 编写订单详情查询集成测试
  - [x] 编写订单状态统计API集成测试
  - [x] 验证所有API测试通过
- [ ] 创建管理后台订单管理页面 (AC: 1, 2, 3, 4)
  - [ ] 创建 `web/src/client/admin/pages/Orders.tsx` 页面组件
  - [ ] 实现订单列表表格（显示订单基本信息）
  - [ ] 实现订单状态筛选器（待支付、待出发、行程中、已完成、已取消）
  - [ ] 实现订单搜索功能（按订单号、用户信息搜索）
  - [ ] 实现订单详情查看对话框
  - [ ] 实现订单状态统计面板
  - [ ] 实现数据导出功能
- [ ] 集成订单页面到管理后台路由 (AC: 1)
  - [ ] 在管理后台路由配置中添加订单管理页面
  - [ ] 在管理后台菜单中添加订单管理入口
- [ ] 编写订单管理页面组件测试 (AC: 1, 2, 3, 4)
  - [ ] 编写订单管理页面组件测试
  - [ ] 编写订单状态统计测试

## Dev Notes

### 数据模型设计
基于 [docs/architecture/data-model-schema-changes.md#订单模型]，需要创建订单实体，包含以下关键属性：

**订单实体关键属性** [Source: architecture/data-model-schema-changes.md#订单模型]:
- `id`: number - 主键标识符
- `userId`: number - 用户ID
- `routeId`: number - 路线ID
- `passengerCount`: number - 乘客数量
- `totalAmount`: number - 订单总金额
- `status`: string - 订单状态（待支付、待出发、行程中、已完成、已取消）
- `paymentStatus`: string - 支付状态
- `passengerSnapshots`: JSON - 乘客信息快照数组（下单时的多个乘客信息）
- `routeSnapshot`: JSON - 路线信息快照（下单时的路线信息）
- `createdAt`: Date - 创建时间

**订单状态枚举定义** [Source: architecture/data-model-schema-changes.md#枚举定义]:
```typescript
export enum OrderStatus {
  PENDING_PAYMENT = '待支付',
  WAITING_DEPARTURE = '待出发',
  IN_PROGRESS = '行程中',
  COMPLETED = '已完成',
  CANCELLED = '已取消'
}
```

**支付状态枚举定义** [Source: architecture/data-model-schema-changes.md#枚举定义]:
```typescript
export enum PaymentStatus {
  PENDING = '待支付',
  PAID = '已支付',
  FAILED = '支付失败',
  REFUNDED = '已退款'
}
```

### 通用CRUD规范要求
基于 [docs/architecture/generic-crud-standards.md#使用指南]，管理后台订单管理必须遵循通用CRUD规范，需要创建以下文件：

### 非通用CRUD路由规范要求
基于 [docs/architecture/non-generic-crud-standards.md#统计查询路由]，订单状态统计API必须遵循非通用CRUD路由规范，需要创建以下文件：

**统计查询路由规范** [Source: architecture/non-generic-crud-standards.md#统计查询路由]:
- 使用 `GET` 方法，路径为 `/stats`
- 返回聚合数据而非分页列表
- 包含完整的错误处理和权限控制
- 自动生成OpenAPI文档

**统计路由代码模板** [Source: architecture/non-generic-crud-standards.md#代码模板]:
```typescript
// 统计路由定义
const statsRoute = createRoute({
  method: 'get',
  path: '/',
  middleware: [authMiddleware, adminMiddleware],
  responses: {
    200: {
      description: '成功获取统计信息',
      content: {
        'application/json': {
          schema: OrderStatsSchema
        }
      }
    },
    401: { description: '未授权' },
    403: { description: '权限不足' },
    500: { description: '服务器错误' }
  }
});
```

**实体设计** [Source: architecture/generic-crud-standards.md#实体设计]:
- 使用TypeORM装饰器定义字段
- 为所有字段添加 `comment` 配置，说明字段用途
- 包含 `createdAt` 和 `updatedAt` 时间戳

**Schema设计** [Source: architecture/generic-crud-standards.md#schema设计]:
- 创建和更新使用不同的schema
- 响应schema应包含完整字段
- 使用 `.optional()` 和 `.nullable()` 明确字段可选性

**CRUD路由注册** [Source: architecture/generic-crud-standards.md#注册crud路由]:
```typescript
export const orderRoutes = createCrudRoutes({
  entity: Order,
  createSchema: OrderCreateSchema,
  updateSchema: OrderUpdateSchema,
  getSchema: OrderGetSchema,
  listSchema: OrderListSchema,
  searchFields: ['id', 'user.username'],
  relations: ['user', 'route', 'passengers'],
  middleware: [authMiddleware, adminMiddleware],
  userTracking: {
    createdByField: 'createdBy',
    updatedByField: 'updatedBy'
  }
});
```

### 管理后台开发规范
基于 [docs/architecture/admin-dashboard-standards.md#页面开发规范]，订单管理页面必须遵循管理后台开发标准，需要创建以下文件：

**页面结构标准** [Source: architecture/admin-dashboard-standards.md#页面结构标准]:
- 使用React + TypeScript + React Query技术栈
- 遵循标准页面结构（标题、搜索栏、表格、分页）
- 使用shadcn/ui组件库和Tailwind CSS样式

**数据表格规范** [Source: architecture/admin-dashboard-standards.md#数据表格规范]:
- 使用标准表格结构（Table、TableHeader、TableBody、TableRow、TableCell）
- 实现分页组件（DataTablePagination）
- 支持搜索和筛选功能

**RPC Client使用规范** [Source: architecture/admin-dashboard-standards.md#rpc-client-使用规范]:
- 从统一的API模块导入客户端
- 使用InferResponseType和InferRequestType提取类型
- 遵循标准API调用模式（GET、POST、PUT、DELETE）

### 文件位置
基于 [docs/architecture/source-tree.md#实际项目结构]，所有订单相关文件必须放置在指定位置：

**后端文件位置** [Source: architecture/source-tree.md#实际项目结构]:
- **API路由**: `packages/server/src/api/admin/orders/index.ts`
- **实体定义**: `packages/server/src/modules/orders/order.entity.ts`
- **业务服务**: `packages/server/src/modules/orders/order.service.ts`
- **Zod Schema**: `packages/server/src/modules/orders/order.schema.ts`

**前端文件位置** [Source: architecture/source-tree.md#实际项目结构]:
- **管理后台页面**: `web/src/client/admin/pages/Orders.tsx`
- **共享类型**: `packages/server/src/share/order.types.ts`

### 技术栈要求
基于 [docs/architecture/tech-stack.md#现有技术栈维护]，必须使用项目标准技术栈：

**后端框架** [Source: architecture/tech-stack.md#现有技术栈维护]:
- **运行时**: Node.js 20.19.2
- **框架**: Hono 4.8.5
- **数据库**: PostgreSQL 17
- **ORM**: TypeORM 0.3.25

**前端框架** [Source: architecture/tech-stack.md#现有技术栈维护]:
- **前端框架**: React 19.1.0+
- **样式**: Tailwind CSS 4.1.11
- **状态管理**: @tanstack/react-query
- **UI组件**: shadcn/ui

### 开发规范要求
基于 [docs/architecture/coding-standards.md#通用crud开发规范]，必须遵循编码标准创建以下文件：

**CRUD开发** [Source: architecture/coding-standards.md#通用crud开发规范]:
- 遵循通用CRUD规范进行开发
- 使用TypeORM装饰器定义字段，为所有字段添加 `comment` 配置
- 包含时间戳字段
- 创建、更新、响应使用不同的Zod schema
- 使用 `createCrudRoutes` 自动生成API路由

**非通用CRUD路由开发** [Source: architecture/coding-standards.md#非通用crud路由开发规范]:
- 遵循非通用CRUD路由规范进行开发
- 统计查询、层级数据查询、业务操作等非标准CRUD场景
- 使用Zod schema定义查询参数、路径参数和响应格式
- 统一错误响应格式，包含完整的错误状态码
- 复用现有中间件，实现资源所有权验证
- 自动生成OpenAPI文档，包含请求响应示例

**管理后台开发** [Source: architecture/coding-standards.md#管理后台开发规范]:
- 遵循管理后台开发规范进行开发
- 统一页面结构和布局标准
- 实现基于角色的访问控制
- 提供统一的加载状态、错误处理和用户反馈机制

### Testing

**测试要求** [Source: architecture/testing-strategy.md#主项目测试体系]:
- **主项目测试位置**: `web/tests/unit/`, `web/tests/integration/`, `web/tests/e2e/` 目录
- **主项目测试框架**: Vitest + Testing Library + hono/testing + Playwright
- **管理后台测试位置**: `web/tests/unit/client/admin/` 目录
- **覆盖率目标**: 核心业务逻辑 > 80%
- **需要创建的测试文件**: 订单管理页面组件测试、订单API集成测试

**具体测试要求** [Source: architecture/testing-strategy.md#测试金字塔策略]:
- **管理后台订单API集成测试** (P1优先级)
  - 测试订单列表API端点
  - 验证订单状态筛选功能
  - 测试订单详情查询
  - 验证订单统计API
- **订单管理页面组件测试** (P1优先级)
  - 测试订单列表页面渲染
  - 验证订单状态筛选器功能
  - 测试订单搜索功能
  - 验证订单详情对话框
  - 测试订单统计面板
- **管理后台权限测试** (P1优先级)
  - 验证只有管理员可以访问订单管理页面
  - 测试权限控制中间件
- **E2E订单管理流程测试** (P2优先级)
  - 测试完整的订单查看流程
  - 验证订单状态筛选和搜索功能
  - 测试订单详情查看功能

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-10-23 | 1.4 | 完成订单API集成测试编写和修复，所有测试通过 | James (Developer) |
| 2025-10-23 | 1.3 | 添加非通用CRUD路由规范引用，更新API开发标准 | Winston (Architect) |
| 2025-10-23 | 1.2 | 更新故事状态为Approved，准备实施 | Sarah (PO) |
| 2025-10-23 | 1.1 | 修正文件存在性错误，添加基础文件创建任务 | Sarah (PO) |
| 2025-10-23 | 1.0 | 初始故事创建，基于史诗005 US005-07需求 | Bob (Scrum Master) |

## Dev Agent Record
*此部分由开发代理在实施过程中填写*

### Agent Model Used
- James (dev agent) - 用于修复订单API集成测试

### Debug Log References
- 修复订单API集成测试参数验证问题
- 修复订单schema数据类型不匹配问题

### Completion Notes List
- 修复了订单API集成测试中的参数验证问题
- 更新了OrderResponseSchema以正确处理数据库返回的数据类型
- 所有7个集成测试用例现在全部通过

### File List
- [packages/server/src/modules/orders/order.schema.ts](packages/server/src/modules/orders/order.schema.ts) - 修复schema数据类型定义
- [web/tests/integration/server/admin/orders.integration.test.ts](web/tests/integration/server/admin/orders.integration.test.ts) - 集成测试文件

## QA Results
*此部分由QA代理在审查完成后填写*