81 lines
3.6 KiB
Markdown
81 lines
3.6 KiB
Markdown
# 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)
|