fix: 稳定顺运宝当天分页同步 (#192)

2026-08-12 18:14:52 +08:00
parent cd160e92d4
commit 30711dfff9
4 changed files with 326 additions and 98 deletions
@@ -466,13 +466,12 @@ Go 的 map 是无序的，不靠它定顺序的话，同一个商品每次刷新
 ### 6.1 工具条

 ```text
-开始日期 [2026-08-07]  结束日期 [2026-08-09] [同步] [同步记录]
+开始日期 [2026-08-08]  结束日期 [2026-08-09] [同步] [同步记录]
 [创建 PDD 采集任务] [创建采购任务]   处理阶段 [全部] 店铺 [___] 订单号 [___] [搜索]   [删除]
 ```

-日期始终显示在主工具条，按 UTC+8 解释且两端都包含。通常默认最近 3 天；如果
-覆盖游标更早，则从游标当天开始补齐。缺口超过 31 天时只预选最早 31 天，并明确
-提示本段成功后继续下一段。
+日期始终显示在主工具条，按 UTC+8 解释且两端都包含。首次打开页面固定默认昨天
+到今天，不因覆盖游标位置自动扩大范围；需要补历史缺口时由采购员明确选择日期。

 `[必须]` 「同步」是唯一同步入口：

@@ -199,14 +199,21 @@ Admin 默认 `max_matches = 10000`，可以在配置中调整；上限针对整
 `[必须]` 每一页 `list.data.total` 必须等于该页 `list` 数组长度。非最后一页
 必须返回 `length` 条，最后一页必须返回预检总数对应的剩余条数。每天翻页结束后
 再次调用 `listTotal`，前后总数必须一致；全部页去重后的货运单 ID 数还必须等于
-预检总数。前后总数变化、短页、重复 ID 或唯一 ID 不足都视为本次同步失败，
+预检总数。历史日期出现前后总数变化、短页、重复 ID 或唯一 ID 不足时立即失败，
 不推进游标。

+今天的货运单会在同步期间持续新增。只有 UTC+8 下的今天发生上述快照漂移时，
+允许只重试今天的列表分页，最多 3 次；已经完成的历史日期不得重复拉取，每次尝试
+也必须使用独立 ID 集合。第三次仍不稳定时，可以对最后一次取得的合法唯一 ID
+读取完整明细并按既有 upsert 保存，但本次同步仍记为失败、明确提示当天未形成
+稳定快照且不推进游标，下一次继续覆盖今天。任何尝试都不得突破 `max_matches`；
+网络/业务错误、非法 ID 或不完整明细不属于可放宽的快照漂移。
+
 ### 4.4 统一日期范围同步与覆盖游标

-页面只有一个同步入口，操作员确认工具条上的开始日和结束日后发起。通常默认最近
-3 天；如果 `last_synced_at` 更早，默认范围从覆盖游标当天开始。缺口超过 31 天时
-只选择最早一段 31 天，本段成功后下一次继续显示后一段。
+页面只有一个同步入口，操作员确认工具条上的开始日和结束日后发起。首次打开页面
+固定默认昨天到今天，不因 `last_synced_at` 更早而自动扩大范围；需要补历史缺口时
+由操作员明确选择日期，单次仍不得超过 31 天。

 `[必须]` 首次成功同步以所选结束日建立覆盖游标。已有游标时，只有日期范围从
 游标当天或更早开始、并且结束日在游标之后，全部成功后才推进游标。局部历史补拉