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

Status

Approved

Story

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

Acceptance Criteria

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

Tasks / Subtasks

[x] 创建订单相关基础文件 (前置任务)
- 创建订单实体 packages/server/src/modules/orders/order.entity.ts
- 创建订单Zod Schema packages/server/src/modules/orders/order.schema.ts
- 创建共享类型 packages/server/src/share/order.types.ts
[x] 创建管理后台订单API路由 (AC: 1, 2, 3, 4)
- 使用通用CRUD规范创建管理后台订单API
- 实现订单列表查询（支持分页、搜索、状态筛选）
- 实现订单详情查询（包含关联的用户、路线、乘客信息）
- 实现订单状态统计API
[x] 编写管理后台订单API集成测试 (AC: 1, 2, 3, 4)
- 编写订单列表API集成测试
- 编写订单状态筛选功能集成测试
- 编写订单详情查询集成测试
- 编写订单状态统计API集成测试
- 验证所有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#枚举定义]:

export enum OrderStatus {
  PENDING_PAYMENT = '待支付',
  WAITING_DEPARTURE = '待出发',
  IN_PROGRESS = '行程中',
  COMPLETED = '已完成',
  CANCELLED = '已取消'
}

支付状态枚举定义 [Source: architecture/data-model-schema-changes.md#枚举定义]:

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#代码模板]:

// 统计路由定义
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路由]:

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 - 修复schema数据类型定义
web/tests/integration/server/admin/orders.integration.test.ts - 集成测试文件

QA Results

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

005.007.story.md 12 KB Histórico Em bruto