diff --git a/docs/task/192-admin顺运宝当天分页漂移重试.md b/docs/task/192-admin顺运宝当天分页漂移重试.md new file mode 100644 index 0000000..72ba383 --- /dev/null +++ b/docs/task/192-admin顺运宝当天分页漂移重试.md @@ -0,0 +1,69 @@ +# 192 Admin:优化顺运宝当天分页漂移重试与默认日期 + +- 工单号:#192 +- 标题:Admin:优化顺运宝当天分页漂移重试与默认日期 +- 类型:缺陷修复 +- 父级大工单:#14 +- 所属 MVP / 版本:#15 Admin 四模块可用闭环 +- 状态:待验收 +- 日期:2026-08-12 +- Gitea: + +## 背景与目标 + +顺运宝当天持续新增货运单时,预检总数与最后一页实际条数会发生漂移。原实现为 +防止 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`:实现和测试。 +