docs: 归档任务 #192

2026-08-12 18:15:25 +08:00
parent 30711dfff9
commit 9ba7419856
1 changed files with 69 additions and 0 deletions
@@ -0,0 +1,69 @@
+# 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`：实现和测试。
+