fix:sample/plate 之前的开发

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

@@ -0,0 +1,56 @@
+# 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`。