# 03 Genotyping - sample 表录入说明

来源：`docs/architecture/03-genotyping-data-flow.md`

## 录入目标

`sample` 是 Genotyping 流程的样本入口，表示送检样本或测序样本。它可以挂到 `plate`，也可以直接关联 `observation_unit`，并冗余保存 program/trial/study 方便查询。

## 上下游关系

| 类型 | 内容 |
| --- | --- |
| 表 | `sample` |
| Java 实体 | `SampleEntity` |
| 前置依赖 | `plate`、`observation_unit`、`program`、`trial`、`study`，可选 `germplasm_taxon` |
| 下游引用 | `callset` |
| API | `/brapi/v2/samples` |

## 字段录入

| 字段 | 业务意义 | 录入方式 | 校验规则 |
| --- | --- | --- | --- |
| `id` | sample 主键 | 系统生成；导入时可指定 | 必填、唯一 |
| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
| `sample_name` | 样本名称 | 用户录入/批量导入 | 建议必填 |
| `sample_barcode` | 样本条码 | 扫码/手填 | 建议唯一 |
| `samplepui` | 样本永久标识 | 用户录入/导入 | 可选，建议唯一 |
| `sample_description` | 样本说明 | 用户录入 | 可选 |
| `sample_type` | 样本类型 | 下拉/文本 | 可选 |
| `tissue_type` | 组织类型 | 下拉/文本 | 可选 |
| `sample_timestamp` | 取样时间 | 日期时间选择器 | 可选 |
| `taken_by` | 取样人 | 文本/人员选择 | 可选 |
| `sample_group_db_id` | 样本分组 ID | 文本/导入 | 可选 |
| `concentration` | 样本浓度 | 文本/数值 | 可选，建议带单位 |
| `volume` | 样本体积 | 文本/数值 | 可选，建议带单位 |
| `plate_id` | 所在样本板 | Plate 选择器 | 可选，若填需存在 |
| `plate_row` | 板行 | 文本 | 与 plate format 联动校验 |
| `plate_column` | 板列 | 数字输入 | 与 plate format 联动校验 |
| `well` | 孔位，如 A01 | 文本/自动生成 | 同一 plate 内建议唯一 |
| `observation_unit_id` | 对应观测单元 | ObservationUnit 选择器 | 可选，若填需存在 |
| `program_id` | 所属项目 | 项目选择器 | 可选，若填需存在 |
| `trial_id` | 所属 trial | Trial 选择器 | 可选，若填需存在 |
| `study_id` | 所属 study | Study 选择器 | 可选，若填需存在 |
| `taxon_id_id` | germplasm taxon | Taxon 选择器 | 可选 |

## 页面与交互

- Sample 列表页支持按 sampleName、barcode、plate、study、trial、program、observationUnit 查询。
- 从 Study 工作台创建 sample 时默认继承 `study_id/trial_id/program_id`。
- 从 ObservationUnit 详情创建 sample 时默认带出 `observation_unit_id`。

## 关键校验

1. `sample` 若关联 `observation_unit`，需要检查 observation unit 所属 study 与 sample 的 study 一致。
2. 同一 plate 内 `well` 不应重复。
3. 删除 sample 前必须检查是否已有 `callset`。