feat: 统一顺运宝日期同步并记录历史 (#59)

2026-08-09 18:22:58 +08:00
parent ea7932db63
commit 05a54b044d
18 changed files with 934 additions and 144 deletions
@@ -196,33 +196,29 @@ Admin 默认 `max_matches = 10000`，可以在配置中调整；上限针对整
 全部页去重后的货运单 ID 数也必须完全相等。分页期间总数变化、短页造成缺失或
 重复 ID 都视为本次同步失败，不推进游标。

-### 4.4 自动增量与指定日期补同步
+### 4.4 统一日期范围同步与覆盖游标

-页面有两种同步入口，但共用 §4.2 的日期范围接口、分页、明细读取和 upsert：
+页面只有一个同步入口，操作员确认工具条上的开始日和结束日后发起。通常默认最近
+3 天；如果 `last_synced_at` 更早，默认范围从覆盖游标当天开始。缺口超过 31 天时
+只选择最早一段 31 天，本段成功后下一次继续显示后一段。

-| 模式 | 日期范围 | `last_synced_at` |
-|---|---|---|
-| 自动增量「同步」 | 上次成功同步日期当天 ～ UTC+8 下的今天；首次从 `sync_from` 开始 | 全部成功后推进 |
-| 「指定日期同步」 | 操作员填写的开始日 ～ 结束日，两端都包含，最多 31 天 | 见下方安全规则 |
+`[必须]` 首次成功同步以所选结束日建立覆盖游标。已有游标时，只有日期范围从
+游标当天或更早开始、并且结束日在游标之后，全部成功后才推进游标。局部历史补拉
+或跳过缺口的范围只 upsert 数据，不动游标。

-`[必须]` 指定范围只有在**完整覆盖自动增量本来应该同步的区间**时，全部成功后
-才可以推进 `last_synced_at`。局部历史补拉只 upsert 数据，不动游标。
-
-例如系统本来应该同步 `2026-08-01 ～ 2026-08-09`，操作员只补拉
-`2026-08-07 ～ 2026-08-08`。如果这时把游标推进到当前时间，前后没有覆盖的
-日期可能永远不会再自动同步，而且不会报错。
+例如覆盖游标为 `2026-08-01`，同步 `2026-08-01 ～ 2026-08-09` 可以推进到
+`2026-08-09`；只同步 `2026-08-07 ～ 2026-08-08` 不能推进，因为中间有缺口。

 `[必须]` 日期格式固定 `YYYY-MM-DD`，按 UTC+8 解释；两端必须同时填写，
-开始不得晚于结束，结束不得晚于 UTC+8 下的今天；闭区间最多 31 天。自动增量
-不受 31 天人工选择限制，但同样逐日查询。中途失败或超过
-`max_matches` 时，两种模式都不推进游标。
+开始不得晚于结束，结束不得晚于 UTC+8 下的今天；闭区间最多 31 天。中途失败
+或超过 `max_matches` 时不推进游标。

 `[必须]` 每批明细响应必须与请求的货运单 ID 一一对应。缺失、重复、出现未请求
 ID，或某张货运单返回空商品明细，都视为不完整并停止同步；已经写入的幂等数据
 可以保留，但只有所有日期全部成功才推进游标。

-`[必须]` 登录和验证码只是同步前置步骤。指定范围经过自动 OCR 降级、手工
-输入验证码和 303 跳转时必须原样保留，不能悄悄退化成自动增量。
+`[必须]` 登录和验证码只是同步前置步骤。日期范围经过自动 OCR 降级、手工
+输入验证码和 303 跳转时必须原样保留。

 ---