cmroubao/docs/tasks/T-222.md

id, title, phase, deps, status, created, context_ref, work_branch, write_paths

id	title	phase	deps	status	created	context_ref	work_branch	write_paths
T-222	货运信息存储 API 与 Admin 页面	2	T-221	DONE	2026-07-28	78dc595	null	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 转稳定失败；失败不写半批货运数据。

验收要点

• migration up/down/up 和有数据时降级保护通过。
• 重复导入不重复货运单/明细，来源变化产生版本/hash 更新和审计时间。
• 多商品、重复外部 ID、超限、协议字段和 connector 失败路径有自动化测试。
• Admin API/SSR 鉴权、CSRF、no-store、响应式页面和 PII 缺失断言通过。
• 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 个页面/视口组合， 无横向溢出或页头控件重叠。伪响应仅用于界面和链路验收。