From 1064ffed59828a46445fe902ffb9f11c2979e6ca Mon Sep 17 00:00:00 2001 From: chengma Date: Sun, 9 Aug 2026 13:24:36 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#53?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/task/53-admin-顺运宝指定日期同步.md | 80 ++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/task/53-admin-顺运宝指定日期同步.md diff --git a/docs/task/53-admin-顺运宝指定日期同步.md b/docs/task/53-admin-顺运宝指定日期同步.md new file mode 100644 index 0000000..9fd2637 --- /dev/null +++ b/docs/task/53-admin-顺运宝指定日期同步.md @@ -0,0 +1,80 @@ +# 53 Admin：顺运宝支持指定日期同步 + +- 类型：需求 +- 父级大工单：#14 +- 所属 MVP / 版本：#15 / MVP +- 状态：已完成 +- 日期：2026-08-09 +- Gitea 工单： + +## 背景与目标 + +原有顺运宝同步超过 `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)