1

T-240

ila edited this page 2026-08-07 16:36:52 +08:00

Table of Contents

• 问题 / 背景
• 关联需求与交互
• 方案
• 验收要点
• 边界
• 执行记录

同步来源：docs/tasks/T-240.md · commit afc651f75a3a

---

id: T-240 title: 缓存并鉴权提供顺运宝货运商品图片 phase: 2 deps:

• T-239 status: DONE created: 2026-07-29 context_ref: 3bd9726 work_branch: null write_paths:
• docs/tasks/T-240.md
• docs/api.md
• docs/current-state.md
• backend-api/migrations/00016_freight_item_images.sql
• backend-api/cmd/api/**
• backend-api/internal/domain/freight.go
• backend-api/internal/platform/shunyunbao/**
• backend-api/internal/usecase/freight_*
• backend-api/internal/repository/sqlite/freight_*
• backend-api/internal/transport/httpapi/**
• backend-api/internal/transport/webui/**

---

问题 / 背景

货运商品已保存来自 ERP productThumb 的正整数引用，但 Admin 只能看到引用文本。浏览器直接 拼接或热链 ERP 地址会泄露外部资源标识、绕过本系统鉴权，并依赖手机或浏览器是否持有 ERP 会话；把货运图片写成 TASK_REFERENCE 又会混淆资产所有权和用途。

图片 endpoint 已知为 /api/p/file?id=<productThumb>。查询参数必须取商品 productThumb， 不能取货运单 ID 或商品明细 ID；是否需要 Cookie/Token 必须通过与现有 ERP 查询相同的会话 客户端兼容。

关联需求与交互

• 单号或日期同步取得商品引用后，由 Go 后端从固定 ERP endpoint 下载图片并保存到本地。
• 货运列表和详情只使用本系统的同源鉴权 URL，不向浏览器暴露 ERP URL 或文件路径。
• 图片失败不得回滚已经成功导入的货运头和商品明细；页面显示明确占位状态并允许后续同步重试。
• 重复同步且 productThumb 未变化时复用本地文件，引用变化时下载新文件并清理被替换文件。

方案

1. 新增 freight_item_images，按货运商品保存 product_thumb_ref、READY/MISSING/FAILED 状态、规范化 JPEG 元数据、稳定错误码、尝试次数和更新时间。缺少记录但商品有引用视为 PENDING。
2. SessionManager 使用配置的 ERP origin、固定 /api/p/file 和 url.Values 构造请求； 复用 Cookie jar、固定请求头、HTTPS、禁止重定向及超时，只接受 2xx 图片响应。401/403 使会话失效，404 映射为 MISSING，其他错误映射为 FAILED。
3. 复用现有图片文件存储完成 20 MiB、尺寸、像素、解码格式、白底合成、最长边 2048 px 和 JPEG 规范化，不在日志输出图片字节、Cookie、查询参数或本地路径。
4. 货运事务先提交并标记同步成功，再在调用方剩余预算内执行有界 best-effort 缓存；单图失败 仅保存状态。同步重放或下一次同步重试未就绪图片，不重复下载相同引用的 READY 图片。
5. 增加受 Admin 会话保护的 GET /api/v1/freight-items/{item_id}/image，仅从本地存储返回 JPEG，带 nosniff、ETag、长度和私有缓存头；不存在、未完成或无权限统一返回 404。

验收要点

• 图片请求固定为配置 ERP origin 的 /api/p/file?id=<productThumb>，不接受任意 URL。
• 请求复用现有 ERP Cookie jar，禁止重定向；401/403、404、错误类型和无效图片稳定分类。
• 有效 JPEG/PNG/WebP 规范化保存为本地 JPEG，大小和像素限制不回归。
• 货运元数据先成功提交；单图失败不改变同步 SUCCEEDED，状态可审计并在后续同步重试。
• 相同 READY 引用不重复下载；引用变化替换关联并 best-effort 删除旧文件。
• Admin 图片接口只返回当前商品本地 READY 图片，未授权及其他状态不泄露存在性。
• 自动测试不访问真实 ERP，覆盖 Cookie、URL、重定向、状态、去重、替换和内容响应头。
• 标准 Go 测试、race、vet 和三个入口构建通过。

边界

• 本任务不修改货运列表和详情的视觉布局；页面引用图片 URL 和占位视觉在 T-241 完成。
• 不建立通用媒体库、不向浏览器返回 ERP URL、不持久化 ERP Cookie/Token。
• 不保证每张外部图片都成功；网络、会话和上游文件错误按商品隔离。
• 不提交或记录真实 ERP 图片、订单、商品、收件人、账号或会话数据。

执行记录

• 2026-07-29：创建任务。采用货运商品专属图片元数据表并复用安全文件编码管线；先提交货运 元数据，再 best-effort 缓存图片，避免单个外部文件阻塞或回滚完整订单。
• 2026-07-29：增加 migration 16、固定 ERP 图片客户端、四 worker/最多 1000 项/15 秒 best-effort 缓存、图片状态仓储和 Admin 本地内容接口。相同 READY 引用跳过，失败引用在 新同步重试，引用替换后删除旧文件；同步成功不受单图失败影响。脱敏测试覆盖 Cookie、 固定 query、重定向、401/404/无效类型、JPEG 规范化、去重、替换、回滚保护、鉴权与响应头。 go test ./...、go test -race ./...、go vet ./... 及三个入口构建均通过；未访问真实 ERP。