docs: import wiki at afc651f75a3a

T-241.-.md

@@ -0,0 +1,83 @@
+<!-- docs-wiki-sync:docs/tasks/T-241.md@afc651f75a3abc2676bb13aa8a80f6aa6a25a72e -->
+> 同步来源：[`docs/tasks/T-241.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/tasks/T-241.md) · commit `afc651f75a3a`
+
+---
+id: T-241
+title: 优化 ERP 货运列表与商品详情展示
+phase: 2
+deps:
+  - T-240
+status: DONE
+created: 2026-07-29
+context_ref: c7e152a
+work_branch: null
+write_paths:
+  - docs/tasks/T-241.md
+  - docs/current-state.md
+  - backend-api/internal/domain/freight.go
+  - backend-api/internal/repository/sqlite/freight_*
+  - backend-api/internal/transport/httpapi/freight_handlers.go
+  - backend-api/internal/transport/webui/**
+---
+
+## 问题 / 背景
+
+当前货运列表只显示来源单号、店铺、原始状态、商品数量和更新时间，采购人员无法在进入详情前
+识别商品；详情把 `productThumb` 作为文字引用显示，规格和 SKU 重复展示，也没有 ERP 原始
+单价。多列技术字段使桌面端扫描路径分散，移动端卡片化表格也缺少稳定图片尺寸。
+
+T-239/T-240 已提供规范规格 SKU、TWD 原始单价、图片状态和本地鉴权图片 URL，可以在不暴露
+ERP 地址、不改变采购操作的前提下完成界面收敛。
+
+## 关联需求与交互
+
+- 货运列表显示每单第一条当前商品的代表图、标题和总商品数。
+- 货运详情逐项显示本地图片、标题、规格/SKU、数量、ERP 原始单价、货运状态和采购操作。
+- 图片未提供、待获取、ERP 缺失或获取失败时显示稳定文字占位，不显示破图或外部引用。
+- 桌面端保持高密度可扫描，手机端无横向溢出、文字遮挡或操作区域挤压。
+
+## 方案
+
+1. 货运列表查询为每个订单读取按外部商品 ID 排序的第一条当前明细，返回代表商品 ID、标题
+   和图片状态；只有 `READY` 生成本地图片 URL。
+2. 列表重排为货运单、商品摘要、店铺、状态、更新时间和操作。代表图固定 56×56 px，标题
+   可换行，ERP ID 只作为弱化审计信息。
+3. 详情商品行使用固定 84×84 px 图片；`productSpec`/`sku` 相同只展示一次，增加数量和
+   `ERP 原始单价`，按 `TWD 123.00` 定点格式显示，未知价格显示“未提供”。
+4. 图片使用 `width/height`、`loading=lazy`、`object-fit=contain` 和有意义的 `alt`；其他
+   状态用同尺寸占位文字，避免 CLS 和破图。
+5. 新增货运专属 CSS 类，不改其他任务表格；桌面使用密集表格，760px 以下沿用语义化移动
+   布局并固定主要信息优先级，保持至少 44px 操作目标和可见焦点。
+6. SSR 测试覆盖转义、价格、图片 URL/占位和字段去重；Playwright 在桌面及手机视口检查
+   无横向溢出、重叠、破图和不完整文字。
+
+## 验收要点
+
+- [x] 货运列表显示确定性的第一商品代表图/占位、商品标题和总项数。
+- [x] 详情逐商品显示图片/占位、标题、规格/SKU、数量、TWD 原始单价和采购操作。
+- [x] 页面不再显示 `productThumb` 原始引用，规格与 SKU 相同时不重复两行。
+- [x] 图片有固定尺寸、懒加载和 alt；非 READY 状态不发出图片请求、不显示破图。
+- [x] 既有 CSRF、采购需求、参考图上传和生成采购任务操作不回归。
+- [x] 1440×900、768×1024、390×844 和 375×667 无横向溢出、遮挡或不可用操作。
+- [x] 标准 Go 测试、race、vet 和三个入口构建通过。
+
+## 边界
+
+- 不解释或猜测 ERP 数字订单/采购状态的业务含义；未知值继续按原值展示。
+- 不增加筛选、分页、编辑、批量操作或总价计算。
+- 不修改图片下载策略、采购状态机、任务生成规则或 Android App。
+- 不在截图、fixture、日志或提交中使用真实订单、商品、店铺、价格和图片。
+
+## 执行记录
+
+- 2026-07-29：创建任务。采用现有安静、工具型管理后台样式，新增货运专属高密度表格和固定
+  图片尺寸；保持既有语义色、系统字体、44px 操作目标和 SSR 交互。
+- 2026-07-29：列表查询在关闭主结果集后按订单读取第一条当前商品，避免 SQLite 单连接
+  嵌套查询阻塞；API/SSR 返回代表商品标题、数量、图片状态和仅限 READY 的本地图片 URL。
+- 2026-07-29：详情收敛为图片、单一规格/SKU、数量、`TWD 0.00` 原始单价、状态和采购
+  操作；未提供、排队、缺失和失败图片使用同尺寸状态占位，不请求 ERP 图片地址。
+- 2026-07-29：`go test ./...`、`go test -race ./...`、`go vet ./...` 和 API、authctl、
+  migrate 三个入口构建通过。Playwright 连接隔离 SQLite 和脱敏运行时图片，在
+  1440×900、768×1024、390×844、375×667 验证列表/详情：页面横向溢出和越界元素均为
+  0；缓存图自然尺寸 320×320，列表渲染 56×56，详情桌面 84×84、手机 72×72；图片请求
+  返回 200，控制台无警告或错误。