From d062d38ffc14588c21dfd609b4ab9ae4a4d014d6 Mon Sep 17 00:00:00 2001 From: chengma Date: Sun, 9 Aug 2026 21:22:49 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#46?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/task/46-顺运宝货运单同步.md | 56 ++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/task/46-顺运宝货运单同步.md diff --git a/docs/task/46-顺运宝货运单同步.md b/docs/task/46-顺运宝货运单同步.md new file mode 100644 index 0000000..f498d7a --- /dev/null +++ b/docs/task/46-顺运宝货运单同步.md @@ -0,0 +1,56 @@ +# 46 Admin：顺运宝货运单同步 + +- 类型：需求 +- 父级大工单：#14 +- 所属 MVP / 版本：#15 / MVP +- 状态：已完成 +- 日期：2026-08-09 +- Gitea 工单： + +## 背景与目标 + +顺运宝模块原来只有页面骨架，无法取得真实货运单，规格匹配和采购任务因此没有数据来源。本任务接入顺运宝配置、手工验证码登录、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) +