2026-09-13-pound-qrcode-public-link-design.md 7.6 KB

磅单二维码公开链接与司机页入口 — 设计文档

日期: 2026-09-13
状态: 待实现
方案: 方案 1 — 抽公共展示组件 + 公开只读 API + 独立路由 + 司机页弹层
Demo: docs/superpowers/demos/2026-09-13-pound-qrcode-public-demo.html

1. 目标

  1. 「复制给司机」文案末尾追加磅单二维码链接(可多行);链接打开独立公共页,样式与管理端「复制磅单二维码」弹窗一致。
  2. 司机填写页(/#/public/pl/transport/:token)底栏增加「磅单二维码」;点击后弹层展示同款界面(多单先选再弹)。

2. 已确认决策

# 项 决策
D1 多单 · 复制文案 多行链接;格式见 D4
D2 多单 · 司机页 先选一张再弹窗(ActionSheet)
D3 公开 URL #/public/pl/pound-qrcode/{inventoryId},免登录按 id 查公开字段
D4 文案格式 先一行标题 磅单二维码链接:,下列 {业务类型} · {往来单位}:{url}
D5 无地磅关联单 复制不加磅单段;司机页隐藏第三钮
D6 底栏布局 同一行三钮:运输记录 \| 磅单二维码 \| 保存回执
D7 实现路径 方案 1(共享 View + 公开 API + 扩展司机页 payload)
D8 作废/已完成单据 仍允许只读展示二维码(核验场景)

3. 非目标

  • 不做公开 URL token 化 / 访问限流(已知 id 枚举风险,后续可单独立项)
  • 不改管理端「复制磅单二维码」图片复制主流程(仍弹窗复制图)
  • 不改现场页 transport-site 底栏
  • 不做小程序端对本能力的移植
  • 不扩展公开接口返回现场回执、金额、租户号等非展示字段

4. 架构

管理端「复制给司机」
  → arrange / inventoryLinks(已有)
  → buildPlanSummaryText 追加磅单链接块
  → 剪贴板

独立公开页
  /#/public/pl/pound-qrcode/:inventoryId
  → GET /api/public/db/inventory/{id}/pound-qr
  → PoundSlipQrcodeView

司机页
  /#/public/pl/transport/:token
  → GET /api/public/pl/transport/{token} 含 poundQrcodeItems[]
  → 有 items 显示第三钮
  → 1 条直接弹层 / 多条 ActionSheet
  → 同 pound-qr API → PoundSlipQrcodeView

管理端「复制磅单二维码」
  → DbPoundSlipQrcodeDialog(鉴权 get)
  → 内嵌同一 PoundSlipQrcodeView(样式不漂移)

4.1 组件边界

单元 职责 依赖
PoundSlipQrcodeView 纯展示:黄牌、往来单位、物料、备注、日期+单号、二维码图、说明 已解析的公开字段 + 图片 URL;样式类 .pound-slip-capture-inline
DbPoundSlipQrcodeDialog 管理端弹窗壳、鉴权加载、复制图片 View + inventoryApi.get
公共页 pound-qrcode/index.vue 路由 id → 公开 API → View / 空态 publicPlGet
司机页弹层 van-popup 深色底 + View;多选 ActionSheet poundQrcodeItems + 公开 API

5. 接口

5.1 新增 GET /api/public/db/inventory/{inventoryId}/pound-qr

  • 挂在现有 public/db/inventory 路由模块;该前缀已在 API_ENCRYPT_EXCLUDE_PATHS。
  • 条件:id 匹配且 del_flag=0;不做登录/租户校验。
  • 响应(camelCase)仅含:
字段 说明
id 出入库单 id(二维码内容)
date 业务日期展示串
businessType 入库 / 出库
vehicleNo 车牌
partnerCompany 往来单位
product 物料名
specification 规格(可空)
quantity 数量
quantityUnit 单位文案,缺省「吨」
remarks 备注(可空;空则不渲染行)
  • 404:不存在或已删。
  • Schema 建议:PublicPoundQrRead(app/schemas/db/public_inventory.py)。

5.2 扩展司机页 PublicTransportPage

增加:

poundQrcodeItems?: {
  inventoryId: string
  businessType: string
  partnerCompany: string
  label: string  // 「出库 · 合肥德泽化工科技有限公司」
}[]

来源:运输对应计划下有效 PlTransportDbLink → DbInboundOutbound(del_flag=0)。无则 []。

6. 前端交互

6.1 路由

staticRoutes.ts 增加:

  • path: /public/pl/pound-qrcode/:inventoryId
  • name: PublicPlPoundQrcode
  • meta: { title: '磅单二维码', isHideTab: true, isPublicMobile: true }
  • 加载成功后可将 document/title 改为「入库/出库磅单二维码」。

6.2 司机页底栏

  • poundQrcodeItems.length > 0 → 三钮:运输记录 | 磅单二维码 | 保存回执。
  • 否则保持现有两钮。
  • 计划作废/归档导致仅「运输记录」时:若仍有 items,仍显示「磅单二维码」(只读核验);「保存回执」按原规则隐藏即可。
  • 多条:showActionSheet({ actions: items.map(i => ({ name: i.label, … })) })。

6.3 复制给司机文案

改 web-admin/src/utils/pl-driver-summary.ts 的 buildPlanSummaryText:

  • 新增可选参数 poundQrcodeLinks?: { label: string; url: string }[]。
  • 有数据时,在「司机链接」行之后追加:
磅单二维码链接:
出库 · 合肥德泽化工科技有限公司:http://host/#/public/pl/pound-qrcode/{id}
入库 · 安庆市山峡化工有限公司:http://host/#/public/pl/pound-qrcode/{id}
  • url = {window.location.origin}/#/public/pl/pound-qrcode/{inventoryId}。
  • 调用方(usePlPlanArrangeActions / pl-plan-view-tabs 等)从已有 dibangInventoryRecords 组装 links;无记录则不传。

6.4 二维码图片

与现 DbPoundSlipQrcodeDialog 一致:对 id 编码生成二维码图(当前为 qrserver);产品标签拼接规则(规格后缀去重)复用现函数。

7. 错误处理

场景 行为
公开页 id 无效/已删 404 → 「链接无效或单据不存在」
公开页网络失败 「加载失败,请稍后重试」
司机弹层加载失败 Toast「加载二维码失败」
items 为空 不渲染第三钮
无 dibang 关联复制 文案无磅单段
二维码图 CDN 失败 公共页保留错误提示;管理端保持现有提示行为

8. 测试要点

  1. 单张地磅单:复制文案含标题 + 一行 label:url;打开样式与管理端弹窗一致。
  2. 多张:文案多行;司机页 ActionSheet → 弹层对应正确单。
  3. 未勾选生成地磅单:无磅单段、无第三钮。
  4. 管理端「复制磅单二维码」复制图片仍可用,样式不回退。
  5. 计划作废后:有 items 时可只读打开二维码;保存回执按原规则。
  6. 删单后旧链接:公开页 404 文案。

9. 主要改动文件(预估)

Backend

  • app/api/db/public_inventory.py — 新增 pound-qr
  • app/schemas/db/public_inventory.py — PublicPoundQrRead
  • app/api/pl/public_transport.py — _build_public_page 填 poundQrcodeItems
  • app/schemas/pl/... — PublicTransportPageRead 字段

web-admin

  • components/business/db/PoundSlipQrcodeView.vue(新建)
  • components/business/db/DbPoundSlipQrcodeDialog.vue(改用 View)
  • views/public/pl/pound-qrcode/index.vue(新建)
  • router/routes/staticRoutes.ts
  • views/public/pl/transport/index.vue
  • api/pl/public-transport.ts、api/db/public-inventory.ts(或并列 pound-qr API)
  • utils/pl-driver-summary.ts
  • composables/usePlPlanArrangeActions.ts(及复制入口调用链)

10. 验收标准

司机通过复制文案中的磅单链接,或在司机页点击「磅单二维码」,看到的界面与后台「复制磅单二维码」弹窗同款;多单可选;无关联单时链接与按钮均不可见。