docs: import wiki at afc651f75a3a

T-240.-.md

@@ -0,0 +1,87 @@
+<!-- docs-wiki-sync:docs/tasks/T-240.md@afc651f75a3abc2676bb13aa8a80f6aa6a25a72e -->
+> 同步来源：[`docs/tasks/T-240.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/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。
+
+## 验收要点
+
+- [x] 图片请求固定为配置 ERP origin 的 `/api/p/file?id=<productThumb>`，不接受任意 URL。
+- [x] 请求复用现有 ERP Cookie jar，禁止重定向；401/403、404、错误类型和无效图片稳定分类。
+- [x] 有效 JPEG/PNG/WebP 规范化保存为本地 JPEG，大小和像素限制不回归。
+- [x] 货运元数据先成功提交；单图失败不改变同步 `SUCCEEDED`，状态可审计并在后续同步重试。
+- [x] 相同 READY 引用不重复下载；引用变化替换关联并 best-effort 删除旧文件。
+- [x] Admin 图片接口只返回当前商品本地 READY 图片，未授权及其他状态不泄露存在性。
+- [x] 自动测试不访问真实 ERP，覆盖 Cookie、URL、重定向、状态、去重、替换和内容响应头。
+- [x] 标准 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。