运费信息菜单 — 实现设计

日期：2026-10-08
状态：已确认（2026-10-08）
关联：docs/superpowers/specs/2026-10-07-sample-freight-batch-design.md（运费批次实体已落地）
Demo：docs/demos/2026-10-08-sample-freight-menu-demo.html

1. 背景

运费批次（biz_sample_freight / biz_sample_freight_item）与协议单内「配置运费」已实现。原设计将「独立运费中心」列为非目标。业务需要在细胞存储侧提供全局台账：一次专线车/快递常混装细胞存储 + 科研捐赠样本，需在一处查看与配置。

2. 已确认决策

项	结论
菜单位置	细胞存储 →「样本信息管理」下方 → 运费信息
协议单入口	两边保留：菜单管全局，协议单作快捷
列表粒度	一笔运费批次；样本多行展示，运费列合并单元格（rowspan）
样本来源	细胞存储 + 科研捐赠均可关联与展示
数据模型	不新建表；复用现有运费 API

3. 目标与非目标

3.1 目标

新增菜单与列表页：管理全部运费批次。
列表：运输方式 / 运费 / 关联数等批次字段合并单元格；右侧展示关联样本（来源、协议单号、样本编码、样本类型等）。
支持：配置运费（新建 / 关联已有）、取消运费关联、编辑运输方式与金额。
样本选择器支持混选细胞存储与科研捐赠样本。
协议单内现有配置运费能力保持不变，共用 API。

3.2 非目标

科研捐赠侧栏再挂一份「运费信息」菜单。
运费计入合同/缴费。
物流明细字段（单号、站点等）扩展。
旧运输数据迁移。
小程序端。

4. 菜单与路由

项	值
侧栏父级	细胞存储
标题	运费信息
顺序	紧挨「样本信息管理」之后
路由 path（建议）	`sample-freight`
组件	`/cell-storage/sample-freight/index`
权限码	`cell-storage:sample-freight:list`
Hash 示例	`/#/market/cell-storage/sample-freight`

web-admin/src/router/modules/sqxp.ts 增加路由。
SQL：docs/sql/migrations/2026-10-08-sample-freight-menu.sql 写入 sys_menu（及按需角色授权），order_num 排在样本信息管理之后。
App.vue panelTitleBarTextRules 注册「运费信息」完整标题（若需竖条）。

5. 列表 UI

对齐标准列表（筛选 → 工具栏 → 表格 → 分页）与 Fresh Mint；参考 Demo HTML。

5.1 筛选

运输方式（字典 sample_transport_mode）
来源：全部 / 仅细胞存储 / 仅科研捐赠（按关联 items 过滤批次）
协议单号 / 样本编码（关键字命中 items）
创建时间范围

5.2 工具栏

最前「已选 N 项」（按批次勾选，合并行共用一个 checkbox）
配置运费（唯一 type="primary"）
取消运费关联（无勾选禁用）
编辑运费（可选工具栏 + 行内编辑）

按钮均带 <el-icon>。

5.3 表格（合并单元格）

批次字段（rowspan）：运输方式、运费(元)、关联数、创建时间、操作（或操作仅行内按需）。

样本字段（每关联样本一行）：来源 Tag、协议单号、样本编码、样本类型。

无关联样本：样本列合并展示「—」，关联数 0；操作提供「关联样本」。
来源 Tag：细胞存储 / 科研捐赠（语义色 Tag）。
运输方式可用 el-tag。
列一律 min-width；操作列 fixed="right"，min-width ≥ 260px。
Element Plus el-table 用 span-method 实现 rowspan。

5.4 分页

按运费批次分页（不是按样本行）。页脚文案可附带「本页样本明细行数」提示。

6. 交互

6.1 配置运费

弹窗（dialog-form-layout，label-position="top"，无 backdrop blur）：

Tab：新建运费 | 关联已有
新建：运输方式（可搜索 + allow-create）+ 运费(元) + 样本多选 → POST /web/admin/sample-freights
关联已有：批次单选列表 + 样本多选 → POST /web/admin/sample-freights/{id}/link
样本选择：支持来源筛选、协议单号/样本编码检索；可混选两种来源

6.2 取消运费关联

工具栏：对勾选批次解绑其下全部 items，空批次软删；确认框提示。
行内「取消关联」：可弹出该批次 items 勾选后部分 unlink（POST .../unlink）。

6.3 编辑运费

PUT /web/admin/sample-freights/{id} 改运输方式/金额。
提示将同步所有关联样本的展示。

6.4 与协议单

协议单 SampleTransportFormSection 行为不变；两边写同一套后端接口。

7. 后端调整

现有 CRUD/API 已覆盖主路径。本需求增量：

列表带 items
GET /web/admin/sample-freights 增加查询参数 includeItems=true（默认 false 保持兼容）。
为 true 时每条返回 items[]：sampleSource、sampleId、sampleCode、protocolId、protocolNo（需联表协议号）、sampleTypeName（可选联表）。
筛选增强（同列表接口）
- sampleSource：cell_storage | research_donation（有匹配 item 的批次）
- keyword：命中 transport_mode / 协议单号 / 样本编码
- 创建时间起止
样本待选列表（供配置弹窗）
- 复用/轻量封装：细胞存储与科研捐赠样本检索 API（只读、租户 + 数据权限），或新增
  GET /web/admin/sample-freights/sample-options
  参数：sampleSource?、keyword、page、pageSize
  返回可挂运费的样本摘要（已挂其他运费的样本仍可选，link 时覆盖并提示）。

权限：菜单码 cell-storage:sample-freight:list；接口沿用 admin 鉴权，数据范围与协议样本一致。

8. 前端文件（建议）

文件	说明
`web-admin/src/views/cell-storage/sample-freight/index.vue`	列表页
`web-admin/src/views/cell-storage/sample-freight/FreightConfigDialog.vue`	配置运费弹窗（可抽公共，供协议单后续复用）
`web-admin/src/api/sample-freight.ts`	扩展 list 参数、`sample-options`
`web-admin/src/router/modules/sqxp.ts`	路由
`docs/sql/migrations/2026-10-08-sample-freight-menu.sql`	菜单

协议单组件可不在本迭代强制抽取公共弹窗；行为一致即可。

9. 验收标准

侧栏「细胞存储」下、样本信息管理下可见「运费信息」。
列表按批次分页；多样本时运输方式/运费/关联数合并单元格正确。
同一批次可同时展示细胞存储与科研捐赠样本。
本页可新建运费并混选两来源样本；可关联已有；可取消关联；可改方式/金额。
协议单内配置运费仍可用，与本页数据一致。
无权限用户不可见菜单（或接口 403）。
UI 符合 Fresh Mint / 按钮图标 / Tag / 表格列宽约定。

10. 实现顺序（建议）

菜单 SQL + 路由 + 空列表页骨架
后端 list includeItems + 筛选 + protocolNo/typeName enrichment；样本 options API
前端合并单元格表格 + 筛选分页
配置 / 取消 / 编辑弹窗对接 API
权限与手测（含跨来源一车多样本）
增量更新 graphify（web-admin，必要时 backend）

11. 风险

风险	对策
el-table span-method 与勾选/斑马纹	按批次生成扁平行 + `span-method`；勾选绑定 freightId
列表 items 过大	分页按批次；单批次 items 异常多时详情懒加载（首版可全带）
样本 options 性能	远程搜索 + 分页，禁止一次拉全表

2026-10-08-sample-freight-menu-design.md 7.7 KB История Директен файл