企业官网建设流程全解析

Medusa 订单的一生：从下单到售后的完整指南

【免费下载链接】medusaThe world's most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa

一笔 Medusa 订单从顾客按下"提交"开始，要经历建单、被修改、打包发货、确认送达，最后可能还要走一趟退货或换货。这篇文章沿着这条时间线，把订单在 Medusa 里走的每一步拆开讲给你看，顺带说明背后是哪几块代码在撑着。

先拿一张地图：订单状态流转图

与其背状态定义，不如把OrderStatus当成一张地图来读。它定义在 packages/core/types/src/order/common.ts，一共六个取值，各占一段旅程：

• draft和pending：旅程的前半段。前者是后台手动开出来的草稿单，后者是真正被确认、等待处理的新订单。
• requires_action：中途亮起的黄灯，表示订单在等某个人去补一个动作（比如重新支付）。
• completed：正片落幕，所有商品发完、送达确认。
• canceled和archived：两种收尾。取消是订单终止，归档则是把已完结的单据收进库房。

正常的流转路径大致长这样：

draft ──确认──▶ pending ──支付/补动作──▶ completed │ ▲ │ │ └──处理完──▶ requires_action ┘ └──放弃──▶ canceled （完成后）completed ──▶ archived

注意两点：订单可以随时在pending与requires_action之间横跳；而退货、换货这些售后动作并不会改写主状态，它们挂在订单下面单独走自己的流程，后面会细说。

下单瞬间：一张订单是怎么被造出来的

顾客提交购物车时，createOrderWorkflow工作流接管了整个过程，源码在 packages/core/core-flows/src/order/workflows/create-order.ts。它按顺序做了这几件事：

1. 校验商品和变体，确认价格与库存可用（缺货会直接拦住）；
2. 应用促销、刷新税费行；
3. 生成订单：一个唯一的id，一个用于追踪后续演变的version号，外加给前台展示用的display_id；
4. 落库时状态置为pending。

也就是说，"下单成功"在 Medusa 里不是保存一条记录那么简单，而是一串可以被回滚的校验和计算。

变动与履约：订单在路上被改了什么

订单确认后、发货之前，经常要动它——加一件商品、删一件、换配送方式。Medusa 不直接改订单，而是走"订单变更"（order change）机制：createOrderChangeWorkflow先开一张变更单，把改动描述成一个个动作（ITEM_ADD、SHIPPING_UPDATE这类ChangeActionType），变更单自己也有状态（requested→confirmed/declined/canceled），确认后才真正落到订单上。好处是每次改动都有据可查，失败也能整体回退。

发货环节由createOrderFulfillmentWorkflow负责（create-fulfillment.ts）。一次履约会更新订单商品（OrderItemDTO）上的几个计数：fulfilled_quantity（已纳入履约）、shipped_quantity（已交给快递）、delivered_quantity（已确认送达）。同一件商品分多次发也没关系，这三个数就是"发了多少、到了多少"的账本。

收尾：把订单送进 completed

当所有商品都发出并确认送达，completeOrderWorkflow出场做最后的清账：库存做最终扣减、账务数字定版，订单状态翻成completed。之后的归档（archived）是纯收尾动作，不影响单据本身。

售后专场：退货与换货各走一条线

出问题不丢脸，关键是流程清晰。Medusa 把售后拆成几条独立的工作流线，都在 packages/core/core-flows/src/order/workflows/ 目录下：

• 退货（return/目录）：request-item-return发起退货申请，receive-item-return-request登记实际收货，create-complete-return完成退款闭环。退货项的状态会经历requested→received/partially_received→canceled等取值，商品上的return_requested_quantity字段记录申请数量。
• 换货（exchange/目录）：begin-order-exchange打开换货流程，支持退回旧商品的同时exchange-add-new-item补发新商品，确认请求、添加运费、更新动作各有对应工作流。
• 另有claim/（订单索赔，比如少件、破损）处理更复杂的争议场景。

这几条线共同点：都不直接改订单，而是生成变更单，确认后由订单变更机制统一落账。

幕后三块积木

撑住上面所有流程的，是三块分工明确的积木：

1. 订单服务（OrderService）：位于 packages/modules/order/src/services/order-service.ts，负责订单的增删改查和状态维护，是其他模块和 API 与订单数据打交道的主要入口。
2. 工作流（Workflows）：createOrderWorkflow、createOrderChangeWorkflow、createOrderFulfillmentWorkflow、completeOrderWorkflow……每个复杂操作被拆成多个步骤（Step），失败可重试可回滚，这也是 Medusa 订单流程可靠的关键。
3. 数据模型（DTO）：OrderDTO、OrderLineItemDTO、OrderShippingMethodDTO等接口同样定义在 packages/core/types/src/order/common.ts，把"订单长什么样"这件事说清楚了，前后端、模块之间因此能各说各话却对齐。

落地清单：照着做即可

日常运营动作

• 每天扫一遍requires_action的订单，它们是卡住等人工的那批；
• 盯住库存余量低于安全线的商品，避免建单时才被拦住；
• 用工作流把发货确认、完成通知这类重复操作自动化；
• 给支付失败、库存不足等分支写明确的提示和重试路径。

常见问题排查

写在最后

Medusa 的订单处理，本质上是"状态地图 + 工作流编排 + 变更留痕"这套组合拳：每一步都有据可查，每个分支都能兜底。想继续深入，直接读官方文档和 packages/modules/order/ 下的源码，比任何转述都快。

【免费下载链接】medusaThe world's most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa