docs: 归档任务 #53

docs/task/53-admin-顺运宝指定日期同步.md

@@ -0,0 +1,80 @@
+# 53 Admin：顺运宝支持指定日期同步
+
+- 类型：需求
+- 父级大工单：#14
+- 所属 MVP / 版本：#15 / MVP
+- 状态：已完成
+- 日期：2026-08-09
+- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/53>
+
+## 背景与目标
+
+原有顺运宝同步超过 `max_matches` 时会提示缩小日期范围，但页面只有自动增量
+“同步”按钮，操作员无法按日期分批拉取或补拉历史数据。本任务保留日常自动
+增量入口，增加指定日期同步，并保护 `last_synced_at` 不被局部补拉错误推进。
+
+## 最终方案
+
+- 工具栏保留主按钮“同步”，新增次要按钮“指定日期同步”。日期输入收在弹窗内，
+  使用可见标签，说明日期按 UTC+8 的货运单创建日期解释、起止日均包含。
+- 服务端统一校验日期两端、`YYYY-MM-DD` 格式、先后顺序和 UTC+8 下的今天，
+  不依赖浏览器校验保障数据安全。
+- 自动增量继续从上次成功同步日期当天拉到今天；指定范围共用原有分页、数量
+  上限、同步互斥、明细读取和 upsert。
+- 指定范围只有完整覆盖自动增量原本应同步区间时才推进游标；局部历史补拉和
+  所有失败路径均不推进。
+- 日期参数贯穿 OCR 自动登录、手工验证码登录和 303 跳转。OCR 未配置时也会
+  正确打开手工登录弹窗。
+- 弹窗打开后焦点落在开始日期，Esc 或取消关闭后焦点返回触发按钮。
+
+实际实现与建单方案一致，没有修改数据库结构或 Client API。
+
+## 改了哪些
+
+- `admin/service/syb.go`：同步选项、日期校验、指定范围编排和游标推进规则。
+- `admin/handler/web/others.go`：解析并贯穿日期范围，日期错误和登录跳转保留状态。
+- `admin/templates/syb/list.html`：新增次要按钮、日期弹窗及登录隐藏字段。
+- `admin/static/css/app.css`、`admin/static/js/app.js`：日期弹窗布局与键盘焦点恢复。
+- `admin/service/syb_test.go`、`admin/handler/web/others_test.go`、`admin/main_test.go`：
+  日期、游标、跳转和页面回归测试。
+- `docs/admin/05-ui-specification.md`、`docs/admin/08-顺运宝接口.md`：更新交互与游标契约。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 原“同步”保持自动增量语义 | 通过 |
+| 新增带标签、UTC+8 说明的指定日期弹窗 | 通过 |
+| 缺失、格式、顺序、未来日期均由服务端拦截 | 通过 |
+| 登录和 OCR 降级流程保留指定范围 | 通过 |
+| 局部历史补拉不推进 `last_synced_at` | 通过 |
+| 完整覆盖自动范围且全部成功才推进游标 | 通过 |
+| 中途失败和超过上限不推进游标 | 通过（原测试继续覆盖） |
+| upsert 不覆盖已有 `shopee_sku_id` | 通过（原端到端测试继续覆盖） |
+| 不修改数据库结构及 Client API | 通过 |
+| 1366×768 工具栏、弹窗和键盘操作 | 通过 |
+| Go 1.23.0 全量检查 | 通过 |
+
+## 测试
+
+- 执行的命令：
+
+  ```powershell
+  cd D:\chengma\cmautobuy\admin
+  $env:GOTOOLCHAIN="go1.23.0"
+  gofmt -l .
+  go vet ./...
+  go build ./...
+  go test ./... -count=1
+  Remove-Item Env:GOTOOLCHAIN
+  ```
+
+- 结果：全部通过；`gofmt -l .` 无输出。
+- 浏览器验证：在 1366×768 访问 `/syb`，工具栏未换行；弹窗 520px 宽；
+  开始日期自动获得焦点；Esc 关闭后焦点返回“指定日期同步”。
+- **没验证到的部分**：没有使用真实顺运宝账号执行实际同步，避免无必要地请求
+  外部系统；网络和数据写入路径由 `httptest` 假服务端覆盖。没有触发真实下单。
+
+## 相关提交
+
+- `a18d4e6` feat: 顺运宝支持指定日期同步 (#53)