mini-starter/docs/stories/011.002.order-cancel-function.md

Story 011.002: 实现订单取消功能

Status

Completed

Story

As a 小程序用户， I want 能够在订单详情页面取消订单， so that 对于已支付订单可以触发退款流程，对于待支付订单可以直接取消，确保订单状态正确流转

Acceptance Criteria

1. 在订单详情页面添加取消订单按钮
2. 取消订单时验证订单状态（仅允许取消"待支付"和"已支付"订单）
3. 对于已支付订单，触发退款流程
4. 订单状态正确更新为"已取消"（支付状态更新为5）
5. 取消原因和操作时间正确记录
6. 在OrderMtService中添加cancelOrder方法

Tasks / Subtasks

• 在 OrderMtService 中添加 cancelOrder 方法 (AC: 2, 3, 4, 5, 6)
  • 在 packages/orders-module-mt/src/services/order.mt.service.ts 中添加方法签名：cancelOrder(tenantId: number, orderId: number, reason: string, userId: number): Promise<void>
  • 实现订单状态验证逻辑（仅允许取消支付状态为0或2的订单）
  • 对于已支付订单（支付状态=2），调用支付模块的退款功能
  • 更新订单状态为5（订单关闭），记录取消时间和原因
  • 确保多租户数据隔离
• 添加取消订单API接口 (AC: 1, 2, 3)
  • 创建 packages/orders-module-mt/src/routes/user/cancel-order.mt.ts 单独路由文件
  • 实现请求参数验证（订单ID、取消原因）
  • 调用 OrderMtService 的 cancelOrder 方法
  • 添加适当的错误处理和响应格式
  • 在 packages/orders-module-mt/src/routes/user/orders.mt.ts 中聚合路由
• 集成取消订单UI到订单详情页面 (AC: 1)
  • 在 mini/src/pages/order-detail/index.tsx 中添加取消订单按钮
  • 实现取消订单的UI交互逻辑
  • 添加取消原因输入对话框
  • 处理取消成功/失败的页面反馈
• 编写集成测试 (AC: 1-6)
  • 在 packages/orders-module-mt/tests/integration/ 现有订单API集成测试中添加取消订单测试
  • 验证订单状态验证逻辑
  • 测试多租户数据隔离
  • 测试已支付订单的退款触发

Dev Notes

技术栈和架构

• 后端框架: Hono 4.8.5 + TypeORM 0.3.25
• 数据库: PostgreSQL 17
• 多租户支持: 通过租户ID字段实现数据隔离
• 项目结构: Monorepo 架构，模块化包设计

现有代码状态分析

• OrderMtService (packages/orders-module-mt/src/services/order.mt.service.ts): 需要添加 cancelOrder 方法
• 订单实体 (packages/orders-module-mt/src/entities/order.mt.entity.ts:72): 支付状态字段定义：0未支付、1支付中、2支付成功、3已退款、4支付失败、5订单关闭
• 用户订单路由 (packages/orders-module-mt/src/routes/user/orders.mt.ts): 需要添加取消订单API端点
• 订单详情页面 (mini/src/pages/order-detail/index.tsx): 需要集成取消订单UI

关键集成点

• 多租户订单模块: OrderMtService 需要与多租户支付模块集成
• 支付退款功能: 需要调用 PaymentMtService 的退款功能（将在Story 3中实现）
• 租户数据隔离: 所有操作必须包含租户ID参数确保数据隔离
• 前端集成: Mini小程序前端需要调用新的取消订单API

文件位置和命名约定

• 订单服务: packages/orders-module-mt/src/services/order.mt.service.ts
• 用户订单路由: packages/orders-module-mt/src/routes/user/orders.mt.ts
• 订单详情页面: mini/src/pages/order-detail/index.tsx
• 现有订单API集成测试路径: packages/orders-module-mt/tests/integration/
• 测试文件: 在现有订单API集成测试中添加取消订单测试

技术约束

• 向后兼容性: 现有订单API保持不变，新增API不影响现有功能
• 多租户支持: 所有新功能必须支持租户隔离
• 错误处理: 需要完善的错误处理和用户友好的错误信息
• 性能要求: 取消订单操作应在合理时间内完成

订单状态流转规则

• 0未支付 → 5订单关闭 (用户取消)
• 2支付成功 → 5订单关闭 (用户取消 + 触发退款)
• 其他状态（1支付中、3已退款、4支付失败）不允许取消

Testing

测试标准

• 测试框架: Vitest + hono/testing
• 测试位置: packages/orders-module-mt/tests/integration/
• 覆盖率目标: 核心业务逻辑 > 80%
• 测试类型: 集成测试（复用现有订单API测试结构）

测试要求

• 集成测试: 验证完整的取消订单流程，包括API调用和业务逻辑
• 多租户测试: 验证不同租户的数据隔离
• 边界测试: 测试各种订单状态的取消权限
• 错误测试: 测试订单不存在、状态不允许取消等异常情况

测试文件命名

• 在现有订单API集成测试文件中添加取消订单测试用例
• 遵循现有测试文件命名约定

Change Log

Date	Version	Description	Author
2025-11-21	1.0	初始故事创建	Bob (Scrum Master)

Dev Agent Record

This section is populated by the development agent during implementation

Agent Model Used

Claude Sonnet 4.5 (d8d-model)

Debug Log References

• 修复了订单实体缺少取消相关字段的问题
• 修复了小程序API调用参数错误
• 遵循了现有路由结构模式（单独文件+聚合）

Completion Notes List

1. ✅ 在 OrderMtService 中添加了完整的 cancelOrder 方法，包含：

   • 订单状态验证（仅允许取消支付状态为0或2的订单）
   • 已支付订单的退款流程占位符
   • 订单状态更新为5（订单关闭）
   • 取消原因和时间记录
   • 未支付订单的商品库存恢复

2. ✅ 创建了单独的取消订单路由文件 cancel-order.mt.ts，包含：

   • 完整的请求参数验证Schema
   • 适当的错误处理和状态码返回
   • 多租户数据隔离验证

3. ✅ 在订单详情页面集成了取消订单UI，包含：

   • 未支付订单的取消按钮
   • 已支付订单的取消按钮（带退款提示）
   • 取消原因输入对话框
   • 完整的用户交互反馈

4. ✅ 编写了完整的集成测试，包含：

   • 成功取消未支付订单
   • 成功取消已支付订单
   • 拒绝不允许的订单状态
   • 拒绝不存在的订单
   • 跨租户和跨用户权限验证

最新完成工作 (2025-11-21)

• ✅ 修复了测试工厂中的TypeScript类型错误
  • 修复了 OrderGoodsMt 实体字段定义（移除不存在的 totalAmount 和 totalCostAmount 字段）
  • 修复了 OrderRefundMt 实体字段定义（移除不存在的 orderId 字段，添加正确的 orderNo 字段）
  • 所有12个集成测试全部通过，包括多租户数据隔离和用户权限验证
• ✅ 完善了订单创建API的响应格式验证
  • 使用 parseWithAwait 验证响应格式
  • 修复了金额字段类型匹配问题
  • 确保API响应与Schema定义完全一致

File List

• 新增文件:

  • packages/orders-module-mt/src/schemas/cancel-order.schema.ts
  • packages/orders-module-mt/src/routes/user/cancel-order.mt.ts

• 修改文件:

  • packages/orders-module-mt/src/services/order.mt.service.ts
  • packages/orders-module-mt/src/entities/order.mt.entity.ts
  • packages/orders-module-mt/src/routes/user/orders.mt.ts
  • mini/src/pages/order-detail/index.tsx
  • packages/orders-module-mt/tests/integration/user-orders-routes.integration.test.ts
  • packages/orders-module-mt/tests/factories/orders-test-factory.ts (修复TypeScript类型错误)
  • packages/orders-module-mt/src/routes/user/create-order.mt.ts (添加响应格式验证)

Change Log

Date	Version	Description	Author
2025-11-21	1.0	初始故事创建	Bob (Scrum Master)
2025-11-21	1.1	实现订单取消功能	James (Developer)
2025-11-21	1.2	修复测试工厂TypeScript类型错误，完善集成测试	James (Developer)

QA Results

Results from QA Agent QA review of the completed story implementation