cmautobuy/docs/task/192-admin顺运宝当天分页漂移重试.md

192 Admin：优化顺运宝当天分页漂移重试与默认日期

• 工单号：#192
• 标题：Admin：优化顺运宝当天分页漂移重试与默认日期
• 类型：缺陷修复
• 父级大工单：#14
• 所属 MVP / 版本：#15 Admin 四模块可用闭环
• 状态：待验收
• 日期：2026-08-12
• Gitea：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/192

背景与目标

顺运宝当天持续新增货运单时，预检总数与最后一页实际条数会发生漂移。原实现为 防止 offset 分页漏单会停止同步，但采购员立即重试仍容易失败，而且会重复拉取 已经稳定的历史日期。本任务让今天具备有限重试和安全的部分保存能力，并把页面 默认范围改为昨天到今天。

最终方案

• 页面首次打开固定预填“昨天～今天”，不再根据旧覆盖游标扩大默认范围。
• 抽取单日列表快照校验；历史日期继续严格核对页长、前后总数和唯一 ID，发现 漂移立即失败。
• 仅 UTC+8 下的今天发生快照漂移时重试今天，最多 3 次；每次创建独立 ID 集合， 已完成的历史日期不重拉。
• 第三次仍漂移时，对最后一次取得的合法唯一 ID 拉取并验证完整明细，再走既有 upsert 保存；同步仍记为失败并且不推进游标，下次继续覆盖今天。
• 每次增长后重新校验 max_matches；超限时不保存该次超限数据。网络、业务响应、 非法 ID 和明细不完整仍按普通失败处理，不进入放宽路径。

最终实现与工单方案一致，没有新增数据库字段或修改 Client 接口。

改了哪些文件

• admin/service/syb.go：默认日期、单日快照校验、今天最多 3 次重试、最后一次 完整明细保存、游标和容量保护。
• admin/service/syb_test.go：覆盖默认日期、历史严格失败、今天重试后稳定、持续 漂移部分保存和增长超限。
• docs/admin/05-ui-specification.md：更新页面默认日期规则。
• docs/admin/08-顺运宝接口.md：记录历史日和今天不同的完整性处理规则。

验收结果

验收项	结果
页面默认开始日为昨天、结束日为今天	通过
历史日期漂移仍立即失败且不推进游标	通过
今天前两次漂移、第三次稳定时成功	通过
今天重试不重复拉取已完成的历史日期	通过
今天连续三次漂移时保存最后一次完整明细	通过
持续漂移仍记失败且不推进游标	通过
重试之间不混入前次 ID	通过
增长后仍受 max_matches 限制	通过
网络、非法 ID 和明细完整性保护保持有效	通过

测试

• 执行命令：在 admin/ 目录使用固定 GOTOOLCHAIN=go1.23.0 执行 go vet ./...、go build ./...、go test ./... -count=1。
• 结果：Go 1.23.0 Windows/amd64；vet、build 和全部 Admin Go 包测试通过。
• 定向场景：历史列表不完整；今天前两次增长后稳定；今天连续三次增长；增长突破 max_matches；明细缺失。
• 未验证到的部分：未调用真实顺运宝接口；未在生产数据上执行同步；未执行 采集或采购任务；未部署生产服务器。

相关提交

• 30711df：实现和测试。