科研捐赠管理模块设计文档

日期：2026-05-17 方案：C — 独立业务 + 共享基础数据状态：已确认

背景与需求

客户现有「细胞存储管理」业务，现需新增「科研捐赠」业务。两者关系：

独立新建：科研捐赠可以直接创建
双向转化：细胞存储协议可「转科研」→ 科研捐赠；科研捐赠可「转存储」→ 细胞存储协议
核心区别：
1. 科研捐赠不收费（无缴费相关流程）
2. 科研捐赠必须上传知情同意书附件
相同部分：当事人信息、采集信息、样本信息、审核流程、状态生命周期

方案选型

方案	描述	结论
A. 完全复制+裁剪	Clone 细胞存储全部代码，删缴费/储存证书	代码重复严重
B. 共享表+类型区分	同一套表，用 business_type 区分	耦合高，维护难
C. 独立业务+共享基础数据	独立表和 CRUD，复用基础数据和前端组件	已选择

选择理由：符合项目现有模式（每业务独立路由/CRUD），风险最低，独立演进。

Section 1：数据库设计

新建表（6 张）

`biz_research_donation` — 主表

字段	类型	说明
`id`	VARCHAR(64) UUID	主键
`donation_no`	VARCHAR(64)	捐赠协议编号
`status`	VARCHAR(20)	状态：dsx/sxz/ygq/yzf/zckc
`donation_date`	DATE	捐赠日期
`source_type`	VARCHAR(20)	来源类型：`direct`（独立新建）/ `from_storage`（从存储转来）
`source_protocol_id`	VARCHAR(64)	来源协议 ID（from_storage 时填源细胞存储协议 ID）
`consent_form_urls`	TEXT	知情同意书附件 URL（逗号分隔，必填）
`attachment_urls`	TEXT	其他附件 URL（逗号分隔，可选）
`remark`	VARCHAR(500)	备注
`tenant_no`	VARCHAR(64)	租户编号
`order_num`	INT	排序号
`create_by`	VARCHAR(64)	创建人
`create_dept_id`	VARCHAR(64)	创建部门
`create_time`	DATETIME	创建时间
`update_by`	VARCHAR(64)	更新人
`update_time`	DATETIME	更新时间
`del_flag`	CHAR(1) DEFAULT '0'	删除标记

`biz_research_donation_audit` — 审核记录

结构与 biz_protocol_audit 一致：审核状态（shtg/shth）+ 备注 + 审核人 + 审核时间。

`biz_research_donation_party` — 当事人信息

结构与 biz_protocol_party_customer 一致：母亲/父亲/新生儿信息。

`biz_research_donation_collection` — 采集信息

结构与 biz_protocol_collection_info 一致：区域/医院/采集人/时间。

`biz_research_donation_sample` — 样本信息

参照 biz_protocol_sample，去掉金额/费用相关字段，保留：样本类型、编码、数量、储存年限。

`biz_research_donation_sample_transport` — 样本运输信息

结构与 biz_protocol_sample_transport 一致。

不新建的表

细胞存储表	原因
`biz_protocol_payment`	科研捐赠不收费
`biz_protocol_payment_detail`	科研捐赠不收费
`biz_protocol_storage_cert`	科研捐赠无储存证书

复用的基础数据表（不新建）

biz_customer — 客户主数据
biz_cell_sample_type — 样本类型
biz_collection_region / biz_collection_hospital — 采集区域/医院
biz_sample_code — 样本编码池
biz_attachment — 通用附件

状态生命周期

科研捐赠：dsx(待生效) → sxz(生效中) → ygq(已过期) / yzf(已作废) / zckc(转细胞存储)
细胞存储：dsx(待生效) → sxz(生效中) → ygq(已过期) / yzf(已作废) / zky(转科研)

双向转化机制

细胞存储 → 科研捐赠：细胞存储协议状态变为 zky，新建科研捐赠记录（source_type=from_storage, source_protocol_id=源协议ID）
科研捐赠 → 细胞存储：科研捐赠状态变为 zckc，新建细胞存储协议记录（缴费信息留空待补填），科研捐赠记录保留关联

Section 2：后端架构

文件结构

backend/app/
├── api/
│   ├── research_donation.py          # 新建：科研捐赠 API 路由
│   └── __init__.py                   # 注册新路由
├── crud/
│   └── research_donation.py          # 新建：科研捐赠 CRUD/业务逻辑
├── models/
│   └── models.py                     # 新增 6 个 Model 类
├── schemas/
│   └── research_donation.py          # 新建：Pydantic schemas
└── main.py                           # 注册新路由

API 路由

前缀：/web/admin/research-donations，tag "科研捐赠管理"

端点	方法	说明
`/`	GET	列表查询（分页、关键字、状态筛选）
`/`	POST	新建科研捐赠
`/{id}`	GET	详情（含所有子资源）
`/{id}`	PUT	更新
`/{id}`	DELETE	删除（软删除）
`/batch-delete`	POST	批量删除
`/audit/list`	GET	审核列表
`/audit/submit`	POST	提交审核（单个/批量）
`/status-change`	POST	状态变更（生效/过期/作废/转存储）
`/convert-from-storage`	POST	从细胞存储协议转化
`/convert-to-storage`	POST	转为细胞存储

CRUD 层

参照 collection_protocol.py 模式，简化（无缴费逻辑）：

子资源整体 upsert
审核逻辑（shtg/shth + remark）
状态机校验
转化逻辑（双向数据复制 + 关联）
租户隔离 + 数据权限过滤

Schemas

ResearchDonationCreate / ResearchDonationUpdate
ResearchDonationResponse / ResearchDonationListResponse
ResearchDonationAuditSubmit
ResearchDonationStatusChange
ConvertFromStorageRequest / ConvertToStorageRequest

代码复用策略

复用：基础数据查询函数、附件处理工具、字段命名转换工具
不复用：CRUD 代码（独立文件，避免耦合）

Section 3：前端结构

路由注册（`sqxp.ts`）

科研捐赠管理 (id: 6000...)
├── /research-donation/list          → 捐赠协议单管理
├── /research-donation/audit         → 捐赠协议审核

页面与组件

web-admin/src/
├── views/research-donation/
│   ├── list/
│   │   ├── index.vue                        # 列表页
│   │   ├── DonationFormDialog.vue           # 新增/编辑弹窗（5 Tab）
│   │   ├── DonationViewDialog.vue           # 查看详情弹窗
│   │   ├── DonationAuditDialog.vue          # 审核弹窗
│   │   └── DonationStatusChangeDialog.vue   # 状态变更弹窗（含转存储）
│   └── audit/
│       └── index.vue                        # 审核管理页
├── api/
│   └── research-donation.ts                 # API 模块
└── components/                              # 从细胞存储提取的公共组件
    ├── party-info/                          # 当事人信息（Form + View）
    ├── collection-info/                     # 采集信息（Form + View）
    └── sample-info/                         # 样本信息（Form + View，捐赠版去金额）

捐赠表单弹窗（5 个 Tab）

Tab	说明	来源
基本信息	协议编号、状态、日期、来源类型、备注	新写
当事人信息	母亲/父亲/新生儿	提取公共组件 `PartyInfoForm`
采集信息	区域/医院/采集人/时间	提取公共组件 `CollectionInfoForm`
样本信息	样本类型/编码/数量/储存年限（无金额）	提取公共组件 `SampleInfoForm`
附件	知情同意书（必传）+ 其他附件	新写

知情同意书上传

在「附件」Tab 中分两个区域：

知情同意书（必传）— 红色 * 标注，提交时校验至少 1 份
其他附件 — 可选

细胞存储端最小改动

ProtocolStatusChangeDialog.vue 增加 zky（转科研）操作
列表页状态筛选增加「转科研」选项
不改表结构，不改现有 CRUD 逻辑

实施顺序建议

SQL 建表脚本 → docs/sql/
后端 Model + Schema
后端 CRUD（子资源 upsert、审核、状态机）
后端 API 路由 + 注册
提取前端公共组件（当事人/采集/样本）
前端页面（列表 → 表单弹窗 → 查看弹窗 → 审核弹窗 → 状态变更）
双向转化功能（转科研 + 转存储）
联调测试

2026-05-17-research-donation-module-design.md 8.5 KB Historia Czysty