cykj/zkxw
1
0 Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity
Files
f8b0e2de11fba96e440036484f0f61e35fba81fa
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

9.7 KiB
Raw Blame History

统一协议单管理 — 实现设计（方案 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
Reference in new issue View Git Blame Copy Permalink