brapi-java/docs/dev/03-genotyping/02-sample.md

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。