导读
结论先说：物流轨迹"查不到""不更新"，九成不是快递的问题，而是回源查询的设计问题——查询频率不对、状态文案没归一化、异常没有监控，客户看到的就永远是"半路失踪"。本文复盘一次商城发货模块的物流轨迹改造，讲清轮询策略、状态机映射与异常识别，把"我的快递到哪了"变成可自动回答的问题。
一、先说背景：为什么轨迹总停在"已揽收"就再也不动
大促后一周，运营同事的工位排起队：客户一个接一个问"我的快递到哪了"。后台一查，一批订单的轨迹停在"已揽收"三天没动。运营同事只能逐个打开快递公司官网手动刷新，单量大时一天要查几百上千单，一半时间耗在"查轨迹"上。
也交代下这套商城的发货环境，轨迹回源的问题就出在这条边界上。商品、订单、会员这些基础数据放在一站式 SaaS 方案上，由这类底座承载基础台账；日常核对单号时，团队还配了固乔快递查询助手（快递批量查询助手）这类批量查询工具：单号批量粘贴导入、自动识别所属快递公司、按"无信息/已签收"筛选异常件，运营同学用它把几百个单号几分钟过一遍。但轨迹要实时同步进商城订单后台、给客户展示"物流跟踪"，还得自己接快递查询 API 做轮询与状态映射——这次"轨迹不更新"的坑，就出在自己实现这一段的查询策略上。
最初的实现是"下单就查一次、查完不回头"：发货后调用一次快递 API 拿到轨迹存库，之后就不再更新。快递刚揽收时轨迹本来就只有一条，客户看到"已揽收"后，后台再没有任何机制去刷新，三天后还是那条——轨迹"不更新"其实是"没人再去查"。
# 错误的回源：只查一次，之后轨迹永远停留在第一次的结果
def on_shipped(order_id, tracking_no):
tracks = express_api.query(tracking_no) # 发货时查一次
save_tracks(order_id, tracks) # 存完就不管了
二、轮询策略：多久查一次，才不会把 API 打爆也不至于失真
快递 API 按次数计费、有 QPS 限制，不可能每分钟把所有在途单号都刷一遍。核心是按物流状态分级设定轮询频率：
# 按状态分级轮询：异常件查得最勤，稳定运输中查得最松
POLL_INTERVAL = {
"EXCEPTION": timedelta(minutes=30), # 异常/停滞，主动盯
"OUT_FOR_DELIVERY": timedelta(hours=2), # 派送中，客户最关心
"IN_TRANSIT": timedelta(hours=4), # 干线运输，常规频率
"ACCEPTED": timedelta(hours=6), # 刚揽收，等首条干线更新
}
- 新发货的单号：发货后 2 小时内先高频查 3 次（间隔 10 分钟），确认轨迹开始流动，防止"查一次就没下文"；
- 状态升级就换档：轨迹从"运输中"变"派送中"，轮询从 4 小时升到 2 小时；客户能看到"快递正在派送"的实时感；
- 停滞就主动加速：某单号超过当前档位 1.5 倍时长没有新轨迹，临时提到 30 分钟一查，并在后台标"疑似停滞"。
def poll_scheduler():
while True:
due = fetch_due_trackings() # 到点的单号
for order in due:
tracks = express_api.query(order.tracking_no)
update_tracks(order, tracks)
order.next_poll = now() + POLL_INTERVAL[order.state]
time.sleep(60) # 调度器每分钟扫一次
轮询调度用一张 tracking_task 表记录每个单号的 next_poll_at，谁到点查谁，而不是全表扫一遍，避免无谓请求。
三、状态映射：每家快递的文案都不一样，必须归一成一套状态机
快递 API 返回的轨迹文案五花八门："干线运输中""运输中""发往XX市""到达XX转运中心"，签收也有"本人签收""代收点代收""已放丰巢"。如果原样展示，客户看到的是混乱文字；如果直接按文本匹配判断"是否签收"，错判率很高。
做法是维护一张标准状态机，把各家文案映射到六个状态：
STATE_MACHINE = {
"CREATED": ["已下单", "订单已创建"],
"ACCEPTED": ["已揽收", "揽件成功", "快件已到达"],
"IN_TRANSIT": ["运输中", "干线运输中", "发往", "到达转运中心", "离开"],
"OUT_FOR_DELIVERY": ["派送中", "正在派送", "快递员正在"],
"DELIVERED": ["签收", "已签收", "本人签收", "代收"],
"EXCEPTION": ["退回", "拒收", "无法联系", "滞留", "超时"],
}
映射时按优先级从强到弱匹配：先看"签收/退回/拒收"这类终态，再看"派送中"，最后才看"运输中"——因为"发往XX市"同时含"运输中"和"发往"两组词，先匹配强语义词，避免状态被弱词抢先。
def map_state(text):
for state, keywords in PRIORITY_ORDER: # 终态优先
if any(k in text for k in keywords):
return state
return "IN_TRANSIT" # 兜底
同一订单的轨迹记录用 (order_id, track_time, location) 做唯一键去重——快递 API 偶尔重复返回同一节点，不去重的话轨迹列表会越攒越乱。
四、异常监控：哪些轨迹要主动报警，而不是等客户来问
轨迹回源的意义不只是展示，更是替客户盯异常。我们定了三条规则，命中即进异常队列、推给运营：
def detect_exception(order):
now = datetime.now()
if order.state == "ACCEPTED" and now - order.shipped_at > timedelta(hours=24):
return "揽收后24小时无新轨迹" # 疑似没发出/丢件
if order.state == "IN_TRANSIT" and now - order.last_track_at > timedelta(hours=48):
return "干线停滞超过48小时" # 中途滞留
if order.state == "EXCEPTION":
return "快递公司标记异常（退回/拒收）" # 终态异常
return None
异常不是只记一条日志，要形成闭环：进异常队列 → 运营确认（打电话核实/联系快递）→ 处理后回填处理结果 → 客户在订单页看到"您的快件疑似异常，已为您核实中"。没有闭环的报警，三个月后就是一堆没人看的脏数据。
五、踩坑清单
- 坑1：只查一次不回头：发货时查一次就完事，轨迹永远停在第一条。必须有按状态分级的持续轮询。
- 坑2：轮询频率一刀切：全部单号同一频率，要么把 API 配额打爆，要么客户最关心的派送中反而更新慢。按状态分级。
- 坑3：文案直接原样展示：各家快递文案不归一，客户看到"干线运输中"不知道啥意思。必须映射到标准状态机。
- 坑4：状态映射先匹配弱词："发往XX市"先被"运输中"抢走没问题，但"已签收（代收）"若被"运输中"之类的弱词抢先就错判。终态关键词必须优先级最高。
- 坑5：异常只记录不闭环：报一条日志没人管，三个月后全是脏数据。异常必须进队列、有人确认、有处理结果回填。
六、上线后的情况
改造后：轨迹"超过48小时不更新"的客诉从大促当周 60 多条降到个位数；运营同学查单从"逐个打开快递官网"变成后台一张异常清单，正常单号不用再看；"我的快递到哪了"这类咨询，超过八成能靠订单页实时轨迹自己解答。原来"轨迹半路失踪"的问题，变成"轨迹不更新会自动报警、有人跟进"。
有个细节印象很深：一次批量发货里，20 多个单号同时卡在"已揽收"没动，系统 24 小时准时标了异常，运营当天就联系快递核实是网点漏扫描，赶在客户追问前处理完——异常监控的价值，不在于报警本身，而在于让问题在客户发现之前先被发现。
结语
物流轨迹回源没有银弹：状态分级轮询管频率、标准状态机管语义、唯一键去重管脏数据、异常闭环管没人盯。把"查、映射、盯"三段各自管好，轨迹才会从"半路失踪"变成"全程有数"。
