1

T-241

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

Table of Contents

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

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

同步来源：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 在桌面及手机视口检查 无横向溢出、重叠、破图和不完整文字。

验收要点

• 货运列表显示确定性的第一商品代表图/占位、商品标题和总项数。
• 详情逐商品显示图片/占位、标题、规格/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 交互。
• 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，控制台无警告或错误。