Files
cmautobuy/docs/task/46-顺运宝货运单同步.md
T

3.1 KiB

46 Admin:顺运宝货运单同步

背景与目标

顺运宝模块原来只有页面骨架,无法取得真实货运单,规格匹配和采购任务因此没有数据来源。本任务接入顺运宝配置、手工验证码登录、SQLite 会话缓存和增量同步,把货运单商品明细安全写入 syb_orders。

最终方案

  • 新增 v5 迁移,追加顺运宝会话、同步游标和货运单规格字段,不改写 v1–v4。
  • 使用同一 Cookie Jar 完成验证码、登录和顺运宝请求;会话缓存到 SQLite,并区分明确未登录与网络故障。
  • 首次从 sync_from 开始,之后从上次同步日期当天重拉;全部成功后才推进游标。
  • 分页取得货运单,再分批取得明细;一条商品明细对应一行 syb_orders。
  • 使用白名单 upsert,保留人工匹配产生的 shopee_sku_id;剔除不需要的收件人个人信息。
  • 同步作为互斥后台任务运行,页面显示可执行下一步的结果或失败信息。

后续 #53、#58、#59、#60 对日期范围、完整性校验、同步记录和分页语义进行了增强与修正;这些变化不否定本任务建立的登录、会话、字段映射和安全 upsert 基础。

改了哪些

  • admin/config/:顺运宝配置读取和安全校验。
  • admin/repository/、admin/model/model.go:v5 迁移、会话、游标及货运单持久化。
  • admin/syb/:验证码、登录、列表和明细 HTTP 客户端及假服务端测试。
  • admin/service/syb.go:同步编排、字段转换、增量边界和报告。
  • admin/handler/web/、admin/templates/syb/list.html、静态资源:登录与同步页面交互。
  • docs/admin/:配置、数据模型、界面和顺运宝接口说明。

验收结果

验收标准 结果
配置错误可读且密码不进入页面、日志或错误 通过
v5 只追加并通过历史迁移与 schema 自检 通过
登录、会话缓存、过期及网络错误分类正确 通过
增量从上次同步日期当天重拉,失败不推进游标 通过
多商品展开、金额与图片映射、无效数量处理正确 通过
upsert 保留 shopee_sku_id 且重复同步幂等 通过
测试使用 httptest,不访问真实顺运宝 通过
五个页面和 Go 1.23 自动化检查通过 通过

测试

  • 执行的命令:在 admin/ 使用 Go 1.23.0 执行 go build ./...、go test ./... -count=1、go vet ./...。
  • 结果:构建、全部测试和静态检查通过;配置、迁移、repository、同步编排和 HTTP 客户端均有自动化覆盖。
  • 没验证到的部分:本次验收未重新连接真实顺运宝账号,未重新执行真实验证码登录、重启后的生产会话复用和真实数据上的 shopee_sku_id 保留检查;用户已明确通过验收。

相关提交

  • 5e426ca feat: 顺运宝货运单同步 (#46)