5.6 KiB
5.6 KiB
移动端协议单:样本及运输对齐 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')增加可选:sampleStatusfreightIdfreightDraft(对象: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接线;移除旧 samplesformSections- 详情展示运输方式/运费
- 单测 +
./scripts/update-graph.sh backend
8. 风险
- 未保存协议时运费仅
freightDraft,须与 Web 挂钩语义一致 - 样本增删改价后缴费面板须继续同步
formSections移除 samples 后,依赖旧字段配置的测试需一并更新