fix: 避开顺运宝高 offset 尾页 (#302)

docs/admin/08-顺运宝接口.md

@@ -188,33 +188,45 @@ POST /am/stock/list        → data.list 是数组，data.total 是当前页条
 ### 4.3 分页
 
 `[必须]` 一个跨日范围要拆成逐日查询。先逐日调用 `listTotal` 做全范围容量
-预检，确认合计不超限后，再按天以 `length = 20` 翻页调用 `list`。明细仍按
-最多 100 个货运单 ID 一批读取。
+预检，确认合计不超限后，再按天优先用
+`start = 0, pageIndex = 1, length = 当天预检总数` 一次调用 `list`。
+生产实测这种低 offset 请求能避开顺运宝不稳定的高 offset 尾页，并显著减少
+列表请求次数。明细仍按最多 100 个货运单 ID 一批读取。
 
 `[必须]` **必须有单次同步的条数上限**，超了报错而不是硬拉。
 Admin 默认 `max_matches = 10000`，可以在配置中调整；上限针对整个日期范围的
 逐日总数合计，不是每天各算一次。任何一天的列表或明细都不得在容量预检通过前
 开始拉取，避免超限后已经产生部分写入。
 
-`[必须]` 每一页 `list.data.total` 必须等于该页 `list` 数组长度。非最后一页
-必须返回 `length` 条，最后一页必须返回预检总数对应的剩余条数。每天翻页结束后
-再次调用 `listTotal`，前后总数必须一致；全部页去重后的货运单 ID 数还必须等于
-预检总数。历史日期出现前后总数变化、短页、重复 ID 或唯一 ID 不足时立即失败，
-不推进游标。
+`[必须]` `list.data.total` 必须等于 `list` 数组长度。整批正常路径必须返回
+预检总数对应的全部行。只有整批请求明确耗尽 3 次临时故障重试时，才回退配置的
+`page_size` 顺序分页；业务、格式、会话或调用方取消错误不得触发回退。分页回退中
+非最后一页必须返回 `page_size` 条，最后一页必须返回预检总数对应的剩余条数。
+列表读取结束后再次调用 `listTotal`，前后总数必须一致；全部结果去重后的货运单 ID
+数还必须等于预检总数。历史日期出现前后总数变化、短响应、重复 ID 或唯一 ID 不足
+时立即失败，不推进游标。
 
 今天的货运单会在同步期间持续新增。只有 UTC+8 下的今天发生上述快照漂移时，
-允许只重试今天的列表分页，最多 3 次；已经完成的历史日期不得重复拉取，每次尝试
+允许只重试今天的列表快照，最多 3 次；已经完成的历史日期不得重复拉取，每次尝试
 也必须使用独立 ID 集合。第三次仍不稳定时，可以对最后一次取得的合法唯一 ID
 读取完整明细并按既有 upsert 保存，但本次同步仍记为失败、明确提示当天未形成
 稳定快照且不推进游标，下一次继续覆盖今天。任何尝试都不得突破 `max_matches`；
 业务错误、非法 ID 或不完整明细不属于可放宽的快照漂移。
 
-`[必须]` 生产实测顺运宝可能在历史日期的高页码查询中超过 30 秒仍未返回响应头。
+`[必须]` 生产实测顺运宝可能在高 offset 尾页查询中连续 60 秒不返回响应头；固定向前
+重叠 20、100 或 500 条也不能覆盖所有日期，而 `start=0,length=当天总数` 已实测
+能完整返回 761 和 894 个唯一货运单 ID。因此整批低 offset 是正常路径，旧分页仅作
+临时故障重试耗尽后的兼容回退。
+
 货运单 `listTotal`、`list` 和 `detail/listByStock` 是只读查询：网络连接/超时、
 响应读取失败或 HTTP 5xx 时，只重试当前总数请求、当前页或当前明细批次，最多
 3 次，间隔 1 秒、2 秒，单次请求总超时 60 秒。重试必须复用同一个 Cookie Jar
 和完全相同的请求参数；调用方取消时立即停止等待。三次仍失败则停止同步且不推进游标。
 
+每次只读失败和重试恢复必须记录安全诊断字段：日期范围（仅限经过格式校验的
+`created` 日期条件）、接口路径、`start`、`pageIndex`、`length`、尝试次数、耗时和
+错误分类。不得记录 Cookie、账号密码、完整请求体、订单号或响应业务数据。
+
 `[必须]` 401/403、业务信封失败、非法 JSON、分页/明细格式错误和完整性错误不自动
 重试。登录、验证码、会话校验也不使用这套货运查询重试。删除入库码、新增明细、
 写入快递单号等真实写请求仍然只允许发送一次；超时或 5xx 后只准重新读取核对，