docs: 归档任务 #46

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

@@ -0,0 +1,56 @@
+# 46 Admin：顺运宝货运单同步
+
+- 类型：需求
+- 父级大工单：#14
+- 所属 MVP / 版本：#15 / MVP
+- 状态：已完成
+- 日期：2026-08-09
+- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/46>
+
+## 背景与目标
+
+顺运宝模块原来只有页面骨架，无法取得真实货运单，规格匹配和采购任务因此没有数据来源。本任务接入顺运宝配置、手工验证码登录、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)
+