From f8b0e2de11fba96e440036484f0f61e35fba81fa Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Wed, 7 Oct 2026 12:01:24 +0800 Subject: [PATCH] docs: add unified protocol page design (shell + two tabs). Record the confirmed approach to merge donation protocols into the cell-storage protocol UI with dual tabs, dual routes, and hidden research-donation menus. Co-authored-by: Cursor --- .../2026-10-07-unified-protocol-design.md | 201 ++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 docs/superpowers/specs/2026-10-07-unified-protocol-design.md diff --git a/docs/superpowers/specs/2026-10-07-unified-protocol-design.md b/docs/superpowers/specs/2026-10-07-unified-protocol-design.md new file mode 100644 index 00000000..08d3dfed --- /dev/null +++ b/docs/superpowers/specs/2026-10-07-unified-protocol-design.md @@ -0,0 +1,201 @@ +# 统一协议单管理 — 实现设计（方案 1：壳页面 + 两个 Tab） + +> 日期：2026-10-07 +> 状态：已确认（2026-10-07） +> 关联：细胞存储「采集协议单」、科研捐赠「捐赠协议单」；交互对齐「统一样本信息管理」 + +--- + +## 1. 背景 + +现状协议单分两处入口： + +- **细胞存储 → 采集协议单**（`CellStorageProtocolAudit` / `protocol-audit`）：含审核、状态变更、转科研、缴费相关展示等。 +- **科研捐赠 → 捐赠协议单**（`ResearchDonationAudit` / `research-donation/audit`）：结构相近，无缴费；含知情同意书、转细胞存储。 + +两边均为独立库表与 API（2026-05-17 科研捐赠设计方案 C：独立业务 + 共享基础数据），表单与弹窗已部分复用公共组件。 + +产品希望**一个界面、两个来源 Tab**，日常从细胞存储进入；科研捐赠侧协议单菜单不再使用。近期「样本信息管理」已按双 Tab 壳页面统一，本需求对齐同一交互模式。 + +--- + +## 2. 目标与非目标 + +### 2.1 目标 + +- 一个协议单管理界面，顶部两个 Tab：**细胞存储** / **科研捐赠**。 +- 日常入口仅：**细胞存储 → 采集协议单**；默认打开「细胞存储」Tab。 +- 科研捐赠下「捐赠协议单」「捐赠协议单录入」侧栏全部隐藏；若无其它可见子项，一级「科研捐赠」一并隐藏。 +- 旧路由 `research-donation/audit` 仍可进入同一壳页面，并支持 `?tab=research_donation`。 +- 进页权限只认细胞存储「采集协议单」；能进页则两个 Tab 都可见。 +- 各 Tab 内业务（列表、新增/编辑、审核、状态变更、双向转化）保持现有能力，不砍功能。 + +### 2.2 非目标 + +- 不合并 `biz_collection_protocol*` 与 `biz_research_donation*`（及捐赠侧独立表）为单表。 +- 不新建「统一协议」聚合 API，不把两套协议混成一张物理列表。 +- 不重做表单字段，不改缴费 / 知情同意书 / 审核结论等业务规则。 +- 不改「样本信息管理」已落地的统一逻辑（仅协议单入口对齐同一壳 + Tab 模式）。 +- 不在本需求中调整科研捐赠「样本信息」菜单（已于 2026-10-06 单独隐藏）。 + +--- + +## 3. 菜单与路由 + +### 3.1 日常入口 + +| 菜单 | 路由 name | 路径 | 默认 Tab | +|------|-----------|------|----------| +| 细胞存储 → 采集协议单 | `CellStorageProtocolAudit` | `/market/cell-storage/protocol-audit` | `cell_storage` | + +菜单标题保持「采集协议单」，不改名。 + +### 3.2 双路由壳（对齐样本信息） + +| 路由 name | 路径 | 壳组件行为 | +|-----------|------|------------| +| `CellStorageProtocolAudit` | `…/protocol-audit` | `UnifiedProtocolPage`，`default-source=cell_storage` | +| `ResearchDonationAudit` | `…/research-donation/audit` | 同一 `UnifiedProtocolPage`，`default-source=research_donation` | + +- `query.tab` 取值：`cell_storage` | `research_donation`。 +- 切换 Tab 时写入 `query.tab`，与默认 source 一致时可规范化 URL。 +- 旧书签 / 外链进入科研捐赠 audit 仍落地统一页并打开捐赠 Tab。 +- 「捐赠协议单录入」`ResearchDonationList`（`…/list`）与细胞存储「采集协议单录入」`CellStorageProtocol`（`…/protocol`）路由可保留且 `isHide`；日常「新增」由各 Tab 内打开对应 FormDialog，不依赖侧栏录入菜单。 + +### 3.3 菜单隐藏 + +**前端固定菜单**（`VITE_ACCESS_MODE=frontend` 主路径）： + +- `web-admin/src/router/modules/sqxp.ts` +- `backend/app/api/menu.py` + +处理： + +1. 科研捐赠子项「捐赠协议单录入」「捐赠协议单」均隐藏（`meta.isHide: true`）。 +2. 若科研捐赠下无其它可见子菜单，一级「科研捐赠」一并隐藏（侧栏不出现空目录）。 +3. 路由 name / path 保留，保证旧链接与 programmatic `router.push` 可用。 + +**DB 菜单模式**（可选同步）：新增迁移脚本，例如 +`docs/sql/migrations/2026-10-07-hide-research-donation-protocol-menus.sql` + +对齐 `2026-10-06-hide-research-donation-sample-info-menu.sql`： + +- 将捐赠协议相关菜单 `visible = '0'`（id / perms / path+parent 条件）。 +- 若一级「科研捐赠」下无可见子项，同步隐藏一级目录。 +- 权限码可保留在库中；本页 Tab 可见性不依赖捐赠权限码。 +- 前端模式环境可不执行该脚本；注释中说明主路径为 `sqxp.ts` + `menu.py`。 + +细胞存储「采集协议单」保持可见。 + +--- + +## 4. 权限 + +### 4.1 前端进页 + +- 仅校验细胞存储采集协议单权限：`biz:cellStorageProtocolAudit:list`（以及该页既有按钮级权限：新增/审核/状态变更等，仍按细胞存储协议侧配置）。 +- **方案 B**：能进入页面 → 「细胞存储」「科研捐赠」两个 Tab **始终展示**，不按 `biz:researchDonation*` 裁剪 Tab。 + +### 4.2 后端 API + +- 当前采集协议与科研捐赠管理端 API 普遍使用 `require_admin_or_super_admin`，细粒度菜单码主要挡前端路由。 +- 实现时仍须冒烟确认：仅挂细胞存储协议菜单权限的账号，在捐赠 Tab 调用捐赠 list/detail/save/audit/status 接口**不出现 403**。 +- 若发现捐赠接口或中间件另有 `biz:researchDonation*` 校验：改为接受「持有细胞存储采集协议单对应权限」即可操作捐赠读写；或与产品确认后放宽为与 admin 门禁一致。不要求用户再单独挂捐赠菜单权限才能用捐赠 Tab。 +- 捐赠侧旧权限码可保留（兼容历史角色），本功能不依赖它们控制 Tab。 + +--- + +## 5. 页面结构与组件 + +### 5.1 统一壳 + +- 新建：`web-admin/src/views/cell-storage/protocol-audit/UnifiedProtocolPage.vue` +- 顶部：`panel-pill-tabs panel-pill-tabs--lg`（与统一样本信息一致） + - Tab 文案：`细胞存储` / `科研捐赠` + - `activeSource`：`cell_storage` | `research_donation` +- 两 Tab 始终可见（权限方案 B）。 +- 切换时更新 `route.query.tab`；建议仅激活当前 Tab 的列表请求（避免双 Tab 同时拉数）。 + +### 5.2 薄路由页 + +- `cell-storage/protocol-audit/index.vue` → + `` + （保留现有旧 `query.tab` 重定向：payment-info / storage-cert 等 → 缴费信息或样本信息，逻辑继续放在该薄页或壳内 `onMounted`，避免回归。） +- `research-donation/audit/index.vue` → 改为薄包装，引用同一壳，`default-source="research_donation"`。 + +### 5.3 Tab 内容 + +| Tab | 组件 | 说明 | +|-----|------|------| +| 细胞存储 | 现有 `ProtocolAuditTab.vue` | 筛选、列表/卡片、新增/编辑/审核/状态变更/转科研；尽量少改 | +| 科研捐赠 | 新建 `protocol-audit/DonationProtocolTab.vue` | 从现 `research-donation/audit/index.vue` 抽出列表主体；与壳同目录，便于统一页引用 | + +捐赠弹窗继续放在 `research-donation/list/`： + +- `DonationFormDialog` +- `DonationViewDialog` +- `DonationAuditDialog` +- `DonationStatusChangeDialog` + +细胞存储弹窗继续用 `protocol/` 下现有组件（`ProtocolFormDialog` 等）。 + +### 5.4 UI 约定 + +- 骨架：`page-container` → `panel` → pill tabs → 当前 Tab 的 filter / toolbar / list / pager。 +- 单面板主标题仍由菜单/页头体现「采集协议单」；筛选区不加「筛选条件」等重复标题。 +- 按钮带图标、操作列 `fixed="right"`、`label-position="top"`、无遮罩模糊等，沿用现页与 Fresh Mint 规范，不重做视觉。 + +--- + +## 6. 数据流 + +``` +UnifiedProtocolPage + ├─ tab=cell_storage → ProtocolAuditTab + │ → collection-protocol / audit APIs + └─ tab=research_donation → DonationProtocolTab + → research-donation APIs +``` + +- 壳页面不做列表聚合，不新建统一协议 API。 +- 「转科研 / 转细胞存储」仍在各自 Tab 工具栏与状态弹窗中。 +- `query.tab` 只控制展示，不参与后端筛选参数。 + +--- + +## 7. 实现清单（摘要） + +| 项 | 路径 / 动作 | +|----|-------------| +| 新建壳 | `protocol-audit/UnifiedProtocolPage.vue` | +| 抽出捐赠 Tab | `protocol-audit/DonationProtocolTab.vue` | +| 薄化路由页 | `protocol-audit/index.vue`、`research-donation/audit/index.vue` | +| 隐藏菜单 | `sqxp.ts`、`menu.py`；一级科研捐赠无可见子项则隐藏 | +| DB 迁移（可选） | `docs/sql/migrations/2026-10-07-hide-research-donation-protocol-menus.sql` | +| 权限冒烟 | 仅细胞存储协议权限账号操作捐赠 Tab | +| 图谱 | 前端改动后 `./scripts/update-graph.sh frontend`（或 all） | + +--- + +## 8. 测试要点 + +- 从「细胞存储 → 采集协议单」进入：默认细胞存储 Tab；可切换科研捐赠；两侧列表/新增/审核/状态变更冒烟通过。 +- 直开 `/#/market/research-donation/audit`（及 `?tab=research_donation`）：统一页 + 捐赠 Tab 激活。 +- 切换 Tab 时 URL `query.tab` 同步；刷新保持当前 Tab。 +- 侧栏无「科研捐赠」及「捐赠协议单 / 捐赠协议单录入」。 +- 细胞存储旧重定向（如 `protocol-audit?tab=storage-cert` → 样本信息）仍有效。 +- 仅有细胞存储协议权限的账号：两 Tab 可用，捐赠接口不 403。 +- 转科研 / 转细胞存储在各自 Tab 仍可用。 + +--- + +## 9. 已确认决策摘要 + +| 议题 | 结论 | +|------|------| +| 交互形态 | 方案 1：壳页面 + 两个 Tab | +| 侧栏 | 仅保留细胞存储「采集协议单」；隐藏捐赠协议单相关菜单及空的一级「科研捐赠」 | +| 旧链接 | 保留科研捐赠 audit 路由，进统一页，`?tab=research_donation` | +| Tab 权限 | 方案 B：只认细胞存储采集协议单权限，进页即两 Tab 都可见 | +| 数据模型 | 保持两套表与 API，不合并 | +| 视觉 demo | 不需要 HTML demo |