245 lines
10 KiB
Markdown
245 lines
10 KiB
Markdown
# 统一样本接收 — 支持科研捐赠来源
|
||
|
||
> 日期:2026-05-19
|
||
> 状态:待审核
|
||
> 关联:AGENTS.md(database-conventions、api-conventions、ui-conventions)
|
||
|
||
## 背景与目标
|
||
|
||
当前【样本接收】模块仅支持来自**细胞存储(采集协议单)**的样本。业务需要**科研捐赠(捐赠协议单)**的样本也走统一的样本接收流程,接收后自动生成质检工单。
|
||
|
||
**核心诉求**:
|
||
1. 样本接收页面统一展示两种来源的待接收/已接收样本,用类型标签区分
|
||
2. 完整展示运输信息(运输方式、快递公司、快递单号、预计到达时间、携带人等),方便接收人员核对
|
||
3. 科研捐赠样本接收后,同样触发质检工单创建
|
||
|
||
## 方案:现有表加字段 + 双路径查询
|
||
|
||
### 1. 数据库变更
|
||
|
||
在 `biz_sample_reception` 表新增 3 个字段:
|
||
|
||
```sql
|
||
-- docs/sql/sample_reception_add_donation_source.sql
|
||
|
||
ALTER TABLE biz_sample_reception
|
||
ADD COLUMN reception_source VARCHAR(20) NOT NULL DEFAULT 'cell_storage'
|
||
COMMENT '来源类型 cell_storage细胞存储 research_donation科研捐赠'
|
||
AFTER receive_attachments,
|
||
ADD COLUMN donation_sample_id VARCHAR(64) NULL
|
||
COMMENT '捐赠样本ID(biz_research_donation_sample.id, 仅科研捐赠来源)'
|
||
AFTER reception_source,
|
||
ADD COLUMN research_donation_id VARCHAR(64) NULL
|
||
COMMENT '科研捐赠单ID(biz_research_donation.id, 仅科研捐赠来源)'
|
||
AFTER donation_sample_id;
|
||
```
|
||
|
||
**约束规则**:
|
||
- `reception_source = 'cell_storage'`:`protocol_sample_id` + `collection_protocol_id` 必填,`donation_sample_id` = NULL
|
||
- `reception_source = 'research_donation'`:`donation_sample_id` + `research_donation_id` 必填,`protocol_sample_id` = NULL
|
||
- 现有数据 `reception_source` 默认 `'cell_storage'`,无迁移风险,无需数据回填
|
||
|
||
### 2. 后端 Model 变更
|
||
|
||
**文件**:`backend/app/models/models.py` — `BizSampleReception` 类
|
||
|
||
新增字段:
|
||
```python
|
||
reception_source = Column(String(20), nullable=False, default="cell_storage", comment="来源类型 cell_storage/research_donation")
|
||
donation_sample_id = Column(String(64), nullable=True, comment="捐赠样本ID(仅科研捐赠)")
|
||
research_donation_id = Column(String(64), nullable=True, comment="科研捐赠单ID(仅科研捐赠)")
|
||
```
|
||
|
||
### 3. 后端 CRUD 变更
|
||
|
||
**文件**:`backend/app/crud/sample_reception.py`
|
||
|
||
#### 3.1 新增捐赠样本查询函数
|
||
|
||
新增 `_donation_sample_detail_rows_query(db)` — 对应捐赠样本的四表 JOIN:
|
||
- `BizResearchDonationSample` + `BizResearchDonation` + `BizResearchDonationParty` + `BizResearchDonationSampleTransport`
|
||
|
||
新增 `_donation_sample_pending_query(db, tenant_no, keyword)` — 查询未被接收的捐赠样本:
|
||
- 排除条件:`BizSampleReception.donation_sample_id IN (已接收的捐赠样本ID)`
|
||
- 关键词搜索:`donation_no`、`sample_code`、`mother_name`、`newborn_name`
|
||
|
||
新增 `_donation_rows_to_sample_list_items(db, rows, tenant_no, ...)` — 将捐赠样本行转为统一列表项字典,字段映射:
|
||
```
|
||
protocolSampleId → donation_sample.id(注意:字段名保持 protocolSampleId 不变,前端统一使用)
|
||
protocolNo → donation.donation_no(协议号/捐赠编号)
|
||
sourceType → 'research_donation'
|
||
sourceTypeLabel → '科研捐赠'
|
||
```
|
||
|
||
#### 3.2 修改待接收列表函数
|
||
|
||
修改 `list_pending_protocol_samples()`:
|
||
- 分别查询细胞存储待接收样本和捐赠待接收样本
|
||
- 合并结果列表
|
||
- 按 eta_time 排序(统一排序)
|
||
- 手动分页(先合并再截取)
|
||
|
||
修改 `list_received_protocol_samples()`:
|
||
- 从 `BizSampleReception` 查询时,按 `reception_source` 分两组
|
||
- `cell_storage` 组走现有 `_sample_detail_rows_query` 逻辑(不变)
|
||
- `research_donation` 组走新增的捐赠查询逻辑
|
||
- 合并后按 `reception_time DESC` 排序
|
||
|
||
#### 3.3 修改创建接收记录函数
|
||
|
||
修改 `create_sample_reception()`:
|
||
- 新增参数:`reception_source: str = "cell_storage"`、`donation_sample_id: Optional[str] = None`、`research_donation_id: Optional[str] = None`
|
||
- 当 `reception_source = 'research_donation'` 时:
|
||
- 校验 `donation_sample_id` 对应的 `BizResearchDonationSample` 存在
|
||
- 校验该捐赠样本未被接收(查 `BizSampleReception.donation_sample_id`)
|
||
- `protocol_sample_id` 置为空字符串或 NULL
|
||
- `collection_protocol_id` 置为空字符串或 NULL
|
||
- 接收结论为 `js` 时,仍触发 `qc_wo_svc.create_work_order_from_reception()`
|
||
|
||
#### 3.4 统一列表项输出格式
|
||
|
||
两种来源的列表项保持统一字段名,前端无需区分:
|
||
|
||
| 字段名 | 细胞存储来源 | 科研捐赠来源 |
|
||
|--------|-------------|-------------|
|
||
| `protocolSampleId` | `biz_protocol_sample.id` | `biz_research_donation_sample.id` |
|
||
| `protocolNo` | 采集协议号 | 捐赠编号 |
|
||
| `sampleCode` | 样本编码 | 样本编码 |
|
||
| `sampleTypeName` | 样本类型名 | 样本类型名 |
|
||
| `motherName` | 母亲姓名 | 母亲姓名 |
|
||
| `newbornName` | 新生儿姓名 | 新生儿姓名 |
|
||
| `sourceType` | `cell_storage` | `research_donation` |
|
||
| `sourceTypeLabel` | 细胞存储 | 科研捐赠 |
|
||
| `etaTime` | 预计到达时间 | 预计到达时间 |
|
||
| `transportType` | 运输方式 | 运输方式 |
|
||
| `waybillNo` | 快递单号 | 快递单号 |
|
||
| `expressCompanyName` | 快递公司名 | 快递公司名 |
|
||
| `carrierName` | 携带人 | 携带人 |
|
||
| `carrierPhone` | 携带人电话 | 携带人电话 |
|
||
|
||
### 4. 后端 API 变更
|
||
|
||
**文件**:`backend/app/api/sample_reception.py`
|
||
|
||
#### 4.1 待接收列表增加来源筛选
|
||
|
||
`GET /web/admin/sample-receptions/pending` 新增可选参数:
|
||
- `sourceType`:`cell_storage` / `research_donation` / 不传(全部)
|
||
|
||
#### 4.2 创建接收记录支持捐赠来源
|
||
|
||
`SampleReceptionCreateBody` 新增字段:
|
||
```python
|
||
source_type: Optional[str] = Field("cell_storage", alias="sourceType") # cell_storage / research_donation
|
||
donation_sample_id: Optional[str] = Field(None, alias="donationSampleId") # 科研捐赠时必传
|
||
```
|
||
|
||
当 `source_type = 'research_donation'` 时,`protocolSampleId` 可不传,改为传 `donationSampleId`。
|
||
|
||
### 5. 前端变更
|
||
|
||
**文件**:`web-admin/src/views/quality-inspection/sample-reception/index.vue`
|
||
|
||
#### 5.1 搜索区增加来源类型筛选
|
||
|
||
在 `filter-grid` 中增加:
|
||
```html
|
||
<el-form-item label="来源类型">
|
||
<el-select v-model="searchForm.sourceType" placeholder="全部" clearable>
|
||
<el-option label="细胞存储" value="cell_storage" />
|
||
<el-option label="科研捐赠" value="research_donation" />
|
||
</el-select>
|
||
</el-form-item>
|
||
```
|
||
|
||
#### 5.2 表格新增"来源类型"列
|
||
|
||
在序号列后增加:
|
||
```html
|
||
<el-table-column prop="sourceTypeLabel" label="来源类型" width="100" align="center" header-align="center">
|
||
<template #default="{ row }">
|
||
<el-tag :type="row.sourceType === 'research_donation' ? 'warning' : 'success'" size="small">
|
||
{{ row.sourceTypeLabel }}
|
||
</el-tag>
|
||
</template>
|
||
</el-table-column>
|
||
```
|
||
|
||
#### 5.3 表格增加运输信息展示列
|
||
|
||
新增列(在快递单号之后):
|
||
- `transportType`:运输方式(快递运输 / 人员携带)
|
||
- `expressCompanyName`:快递公司
|
||
- `carrierName`:携带人
|
||
- `carrierPhone`:携带人电话
|
||
|
||
#### 5.4 接收弹窗展示完整运输信息
|
||
|
||
单个接收弹窗(`receiveDialogVisible`)和查看详情弹窗(`viewDialogVisible`)中,在"样本信息"区块后增加"运输信息"区块:
|
||
|
||
```
|
||
运输信息
|
||
运输方式:快递运输
|
||
快递公司:顺丰速运
|
||
快递单号:SF1234567890
|
||
预计到达:2026-05-20 14:00:00
|
||
携带人:张三 / 13800138000
|
||
```
|
||
|
||
使用 `readonly-grid form-grid-2` 布局,运输方式为"快递运输"时显示快递公司和快递单号,为"人员携带"时显示携带人和电话。
|
||
|
||
#### 5.5 批量接收弹窗同步调整
|
||
|
||
`batch-receive-card__meta` 区域增加来源类型标签和运输信息展示。
|
||
|
||
#### 5.6 提交参数调整
|
||
|
||
`fetchSampleReceptionSubmit` 调用时,增加 `sourceType` 和 `donationSampleId` 参数:
|
||
- 细胞存储样本:`sourceType: 'cell_storage'`,传 `protocolSampleId`
|
||
- 科研捐赠样本:`sourceType: 'research_donation'`,传 `donationSampleId`
|
||
|
||
**文件**:`web-admin/src/api/sample-reception.ts`
|
||
|
||
`fetchSampleReceptionSubmit` 参数类型增加:
|
||
```typescript
|
||
sourceType?: 'cell_storage' | 'research_donation'
|
||
donationSampleId?: string // sourceType=research_donation 时必传
|
||
```
|
||
|
||
`fetchSampleReceptionPendingList` 参数增加 `sourceType?: string`。
|
||
|
||
#### 5.7 row-key 兼容
|
||
|
||
当前 `row-key="protocolSampleId"`,捐赠样本也复用此字段名(后端统一输出),无需修改。
|
||
|
||
### 6. 变更范围汇总
|
||
|
||
| 层 | 文件 | 变更类型 |
|
||
|----|------|---------|
|
||
| SQL | `docs/sql/sample_reception_add_donation_source.sql`(新建) | ALTER TABLE |
|
||
| Model | `backend/app/models/models.py`(BizSampleReception) | 新增 3 字段 |
|
||
| CRUD | `backend/app/crud/sample_reception.py` | 新增捐赠查询函数 + 修改 pending/received/create |
|
||
| API | `backend/app/api/sample_reception.py` | 修改 schema + 路由参数 |
|
||
| 前端 API | `web-admin/src/api/sample-reception.ts` | 参数扩展 |
|
||
| 前端页面 | `web-admin/src/views/quality-inspection/sample-reception/index.vue` | UI 变更 |
|
||
|
||
**不涉及的文件**(零影响):
|
||
- 采集协议单 CRUD/API/前端
|
||
- 捐赠协议单 CRUD/API/前端
|
||
- 质检工单 CRUD(`create_work_order_from_reception` 已基于 reception 对象创建,无需改动)
|
||
|
||
### 7. 质检工单衔接
|
||
|
||
`create_work_order_from_reception()` 接收 `BizSampleReception` 对象。新增的捐赠接收记录走同一函数,内部通过 `reception.collection_protocol_id` 查询协议信息。对于捐赠来源,需确认该函数是否依赖 `collection_protocol_id` 非空。
|
||
|
||
如依赖,则需在质检工单创建逻辑中增加 `reception_source` 判断,对捐赠来源改为通过 `research_donation_id` 查询捐赠单信息作为工单的关联协议。**实施时需读取 `qc_work_order.py` 的 `create_work_order_from_reception` 函数确认并适配。**
|
||
|
||
## 设计决策记录
|
||
|
||
| 决策 | 选择 | 理由 |
|
||
|------|------|------|
|
||
| 统一表 vs 独立表 | 统一表加字段 | 用户要求统一入口,且现有细胞存储流程零改动 |
|
||
| 新增字段 vs 改用通用FK | 新增字段 | 不破坏现有数据引用,风险最低 |
|
||
| 质检工单触发 | 捐赠也触发 | 用户确认需求一致 |
|
||
| 前端字段名 | 保持 protocolSampleId 不变 | 后端统一输出,前端改动最小化 |
|