From 45790b171d1c28dca659e570e9a019e8d58a8563 Mon Sep 17 00:00:00 2001 From: ila Date: Fri, 7 Aug 2026 16:36:37 +0800 Subject: [PATCH] docs: import wiki at afc651f75a3a --- T-222.-.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 T-222.-.md diff --git a/T-222.-.md b/T-222.-.md new file mode 100644 index 0000000..e5cfb9a --- /dev/null +++ b/T-222.-.md @@ -0,0 +1,78 @@ + +> 同步来源：[`docs/tasks/T-222.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/tasks/T-222.md) · commit `afc651f75a3a` + +--- +id: T-222 +title: 货运信息存储 API 与 Admin 页面 +phase: 2 +deps: + - T-221 +status: DONE +created: 2026-07-28 +context_ref: 78dc595 +work_branch: null +write_paths: + - backend-api/cmd/** + - backend-api/internal/config/** + - backend-api/internal/domain/** + - backend-api/internal/usecase/** + - backend-api/internal/repository/sqlite/** + - backend-api/internal/transport/httpapi/** + - backend-api/internal/transport/webui/** + - backend-api/migrations/** + - docs/api.md + - docs/routes.md + - docs/tasks/T-222.md + - docs/current-state.md +--- + +## 问题 / 背景 + +现有 `purchase_tasks.source_ref` 只能防止任务重复创建，无法表示 ERP 同步、货运头、 +多商品明细、来源版本和待处理异常。需要独立货运数据层，Admin 先查看来源事实，再 +进入采购需求生成。 + +## 关联需求与交互 + +- 功能：F-011 +- 用户故事：US-011 +- 交互：IX-012 +- 架构/API：`erp_sync_runs`、`freight_orders`、`freight_order_items` + +## 方案 + +1. 新增 migration，按 creator scope 保存同步记录、货运单和商品明细。 +2. 唯一键分别为 `(creator, source_system, external_stock_id)` 和 + `(freight_order_id, external_item_id)`；重复响应按 canonical hash 幂等 upsert。 +3. 只保存采购和审计必要字段；不保存收件人姓名、电话、详细地址、Cookie/JWT 或 + 未裁剪原始响应。 +4. Admin 创建“按单号导入”同步记录，由后台有界调用 loopback Connector；请求返回 + job id，不把验证码/ERP 延迟绑定到浏览器长请求。 +5. 新增 `/freight` 列表、`/freight/import` 和 `/freight/{id}` 详情；页面展示来源 + 单号、店铺、ERP 时间、状态、明细数量、同步状态和可修复异常。 +6. 进程重启时遗留 RUNNING job 转稳定失败；失败不写半批货运数据。 + +## 验收要点 + +- [x] migration up/down/up 和有数据时降级保护通过。 +- [x] 重复导入不重复货运单/明细，来源变化产生版本/hash 更新和审计时间。 +- [x] 多商品、重复外部 ID、超限、协议字段和 connector 失败路径有自动化测试。 +- [x] Admin API/SSR 鉴权、CSRF、no-store、响应式页面和 PII 缺失断言通过。 +- [x] `go test ./...`、race、vet 和根验证通过。 + +## 边界 + +- 不在本任务生成采购任务。 +- 不自动下载 `productThumb`，只保存非秘密 ERP 引用。 +- 不按 ERP 数字状态自动判断“应采购”，状态枚举确认属于 T-223。 + +## 执行记录 + +- 2026-07-28：任务合约已冻结；T-221 完成后领取。 +- 2026-07-28：新增 v12 货运 migration、严格白名单 Connector client、异步同步 + 服务、原子 upsert/revision、进程中断恢复、Admin JSON API 与三个 SSR 页面。 +- 2026-07-28：Connector 未配置时不阻断后端启动；同步任务以稳定错误码失败。未在 + 本任务使用真实 ERP 凭证或执行线上查询。 +- 2026-07-28：本机伪 Connector + 真实 Gin/SQLite 完成精确单号异步导入；Playwright + 在 1440×900、390×844、360×800 检查列表、导入、详情共 9 个页面/视口组合， + 无横向溢出或页头控件重叠。伪响应仅用于界面和链路验收。