看了tb的碎片化文档，我想状态机了，要是有这个状态机文档在，解决这种问题还用花这么长时间?

烟雨平生

发布于 2025-11-20 11:52:25

160

结论：借助DeepSeek、基于状态机模型，连接了淘宝开放平台分散的技术文档，重点覆盖订单正向链路涉及的事件、状态及事件触发的状态转换。有一丢丢“越俎代庖”。为啥？在淘宝文档中心能不能找到，凭经验凭运气，直接影响了解决问题的效率。找文档花的时间有些长，不开心。

业务怎么了？

天猫旗舰店，用户4天前下的订单还没有发货。这影响客户体验，业务来问原因。

是我也会不开心。都什么年代了，买你个东西，1星期后才到手。我是在新疆，还是在西藏呀？

1年前上线的功能，什么也没有做，然后就坏了？

查了下，这个店铺今天的订单正常通知了。。。

什么原因？

原因是淘宝“礼品订单”暂未支持。这单正好是礼品单...

在等待淘宝工单回复期间，与业务沟通后发现，这种订单果然不一样，是“礼品订单”。

提工单与淘宝沟通后，得到如下信息：

怎么办？

不管什么原因，总不能用户付了钱，晚给人家发货，这总是不对的吧。

怎么解决呢？

之前的逻辑是订阅taobao_trade_TradeBuyerPay这个topic的tmc消息。现在送礼订单，不再投递这个消息，那我怎么知道啥时候去通知客服去处理这个订单呢？

再看上面的订单数据，“收件人填写地址时间”的确是晚于支付时间的。

原因找到了，但这个文档看了几遍也没有找到解决的办法，譬如可以通过监听哪个topic可以知道这个订单可以发货了。。。

解决了，但有些匆匆忙忙

但解决过程，很不顺利，信息缺东缺西，拼拼凑凑，这么快响应业务诉求把问题解决掉，也有运气的成分，当时正好搜到上面这些文档。

在复盘问题解决过程时，突然我想状态机了，如果有订单状态流转的状态机，解决这个问题会更节省时间，也更笃定一些。

为什么？

因为状态机（State Machine）包含三个核心要素：

状态（State）对象所处的具体情况（如 "下单"、"支付完成" 等）
事件（Event）触发状态转换的动作或条件（如 "用户付款"、"供应商发货"）
转换（Transition）从一个状态到另一个状态的过程（如 "支付完成"→"触发采购"）

事件，譬如本次TMC消息中不同Topic中的数据，就是由不同的事件触发的。

有事件，必然会影响到状态。

状态之前的转换，肯定也是有限制的，譬如下单事件肯定不可以触发签单返回事件。

以“礼品订单”为例，这种订单不会触发taobao_trade_TradeBuyerPay消息，那会触发什么消息呢？没有文档可以找到。但这些是可以放在状态机这个数据模型中的。

订单就是一个典型的状态机载体，它会按照固定规则在各个状态间流转，且同一时间只能处于一种状态。

当业务流程包含多个状态且转换规则复杂时，状态机的优势非常明显：

清晰的流程控制避免状态混乱（比如 "未支付" 的订单不能直接 "退货"）
可维护性状态转换规则集中管理，便于修改和扩展
可预测性明确的状态流转路径让业务行为可预期

特别是淘宝这种体量的电商平台。

一个基于状态机建模的电商系统具有更好的可扩展性和可维护性。

一个好的文档，一个包含全链路视角的文档。

用户怎么省劲怎么来。不要让我思考上哪找，应该就是手头边；不要让我思考怎么用，直接step by step copy+paste就可以了；不要让我担心有安全隐患，为什么安全写在边上，让我放心；省找的时间；省理解的时间；省fix漏洞的时间，越是重要的服务，这方面越要更好的支持； Don't make me think! 唐成，公众号：的数字化之路如何写出人见人爱的API文档?

写这个文档很费事费时吧？

以前是，但现在有了AI，我先用AI写一个，打个样：

基于淘宝交易场景的事件消息及订单流转状态，我生成了一个全流程的状态机流转图。该状态机涵盖了订单从创建到最终状态（交易成功或交易关闭）的核心流转过程，主要基于提供的API事件和订单正向链路逻辑。状态机重点关注那些会导致订单状态改变的关键事件，而如修改备注、修改地址等不改变状态的事件则未包含在图中。

状态说明

WAIT_BUYER_PAY：订单创建后，等待买家付款状态。
WAIT_SELLER_SEND_GOODS：买家付款后，等待卖家发货状态。
WAIT_BUYER_CONFIRM_GOODS：卖家发货后，等待买家确认收货状态。
TRADE_FINISHED：买家确认收货后，交易成功状态。
TRADE_CLOSED：交易关闭状态（如超时未付款、退款关闭等）。

事件说明

taobao_trade_TradeCreate：创建淘宝交易，触发订单进入WAIT_BUYER_PAY状态。
taobao_trade_TradeBuyerPay：买家付款完成，触发订单从WAIT_BUYER_PAY进入WAIT_SELLER_SEND_GOODS状态。
taobao_trade_TradeSellerShip：卖家发货（全部发货），触发订单从WAIT_SELLER_SEND_GOODS进入WAIT_BUYER_CONFIRM_GOODS状态。
taobao_trade_TradeSuccess：交易成功（买家确认收货或系统自动确认），触发订单从WAIT_BUYER_CONFIRM_GOODS进入TRADE_FINISHED状态。
taobao_trade_TradeClose：交易关闭，触发订单从WAIT_BUYER_PAY、WAIT_SELLER_SEND_GOODS或WAIT_BUYER_CONFIRM_GOODS进入TRADE_CLOSED状态。

注意事项

部分事件（如taobao_trade_TradePartlySellerShip部分发货、taobao_trade_TradePartlyRefund部分退款）不改变主订单状态，因此未在状态机中体现。这些事件通常影响子订单状态，但主订单状态保持不变直到全部发货或全额退款。
其他事件（如taobao_trade_TradeMemoModified修改备注、taobao_trade_TradeLogisticsAddressChanged修改地址）不触发状态转换，因此未包含。
状态机仅覆盖一般交易流程，特殊场景（如分阶段付款、以旧换新）可能涉及额外状态，但基于提供的信息，已聚焦核心流程。

此状态机可用于理解淘宝订单的基本流转，在实际开发中可根据具体需求扩展更多状态和事件。

增加“礼品订单”

“增加一个新场景：礼品订单，这种订单是先付钱，付钱后订单状态不是WAIT_SELLER_SEND_GOODS，需要另一个用户填地址，地址填完后，才能到达WAIT_SELLER_SEND_GOODS。并且用户付完钱后，不会触发taobao_trade_TradeBuyerPay事件”

新增状态说明

WAIT_RECEIVER_ADDRESS：礼品订单特有状态，买家付款完成后，等待收礼人填写收货地址的状态。

新增事件说明

礼品订单支付完成：礼品订单特有的支付完成事件（由于您提到不会触发taobao_trade_TradeBuyerPay，这里使用描述性名称）
收礼人地址填写完成：收礼人填写完收货地址后触发的事件

礼品订单特殊流程说明

创建订单：礼品订单创建后同样进入WAIT_BUYER_PAY状态
支付完成：买家支付完成后，礼品订单不会触发标准的taobao_trade_TradeBuyerPay事件，而是通过其他机制（可能是特定的事件或API调用）将订单状态转移到WAIT_RECEIVER_ADDRESS
填写地址：在WAIT_RECEIVER_ADDRESS状态下，需要等待收礼人填写收货地址
进入发货流程：地址填写完成后，订单进入标准的WAIT_SELLER_SEND_GOODS状态，后续流程与普通订单一致