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

docs/admin/03-data-model.md

@@ -97,6 +97,7 @@ SQLite 同一时刻只允许一个写事务，连接放太开会互相抢锁、
 | v5 | 顺运宝货运单同步（工单 #46）：新增 `syb_session`（会话缓存）、`syb_sync_state`（同步进度）两张表；`syb_orders` 增加可空的 `product_spec`（规格原文）。三条都是新增，v1–v4 一个字节没改。 |
 | v6（#50） | Admin 网页登录：新增 `users` 和 `web_sessions`，只在迁移末尾追加，未改写 v1–v5。 |
 | v7（#54） | 客户端负责人：新增 `client_user_assignments` 和当前归属唯一索引，保留绑定、转交、解绑历史；未改写 v1–v6。 |
+| v8（#59） | 顺运宝同步记录：新增 `syb_sync_runs` 和开始时间倒序索引；未改写 v1–v7。 |
 
 **v3 为什么丢弃旧 `sku_mappings` 数据（见 #20）：** 新主键需要 `pdd_option_key`，
 这是 Go 的 `service.OptionKey()` 用 `json.Marshal` 算出来的规范化键，SQL 语句
@@ -498,6 +499,16 @@ CREATE TABLE syb_sync_state (
 - `[必须]` 只有一次同步**全部成功**才更新 `last_synced_at`；中途失败不更新，
   否则下次同步会跳过这段区间，漏掉的单永远补不回来。
 
+### 5.2 `syb_sync_runs` 同步记录（v8）
+
+每次从页面发起同步时，先写一条 `running` 记录，再启动后台任务。记录保存操作
+账号、日期范围、开始/完成时间、结果统计、是否推进覆盖游标以及必要的失败原因。
+状态只能是 `running`、`succeeded`、`failed`、`interrupted`；Admin 启动时把上次
+进程遗留的 `running` 记录改成 `interrupted`。
+
+`[必须]` 本表不保存顺运宝 Cookie、token、密码、验证码、收件信息或原始响应。
+失败原因最多保留 500 个字符，并在页面输出时由模板转义。
+
 ## 6. `sku_mappings` 规格映射
 
 "蝦皮的这个规格 = 拼多多的那个规格"，**匹配一次，以后复用**。

docs/admin/05-ui-specification.md

@@ -411,10 +411,15 @@ Go 的 map 是无序的，不靠它定顺序的话，同一个商品每次刷新
 ### 6.1 工具条
 
 ```text
-[同步] [指定日期同步] [创建采购任务]   订单号 [___] [搜索]   [删除]
+开始日期 [2026-08-07]  结束日期 [2026-08-09] [同步] [同步记录]
+[创建采购任务]   订单号 [___] [搜索]   [删除]
 ```
 
-`[必须]` 「同步」按工单 #46 实现：
+日期始终显示在主工具条，按 UTC+8 解释且两端都包含。通常默认最近 3 天；如果
+覆盖游标更早，则从游标当天开始补齐。缺口超过 31 天时只预选最早 31 天，并明确
+提示本段成功后继续下一段。
+
+`[必须]` 「同步」是唯一同步入口：
 
 ```text
 点「同步」
@@ -428,7 +433,7 @@ Go 的 map 是无序的，不靠它定顺序的话，同一个商品每次刷新
 ```
 
 同步是长任务，不阻塞 HTTP 请求线程——点完立即跳转，结果异步写进内存态的
-"最近一次同步报告"，下次刷新页面时状态条会显示：
+“最近一次同步报告”和持久化同步记录，下次刷新页面时状态条会显示：
 
 ```text
 同步完成：日期范围 2026-08-09 ~ 2026-08-09，货运单 12 张，商品明细 27 条
@@ -438,25 +443,16 @@ Go 的 map 是无序的，不靠它定顺序的话，同一个商品每次刷新
 有跳过/失败会在后面列出具体原因，不是只给个数字。同步中再次点「同步」会提示
 "已经有一个同步任务在跑"，不会并发跑两个。
 
-`[必须]` 工单 #53 增加的「指定日期同步」是次要操作，不改变上面「同步」的
-自动增量语义。点击后打开小弹窗：
-
-```text
-指定日期同步
-
-开始日期 [2026-08-01]  结束日期 [2026-08-09]
-按货运单创建日期（UTC+8）同步，开始日和结束日都包含。每次最多选择 31 天。
-
-[取消] [开始同步]
-```
-
 - 两端都必填，结束日期不得晚于 UTC+8 下的今天，闭区间最多 31 天。
-- 指定历史范围用于首次分批拉取和补数据；日常操作仍点「同步」。
-- 指定范围经过自动 OCR 或手工验证码登录后必须原样保留。
-- 日期校验失败时重开弹窗、保留原输入，并在字段区域显示可读错误。
-- 指定历史范围默认不推进自动增量游标；游标规则见
+- 日期范围经过自动 OCR 或手工验证码登录后必须原样保留。
+- 日期校验失败时保留原输入，并在工具条下方显示可读错误。
+- 是否推进覆盖游标的规则见
   [08 顺运宝接口](08-顺运宝接口.md) §4.4。
 
+`[必须]` 「同步记录」打开宽弹窗，按开始时间从新到旧分页显示状态、日期范围、
+操作账号、开始/完成时间、同步统计、覆盖游标结果和失败原因。状态至少区分同步中、
+成功、失败、已中断；不能只靠颜色表达。刷新或重启 Admin 后记录仍可查看。
+
 `[必须]` 搜索框宽度见 [§3.1](#31-搜索框宽度)。
 
 ### 6.2 表格列

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

@@ -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 跳转时必须原样保留。
 
 ---