feat: 顺运宝支持指定日期同步 (#53)

2026-08-09 13:24:02 +08:00
parent 24b6c742c1
commit a18d4e67ae
10 changed files with 435 additions and 29 deletions
@@ -189,6 +189,29 @@ POST /am/stock/list        → data.list 是数组
 示例脚本用的是 `max_matches = 100`。日期范围拉全量时这个上限要调大，
 但不能没有——手滑填成一年的范围会把整库拉下来。

+### 4.4 自动增量与指定日期补同步
+
+页面有两种同步入口，但共用 §4.2 的日期范围接口、分页、明细读取和 upsert：
+
+| 模式 | 日期范围 | `last_synced_at` |
+|---|---|---|
+| 自动增量「同步」 | 上次成功同步日期当天 ～ UTC+8 下的今天；首次从 `sync_from` 开始 | 全部成功后推进 |
+| 「指定日期同步」 | 操作员填写的开始日 ～ 结束日，两端都包含 | 见下方安全规则 |
+
+`[必须]` 指定范围只有在**完整覆盖自动增量本来应该同步的区间**时，全部成功后
+才可以推进 `last_synced_at`。局部历史补拉只 upsert 数据，不动游标。
+
+例如系统本来应该同步 `2026-08-01 ～ 2026-08-09`，操作员只补拉
+`2026-08-07 ～ 2026-08-08`。如果这时把游标推进到当前时间，前后没有覆盖的
+日期可能永远不会再自动同步，而且不会报错。
+
+`[必须]` 日期格式固定 `YYYY-MM-DD`，按 UTC+8 解释；两端必须同时填写，
+开始不得晚于结束，结束不得晚于 UTC+8 下的今天。中途失败或超过
+`max_matches` 时，两种模式都不推进游标。
+
+`[必须]` 登录和验证码只是同步前置步骤。指定范围经过自动 OCR 降级、手工
+输入验证码和 303 跳转时必须原样保留，不能悄悄退化成自动增量。
+
 ---

 ## 5. 货运单字段