# 运费信息菜单 — 实现设计

> 日期：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 已覆盖主路径。本需求增量：

1. **列表带 items**  
   `GET /web/admin/sample-freights` 增加查询参数 `includeItems=true`（默认 false 保持兼容）。  
   为 true 时每条返回 `items[]`：`sampleSource`、`sampleId`、`sampleCode`、`protocolId`、`protocolNo`（需联表协议号）、`sampleTypeName`（可选联表）。

2. **筛选增强**（同列表接口）  
   - `sampleSource`：`cell_storage` \| `research_donation`（有匹配 item 的批次）  
   - `keyword`：命中 `transport_mode` / 协议单号 / 样本编码  
   - 创建时间起止  

3. **样本待选列表**（供配置弹窗）  
   - 复用/轻量封装：细胞存储与科研捐赠样本检索 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. 验收标准

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

---

## 10. 实现顺序（建议）

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

---

## 11. 风险

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