Medusa订单处理：从pending到completed，订单要过哪3道关
【免费下载链接】medusaThe world's most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa
一笔Medusa订单处理请求执行完，订单往往并不是"结束"了——后台里停在pending状态的订单是常态，关键在于分辨它是正常流转中还是真的卡住了。这篇文章跟着代码走一遍一笔订单的旅程，把它经过的3道关拆开看。
pending什么时候不算卡住？
OrderStatus在 common.ts 里只定义了6个值：pending、completed、draft、archived、canceled、requires_action。
pending表示订单已创建，但库存确认和履行还没发生。创建入口是createOrderWorkflow（工作流id叫create-orders，代码在 create-order.ts），内部依次做：定位region、找或建客户、校验行项目价格、确认库存足够，然后落库。落库后status就是pending——订单刚离开发令枪，"没被处理"本来就是它该有的样子，先别急着报警。
库存：履行环节最容易踩的坑
⚠️ create-order.ts 的注释里有一句很直白的提醒：这个workflow只校验库存"够不够"，并不会为订单商品创建库存预留（reservation）。
后果是：如果变体开了manage_inventory，你直接拿createOrderWorkflow造出来的订单去履行，createOrderFulfillmentWorkflow会因为没有对应reservation而报错。正确姿势是先跑createReservationsWorkflow，给每个预留带上line_item_id，履行workflow靠它把预留找到。
履行workflow的校验逻辑写得相当"死板"（create-fulfillment.ts）：订单不能是canceled、items必须真实存在于订单里、items要按shipping requirement分组，任何一条不满足直接抛错。通过后它会并行做几件事：调整库存水位（adjustInventoryLevelsStep）、清掉用掉的reservation，最后registerOrderFulfillmentStep把履行记录写进订单，行项目的fulfilled_quantity也是在这一步更新的。
要改订单，别直接改字段
订单的增删改查集中在OrderService（order-service.ts），但注意：它不会直接改动一笔已创建的订单。v2里改单走的是"订单变更"机制——用createOrderChangeWorkflow建一个order change，它的状态机OrderChangeStatus有5个值：requested、pending、confirmed、declined、canceled，只有confirmed之后变更才会真正落进订单，同时订单的version加一。
OrderDTO里那个version字段不是摆设：每次confirmed的变更都会递增它，对账和排查"这单怎么变成这样"时，靠它就能回溯到某一时刻的订单快照。
退货之后，数量去哪了？
客户退回商品，不是简单扣一个数字。退货有独立的一套workflow（在 packages/core/core-flows/src/order/workflows/return/ 目录下），而订单模块的action层把每个数量变化都拆成了专门的文件：fulfill-item.ts管fulfilled_quantity，deliver-item.ts管签收，ship-item.ts管发货——都放在 packages/modules/order/src/utils/actions/ 里，想核对某个字段何时变，去那里按文件名找就行。换货（exchange）同理，在旁边的exchange/目录。
接下来读哪3个地方
- 状态与DTO定义：packages/core/types/src/order/common.ts
- 全部订单workflow：packages/core/core-flows/src/order/workflows/，一个文件一个流程（create、fulfill、complete、cancel、return、exchange都在里面）
- 订单模块服务与模型：packages/modules/order/src/services/ 和 models/
想本地跑起来验证，先克隆仓库：
git clone https://gitcode.com/GitHub_Trending/me/medusa
建议从 integration-tests/http/tests/order/ 下的用例入手，配合源码读create-fulfillment这个workflow——它的校验和预留逻辑理顺了，剩下那套状态机基本就是顺水推舟的事。
【免费下载链接】medusaThe world's most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
