zlwuandCursor
57d6241804
Document the cell-storage freight info menu with rowspan list, dual-source samples, and dual entry with protocol forms; include a static HTML preview. Co-authored-by: Cursor <cursoragent@cursor.com>
198 lines
7.7 KiB
Markdown
198 lines
7.7 KiB
Markdown
# 运费信息菜单 — 实现设计
|
||
|
||
> 日期：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 性能 | 远程搜索 + 分页，禁止一次拉全表 |
|