物流追踪模块需要哪些字段？怎么对接更稳？

最少需要四组字段：业务标识（订单号、子订单号）、物流标识（运单号、承运商）、状态信息（状态码、状态文本、时间戳、地理节点）、补充信息（签收人、异常原因、附件）。对接稳定性主要看回传方式——优先用承运商的主动推送（webhook），其次是定时轮询接口，最差才是人工补录。

字段层面我们一般会按下面这套设计：

业务侧：order_id, sub_order_id, customer_id
物流侧：tracking_no, carrier_code, carrier_name, shipped_at
状态侧：status_code, status_text, event_time, location, node_type
附加项：signed_by, sign_image_url, exception_code, exception_remark
来源：source(api/webhook/manual), raw_payload(原始报文 JSON 串)

raw_payload 这一项尤其重要——把承运商原始报文存下来，后期对账或扯皮时能找到证据。

对接方式按稳定性排序：

1. 承运商主动推送（webhook）：最稳的方式。承运商有节点更新时通过 HTTP 回调你的接口，你只需要一个对外接收端点。要做好幂等（避免重复回调写两次）、签名验证、失败重试机制。
2. 轮询查询接口：自己定时（5-15 分钟一次）调承运商的查询接口。适合不提供 webhook 的小承运商。要控制查询频率，避免被限流。
3. 第三方聚合平台：比如快递鸟、菜鸟、Yunexpress 这种，一个接口接入多家承运商。开发量小但有抽成、数据延迟稍大。
4. 人工补录：作为兜底，少数没接口的承运商或异常订单使用。

几个常见的坑：

• 同一个运单可能在不同时刻收到乱序的事件，要按 event_time 而不是接收时间排序
• 国际物流的状态码各国海关定义不一样，要做一份本地化的状态映射表
• 承运商接口偶尔会"假死"——返回 200 但实际没有更新，要做差异比对兜底
• 一笔订单可能拆成多个包裹，要支持一对多的运单关系

实施周期视承运商数量而定，单家对接通常 3-5 天，全套上线（含异常处理、对账后台）一般要 1-2 个月。