Files
zkxw/docs/superpowers/specs/2026-05-17-research-donation-module-design.md
T
2026-05-18 16:21:38 +08:00

232 lines
8.5 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.
# 科研捐赠管理模块设计文档
> 日期: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. 联调测试