docs: add implementation plan for unified protocol page.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed 2026-10-07 12:06:18 +08:00
1 parent f8b0e2de11
commit f447db7681
1 file changed
+506
@@ -0,0 +1,506 @@
# 统一协议单管理 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 细胞存储「采集协议单」与科研捐赠「捐赠协议单」共用一个壳页面(两个来源 Tab),日常只从细胞存储进入;科研捐赠侧协议单菜单(含一级空目录)隐藏,旧 audit 路由仍可进统一页。
**Architecture:** 对齐统一样本信息:`UnifiedProtocolPage` 用 `panel-pill-tabs` 切换来源;细胞存储 Tab 复用现有 `ProtocolAuditTab`;科研捐赠 Tab 从 `research-donation/audit/index.vue` 抽出为 `DonationProtocolTab`。两套 API/表不变。进页只认细胞存储采集协议单权限,两 Tab 始终可见。`query.tab` = `cell_storage` | `research_donation`。
**Tech Stack:** Vue 3 + Element Plus + vue-router(hash)/ FastAPI 固定菜单 `menu.py` / MySQL `sys_menu` 可选迁移
**Design Doc:** `docs/superpowers/specs/2026-10-07-unified-protocol-design.md`
**Reuse:** `UnifiedSampleInfoPage.vue` 的 pill tabs + `query.tab` 写法;`ProtocolAuditTab.vue` 的 Tab 根结构;`ClinicalApplication` 父级 `meta.isHide: true` 隐藏空一级菜单的先例。
---
## File Structure Map
### New files
| File | Responsibility |
|------|----------------|
| `web-admin/src/views/cell-storage/protocol-audit/UnifiedProtocolPage.vue` | 双 Tab 壳;切换写 `query.tab`;按来源挂载子 Tab |
| `web-admin/src/views/cell-storage/protocol-audit/DonationProtocolTab.vue` | 原捐赠协议单列表/工具栏/弹窗逻辑(自 audit 页抽出) |
| `docs/sql/migrations/2026-10-07-hide-research-donation-protocol-menus.sql` | DB 菜单模式:隐藏捐赠协议相关菜单与空一级目录 |
### Modified files
| File | Change |
|------|--------|
| `web-admin/src/views/cell-storage/protocol-audit/index.vue` | 挂载 `UnifiedProtocolPage`;保留旧 `query.tab` 重定向 |
| `web-admin/src/views/research-donation/audit/index.vue` | 薄包装 → 同一壳,`default-source=research_donation` |
| `web-admin/src/router/modules/sqxp.ts` | 捐赠 list/audit `isHide: true`;一级 `ResearchDonation` `isHide: true` |
| `backend/app/api/menu.py` | 与 `sqxp.ts` 同步隐藏 |
### Unchanged (explicit)
- `ProtocolAuditTab.vue`、捐赠/采集 Form/View/Audit/Status 弹窗、两端 API CRUD、库表
- 隐藏录入路由 `CellStorageProtocol` / `ResearchDonationList` 仍保留可直开
- 样本信息统一页逻辑不改
---
### Task 1: 抽出 `DonationProtocolTab`
**Files:**
- Create: `web-admin/src/views/cell-storage/protocol-audit/DonationProtocolTab.vue`
- Modify: (本 Task 不改路由页;audit 薄化在 Task 3)
- [ ] **Step 1: 复制并改造组件外壳**
从 `web-admin/src/views/research-donation/audit/index.vue` **整文件复制**到
`web-admin/src/views/cell-storage/protocol-audit/DonationProtocolTab.vue`,然后按下列规则改(不要改业务逻辑):
1. 去掉外层:
- `<div class="page-container">`
- `<section class="panel">` / `</section>`
2. 根节点改为(与 `ProtocolAuditTab` 对齐):
```vue
<!-- 采集协议单管理 · 科研捐赠 Tab -->
<!-- eslint-disable vue/no-v-model-argument -->
<template>
<div class="donation-protocol-tab">
<!-- 原 filter-block → list-body → dialogs,内容原样保留 -->
</div>
</template>
```
3. `defineOptions`:
```ts
defineOptions({ name: 'DonationProtocolTab' })
```
4. 弹窗 import 路径从相对 `../list/` 改为别名(因文件已迁到 `protocol-audit/`):
```ts
import DonationFormDialog from '@/views/research-donation/list/DonationFormDialog.vue'
import DonationViewDialog from '@/views/research-donation/list/DonationViewDialog.vue'
import DonationAuditDialog, {
type DonationAuditTarget
} from '@/views/research-donation/list/DonationAuditDialog.vue'
import DonationStatusChangeDialog, {
type DonationStatusChangeAction,
type DonationStatusChangeTarget
} from '@/views/research-donation/list/DonationStatusChangeDialog.vue'
```
其余 import(API、icons、`status-tag-registry`、`fullscreen-loading` 等)保持不变。
5. 原 `<style scoped>` 中卡片样式原样保留;不必新增页面级 `page-container` 样式。
- [ ] **Step 2: 本地确认无坏 import**
在 `web-admin/`:
```bash
pnpm exec vue-tsc --noEmit 2>&1 | head -80
```
Expected: 无 `DonationProtocolTab` 相关报错(若仓库原有无关 tsc 错误可忽略,但本文件路径解析须通过)。或用 IDE 打开该文件确认 import 全绿。
- [ ] **Step 3: Commit**
```bash
git add web-admin/src/views/cell-storage/protocol-audit/DonationProtocolTab.vue
git commit -m "$(cat <<'EOF'
refactor(web-admin): extract DonationProtocolTab from research-donation audit page.
EOF
)"
```
---
### Task 2: 新建 `UnifiedProtocolPage` 壳
**Files:**
- Create: `web-admin/src/views/cell-storage/protocol-audit/UnifiedProtocolPage.vue`
- [ ] **Step 1: 写入完整壳组件**
```vue
<template>
<div class="unified-protocol-page">
<div class="panel-pill-tabs panel-pill-tabs--lg">
<div class="panel-pill-tabs__track" role="tablist" aria-label="协议来源">
<button
v-for="item in tabs"
:key="item.key"
type="button"
role="tab"
class="panel-pill-tabs__btn"
:class="{ 'is-active': activeSource === item.key }"
:aria-selected="activeSource === item.key"
@click="switchSource(item.key)"
>
{{ item.title }}
</button>
</div>
</div>
<!-- v-if:仅挂载当前 Tab,避免双列表同时请求 -->
<ProtocolAuditTab v-if="activeSource === 'cell_storage'" />
<DonationProtocolTab v-else />
</div>
</template>
<script setup lang="ts">
import ProtocolAuditTab from './ProtocolAuditTab.vue'
import DonationProtocolTab from './DonationProtocolTab.vue'
defineOptions({ name: 'UnifiedProtocolPage' })
const props = defineProps<{
defaultSource: 'cell_storage' | 'research_donation'
}>()
type SourceKey = 'cell_storage' | 'research_donation'
const tabs: Array<{ key: SourceKey; title: string }> = [
{ key: 'cell_storage', title: '细胞存储' },
{ key: 'research_donation', title: '科研捐赠' }
]
const route = useRoute()
const router = useRouter()
const activeSource = ref<SourceKey>(props.defaultSource)
function switchSource(key: SourceKey) {
if (activeSource.value === key) return
activeSource.value = key
router.replace({ query: { ...route.query, tab: key } })
}
onMounted(() => {
const tab = String(route.query.tab || '')
if (tab === 'cell_storage' || tab === 'research_donation') {
activeSource.value = tab
return
}
activeSource.value = props.defaultSource
})
</script>
```
说明(与样本信息差异,按设计方案 B):
- **不**用 `useMenuPerm` 裁剪 Tab;两 Tab 写死始终展示。
- 旧 `payment-info` / `storage-cert` 等 query **不**在本组件处理(留给 Task 3 薄页重定向,避免与来源 tab 冲突)。
- [ ] **Step 2: 快速目视**
打开文件确认:pill tabs 类名与 `UnifiedSampleInfoPage` / `app.scss` 一致;`v-if` 分支正确。
- [ ] **Step 3: Commit**
```bash
git add web-admin/src/views/cell-storage/protocol-audit/UnifiedProtocolPage.vue
git commit -m "$(cat <<'EOF'
feat(web-admin): add UnifiedProtocolPage shell with cell-storage and research-donation tabs.
EOF
)"
```
---
### Task 3: 薄化双路由入口并保留旧重定向
**Files:**
- Modify: `web-admin/src/views/cell-storage/protocol-audit/index.vue`
- Modify: `web-admin/src/views/research-donation/audit/index.vue`
- [ ] **Step 1: 重写细胞存储 `protocol-audit/index.vue`**
完整替换为:
```vue
<template>
<div class="page-container">
<section class="panel">
<UnifiedProtocolPage v-if="showUnified" default-source="cell_storage" />
</section>
</div>
</template>
<script setup lang="ts">
import UnifiedProtocolPage from './UnifiedProtocolPage.vue'
defineOptions({ name: 'CellStorageProtocolAudit' })
const route = useRoute()
const router = useRouter()
const showUnified = ref(false)
onMounted(() => {
const tab = String(route.query.tab || '')
if (tab === 'payment-info') {
router.replace({
name: 'CellStoragePaymentInfo',
query: { ...route.query, tab: 'dfj' }
})
return
}
if (
['storage-cert', 'fullmoon-todo', 'sample-reception', 'storage-entry', 'sample-qc'].includes(
tab
)
) {
router.replace({
name: 'CellStorageSampleInfo',
query: { ...route.query, tab: 'cell_storage' }
})
return
}
showUnified.value = true
})
</script>
```
要点:先判旧 tab 再挂载统一页,避免闪一下错误 Tab。
- [ ] **Step 2: 重写科研捐赠 `audit/index.vue` 为薄包装**
完整替换为:
```vue
<template>
<div class="page-container">
<section class="panel">
<UnifiedProtocolPage default-source="research_donation" />
</section>
</div>
</template>
<script setup lang="ts">
import UnifiedProtocolPage from '@/views/cell-storage/protocol-audit/UnifiedProtocolPage.vue'
defineOptions({ name: 'ResearchDonationAudit' })
</script>
```
原 ~1000 行列表逻辑已在 `DonationProtocolTab`,本文件不得再保留一份副本。
- [ ] **Step 3: 手动冒烟(dev)**
```bash
cd web-admin && pnpm dev
```
浏览器验证:
1. `/#/market/cell-storage/protocol-audit` → 默认「细胞存储」Tab,列表与改前一致。
2. 点「科研捐赠」→ 捐赠列表出现;URL 含 `tab=research_donation`;刷新仍停在捐赠 Tab。
3. `/#/market/research-donation/audit` → 统一页 + 默认捐赠 Tab。
4. `/#/market/cell-storage/protocol-audit?tab=storage-cert` → 跳到样本信息(不卡在协议壳)。
- [ ] **Step 4: Commit**
```bash
git add \
web-admin/src/views/cell-storage/protocol-audit/index.vue \
web-admin/src/views/research-donation/audit/index.vue
git commit -m "$(cat <<'EOF'
feat(web-admin): wire protocol-audit and donation audit routes to UnifiedProtocolPage.
EOF
)"
```
---
### Task 4: 隐藏科研捐赠协议菜单(前端固定菜单)
**Files:**
- Modify: `web-admin/src/router/modules/sqxp.ts`(ResearchDonation 块,约 L182–219)
- Modify: `backend/app/api/menu.py`(科研捐赠块,约 L99–127)
- [ ] **Step 1: 改 `sqxp.ts`**
将一级与两个子项都设 `isHide: true`(路由保留)。对齐 `ClinicalApplication` 父级隐藏写法:
```ts
{
id: 'RSC00000000000000000000000000001',
name: 'ResearchDonation',
path: 'research-donation',
component: '',
meta: {
title: '科研捐赠',
icon: 'ri:hand-heart-line',
keepAlive: false,
isHide: true,
roles: ['admin']
},
children: [
{
id: '60000000000000000000000000000002',
name: 'ResearchDonationList',
path: 'list',
component: '/research-donation/list/index',
meta: {
title: '捐赠协议单录入',
keepAlive: true,
isHide: true,
menuCode: 'biz:researchDonation:list'
}
},
{
id: '60000000000000000000000000000003',
name: 'ResearchDonationAudit',
path: 'audit',
component: '/research-donation/audit/index',
meta: {
title: '捐赠协议单',
keepAlive: true,
isHide: true,
menuCode: 'biz:researchDonationAudit:list'
}
}
]
}
```
- [ ] **Step 2: 同步 `menu.py`**
同一结构:父级 `meta` 增加 `"isHide": True`;audit 子项补 `"isHide": True`(list 已有)。
- [ ] **Step 3: 验证侧栏**
刷新管理端:侧栏无「科研捐赠」;「细胞存储 → 采集协议单」仍在。直接访问 `/#/market/research-donation/audit` 仍可打开统一页。
- [ ] **Step 4: Commit**
```bash
git add web-admin/src/router/modules/sqxp.ts backend/app/api/menu.py
git commit -m "$(cat <<'EOF'
chore(menu): hide research-donation protocol menus; keep routes for unified page deep links.
EOF
)"
```
---
### Task 5: DB 菜单迁移脚本(可选同步)
**Files:**
- Create: `docs/sql/migrations/2026-10-07-hide-research-donation-protocol-menus.sql`
- [ ] **Step 1: 写入迁移**
```sql
-- =============================================================================
-- 下线「科研捐赠」协议单侧栏菜单(含一级空目录)(2026-10-07)
-- =============================================================================
--
-- 【主路径 — 前端固定菜单】
-- VITE_ACCESS_MODE=frontend 时已在以下文件隐藏:
-- - web-admin/src/router/modules/sqxp.ts
-- - backend/app/api/menu.py
-- 协议单从「细胞存储 → 采集协议单」进入(统一页含科研捐赠 Tab)。
-- 前端模式环境 **无需执行** 本脚本;保留供 DB 菜单模式同步。
--
-- 科研捐赠目录 parent_id / id: RSC00000000000000000000000000001
-- 捐赠协议单录入 id: 60000000000000000000000000000002
-- perms: biz:researchDonation:list
-- 捐赠协议单 id: 60000000000000000000000000000003
-- perms: biz:researchDonationAudit:list
-- visible: '0'=隐藏(权限码可保留;统一页不依赖捐赠菜单控 Tab)
-- =============================================================================
UPDATE sys_menu
SET visible = '0',
update_time = NOW()
WHERE del_flag = 0
AND (
id IN (
'RSC00000000000000000000000000001',
'60000000000000000000000000000002',
'60000000000000000000000000000003'
)
OR perms IN (
'biz:researchDonation:list',
'biz:researchDonationAudit:list'
)
OR (
parent_id = 'RSC00000000000000000000000000001'
AND path IN ('list', 'audit')
)
);
```
- [ ] **Step 2: Commit**
```bash
git add docs/sql/migrations/2026-10-07-hide-research-donation-protocol-menus.sql
git commit -m "$(cat <<'EOF'
docs(sql): add migration to hide research-donation protocol menus for DB menu mode.
EOF
)"
```
---
### Task 6: 权限冒烟、回归清单与图谱
**Files:**
- 无必须代码改动;若捐赠 API 出现细粒度 403,再改对应 `Depends`(当前 `research_donation` / `collection_protocol` 管理端为 `require_admin_or_super_admin`,预期无需改后端)。
- [ ] **Step 1: 权限冒烟**
用仅具备细胞存储「采集协议单」菜单权限的账号(或 admin):
1. 打开采集协议单 → 两 Tab 可见。
2. 捐赠 Tab:列表加载、打开查看、(若允许)新增弹窗能打开;Network 中捐赠 list 接口 **非 403**。
3. 若 403:在 `backend/app/api/research_donation.py` 查 `require_menu_code` / `require_any_menu_code`,按设计改为接受 `biz:cellStorageProtocolAudit:list`(或与 admin 门禁一致)。改完补测再单独 commit。
- [ ] **Step 2: 完整回归勾选**
- [ ] 细胞存储 Tab:筛选、新增、编辑、审核、生效/过期/作废、转科研、删除
- [ ] 科研捐赠 Tab:筛选、新增、编辑、审核、生效/过期/作废、转细胞存储、删除
- [ ] Tab 切换与刷新保持 `query.tab`
- [ ] 旧 `protocol-audit?tab=storage-cert`(及 payment-info / sample-*)重定向仍有效
- [ ] 侧栏无科研捐赠 / 捐赠协议单
- [ ] 直开 `research-donation/audit` 进统一页捐赠 Tab
- [ ] **Step 3: 更新前端图谱**
```bash
./scripts/update-graph.sh frontend
```
- [ ] **Step 4: Commit 图谱(若有 diff)**
```bash
git add web-admin/graphify-out/
git commit -m "$(cat <<'EOF'
chore(graphify): refresh frontend graph after unified protocol page.
EOF
)"
```
若 `graphify-out` 无变化可跳过本 commit。
---
## Spec coverage(自检)
| Spec 要求 | Task |
|-----------|------|
| 壳 + 两 Tab(细胞存储 / 科研捐赠) | Task 2 |
| 日常入口仅细胞存储采集协议单 | Task 3 + 4 |
| 隐藏捐赠协议单/录入;一级科研捐赠隐藏 | Task 4 + 5 |
| 旧 audit 路由 + `?tab=` | Task 2 + 3 |
| 进页只认细胞存储权限,两 Tab 都可见 | Task 2(不裁剪)+ Task 6 |
| 不合并表/API;业务能力保留 | Task 1 原样搬迁 |
| 旧 protocol-audit tab 重定向 | Task 3 |
| DB 迁移可选 | Task 5 |
| 图谱更新 | Task 6 |
无占位符 TBD;`DonationProtocolTab` 路径与设计一致;权限方案 B 与壳实现一致。