# 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`：实现和测试。