232 lines
8.5 KiB
Markdown
232 lines
8.5 KiB
Markdown
# 科研捐赠管理模块设计文档
|
||
|
||
> 日期: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. **知情同意书**(必传)— 红色 `*` 标注,提交时校验至少 1 份
|
||
2. **其他附件** — 可选
|
||
|
||
### 细胞存储端最小改动
|
||
|
||
- `ProtocolStatusChangeDialog.vue` 增加 `zky`(转科研)操作
|
||
- 列表页状态筛选增加「转科研」选项
|
||
- 不改表结构,不改现有 CRUD 逻辑
|
||
|
||
---
|
||
|
||
## 实施顺序建议
|
||
|
||
1. SQL 建表脚本 → `docs/sql/`
|
||
2. 后端 Model + Schema
|
||
3. 后端 CRUD(子资源 upsert、审核、状态机)
|
||
4. 后端 API 路由 + 注册
|
||
5. 提取前端公共组件(当事人/采集/样本)
|
||
6. 前端页面(列表 → 表单弹窗 → 查看弹窗 → 审核弹窗 → 状态变更)
|
||
7. 双向转化功能(转科研 + 转存储)
|
||
8. 联调测试
|