Files
zkxw/docs/superpowers/specs/2026-10-07-unified-protocol-design.md
T
zlwuandCursor f8b0e2de11 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>
2026-10-07 12:01:24 +08:00

202 lines
9.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 统一协议单管理 — 实现设计(方案 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 |