Also include the two-button freight config/cancel design spec and plan. Co-authored-by: Cursor <cursoragent@cursor.com>
9.1 KiB
运费「配置 / 取消」双按钮规则 — 设计
日期:2026-10-12
状态:待审阅
关联:
docs/superpowers/specs/2026-10-07-sample-freight-batch-design.md(运费批次基线)docs/superpowers/specs/2026-10-08-sample-freight-menu-design.md(运费信息页)- 实现入口:
SampleTransportFormSection、sample-freight/*、mobile-oa-h5运费模块
1. 背景与结论
1.1 问题
采集协议单「样本及运输信息」中,样本已配置或关联运费后,再次点击「配置运费」会打开空白「新建」弹窗,既不回填历史,也不阻止重复配置。相对基线设计中的「修改方式与金额」能力,现状易造成误建批次或静默换绑。
1.2 产品决策(本需求)
采用双按钮、先取消再配置模型,放弃「单按钮:确认取消后直接进配置」方案:
| 决策 | 说明 |
|---|---|
| 两个按钮 | 配置运费、取消运费(原「取消运费关联 / 取消关联」统一改名) |
| 已配不可再配 | 已有运费的样本不得进入配置弹窗作为配置对象 |
| 混合勾选 | 「配置运费」可点;仅未配样本进入弹窗;提示已跳过 N 个已配样本 |
| 取消可部分解除 | 点「取消运费」先开弹窗,列出相关已关联样本,勾选后再确认;同批多个样本不必全部取消 |
| 覆盖范围 | Web:协议单 + 运费信息页;市场小程序:mobile-oa-h5 行为对齐 |
| 编辑批次头 | 「编辑运费」(改运输方式/金额)保留,与取消/重配分离 |
心智模型: 配置 = 给「还没有运费」的样本挂批次;改挂靠关系 = 先取消再配置;改金额/方式 = 编辑。
2. 非目标
- 不新增「重新配置」原子 API。
- 不在配置弹窗内直接编辑已关联批次的方式/金额(改价走「编辑运费」)。
- 不改合同/缴费与运费的无联动约定。
- 不强制物理删除运费批次(仍按现有:无剩余关联则软删批次)。
- 不改造经典
miniprogram工程(本需求仅web-admin+mobile-oa-h5)。
3. 交互规则
3.1 配置运费
前置:用户已勾选至少一个样本(协议单表格)或已在配置弹窗内选样(运费信息页 / 小程序)。
| 勾选/选样情况 | 行为 |
|---|---|
| 无有效未配运费样本(全部已有运费,或未选) | 不打开配置弹窗;提示先取消运费(或先勾选未配置样本) |
| 全部未配运费 | 打开配置弹窗(新建 / 关联已有),对象 = 全部选中样本 |
| 混合(部分已配、部分未配) | 打开配置弹窗,对象 = 仅未配样本;必须提示:已跳过 N 个已配置运费的样本 |
配置弹窗打开后表单为空(新建默认),不回填已跳过样本的历史运费。关联已有时,目标批次可选;提交后仅挂到「本次弹窗内的未配样本」。
提示文案(建议):
- 全部已配:
所选样本均已配置运费,请先取消运费后再配置 - 混合跳过:
已跳过 N 个已配置运费的样本,将仅为其余样本配置运费
3.2 取消运费
两端(协议单、运费信息页)与小程序统一流程:
- 用户触发「取消运费」(工具栏或行内)。
- 打开弹窗,标题为 取消运费。
- 列出相关已关联样本,支持多选;默认勾选与触发上下文相关的样本(见 §4)。
- 用户确认 → 仅对勾选样本调用现有 unlink API;未勾选的同批样本保持关联。
- 批次下若无剩余有效关联 → 沿用现有软删批次逻辑。
确认文案(建议): 确定取消所选样本的运费吗?取消后可再次配置运费。
无任何可取消样本时:按钮禁用,或点击后提示「请先选择已配置运费的样本」。
3.3 与「编辑运费」的边界
| 诉求 | 入口 |
|---|---|
| 给未配样本挂新建/已有批次 | 配置运费 |
| 解除部分或全部样本与批次的关联 | 取消运费 |
| 改同一批次的运输方式/金额(关联样本不变) | 编辑运费 |
4. Web 管理端
4.1 协议单(细胞存储 / 科研捐赠)
组件:web-admin/src/components/business/sample-transport-form-section/index.vue(两协议共用)。
| 控件 | 改动 |
|---|---|
| 配置运费 | 按 §3.1 过滤;openFreightDialog 仅传入未配样本;混合时 ElMessage 提示跳过 N |
| 取消运费 | 文案替换「取消运费关联」;不再对表格勾选直接 unlink;改为打开共用取消弹窗 |
| 取消弹窗样本来源 | 以当前表格勾选中「已有运费」的样本为种子;按其所涉 freightId 拉取批次详情,列出这些批次下的全部关联样本(可含其他协议单上的共用样本,与运费信息页一致)。拉取失败时至少列出种子样本。默认勾选 = 种子样本 |
4.2 运费信息页
路径:/#/market/cell-storage/sample-freight
组件:sample-freight/index.vue、FreightConfigDialog.vue 等。
| 控件 | 改动 |
|---|---|
| 工具栏 / 行内「取消关联」 | 文案改为 取消运费 |
| 取消弹窗 | 保持「按批次列出 items 勾选」能力;标题改为「取消运费」;可抽为公共组件供协议单复用 |
| 配置运费 | 选样列表中已有 freightId 的样本不可作为本次配置对象(过滤或禁用勾选);若用户从外部带入混合集,适用 §3.1 跳过提示 |
| 编辑 | 保留 |
4.3 公共组件(建议)
新建或抽离:web-admin/src/components/business/freight-unlink-dialog/index.vue(名称可微调)
- Props:可见性、候选样本列表、默认勾选、提交中状态
- Emits:确认(勾选 items)、取消
- 展示列:来源、协议单号、样本编码、样本类型(与现运费页取消弹窗对齐)
协议单与运费信息页共用,避免两套文案与列定义。
4.4 API
不新增接口。沿用:
POST /web/admin/sample-freights(新建)POST /web/admin/sample-freights/{id}/linkPOST /web/admin/sample-freights/{id}/unlinkPUT /web/admin/sample-freights/{id}(编辑)GET /web/admin/sample-freights/{id}(取消弹窗补全同批样本时按需)
5. 市场小程序(mobile-oa-h5)
模块:mobile-oa-h5/src/market/modules/freight.js 及列表/详情/表单视图。
| 动作 | 行为 |
|---|---|
| create / link | 选样仅未关联样本可提交;若出现已关联样本则跳过并提示 N;候选全为已关联则阻断并提示先取消运费 |
| unlink | 对外文案 取消运费;表单内多选要解除的样本(沿用 detail items),允许只取消一部分 |
| edit | 保留批次头编辑 |
权限:后端 unlink 能力保留;前端主按钮文案与禁用/提示规则与 Web 对齐。列表 presenter 中 unlink 展示名由「取消关联」改为「取消运费」。
6. 错误与边界
| 场景 | 处理 |
|---|---|
| unlink 失败 | 提示错误;不假装已取消;列表按服务端刷新 |
| 配置提交失败 | 已跳过的已配样本不受影响;未配样本保持未配 |
| 取消弹窗未勾选任何行点确定 | 前端拦截,提示至少选择一条 |
| 用户取消确认框 | 不调用 API |
草稿样本(仅 freightDraft) |
视为「已配」:配置时跳过;取消时从本地清除 draft / 若有 freightId 再调 unlink |
7. 验收标准
- 协议单:已配样本不会出现在「配置运费」提交对象中;混合勾选有跳过 N 提示;全部已配时无法进入配置。
- 协议单与运费信息页:「取消运费」均先弹窗勾选样本再确认;可只取消同批中的部分样本。
- 所有相关按钮/标题文案为「取消运费」,不再使用「取消运费关联」「取消关联」(编辑除外)。
- 运费信息页「编辑」仍可改方式与金额。
- mobile-oa-h5 运费 create/link/unlink 与 §3、§5 一致。
- 回归:未配样本配置新建/关联已有、共用批金额展示、协议保存与 enrichment 正常。
8. 影响面(实现时核对)
| 区域 | 路径(预期) |
|---|---|
| Web 协议运输区 | web-admin/src/components/business/sample-transport-form-section/index.vue |
| Web 运费页 | web-admin/src/views/cell-storage/sample-freight/* |
| Web 公共取消弹窗 | web-admin/src/components/business/freight-unlink-dialog/(新建) |
| 小程序运费模块 | mobile-oa-h5/src/market/modules/freight.js、list-presenter.js、表单/详情视图 |
| 测试 | 按需补前端单测或手工验收清单;后端无契约变更则可不改 pytest |
9. 修订相对基线设计
相对 2026-10-07-sample-freight-batch-design.md §4.3–§4.4:
- 不再要求「配置运费」弹窗内直接修改已关联批次的方式与金额。
- 明确已关联样本必须先「取消运费」再配置;混合勾选跳过已配并提示。
- 取消交互升级为统一弹窗勾选(与运费信息页能力对齐并反哺协议单)。
本文档为本需求的权威交互说明;实现与评审以本文为准。