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

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 全量检查	通过

测试

• 执行的命令：

  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)