fix:sample/plate 之前的开发

2026-05-28 11:56:17 +08:00
parent fc36bc83e3
commit 8b65de36b8
367 changed files with 57752 additions and 947 deletions
--- a/docs/dev/03-genotyping/01-plate.md
+++ b/docs/dev/03-genotyping/01-plate.md
@@ -0,0 +1,48 @@
+# 03 Genotyping - plate 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 录入目标
+
+`plate` 表示样本板，是批量送检和测序前的样本组织单元。一个 plate 可以包含多个 `sample`，也可以关联 vendor submission。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `plate` |
+| Java 实体 | `PlateEntity` |
+| 前置依赖 | `program`、`trial`、`study`，可选 `plate_submission` |
+| 下游引用 | `sample` |
+| API | `/brapi/v2/plates` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | plate 主键 | 系统生成；导入时可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `plate_name` | 样本板名称 | 用户录入 | 建议必填，同一 study 下建议唯一 |
+| `plate_barcode` | 样本板条码 | 扫码/手填 | 建议唯一 |
+| `client_plate_db_id` | 客户侧 plate ID | 用户录入/导入 | 可选 |
+| `client_plate_barcode` | 客户侧 plate 条码 | 用户录入/导入 | 可选 |
+| `plate_format` | plate 规格，如 96/384 孔板 | 枚举选择 | 可选；与样本孔位校验联动 |
+| `sample_type` | plate 中样本类型 | 枚举选择 | 可选 |
+| `sample_submission_format` | 提交给 vendor 的样本板格式 | 枚举选择 | 可选 |
+| `status_time_stamp` | 状态时间 | 系统写入或导入 | 可选 |
+| `program_id` | 所属项目 | 项目选择器 | 可选；若填需存在 |
+| `trial_id` | 所属 trial | Trial 选择器 | 可选；若填需存在 |
+| `study_id` | 所属 study | Study 选择器 | 可选；若填需存在 |
+| `submission_id` | vendor plate submission | Vendor submission 选择器 | 可选 |
+
+## 页面与交互
+
+- Plate 列表页支持按 program、trial、study、barcode、plateName 查询。
+- 详情页展示 plate 基本信息和下属 sample 列表。
+- 新增 sample 时如果从 plate 详情进入，默认带出 `plate_id`。
+
+## 关键校验
+
+1. 如果录入 `program_id/trial_id/study_id`，需要校验 Core 上下文一致性。
+2. 如果使用 `plate_format`，样本 `plate_row/plate_column/well` 不能超出规格。
+3. 已有关联 `sample` 的 plate 删除前必须提示，通常只允许停用或先迁移样本。
--- a/docs/dev/03-genotyping/02-sample.md
+++ b/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`。
--- a/docs/dev/03-genotyping/03-reference_set.md
+++ b/docs/dev/03-genotyping/03-reference_set.md
@@ -0,0 +1,44 @@
+# 03 Genotyping - reference_set 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 录入目标
+
+`reference_set` 表示参考基因组集合，是 reference、variantset、variant 的参考侧上游。它可以关联来源 germplasm。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `reference_set` |
+| Java 实体 | `ReferenceSetEntity` |
+| 前置依赖 | 可选 `germplasm` |
+| 下游引用 | `reference`、`variantset`、`variant` |
+| API | `/brapi/v2/referencesets` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | reference set 主键 | 系统生成；导入时可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `reference_set_name` | 参考集合名称 | 用户录入 | 建议必填 |
+| `assemblypui` | assembly 永久标识 | 用户录入/导入 | 可选，建议唯一 |
+| `description` | 参考集合说明 | 多行文本 | 可选 |
+| `is_derived` | 是否派生参考 | 开关 | 可选 |
+| `md5checksum` | 校验值 | 文本 | 可选，格式提示 |
+| `sourceuri` | 来源 URI | URL 输入 | 可选，URL 格式校验 |
+| `species_ontology_term` | 物种本体 term | 文本/本体选择器 | 可选 |
+| `species_ontology_termuri` | 物种本体 URI | URL 输入 | 可选，URL 格式校验 |
+| `source_germplasm_id` | 来源 germplasm | Germplasm 选择器 | 可选，若填需存在 |
+
+## 页面与交互
+
+- 列表页展示 referenceSetName、assemblyPUI、species、sourceGermplasm、reference 数、variantset 数。
+- 详情页展示 reference、variantset、variant 入口。
+
+## 关键校验
+
+1. 删除 reference_set 前检查 `reference`、`variantset`、`variant` 引用。
+2. 若填写 `source_germplasm_id`，必须引用已存在 germplasm。
+3. md5 checksum 建议做格式提示，不强行阻断历史数据。
--- a/docs/dev/03-genotyping/04-reference.md
+++ b/docs/dev/03-genotyping/04-reference.md
@@ -0,0 +1,40 @@
+# 03 Genotyping - reference 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 录入目标
+
+`reference` 表示具体参考序列，例如 chromosome、contig 或 scaffold。它属于一个 `reference_set`，下游可以分页保存序列片段。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `reference` |
+| Java 实体 | `ReferenceEntity` |
+| 前置依赖 | `reference_set` |
+| 下游引用 | `reference_bases` |
+| API | `/brapi/v2/references` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | reference 主键 | 系统生成；导入时可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `reference_name` | 参考序列名称 | 用户录入 | 建议必填 |
+| `reference_set_id` | 所属 reference_set | ReferenceSet 选择器 | 必选，必须存在 |
+| `length` | 序列长度 | 数字输入/导入 | 可选，非负 |
+| `md5checksum` | 序列校验值 | 文本 | 可选 |
+| `source_divergence` | 与来源差异度 | 数字输入 | 可选 |
+
+## 页面与交互
+
+- Reference 列表页支持按 referenceSet、referenceName 查询。
+- Reference 详情页展示 reference_bases 分页和长度、checksum 信息。
+
+## 关键校验
+
+1. `reference_set_id` 必须存在。
+2. 删除 reference 前检查 `reference_bases`。
+3. 若维护 `reference_bases`，建议校验分页总长度与 `length` 的一致性。
--- a/docs/dev/03-genotyping/05-reference_bases.md
+++ b/docs/dev/03-genotyping/05-reference_bases.md
@@ -0,0 +1,37 @@
+# 03 Genotyping - reference_bases 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 录入目标
+
+`reference_bases` 保存 reference 的序列片段或分页内容。它是参考序列的明细表，通常通过导入或后端任务写入。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `reference_bases` |
+| Java 实体 | `ReferenceBasesPageEntity` |
+| 前置依赖 | `reference` |
+| 下游引用 | 无 |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | reference bases 主键 | 系统生成；导入时可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `reference_id` | 所属 reference | Reference 选择器/导入 | 必选，必须存在 |
+| `page_number` | 分页序号 | 数字输入/导入 | 同一 reference 内建议唯一 |
+| `bases` | 碱基序列片段 | 文本/文件导入 | 最大 2048 字符；建议仅允许 A/C/G/T/N 等字符 |
+
+## 页面与交互
+
+- 一般不单独提供复杂 CRUD，可在 Reference 详情页查看或导入。
+- 长序列建议走文件导入或异步任务，不建议手工逐页录入。
+
+## 关键校验
+
+1. `reference_id` 必须存在。
+2. `bases` 长度不能超过数据库字段限制。
+3. 同一 reference 下 `page_number` 不应重复。
--- a/docs/dev/03-genotyping/06-variantset.md
+++ b/docs/dev/03-genotyping/06-variantset.md
@@ -0,0 +1,39 @@
+# 03 Genotyping - variantset 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 录入目标
+
+`variantset` 表示一批 variant 的集合，通常对应一次测序、芯片、DArTSeq 或某个 study 下的位点集合。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `variantset` |
+| Java 实体 | `VariantSetEntity` |
+| 前置依赖 | `reference_set`、`study` |
+| 下游引用 | `variant`、`callset_variant_sets`、`variantset_analysis`、`variantset_format` |
+| API | `/brapi/v2/variantsets` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | variantset 主键 | 系统生成；导入时可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `variant_set_name` | 变异集合名称 | 用户录入/导入 | 建议必填 |
+| `reference_set_id` | 参考基因组集合 | ReferenceSet 选择器 | 建议必选，若填需存在 |
+| `study_id` | 所属 study | Study 选择器 | 可选，若填需存在 |
+
+## 页面与交互
+
+- VariantSet 列表页支持按 referenceSet、study、variantSetName 查询。
+- 详情页展示 variants、callsets、analysis、available formats。
+- 从 Study 工作台创建时默认带出 `study_id`。
+
+## 关键校验
+
+1. `reference_set_id` 与下属 `variant.reference_set_id` 应保持一致。
+2. 删除 variantset 前检查 `variant`、`callset_variant_sets`、`variantset_analysis`、`variantset_format`。
+3. 导入大型 variantset 时建议先建 variantset，再异步导入 variants 和 calls。
--- a/docs/dev/03-genotyping/07-variant.md
+++ b/docs/dev/03-genotyping/07-variant.md
@@ -0,0 +1,57 @@
+# 03 Genotyping - variant 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 录入目标
+
+`variant` 表示具体变异位点，例如 SNP、Indel 或结构变异。它是位点定义，不是某个样本的结果；样本上的 genotype 结果写入 `allele_call`。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `variant` |
+| Java 实体 | `VariantEntity` |
+| 前置依赖 | `reference_set`、`variantset` |
+| 下游引用 | `allele_call`、`marker_position` |
+| API | `/brapi/v2/variants` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | variant 主键 | 系统生成；导入时可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `variant_name` | 位点名称/marker 名称 | 用户录入/导入 | 建议必填 |
+| `variant_type` | 位点类型，如 SNP/INDEL/SV | 下拉/导入 | 可选，建议枚举 |
+| `reference_set_id` | 参考集合 | ReferenceSet 选择器 | 可选，若填需存在 |
+| `variant_set_id` | 所属 variantset | VariantSet 选择器 | 建议必选，若填需存在 |
+| `reference_bases` | 参考碱基 | 文本/导入 | 可选 |
+| `variant_start` | 起始位置 | 数字输入/导入 | 可选，非负 |
+| `variant_end` | 结束位置 | 数字输入/导入 | 可选，不能小于 start |
+| `svlen` | 结构变异长度 | 数字输入/导入 | 可选 |
+| `filters_applied` | 是否做过过滤 | 开关/导入 | 可选 |
+| `filters_passed` | 是否通过过滤 | 开关/导入 | 可选 |
+| `created` | 创建时间 | 系统写入/导入 | 可选 |
+| `updated` | 更新时间 | 系统写入/导入 | 可选 |
+
+## 附属集合字段
+
+| 附属表 | 内容 |
+| --- | --- |
+| `variant_entity_alternate_bases` | alternateBases 列表 |
+| `variant_entity_ciend` | CIEND 区间 |
+| `variant_entity_cipos` | CIPOS 区间 |
+| `variant_entity_filters_failed` | 未通过的 filter 列表 |
+
+## 页面与交互
+
+- Variant 列表页支持按 variantSet、referenceSet、variantName、variantType 查询。
+- 大批量位点建议通过文件导入，不建议普通表单逐条录入。
+- 详情页展示 allele_call 数量和 marker_position 入口。
+
+## 关键校验
+
+1. `variant` 是位点定义，不能把样本 genotype 写在本表。
+2. `variant_set_id` 和 `reference_set_id` 应与所属 variantset 保持一致。
+3. 删除 variant 前检查 `allele_call` 和 `marker_position` 引用。
--- a/docs/dev/03-genotyping/08-callset.md
+++ b/docs/dev/03-genotyping/08-callset.md
@@ -0,0 +1,40 @@
+# 03 Genotyping - callset 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 录入目标
+
+`callset` 表示某个 sample 的一组 genotype calls，通常对应一个样本在一个或多个 variantset 上的调用集合。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `callset` |
+| Java 实体 | `CallSetEntity` |
+| 前置依赖 | `sample` |
+| 下游引用 | `allele_call`、`callset_variant_sets` |
+| API | `/brapi/v2/callsets` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | callset 主键 | 系统生成；导入时可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `call_set_name` | 调用集合名称 | 用户录入/导入 | 建议必填，同一 sample 下建议唯一 |
+| `sample_id` | 所属 sample | Sample 选择器/导入 | 必选，必须存在 |
+| `created` | 创建时间 | 系统写入/导入 | 可选 |
+| `updated` | 更新时间 | 系统写入/导入 | 可选 |
+
+## 页面与交互
+
+- CallSet 列表页支持按 sample、variantSet、callSetName 查询。
+- 从 Sample 详情创建时默认带出 `sample_id`。
+- 需要通过 `callset_variant_sets` 绑定参与的 variantset。
+
+## 关键校验
+
+1. `sample_id` 必须存在。
+2. 删除 callset 前检查 `allele_call` 和 `callset_variant_sets`。
+3. 如果 callset 绑定多个 variantset，查询和导出时要明确当前 variantset 范围。
--- a/docs/dev/03-genotyping/09-allele_call.md
+++ b/docs/dev/03-genotyping/09-allele_call.md
@@ -0,0 +1,42 @@
+# 03 Genotyping - allele_call 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 录入目标
+
+`allele_call` 是最终 genotype 调用结果。业务上它就是 Call：一条记录表示某个 sample/callset 在某个 variant 上的 genotype、read depth、likelihood 等结果。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `allele_call` |
+| Java 实体 | `CallEntity` |
+| 前置依赖 | `callset`、`variant` |
+| 下游引用 | 无 |
+| API | `/brapi/v2/calls` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | call 主键 | 系统生成；导入时可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `call_set_id` | 所属 callset | CallSet 选择器/导入 | 必选，必须存在 |
+| `variant_id` | 对应 variant | Variant 选择器/导入 | 必选，必须存在 |
+| `genotype` | genotype 值，如 0/1、A/T | 文本/导入 | 建议必填 |
+| `read_depth` | 测序深度 | 数字输入/导入 | 可选，非负 |
+| `genotype_likelihood` | genotype likelihood | 数字输入/导入 | 可选 |
+| `phase_set` | phase set | 文本/导入 | 可选 |
+
+## 页面与交互
+
+- 通常不做逐条手工录入，主要通过 VCF/HapMap/矩阵文件导入。
+- 列表页支持按 callset、sample、variantset、variant 查询。
+- 在 Variant 详情页可查看该位点下的 calls，在 Sample/CallSet 详情页可查看该样本的 calls。
+
+## 关键校验
+
+1. `call_set_id` 和 `variant_id` 必须存在。
+2. 同一 callset 对同一 variant 不应重复。
+3. `allele_call` 不应直接承担 variant 定义字段；位点信息应来自 `variant`。
--- a/docs/dev/03-genotyping/10-genome_map.md
+++ b/docs/dev/03-genotyping/10-genome_map.md
@@ -0,0 +1,45 @@
+# 03 Genotyping - genome_map 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 录入目标
+
+`genome_map` 表示遗传图谱，用于组织 linkage group，并通过 marker_position 将 variant 放到图谱坐标上。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `genome_map` |
+| Java 实体 | `GenomeMapEntity` |
+| 前置依赖 | `crop`，可关联 `study` |
+| 下游引用 | `linkageGroup` / `linkage_group` |
+| API | `/brapi/v2/maps` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | map 主键 | 系统生成；导入时可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `map_name` | 图谱名称 | 用户录入 | 建议必填 |
+| `mappui` | map 永久标识 | 用户录入/导入 | 可选，建议唯一 |
+| `crop_id` | 所属作物 | Crop 选择器 | 可选，若填需存在 |
+| `scientific_name` | 学名 | 文本 | 可选 |
+| `type` | 图谱类型 | 下拉/文本 | 可选 |
+| `unit` | 图谱单位，如 cM | 文本/下拉 | 可选 |
+| `published_date` | 发表日期 | 日期选择器 | 可选 |
+| `documentationurl` | 文档链接 | URL 输入 | 可选，URL 格式校验 |
+| `comments` | 备注 | 多行文本 | 可选 |
+
+## 页面与交互
+
+- GenomeMap 列表页支持按 crop、mapName、type 查询。
+- 详情页展示 linkage groups 和 marker positions。
+- 可通过图谱详情批量导入 linkage group 与 marker position。
+
+## 关键校验
+
+1. 删除 genome_map 前检查 linkage group 引用。
+2. 若关联 study，应检查 study 的 crop 与 map 的 crop 一致。
+3. `unit` 应与 marker_position 的 position 语义保持一致。
--- a/docs/dev/03-genotyping/11-linkage_group.md
+++ b/docs/dev/03-genotyping/11-linkage_group.md
@@ -0,0 +1,42 @@
+# 03 Genotyping - linkageGroup / linkage_group 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 命名注意
+
+架构文档标注 `LinkageGroupEntity` 对应表名是驼峰 `linkageGroup`。当前初始 schema DDL 中实际表名为 `linkage_group`。做 Atlas/Flyway 迁移时，必须先确认目标数据库中的真实表名，避免生成大小写或命名不一致的重复表。
+
+## 录入目标
+
+连锁群是 genome_map 下的分组，例如 chromosome 或 linkage group。`marker_position` 会把 variant 放到具体 linkage group 的位置上。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| Java 实体 | `LinkageGroupEntity` |
+| 表 | 架构文档：`linkageGroup`；当前 DDL：`linkage_group` |
+| 前置依赖 | `genome_map` |
+| 下游引用 | `marker_position` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | linkage group 主键 | 系统生成；导入时可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `genome_map_id` | 所属 genome_map | GenomeMap 选择器 | 必选，必须存在 |
+| `linkage_group_name` | 连锁群名称 | 用户录入/导入 | 建议必填，同一 map 下唯一 |
+| `max_marker_position` | 最大 marker 位置 | 数字输入/导入 | 可选，非负 |
+
+## 页面与交互
+
+- 通常作为 GenomeMap 详情页的子表维护。
+- 支持批量导入 linkage group。
+- 详情页展示该 linkage group 下的 marker_position 列表。
+
+## 关键校验
+
+1. `genome_map_id` 必须存在。
+2. 同一 genome_map 下 `linkage_group_name` 不应重复。
+3. 删除 linkage group 前检查 `marker_position` 引用。
--- a/docs/dev/03-genotyping/12-marker_position.md
+++ b/docs/dev/03-genotyping/12-marker_position.md
@@ -0,0 +1,39 @@
+# 03 Genotyping - marker_position 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 录入目标
+
+`marker_position` 记录 marker/variant 在 linkage group 上的位置，是遗传图谱定位侧与 variant 位点侧的连接表。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `marker_position` |
+| Java 实体 | `MarkerPositionEntity` |
+| 前置依赖 | `linkageGroup` / `linkage_group`、`variant` |
+| 下游引用 | 无 |
+| API | `/brapi/v2/markerpositions` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | marker position 主键 | 系统生成；导入时可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `linkage_group_id` | 所属 linkage group | LinkageGroup 选择器/导入 | 必选，必须存在 |
+| `variant_id` | 对应 variant | Variant 选择器/导入 | 必选，必须存在 |
+| `position` | 图谱位置 | 数字输入/导入 | 必填，非负 |
+
+## 页面与交互
+
+- 可在 GenomeMap/LinkageGroup 详情页批量维护。
+- 列表页支持按 map、linkageGroup、variant 查询。
+- Variant 详情页可展示 marker_position 信息。
+
+## 关键校验
+
+1. `linkage_group_id` 和 `variant_id` 必须存在。
+2. 同一 linkage group 下同一 variant 不应重复。
+3. `position` 不应超过 linkage group 的 `max_marker_position`。
--- a/docs/dev/03-genotyping/13-callset_variant_sets.md
+++ b/docs/dev/03-genotyping/13-callset_variant_sets.md
@@ -0,0 +1,34 @@
+# 03 Genotyping - callset_variant_sets 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 录入目标
+
+`callset_variant_sets` 是 `callset` 与 `variantset` 的多对多关系表，表示某个样本调用集合覆盖了哪些 variantset。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `callset_variant_sets` |
+| 前置依赖 | `callset`、`variantset` |
+| 下游引用 | 查询、导出和 allele matrix 范围过滤 |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `call_sets_id` | callset 主键 | CallSet 选择器/导入 | 必选，必须存在 |
+| `variant_sets_id` | variantset 主键 | VariantSet 选择器/导入 | 必选，必须存在 |
+
+## 页面与交互
+
+- 通常在 CallSet 详情页或 VariantSet 详情页维护，不建议独立做主菜单。
+- 创建 callset 后可选择一个或多个 variantset。
+- 大批量导入 calls 时可以由导入任务自动创建关系。
+
+## 关键校验
+
+1. `call_sets_id` 和 `variant_sets_id` 必须存在。
+2. 同一 callset 与 variantset 关系不应重复。
+3. 删除关系不应删除 callset 或 variantset 主数据。
--- a/docs/dev/03-genotyping/14-variantset_analysis.md
+++ b/docs/dev/03-genotyping/14-variantset_analysis.md
@@ -0,0 +1,45 @@
+# 03 Genotyping - variantset_analysis 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 录入目标
+
+`variantset_analysis` 记录 variantset 的分析或 QC 信息，例如分析名称、软件、类型、描述和时间。它是 variantset 的附属明细表。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `variantset_analysis` |
+| Java 实体 | `VariantSetAnalysisEntity` |
+| 前置依赖 | `variantset` |
+| 下游引用 | 分析信息展示 |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | analysis 主键 | 系统生成；导入时可指定 | 必填、唯一 |
+| `variant_set_id` | 所属 variantset | VariantSet 选择器/导入 | 必选，必须存在 |
+| `analysis_name` | 分析名称 | 用户录入 | 建议必填 |
+| `description` | 分析说明 | 多行文本 | 可选 |
+| `type` | 分析类型，如 QC | 下拉/文本 | 可选 |
+| `created` | 创建时间 | 日期时间 | 可选 |
+| `updated` | 更新时间 | 日期时间 | 可选 |
+
+## 附属集合字段
+
+| 附属表 | 内容 |
+| --- | --- |
+| `variant_set_analysis_entity_software` | software 列表，如软件名称、版本或 URL |
+
+## 页面与交互
+
+- 在 VariantSet 详情页以 Analysis Tab 维护。
+- 支持添加多条分析记录，每条可维护多个 software。
+
+## 关键校验
+
+1. `variant_set_id` 必须存在。
+2. 删除 variantset 时需要先处理或级联处理 analysis。
+3. `software` 如果是 URL，前端可做 URL 格式提示。
--- a/docs/dev/03-genotyping/15-variantset_format.md
+++ b/docs/dev/03-genotyping/15-variantset_format.md
@@ -0,0 +1,42 @@
+# 03 Genotyping - variantset_format 表录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+## 录入目标
+
+`variantset_format` 记录 variantset 可用的数据格式和文件地址，例如 allele matrix、VCF、HapMap 或 CSV。它用于下载、导出和矩阵读取。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `variantset_format` |
+| Java 实体 | `VariantSetAvailableFormatEntity` |
+| 前置依赖 | `variantset` |
+| 下游引用 | 文件下载、allele matrix 展示、导出 |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | format 主键 | 系统生成；导入时可指定 | 必填、唯一 |
+| `variant_set_id` | 所属 variantset | VariantSet 选择器/导入 | 必选，必须存在 |
+| `data_format` | 数据格式，如 VCF/HapMap/矩阵 | 枚举选择 | 建议必填 |
+| `file_format` | MIME/文件格式 | 枚举选择 | 建议必填 |
+| `fileurl` | 文件 URL | URL 输入/导入 | 可选，URL 格式校验 |
+| `expand_homozygotes` | 是否展开纯合位点 | 开关 | 可选 |
+| `sep_phased` | phased genotype 分隔符 | 文本 | 可选 |
+| `sep_unphased` | unphased genotype 分隔符 | 文本 | 可选 |
+| `unknown_string` | 缺失值字符串 | 文本 | 可选 |
+
+## 页面与交互
+
+- 在 VariantSet 详情页以 Formats Tab 维护。
+- 支持一组 variantset 配置多个可下载格式。
+- 点击 `fileurl` 可下载或预览，对 allele matrix URL 可进入矩阵查看。
+
+## 关键校验
+
+1. `variant_set_id` 必须存在。
+2. `fileurl` 如填写需通过 URL 格式校验。
+3. 对矩阵格式，`sep_phased/sep_unphased/unknown_string` 会影响解析，应在导入预览时展示。
--- a/docs/dev/03-genotyping/README.md
+++ b/docs/dev/03-genotyping/README.md
@@ -0,0 +1,45 @@
+# 03 Genotyping 开发录入说明
+
+来源：`docs/architecture/03-genotyping-data-flow.md`
+
+本目录按 Genotyping 模块的数据录入顺序拆分开发说明。主线是：
+
+```text
+Core/Phenotyping 上游数据 -> plate / sample
+reference_set -> reference -> reference_bases
+reference_set + study -> variantset -> variant
+sample -> callset
+callset + variantset -> callset_variant_sets
+callset + variant -> allele_call
+genome_map -> linkageGroup/linkage_group -> marker_position -> variant
+```
+
+## 文档清单
+
+| 顺序 | 文档 | 表 | 作用 |
+| --- | --- | --- | --- |
+| 01 | `01-plate.md` | `plate` | 样本板 |
+| 02 | `02-sample.md` | `sample` | 送检样本/测序样本 |
+| 03 | `03-reference_set.md` | `reference_set` | 参考基因组集合 |
+| 04 | `04-reference.md` | `reference` | 参考序列 |
+| 05 | `05-reference_bases.md` | `reference_bases` | 参考序列片段/分页 |
+| 06 | `06-variantset.md` | `variantset` | 变异集合 |
+| 07 | `07-variant.md` | `variant` | 变异位点 |
+| 08 | `08-callset.md` | `callset` | 样本调用集合 |
+| 09 | `09-allele_call.md` | `allele_call` | genotype 调用结果 |
+| 10 | `10-genome_map.md` | `genome_map` | 遗传图谱 |
+| 11 | `11-linkage_group.md` | `linkageGroup` / `linkage_group` | 连锁群 |
+| 12 | `12-marker_position.md` | `marker_position` | marker/variant 图谱位置 |
+| 13 | `13-callset_variant_sets.md` | `callset_variant_sets` | callset 与 variantset 关系 |
+| 14 | `14-variantset_analysis.md` | `variantset_analysis` | variantset 分析信息 |
+| 15 | `15-variantset_format.md` | `variantset_format` | variantset 可用文件/矩阵格式 |
+
+## 全局注意点
+
+1. `CallEntity` 对应真实业务表是 `allele_call`，不要新建 `call` 表。
+2. `CallSetEntity` 对应 `callset`，不是 `call_set`。
+3. `VariantSetEntity` 对应 `variantset`，不是 `variant_set`。
+4. 架构文档标注 `LinkageGroupEntity` 的表名为 `linkageGroup`；当前初始 DDL 中表名为 `linkage_group`。做迁移前必须以实际数据库 catalog 为准。
+5. `sample` 是 Genotyping 样本入口，向上关联 `plate/observation_unit/study/trial/program`。
+6. `variant` 是位点定义，`allele_call` 是某个样本/callset 在位点上的结果。
+7. `reference_set/reference/reference_bases` 是参考基因组侧；`variantset/variant/callset/allele_call` 是变异和结果侧。