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

2026-08-09 13:24:02 +08:00
parent 24b6c742c1
commit a18d4e67ae
10 changed files with 435 additions and 29 deletions
@@ -407,7 +407,7 @@ Go 的 map 是无序的，不靠它定顺序的话，同一个商品每次刷新
 ### 6.1 工具条

 ```text
-[同步] [创建采购任务]   订单号 [___] [搜索]              [删除]
+[同步] [指定日期同步] [创建采购任务]   订单号 [___] [搜索]   [删除]
 ```

 `[必须]` 「同步」按工单 #46 实现：
@@ -434,6 +434,25 @@ Go 的 map 是无序的，不靠它定顺序的话，同一个商品每次刷新
 有跳过/失败会在后面列出具体原因，不是只给个数字。同步中再次点「同步」会提示
 "已经有一个同步任务在跑"，不会并发跑两个。

+`[必须]` 工单 #53 增加的「指定日期同步」是次要操作，不改变上面「同步」的
+自动增量语义。点击后打开小弹窗：
+
+```text
+指定日期同步
+
+开始日期 [2026-08-01]  结束日期 [2026-08-09]
+按货运单创建日期（UTC+8）同步，开始日和结束日都包含。
+
+[取消] [开始同步]
+```
+
+- 两端都必填，结束日期不得晚于 UTC+8 下的今天。
+- 指定历史范围用于首次分批拉取和补数据；日常操作仍点「同步」。
+- 指定范围经过自动 OCR 或手工验证码登录后必须原样保留。
+- 日期校验失败时重开弹窗、保留原输入，并在字段区域显示可读错误。
+- 指定历史范围默认不推进自动增量游标；游标规则见
+  [08 顺运宝接口](08-顺运宝接口.md) §4.4。
+
 `[必须]` 搜索框宽度见 [§3.1](#31-搜索框宽度)。

 ### 6.2 表格列
@@ -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. 货运单字段