移动端协议单：样本及运输对齐 Web — 设计说明

日期： 2026-10-13
状态： 已确认
范围： mobile-oa-h5 协议单（细胞存储 + 科研捐赠）编辑/详情；backend 市场协议样本 schema 与详情 enrichment
决策： 方案 A 协议页内嵌；实现路径方案 1（新建 ProtocolSampleTransportPanel）

1. 目标

小程序协议单「样本及运输」与 Web sample-transport-form-section 功能一致，仅交互与样式按小程序（Vant）呈现。覆盖细胞存储与科研捐赠。

2. 范围与对齐清单

2.1 样本字段（对齐 Web 弹窗）

字段	细胞存储	科研捐赠	行为
样本类型	必填	必填	变更带出原价/优惠价/存储年限（捐赠无价格）
样本编码	选库内编码	自动生成只读	行间互斥已占用；排除他单已用
原价	只读	隐藏	来自样本类型
优惠价	可编	隐藏
存储年限	可编	隐藏
样本状态	有	有	`ycj` / `jcz` / `yrk` / `yzf`
预计到达	有	有	扁平 `etaTime` 提交（后端写入运输表）
特殊样本 / 特殊说明	有	有	勾选特殊则说明必填（max 256）
采集量 / 单位	不做	不做	与 Web 当前弹窗一致（已移除）
样本备注	不展示	不展示	与 Web 弹窗一致；历史数据详情仍可读 remark 若后端返回

2.2 运费（协议页内，对齐 Web 工具栏）

勾选样本 → 配置运费：新建批次（运输方式 + 金额）或 关联已有 运费批次
取消运费（已配置样本）
已持久化样本（有 sample.id）：立即调 freight create / link / unlink
未保存样本：写 freightDraft；协议保存时由 apply_freight_on_protocol_save 挂钩
行上展示：运输方式标签、运费金额、ETA

2.3 详情

样本卡片补齐：运输方式、运费金额、预计到达（与 Web 查看一致）。

2.4 非目标

已废弃运输字段（快递公司、运单号、目的站点等）
删除独立「运费」模块
Web 管理端改动
列表筛选、审核/退费/开票等既定 Web-only 能力

3. 组件结构与数据流

3.1 前端结构

MarketModuleForm (module=protocol)
  └─ ProtocolSampleTransportPanel   ← 新建
       ├─ 样本卡片列表（增 / 删 / 编辑）
       ├─ 勾选 + 配置运费 / 取消运费
       └─ 运费 Popup（新建 | 关联已有）
  └─ ProtocolSamplePaymentPanel     ← 仅 cell_storage，保持

protocol.js：formSections 移除 samples（改由面板托管，避免双轨）
Props 建议：modelValue（samples）、source、protocolId、marketRole、sampleTypes、sampleCodes、transportModes、disabled
细胞存储：showPrice=true；科研捐赠：showPrice=false + 编码自动生成

3.2 数据流

时机	行为
编辑回填	详情 `samples[]` 含 `etaTime`、`sampleStatus`、`freight` / `freightId`
配置运费（已有 sample.id）	freight API → 写回行上 `freight`
配置运费（草稿样本）	写 `freightDraft`
保存协议	samples 含样本字段 + `etaTime` + `sampleStatus` + `freightId` / `freightDraft`
后端落库	`save_samples` → 运输 ETA；`apply_freight_on_protocol_save` 挂钩运费

3.3 关键交互

添加/编辑样本：Popup / 内联展开，字段与 Web 校验一致
配置运费：Popup 填运输方式 + 金额，或选已有批次（复用 freight 列表/选项 API）
校验失败：Toast；特殊说明、类型、编码、运费 ≥ 0

4. 后端增量

MarketProtocolSampleBody（extra='forbid'）增加可选：
- sampleStatus
- freightId
- freightDraft（对象：clientKey / transportMode / freightAmount）
详情 enrichment：样本挂 freight（id、transportMode、transportModeLabel、freightAmount），编辑与详情共用
科研捐赠编码：对齐 Web 自动生成（市场端创建样本时后端生成或提供 reserve 接口；与 Web autoGenerateSampleCode 行为一致）
写路径：确认 market_protocol → save_samples 已调用 apply_freight_on_protocol_save；schema 放行后即可挂钩，无需重写运费核心逻辑

5. 与既有模块关系

模块	关系
独立「运费」	保留；协议内嵌为第二入口（同 payment 转账模式）
缴费面板	仍监听 samples 价格/编码变更；样本托管改面板后须继续 `v-model` 同步
客户检索 / 转账	非本轮范围，回归不破坏

6. 测试要点

面板契约：添加样本、配置运费、取消运费；细胞有价、捐赠无价
校验：特殊说明必填、编码互斥、未选类型不可保存样本
Payload：保存含 etaTime / sampleStatus / freightId / freightDraft
后端：新字段接受；详情带回 freight；非法 freight 拒绝
回归：缴费、客户绑定、协议内转账

7. 落地顺序

后端 schema + 详情 freight + 捐赠编码（如需）
ProtocolSampleTransportPanel 样本字段与校验
面板内嵌运费配置/关联/取消
MarketModuleForm 接线；移除旧 samples formSections
详情展示运输方式/运费
单测 + ./scripts/update-graph.sh backend

8. 风险

未保存协议时运费仅 freightDraft，须与 Web 挂钩语义一致
样本增删改价后缴费面板须继续同步
formSections 移除 samples 后，依赖旧字段配置的测试需一并更新

2026-10-13-mobile-protocol-sample-transport-parity-design.md 5.6 KB Histórico Raw