fix: 增强顺运宝同步完整性保护 (#58)

docs/admin/05-ui-specification.md

@@ -445,12 +445,12 @@ Go 的 map 是无序的，不靠它定顺序的话，同一个商品每次刷新
 指定日期同步
 
 开始日期 [2026-08-01]  结束日期 [2026-08-09]
-按货运单创建日期（UTC+8）同步，开始日和结束日都包含。
+按货运单创建日期（UTC+8）同步，开始日和结束日都包含。每次最多选择 31 天。
 
 [取消] [开始同步]
 ```
 
-- 两端都必填，结束日期不得晚于 UTC+8 下的今天。
+- 两端都必填，结束日期不得晚于 UTC+8 下的今天，闭区间最多 31 天。
 - 指定历史范围用于首次分批拉取和补数据；日常操作仍点「同步」。
 - 指定范围经过自动 OCR 或手工验证码登录后必须原样保留。
 - 日期校验失败时重开弹窗、保留原输入，并在字段区域显示可读错误。

docs/admin/08-顺运宝接口.md

@@ -183,11 +183,18 @@ POST /am/stock/list        → data.list 是数组
 
 ### 4.3 分页
 
-`[必须]` 先调 `listTotal` 拿总数，再按 `length` 翻页调 `list`。
+`[必须]` 一个跨日范围要拆成逐日查询。先逐日调用 `listTotal` 做全范围容量
+预检，确认合计不超限后，再按天以 `length = 20` 翻页调用 `list`。明细仍按
+最多 100 个货运单 ID 一批读取。
 
 `[必须]` **必须有单次同步的条数上限**，超了报错而不是硬拉。
-示例脚本用的是 `max_matches = 100`。日期范围拉全量时这个上限要调大，
-但不能没有——手滑填成一年的范围会把整库拉下来。
+Admin 默认 `max_matches = 10000`，可以在配置中调整；上限针对整个日期范围的
+逐日总数合计，不是每天各算一次。任何一天的列表或明细都不得在容量预检通过前
+开始拉取，避免超限后已经产生部分写入。
+
+`[必须]` 每一页 `list` 响应里的 `total` 必须等于该日预检的 `listTotal`，
+全部页去重后的货运单 ID 数也必须完全相等。分页期间总数变化、短页造成缺失或
+重复 ID 都视为本次同步失败，不推进游标。
 
 ### 4.4 自动增量与指定日期补同步
 
@@ -196,7 +203,7 @@ POST /am/stock/list        → data.list 是数组
 | 模式 | 日期范围 | `last_synced_at` |
 |---|---|---|
 | 自动增量「同步」 | 上次成功同步日期当天 ～ UTC+8 下的今天；首次从 `sync_from` 开始 | 全部成功后推进 |
-| 「指定日期同步」 | 操作员填写的开始日 ～ 结束日，两端都包含 | 见下方安全规则 |
+| 「指定日期同步」 | 操作员填写的开始日 ～ 结束日，两端都包含，最多 31 天 | 见下方安全规则 |
 
 `[必须]` 指定范围只有在**完整覆盖自动增量本来应该同步的区间**时，全部成功后
 才可以推进 `last_synced_at`。局部历史补拉只 upsert 数据，不动游标。
@@ -206,9 +213,14 @@ POST /am/stock/list        → data.list 是数组
 日期可能永远不会再自动同步，而且不会报错。
 
 `[必须]` 日期格式固定 `YYYY-MM-DD`，按 UTC+8 解释；两端必须同时填写，
-开始不得晚于结束，结束不得晚于 UTC+8 下的今天。中途失败或超过
+开始不得晚于结束，结束不得晚于 UTC+8 下的今天；闭区间最多 31 天。自动增量
+不受 31 天人工选择限制，但同样逐日查询。中途失败或超过
 `max_matches` 时，两种模式都不推进游标。
 
+`[必须]` 每批明细响应必须与请求的货运单 ID 一一对应。缺失、重复、出现未请求
+ID，或某张货运单返回空商品明细，都视为不完整并停止同步；已经写入的幂等数据
+可以保留，但只有所有日期全部成功才推进游标。
+
 `[必须]` 登录和验证码只是同步前置步骤。指定范围经过自动 OCR 降级、手工
 输入验证码和 303 跳转时必须原样保留，不能悄悄退化成自动增量。