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 <cursoragent@cursor.com>

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` →  
+  `<UnifiedProtocolPage default-source="cell_storage" />`  
+  （保留现有旧 `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 |