diff --git a/T-241.-.md b/T-241.-.md new file mode 100644 index 0000000..0bec405 --- /dev/null +++ b/T-241.-.md @@ -0,0 +1,83 @@ + +> 同步来源:[`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,控制台无警告或错误。