Admin：顺运宝支持指定日期同步 #53

New Issue

2026-08-09T13:15:07+08:00

ila commented

2026-08-09 13:15:07 +08:00

基本信息

类型：需求
父级大工单：#14
所属 MVP / 版本：#15 / MVP
阶段：5. 顺运宝货运单与采购任务
关联：#46（现有自动增量同步）

要解决什么

顺运宝后端已按货运单 created 日期范围同步，自动增量范围为“上次成功同步日期当天 → 今天”。当数量超过 max_matches 时，系统提示“请缩小日期范围”，但页面只有无参数“同步”按钮，操作员没有缩小范围或补拉历史日期的入口。

目标是在不改变日常自动增量同步语义的前提下，增加安全、清晰的指定日期补同步能力。

做什么 / 不做什么

做：
- 保留现有“同步”按钮，继续执行自动增量同步。
- 新增次要按钮“指定日期同步”，通过弹窗填写开始日期和结束日期。
- 日期按顺运宝货运单创建日期（UTC+8）解释，起止日期均包含。
- 服务端校验两个日期必须同时填写、格式合法、开始日期不晚于结束日期、结束日期不晚于今天。
- 指定范围同步沿用现有分页、max_matches、互斥、upsert 和报告逻辑。
- 指定历史范围默认不推进 last_synced_at；只有指定范围完整覆盖系统原本应同步区间且全部成功时才推进，避免漏单。
- 登录、OCR 降级及手工验证码流程必须完整保留指定范围。
不做：
- 不修改数据库结构。
- 不修改给 Client 的四个接口。
- 不增加时分秒选择；上游接口只有日期粒度。
- 不自动拆分超出 max_matches 的日期范围。
- 不改规格匹配、创建采购任务或真实下单逻辑。

怎么做

admin/templates/syb/list.html：保留主按钮“同步”，增加次要按钮和指定日期弹窗；日期输入有可见标签、UTC+8/闭区间说明及明确取消入口。
admin/handler/web/others.go：解析可选日期范围，调用 service 校验；在自动登录、手工登录、重定向和后台同步启动之间传递同步选项。
admin/service/syb.go：引入清晰的同步选项/范围对象；自动模式沿用现有 syncDateRange，指定模式校验日期并判断是否允许推进游标；同步报告标明实际日期范围。
对应测试：覆盖日期校验、UTC+8 的“今天”、指定历史范围不推进游标、完整覆盖才推进、登录流程参数保留、超限仍拒绝、重复同步不覆盖 shopee_sku_id。
docs/admin/05-ui-specification.md 与 docs/admin/08-顺运宝接口.md：同步更新交互和游标规则。

验收标准

原“同步”按钮行为不变，仍执行上次成功同步日期当天到今天的自动增量同步。
页面新增“指定日期同步”次要按钮，弹窗包含带可见标签的开始/结束日期输入、UTC+8 和闭区间说明。
日期缺失、格式错误、开始晚于结束、结束晚于今天时不启动后台任务，并显示可操作的错误信息。
指定范围经过登录、OCR 降级、手工验证码流程后仍保持不变。
指定历史范围同步成功后不推进 last_synced_at。
指定范围只有完整覆盖自动应同步区间并全部成功时才推进 last_synced_at。
中途失败、超过 max_matches 均不推进 last_synced_at。
重复补同步继续使用 upsert，已有 shopee_sku_id 不被覆盖。
不修改数据库结构及 Client API。
1366×768 下工具栏和弹窗可正常操作，键盘可聚焦并关闭弹窗。
Go 1.23.0 下 go vet ./...、gofmt -l .、go test ./... -count=1 全部通过。

怎么验证

从 D:\chengma\cmautobuy\admin 执行：

$env:GOTOOLCHAIN="go1.23.0"
go vet ./...
gofmt -l .
go test ./... -count=1
Remove-Item Env:GOTOOLCHAIN

浏览器验证（不需要真实下单）：

打开 /syb，确认原“同步”和“指定日期同步”同时存在。
检查非法日期组合均被拦截且有明确提示。
使用脱敏 httptest 验证指定范围、登录后参数保留、游标和 upsert；不请求真实顺运宝。
1366×768 检查工具栏、弹窗和键盘操作。

风险和回退

风险：指定历史范围错误推进同步游标，导致未覆盖日期永久漏单。通过“完整覆盖自动区间才推进”规则和独立测试防护。
风险：登录/验证码跳转丢失日期参数，最终执行成自动增量。日期范围必须贯穿所有登录路径并有 Handler 测试。
风险：指定范围过大导致上游压力。继续保留 max_matches 硬上限。
回退：git revert 本工单实现提交；无数据库迁移，回退后恢复为单一自动增量同步按钮。

实施记录

状态：已完成
实现提交：a18d4e6（指定日期同步、游标保护、登录参数传递、UI 与测试）
归档提交：1064ffe
归档文档：docs/task/53-admin-顺运宝指定日期同步.md
与方案差异：无。未修改数据库结构和 Client API。

测试结果

在 admin/ 使用 GOTOOLCHAIN=go1.23.0 执行：

gofmt -l .
go vet ./...
go build ./...
go test ./... -count=1

全部通过，gofmt -l . 无输出。另在 1366×768 浏览器验证工具栏、弹窗、日期焦点、Esc 关闭与焦点返回均通过。

未验证：没有使用真实顺运宝账号发起外部同步；网络及落库路径使用 httptest 假服务端验证。没有触发真实下单。

## 基本信息 - 类型：需求 - 父级大工单：#14 - 所属 MVP / 版本：#15 / MVP - 阶段：5. 顺运宝货运单与采购任务 - 关联：#46（现有自动增量同步） ## 要解决什么顺运宝后端已按货运单 `created` 日期范围同步，自动增量范围为“上次成功同步日期当天 → 今天”。当数量超过 `max_matches` 时，系统提示“请缩小日期范围”，但页面只有无参数“同步”按钮，操作员没有缩小范围或补拉历史日期的入口。目标是在不改变日常自动增量同步语义的前提下，增加安全、清晰的指定日期补同步能力。 ## 做什么 / 不做什么 - 做： - 保留现有“同步”按钮，继续执行自动增量同步。 - 新增次要按钮“指定日期同步”，通过弹窗填写开始日期和结束日期。 - 日期按顺运宝货运单创建日期（UTC+8）解释，起止日期均包含。 - 服务端校验两个日期必须同时填写、格式合法、开始日期不晚于结束日期、结束日期不晚于今天。 - 指定范围同步沿用现有分页、`max_matches`、互斥、upsert 和报告逻辑。 - 指定历史范围默认不推进 `last_synced_at`；只有指定范围完整覆盖系统原本应同步区间且全部成功时才推进，避免漏单。 - 登录、OCR 降级及手工验证码流程必须完整保留指定范围。 - 不做： - 不修改数据库结构。 - 不修改给 Client 的四个接口。 - 不增加时分秒选择；上游接口只有日期粒度。 - 不自动拆分超出 `max_matches` 的日期范围。 - 不改规格匹配、创建采购任务或真实下单逻辑。 ## 怎么做 - `admin/templates/syb/list.html`：保留主按钮“同步”，增加次要按钮和指定日期弹窗；日期输入有可见标签、UTC+8/闭区间说明及明确取消入口。 - `admin/handler/web/others.go`：解析可选日期范围，调用 service 校验；在自动登录、手工登录、重定向和后台同步启动之间传递同步选项。 - `admin/service/syb.go`：引入清晰的同步选项/范围对象；自动模式沿用现有 `syncDateRange`，指定模式校验日期并判断是否允许推进游标；同步报告标明实际日期范围。 - 对应测试：覆盖日期校验、UTC+8 的“今天”、指定历史范围不推进游标、完整覆盖才推进、登录流程参数保留、超限仍拒绝、重复同步不覆盖 `shopee_sku_id`。 - `docs/admin/05-ui-specification.md` 与 `docs/admin/08-顺运宝接口.md`：同步更新交互和游标规则。 ## 验收标准 - [x] 原“同步”按钮行为不变，仍执行上次成功同步日期当天到今天的自动增量同步。 - [x] 页面新增“指定日期同步”次要按钮，弹窗包含带可见标签的开始/结束日期输入、UTC+8 和闭区间说明。 - [x] 日期缺失、格式错误、开始晚于结束、结束晚于今天时不启动后台任务，并显示可操作的错误信息。 - [x] 指定范围经过登录、OCR 降级、手工验证码流程后仍保持不变。 - [x] 指定历史范围同步成功后不推进 `last_synced_at`。 - [x] 指定范围只有完整覆盖自动应同步区间并全部成功时才推进 `last_synced_at`。 - [x] 中途失败、超过 `max_matches` 均不推进 `last_synced_at`。 - [x] 重复补同步继续使用 upsert，已有 `shopee_sku_id` 不被覆盖。 - [x] 不修改数据库结构及 Client API。 - [x] 1366×768 下工具栏和弹窗可正常操作，键盘可聚焦并关闭弹窗。 - [x] Go 1.23.0 下 `go vet ./...`、`gofmt -l .`、`go test ./... -count=1` 全部通过。 ## 怎么验证从 `D:\chengma\cmautobuy\admin` 执行： ```powershell $env:GOTOOLCHAIN="go1.23.0" go vet ./... gofmt -l . go test ./... -count=1 Remove-Item Env:GOTOOLCHAIN ``` 浏览器验证（不需要真实下单）： 1. 打开 `/syb`，确认原“同步”和“指定日期同步”同时存在。 2. 检查非法日期组合均被拦截且有明确提示。 3. 使用脱敏 `httptest` 验证指定范围、登录后参数保留、游标和 upsert；不请求真实顺运宝。 4. 1366×768 检查工具栏、弹窗和键盘操作。 ## 风险和回退 - 风险：指定历史范围错误推进同步游标，导致未覆盖日期永久漏单。通过“完整覆盖自动区间才推进”规则和独立测试防护。 - 风险：登录/验证码跳转丢失日期参数，最终执行成自动增量。日期范围必须贯穿所有登录路径并有 Handler 测试。 - 风险：指定范围过大导致上游压力。继续保留 `max_matches` 硬上限。 - 回退：`git revert` 本工单实现提交；无数据库迁移，回退后恢复为单一自动增量同步按钮。 ## 实施记录 - 状态：已完成 - 实现提交：`a18d4e6`（指定日期同步、游标保护、登录参数传递、UI 与测试） - 归档提交：`1064ffe` - 归档文档：`docs/task/53-admin-顺运宝指定日期同步.md` - 与方案差异：无。未修改数据库结构和 Client API。 ## 测试结果在 `admin/` 使用 `GOTOOLCHAIN=go1.23.0` 执行： ```powershell gofmt -l . go vet ./... go build ./... go test ./... -count=1 ``` 全部通过，`gofmt -l .` 无输出。另在 1366×768 浏览器验证工具栏、弹窗、日期焦点、Esc 关闭与焦点返回均通过。未验证：没有使用真实顺运宝账号发起外部同步；网络及落库路径使用 `httptest` 假服务端验证。没有触发真实下单。

ila referenced this issue

2026-08-09 13:15:25 +08:00

[Epic] Admin 采集采购管理端 #14

ila referenced this issue

2026-08-09 13:15:26 +08:00

[MVP] Admin 四模块可用闭环 #15

ila commented

2026-08-09 13:15:44 +08:00