# 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)