From 8b0752dc536150422c218336dc269e3d84301918 Mon Sep 17 00:00:00 2001
From: QiuSW <105186638@qq.com>
Date: Wed, 29 Jul 2026 15:14:43 +0800
Subject: [PATCH] docs(t241): plan freight admin redesign

---
 docs/tasks/T-241.md | 71 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 docs/tasks/T-241.md

diff --git a/docs/tasks/T-241.md b/docs/tasks/T-241.md
new file mode 100644
index 0000000..8961a77
--- /dev/null
+++ b/docs/tasks/T-241.md
@@ -0,0 +1,71 @@
+---
+id: T-241
+title: 优化 ERP 货运列表与商品详情展示
+phase: 2
+deps:
+  - T-240
+status: TODO
+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 在桌面及手机视口检查
+   无横向溢出、重叠、破图和不完整文字。
+
+## 验收要点
+
+- [ ] 货运列表显示确定性的第一商品代表图/占位、商品标题和总项数。
+- [ ] 详情逐商品显示图片/占位、标题、规格/SKU、数量、TWD 原始单价和采购操作。
+- [ ] 页面不再显示 `productThumb` 原始引用，规格与 SKU 相同时不重复两行。
+- [ ] 图片有固定尺寸、懒加载和 alt；非 READY 状态不发出图片请求、不显示破图。
+- [ ] 既有 CSRF、采购需求、参考图上传和生成采购任务操作不回归。
+- [ ] 1440×900、768×1024、390×844 和 375×667 无横向溢出、遮挡或不可用操作。
+- [ ] 标准 Go 测试、race、vet 和三个入口构建通过。
+
+## 边界
+
+- 不解释或猜测 ERP 数字订单/采购状态的业务含义；未知值继续按原值展示。
+- 不增加筛选、分页、编辑、批量操作或总价计算。
+- 不修改图片下载策略、采购状态机、任务生成规则或 Android App。
+- 不在截图、fixture、日志或提交中使用真实订单、商品、店铺、价格和图片。
+
+## 执行记录
+
+- 2026-07-29：创建任务。采用现有安静、工具型管理后台样式，新增货运专属高密度表格和固定
+  图片尺寸；保持既有语义色、系统字体、44px 操作目标和 SSR 交互。