feat(t240): cache freight item images

docs/api.md

@@ -205,6 +205,33 @@ T-203 成功返回 `201`。使用相同 `Idempotency-Key` 和相同图片内容
 `null`，币种固定为 `TWD`。`product_thumb_ref` 来自商品 `productThumb`，存在时必须是
 规范化正整数，不能使用货运单 ID、商品明细 ID 或完整 URL。
 
+货运详情中的每个商品还返回：
+
+```json
+{
+  "image_status": "READY",
+  "image_error_code": null,
+  "image_url": "/api/v1/freight-items/{item_id}/image"
+}
+```
+
+`image_status` 为 `NONE/PENDING/READY/MISSING/FAILED`。只有 `READY` 返回同源
+`image_url`；其他状态返回 `null`，失败时 `image_error_code` 是不包含上游正文的稳定错误码。
+元数据同步先提交，图片在剩余请求预算内 best-effort 缓存，因此图片失败不改变货运同步的
+`SUCCEEDED` 终态。后续新同步会重试非 `READY` 图片，相同引用的 `READY` 图片不会重复下载。
+
+### `GET /api/v1/freight-items/{item_id}/image`
+
+Admin 会话鉴权的本地货运商品图片流。仅当商品仍在当前货运版本中、当前 `productThumb`
+与已缓存引用一致且状态为 `READY` 时返回 `200 image/jpeg`；不存在、未完成、引用已变化或
+无权访问统一返回 `404`。响应包含 `Content-Length`、ETag、
+`X-Content-Type-Options: nosniff` 和 `Cache-Control: private, no-store`，不返回 ERP URL、
+查询参数或服务端文件路径。
+
+后端只使用配置的 `CMROUBAO_SHUNYUNBAO_URL` origin 和固定
+`/api/p/file?id=<productThumb>` 请求图片，复用 ERP Cookie jar 并禁止重定向。下载内容经过
+既有大小、尺寸、像素和解码校验，统一白底规范化为最长边不超过 2048 px 的 JPEG。
+
 ### Go ERP 会话（T-230、T-236）
 
 `/erp`、`/erp/captcha`、`/erp/login` 和 `/api/v1/erp-session*` 不再暴露。创建货运同步