69 lines
2.5 KiB
Markdown
69 lines
2.5 KiB
Markdown
|
---
|
|||
|
|
id: T-222
|
|||
|
|
title: 货运信息存储 API 与 Admin 页面
|
|||
|
|
phase: 2
|
|||
|
|
deps:
|
|||
|
|
- T-221
|
|||
|
|
status: TODO
|
|||
|
|
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 转稳定失败；失败不写半批货运数据。
|
|||
|
|
|
|||
|
|
## 验收要点
|
|||
|
|
|
|||
|
|
- [ ] 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。
|