diff --git a/docs/demos/2026-10-08-sample-freight-menu-demo.html b/docs/demos/2026-10-08-sample-freight-menu-demo.html new file mode 100644 index 00000000..b349e81e --- /dev/null +++ b/docs/demos/2026-10-08-sample-freight-menu-demo.html @@ -0,0 +1,617 @@ + + + + + + 运费信息 · 列表 Demo（细胞存储） + + + + + + +
+ + +
+
+ 细胞存储 / 运费信息 + 静态 Demo · Fresh Mint +
+ +
+
+
+

运费信息

+

+ 一行逻辑对应一笔运费批次；左侧「运输方式 / 运费 / 关联数」合并单元格。 + 右侧按实际关联展示细胞存储与科研捐赠样本（一次专线车可混装）。 +

+
+ +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ +
+ 已选 0 项 + + + +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
运输方式运费(元)关联数来源协议单号样本编码样本类型创建时间操作
专线车¥800.003细胞存储CP20261008001ZK-UC-20261008-01脐带血2026-10-08 09:12:00 + + +
科研捐赠RD20261008012RD-PL-20261008-03胎盘
细胞存储CP20261008007ZK-UC-20261008-07脐带血
顺丰快递¥120.001细胞存储CP20261007022ZK-UC-20261007-22脐带血2026-10-07 16:40:11 + + +
同城闪送¥260.002科研捐赠RD20261006003RD-CB-20261006-01脐带2026-10-06 11:05:33 + + +
科研捐赠RD20261006003RD-CB-20261006-02脐带
专线车¥500.000— 暂无关联样本 —2026-10-05 18:20:00 + + +
+
+ +
+ 共 4 笔运费 · 6 条样本明细 + + 1 / 1 + +
+
+ +
+ Demo 说明： + 浅色竖条标题对齐 Fresh Mint；批次 A 展示「专线车一次拉 3 个样本（含细胞存储 + 科研捐赠）」的合并单元格效果。 + 正式实现走 Vue + Element Plus，文件路径： + docs/demos/2026-10-08-sample-freight-menu-demo.html +
+
+
+
+ +
+ +
+ + + + diff --git a/docs/superpowers/specs/2026-10-08-sample-freight-menu-design.md b/docs/superpowers/specs/2026-10-08-sample-freight-menu-design.md new file mode 100644 index 00000000..e16cc2d9 --- /dev/null +++ b/docs/superpowers/specs/2026-10-08-sample-freight-menu-design.md @@ -0,0 +1,197 @@ +# 运费信息菜单 — 实现设计 + +> 日期：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"`） +- **取消运费关联**（无勾选禁用） +- **编辑运费**（可选工具栏 + 行内编辑） + +按钮均带 ``。 + +### 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 性能 | 远程搜索 + 分页，禁止一次拉全表 |