# 样本特殊标记与特殊说明

> 日期：2026-07-01  
> 状态：待审核  
> 关联：`2026-05-19-protocol-donation-convert-design.md`（捐赠转细胞存储样本复制）  
> 关联模块：采集协议单、捐赠协议单、样本信息、质检、生产、入库审核

---

## 1. 背景与目标

### 1.1 业务诉求

在**采集协议单**与**捐赠协议单**的样本信息中，增加「特殊样本」标记及「特殊说明」文本字段。例如样本为小三阳时：勾选特殊样本，特殊说明填写「小三阳」。

凡展示样本数据的界面，若该样本为特殊样本，须**醒目展示**：

- 红色加粗 **【特殊样本】**
- 红色加粗 **特殊说明** 内容

### 1.2 目标

1. 两种协议单的样本录入弹窗支持维护 `isSpecial` + `specialRemark`。
2. 勾选特殊样本时，特殊说明**必填**（已确认：选项 A）。
3. 所有 web-admin 展示样本数据的页面/弹窗/卡片，特殊样本信息只读展示，样式统一。
4. 捐赠转细胞存储时，特殊标记随样本复制到新 `biz_protocol_sample` 行。
5. 历史数据默认非特殊样本，兼容现有流程。

### 1.3 非目标（本期不做）

- 小程序端展示
- 按特殊样本筛选列表
- 导出 Excel 增加特殊说明列
- 下游业务表（接收、质检工单等）冗余存储特殊字段

---

## 2. 业务规则

### 2.1 字段语义

| 字段 | API 名 | 类型 | 说明 |
|------|--------|------|------|
| 特殊样本标记 | `isSpecial` | `boolean` | `true` 表示特殊样本 |
| 特殊说明 | `specialRemark` | `string` | 自由文本，如「小三阳」 |

与现有 `remark`（普通备注）**语义分离**：`remark` 为通用备注；`specialRemark` 为结构化警示说明，仅在 `isSpecial=true` 时有效。

### 2.2 校验规则（已确认）

| 条件 | 规则 |
|------|------|
| `isSpecial = true` | `specialRemark` **必填**，trim 后非空，最大 256 字符 |
| `isSpecial = false` | `specialRemark` 保存时**清空**为 `null` / 空字符串 |
| 未勾选却填写了说明 | 前端保存前清空；后端以 `isSpecial` 为准，忽略 `specialRemark` |

前后端均须校验；后端为最终门禁。

### 2.3 编辑与展示

- **可编辑**：采集/捐赠协议单新增、编辑样本（`SampleTransportFormSection` 子弹窗）。
- **只读展示**：协议查看弹窗、下游质检/生产/接收等所有样本展示位。
- **编辑时机**：协议单保存样本时一并持久化；下游模块通过 JOIN 源样本表读取最新值。

### 2.4 捐赠转细胞存储

`research_donation.py` 复制 `BizResearchDonationSample` → `BizProtocolSample` 时，须同步复制：

- `is_special` ← 源样本 `is_special`
- `special_remark` ← 源样本 `special_remark`

---

## 3. 数据模型

### 3.1 表结构变更

两张样本表**对称**增加字段（位于业务字段末尾、`tenant_no` 之前）：

**`biz_protocol_sample`**

```sql
ALTER TABLE `biz_protocol_sample`
  ADD COLUMN `is_special` tinyint(4) NOT NULL DEFAULT 0 COMMENT '是否特殊样本：0否 1是' AFTER `storage_expire_date`,
  ADD COLUMN `special_remark` varchar(256) DEFAULT NULL COMMENT '特殊说明' AFTER `is_special`;
```

**`biz_research_donation_sample`**

```sql
ALTER TABLE `biz_research_donation_sample`
  ADD COLUMN `is_special` tinyint(4) NOT NULL DEFAULT 0 COMMENT '是否特殊样本：0否 1是' AFTER `storage_expire_date`,
  ADD COLUMN `special_remark` varchar(256) DEFAULT NULL COMMENT '特殊说明' AFTER `is_special`;
```

同步更新 `docs/sql/zkxw.sql` 基线。

### 3.2 ORM

- `backend/app/models/models.py` → `BizProtocolSample`
- `backend/app/models/research_donation.py` → `BizResearchDonationSample`

### 3.3 API 字段（camelCase）

`_sample_to_dict` 统一输出：

```python
"isSpecial": bool(s.is_special),
"specialRemark": (s.special_remark or "").strip(),
```

`save_samples` 写入时：

- `is_special = 1 if raw.get("isSpecial") else 0`
- `special_remark` 仅在 `is_special=1` 时写入 trim 后文本，否则 `None`

---

## 4. 架构方案

### 4.1 选定方案：样本表唯一数据源 + 读取 JOIN

特殊标记仅存于 `biz_protocol_sample` / `biz_research_donation_sample`，下游模块在 list/detail API 中 JOIN 或复用已有样本查询补出 `isSpecial`、`specialRemark`。

**不**在 `biz_sample_reception`、`biz_qc_work_order` 等子表冗余。

### 4.2 后端改造模式

凡构建样本相关 dict 的位置，按 `_sample_to_dict` 模式补字段。重点文件：

| 文件 | 改动 |
|------|------|
| `crud/collection_protocol.py` | `_sample_to_dict`、`save_samples` |
| `crud/research_donation.py` | `_sample_to_dict`、`save_samples`、转存储复制 |
| `crud/protocol_sample_collection.py` | list item 构建 |
| `crud/research_donation_sample_collection.py` | list item 构建 |
| `crud/sample_reception.py` | 待接收/已接收/批量 list |
| `crud/qc_work_order.py` | 工单 list/detail 中样本信息 |
| `crud/production_work_order.py` | 同上 |
| `crud/storage_release_review.py` | 入库审核 list/detail |
| 转运前样本等相关 CRUD | 协议卡片内样本 list |

Pydantic Create/Update body 中 samples 数组项增加可选字段 `isSpecial`、`specialRemark`；后端 save 时校验。

运行 `python scripts/check_field_consistency.py` 验证 CRUD ↔ Schema ↔ 前端字段一致。

---

## 5. 前端设计

### 5.1 录入 UI — `SampleTransportFormSection`

**位置**：添加/编辑样本子弹窗，「样本状态」表单项之后。

**控件**：

1. `el-checkbox` — 标签「特殊样本」，绑定 `sampleDraft.isSpecial`
2. `el-input` type="textarea" — 标签「特殊说明」，`:disabled="!sampleDraft.isSpecial"`，`maxlength=256`，`show-word-limit`

**交互**：

- 取消勾选 → 清空 `specialRemark`
- 确定时：`isSpecial=true` 且 `specialRemark` 为空 → `ElMessage.warning` + 表单校验失败

**列表表格**：新增列「特殊样本」（`min-width` ≥ 120）：

- 非特殊：显示 `—`
- 特殊：inline 展示 `SpecialSampleDisplay` 组件内容

`createEmptySample()` / `sampleDraft` 初始化增加 `isSpecial: false`、`specialRemark: ''`。

采集协议单、捐赠协议单共用此组件，**改一处覆盖两种协议**。

### 5.2 展示 UI — 公共组件

新建 `web-admin/src/components/business/special-sample-display/index.vue`：

```vue
<!-- props: isSpecial, specialRemark, layout?: 'inline' | 'block' -->
<template v-if="isSpecial">
  <span class="special-sample-mark">【特殊样本】</span>
  <span v-if="specialRemark" class="special-sample-remark">{{ specialRemark }}</span>
</template>
```

样式（scoped + 可全局复用 class）：

```scss
.special-sample-mark,
.special-sample-remark {
  color: var(--el-color-danger);
  font-weight: 700;
}
.special-sample-remark {
  margin-left: 4px;
}
```

- **非特殊样本**：组件不渲染任何 DOM（不占位、不显示「—」）。
- **不使用 `el-tag`**：此为警示文本，非状态枚举。

### 5.3 查看弹窗

**`ProtocolViewDialog` / `DonationViewDialog`** 样本卡片：

- 卡片 header 标题行：样本类型名旁 inline 展示 `SpecialSampleDisplay`
- 样本信息 data-grid：独立一行「特殊说明」（仅 `isSpecial` 时显示，block 布局）

### 5.4 下游展示接入点（P1 全量）

| 模块 | 文件 |
|------|------|
| 协议管理 | `ProtocolAuditTab.vue`、`PreTransitProtocolCardList.vue` |
| 捐赠审核 | `research-donation/audit/index.vue` |
| 样本采集信息 | `SampleCollectionInfoTab.vue`、`DonationSampleCollectionInfoTab.vue` |
| 样本接收 | `sample-reception/index.vue`、`SampleReceptionCardList.vue` |
| 质检工单 | `QcWorkOrderProtocolGroup.vue`、`QcWorkOrderSampleGroup.vue`、`QcWorkOrderTaskSubList.vue` |
| 入库审核 | `storage-release-review/index.vue`、`StorageReleaseReviewDialog.vue`、`StorageReleaseViewDialog.vue` |
| 生产工单 | `ProductionWorkOrderCardList.vue`、`SampleReceptionDialog.vue`、`DispatchTaskDialog.vue` 等 |
| 溯源 | `SampleCustomerViewDialog.vue` |

**展示策略**：

1. 列表/卡片：**样本编码列或标题行**旁 inline 展示（最醒目）
2. 详情弹窗：样本编码下方或信息区独立一行
3. 统一使用 `SpecialSampleDisplay`，禁止各页复制样式

### 5.5 TypeScript 类型

`web-admin/src/types/api.d.ts` 中协议/捐赠样本相关类型补充 `isSpecial?: boolean`、`specialRemark?: string`。

---

## 6. 实施阶段

| 阶段 | 范围 | 交付标准 |
|------|------|----------|
| **P0** | DB + Model + 两协议 CRUD + 录入组件 + 两协议查看弹窗 | 可在协议单录入/查看特殊样本 |
| **P1** | 公共展示组件 + 下游全部展示点 + 转存储复制 | 质检/生产/接收等链路可见红色警示 |
| **P2**（可选） | 筛选、导出、小程序 | 产品另行排期 |

建议 P0、P1 **同一 PR 或连续 PR** 交付，避免下游看不到标记造成业务风险。

---

## 7. 测试要点

### 7.1 录入校验

- [ ] 勾选特殊样本、说明为空 → 前端拦截
- [ ] 勾选特殊样本、说明为空 → 后端 API 返回 422/400
- [ ] 未勾选、说明有值 → 保存后 `specialRemark` 为空
- [ ] 说明超 256 字 → 校验失败

### 7.2 持久化

- [ ] 采集协议单编辑保存后 detail 回显正确
- [ ] 捐赠协议单同上
- [ ] 历史样本（无新字段）→ `isSpecial=false`

### 7.3 展示

- [ ] 协议查看弹窗：红色加粗【特殊样本】+ 说明
- [ ] 非特殊样本：各页无多余占位
- [ ] 样本接收、质检工单、生产工单卡片可见特殊标记

### 7.4 转存储

- [ ] 捐赠单特殊样本转细胞存储后，新采集协议单样本保留 `isSpecial` + `specialRemark`

### 7.5 字段一致性

- [ ] `python scripts/check_field_consistency.py` 通过

---

## 8. 风险与约束

1. **双表对称**：采集与捐赠样本表、CRUD、UI 须同步改动，避免只改一侧。
2. **改动面大**：下游展示点 15+，须用公共组件收敛样式。
3. **与普通 remark 区分**：文档与 UI 文案明确，避免用户把特殊说明写入备注。
4. **警示色**：使用 Element Plus danger 色 + `font-weight: 700`，符合 Fresh Mint 规范中对强提醒的使用场景。

---

## 9. 决策记录

| 议题 | 决策 |
|------|------|
| 勾选特殊样本时特殊说明是否必填 | **A. 必填**（前后端校验） |
| 数据存储位置 | 样本源表唯一数据源，下游 JOIN |
| 展示组件 | 新建 `SpecialSampleDisplay`，红色加粗文本，非 Tag |
| 本期范围 | web-admin 全链路展示；不含筛选/导出/小程序 |