70 lines
3.3 KiB
Markdown
70 lines
3.3 KiB
Markdown
# 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`：实现和测试。
|
||
|