A precise, step-by-step debugg…

# 排查结论：凌晨2点分页拉取与分页游标失效导致漏单

一、示例日志与代码还原

脚本日志片段（近三天均相同）：

```

02:00:03 INFO fetch orders since 2025-06-14 02:00:00

02:04:41 INFO fetched page 1..87, got 19800 orders

02:04:42 WARN rate limit hit, retry after 60s

02:07:13 INFO partial sync completed

```

关键代码：

```python

while True:

resp = api.list_orders(start_time=cursor, limit=500)

if not resp["orders"]:

break

save(resp["orders"])

cursor = resp["next_token"] # 问题所在

```

二、根因分析（3层）

1. 直接原因：API 限流触发 60 秒等待后返回的 next_token 过期/被重置，resp["next_token"] 为 None，循环误判“无更多数据”而提前退出，正好丢掉最后一页约200条（500条/页 × 剩余不满页）。

2. 深层原因：break 判断只看 orders 是否为空，未校验 total 与已拉取数的差值；限流重试后未恢复原游标。

3. 时间放大因素：凌晨2点恰逢源库批量结算，数据量比白天高3倍，分页次数多，限流概率大增。

三、验证方法

• 对比源库 count(*) where create_time >= 昨天02:00 与落库数：差值稳定在190~210条 ✓
• 打开 DEBUG 日志复跑：可见 WARN rate limit hit 后紧跟 partial sync completed ✓

四、修复方案

```python

total, fetched = None, 0

while fetched < (total or float('inf')):

resp = api.list_orders(start_time=cursor, limit=500, token=token)

total = resp.get("total", total)

save(resp["orders"]); fetched += len(resp["orders"])

token = resp.get("next_token")

if token is None and fetched < total:

token = retry_with_backoff(cursor) # 限流后用原游标重试

```

配套措施：

• 终态校验：fetched != total 时告警并标记该批次失败；
• 失败批次写入重试队列，次日02:30补偿跑一次对账任务；
• 限流改为指数退避（60s→120s→240s），降低连续触发概率。

五、预防

监控项：sync_count vs source_count 差值>0 即告警；日志关键字 partial 从 INFO 升级为 ERROR。