根据用户提供的模块职责，自动生成包含接口定义、行为规范和依赖…

# 订单模块设计文档

一、模块职责

• 订单创建：校验用户与商品信息、锁定库存、生成订单记录，返回订单编号。
• 支付回调处理：接收支付网关异步通知，验签、幂等校验，更新订单支付状态。
• 状态流转：管理订单生命周期状态机（待支付 → 已支付 → 待发货 → 已发货 → 已完成 / 已取消 / 退款中）。

二、依赖服务与中间件

• 库存服务：通过 RPC/HTTP 调用，下单时预占库存，取消时释放库存。
• Redis：
• 订单号生成（incr 序号或分布式 ID）
• 支付回调幂等去重（setnx + TTL）
• 热点订单缓存
• MySQL：订单主表、订单明细表、订单状态流转日志表；建议分库分表（按用户 ID 或订单 ID 分片）。

三、接口设计（RESTful）

| 方法 | 路径 | 说明 |

|---|---|---|

| POST | /api/v1/orders | 创建订单 |

| GET | /api/v1/orders/{orderId} | 查询订单详情 |

| GET | /api/v1/orders?userId=&status=&page= | 分页查询用户订单 |

| POST | /api/v1/orders/{orderId}/cancel | 取消订单 |

| POST | /api/v1/orders/payment/callback | 支付回调（网关调用） |

| PATCH | /api/v1/orders/{orderId}/status | 状态变更（内部/运营） |

通用约定：

• 请求/响应使用 JSON，返回统一结构：{code, message, data}。
• 回调接口需验签 + 幂等（Redis setnx 去重），处理成功返回固定成功标识给网关。

四、状态流转规则

1. 待支付 → 已支付（支付回调成功）

2. 待支付 → 已取消（超时未支付，延时任务自动取消并释放库存）

3. 已支付 → 已发货（履约系统触发）

4. 已发货 → 已完成（确认收货或超时自动完成）

5. 已支付 → 退款中 → 已退款（逆向流程）

约束：状态变更仅允许合法迁移，每次变更写入状态流转日志表，便于审计排查。

五、关键设计要点

• 创建流程：参数校验 → 锁定库存（失败快速返回）→ 生成订单（事务内）→ 返回订单号。
• 一致性：库存锁定与订单落库采用“先锁库存、事务提交订单、失败补偿释放”策略；支付回调涉及与库存扣减的最终一致性，建议消息队列 + 本地消息表。
• 可靠性：回调接口需支持网关重试，保证幂等；订单超时取消使用延迟队列（Redis zset 或 MQ 延迟消息）。
• 监控：状态流转异常、回调失败率、库存释放失败等关键指标埋点告警。