Files

2026-05-28 11:56:17 +08:00

50 KiB

Raw Permalink Blame History

Genotyping 模块专业数据录入需求文档 V2

1. 文档目的

本文档用于指导 Genotyping 基因型模块的前端页面、后端接口、字段校验、文件导入、矩阵展示和测试验收设计。本文档不只描述数据库表关系，而是从真实基因型检测业务出发，解释每个对象和字段的业务意义、录入方式、控件建议、校验规则和上下游影响。

2. 模块定位

Genotyping 模块描述从田间或实验对象取样，到实验室检测，再到导入基因型结果矩阵的完整流程。

它的核心业务不是“录 allele_call 表”，而是：

从哪个 study / observation_unit 取样
样本放在哪块 plate 的哪个 well
检测结果基于哪个 reference_set
结果文件包含哪些 variantset / variant
每个 sample 在每个 variant 上的 genotype 是什么
这些位点是否还映射到 genome_map / linkage_group

3. 核心业务主线

Genotyping 有三条主线：

样本线：study / observation_unit -> plate -> sample -> callset
位点线：reference_set -> reference -> reference_bases -> variantset -> variant
结果线：callset + variant -> allele_call
图谱线：crop -> genome_map -> linkage_group -> marker_position -> variant

3.1 样本线

样本线回答：

从哪个材料、哪个 plot、哪株植物或哪个样本来源取样？
样本叫什么？
谁采的？什么时候采的？
放在哪块样本板哪个孔？

对应核心表：

plate
sample
callset

3.2 位点线

位点线回答：

检测结果基于哪个参考基因组？
参考序列有哪些 chromosome / scaffold / contig？
检测了哪些 SNP / Indel / SV 位点？
这些位点属于哪个 variantset？

对应核心表：

reference_set
reference
reference_bases
variantset
variant

3.3 结果线

结果线回答：

某个 sample 在某个 variant 上的 genotype 是什么？
测序深度是多少？
是否 phased？
是否有 likelihood？

对应核心表：

callset
allele_call

3.4 图谱线

图谱线回答：

某个位点在遗传图谱或物理图谱上的位置是什么？
它属于哪个 linkage group / chromosome / scaffold？
单位是 cM 还是 Mb？

对应核心表：

genome_map
linkage_group
marker_position

4. 推荐业务流程

1. 准备 Core / Phenotyping 上游数据：crop、program、trial、study、observation_unit
2. 从 observation_unit 或 study 批量生成 sample
3. 创建 plate，并把 sample 分配到 well / row / column
4. 送检或接收实验室结果文件
5. 创建 reference_set，维护 reference / reference_bases
6. 创建 variantset，导入 variant
7. 为 sample 生成 callset
8. 绑定 callset 与 variantset
9. 导入 allele_call，形成 sample × variant 基因型矩阵
10. 如有遗传图谱，创建 genome_map / linkage_group / marker_position
11. 做结果质控：缺失率、重复位点、重复样本、read depth、genotype 格式、reference 一致性

5. 推荐页面形态

5.1 Genotyping 工作台

建议以 study 或 genotyping project 为入口组织页面：

Genotyping 工作台
├─ 样本管理：sample 列表、从 observation_unit 生成 sample
├─ 样本板：plate 列表、96/384 孔位布局
├─ 参考基因组：reference_set、reference、reference_bases
├─ 变异集合：variantset、variant、analysis、format
├─ 检测结果：callset、allele_call、genotype matrix
├─ 遗传图谱：genome_map、linkage_group、marker_position
├─ 导入导出：sample 模板、VCF/Hapmap/CSV、allele matrix
└─ 质控：缺失率、重复率、深度、位点过滤、样本过滤

5.2 Plate 孔位布局页

样本板不建议只做普通 CRUD，应提供 96 孔 / 384 孔布局视图：

Plate-96-001
     01          02          03          04
A  SAMPLE-001  SAMPLE-002  SAMPLE-003  SAMPLE-004
B  SAMPLE-013  SAMPLE-014  SAMPLE-015  SAMPLE-016
C  SAMPLE-025  SAMPLE-026  EMPTY       EMPTY
...

用户在孔位上放置 sample，系统保存：

sample.plate_id
sample.well
sample.plate_row
sample.plate_column

5.3 Genotype Matrix 结果页

allele_call 是基因型矩阵中的一个格子：

sample / callset	SNP001	SNP002	SNP003
SAMPLE-001	A/G	C/C	T/G
SAMPLE-002	A/A	C/T	T/T
SAMPLE-003	./ .	C/C	T/G

导入时：

样本列 / 样本行 -> sample / callset
位点列 / 位点行 -> variant
单元格 genotype -> allele_call.genotype

6. 字段级专业录入需求

6.1 plate 样本板

业务说明

plate 用于管理承载样本的样本板或样本容器组。真实业务里，它通常是一块 96 孔板、384 孔板，也可能是一组试管或实验室提交批次。plate 的核心价值是支持实验室送样、扫码、孔位追踪和结果回填。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	样本板主键，系统内部唯一标识	系统生成；导入可指定	隐藏/只读	必填、唯一；编辑不可修改
`auth_user_id`	数据所属用户或租户	登录上下文自动写入	隐藏	不允许前端手填
`client_plate_barcode`	客户侧或外部实验室给出的板条码	用户录入/扫码/导入	文本框/扫码框	可选；建议唯一
`client_plate_db_id`	客户侧系统中的 plate ID	用户录入/导入	文本框	可选；用于外部系统对接
`plate_barcode`	本系统样本板条码	系统生成/扫码录入	文本框/扫码框	可选；建议唯一
`plate_format`	样本板规格，如 96、384	用户选择	下拉框	可选；若填写，应限制为系统支持规格
`plate_name`	样本板名称，如 Plate-2026-001	用户录入/系统生成	文本框	与 barcode 至少一个必填
`sample_submission_format`	样本提交格式，如 DNA、tissue、seed、tube、plate	用户选择	下拉框	可选；建议枚举化
`sample_type`	该板默认样本类型	用户选择	下拉框	可选；可作为 sample 默认值
`status_time_stamp`	样本板状态更新时间	系统自动写入	只读日期时间	可选；状态变化时自动更新
`program_id`	所属项目	从 program 选择或由 study 带出	项目选择器/只读	可选；若 study 已选，应与 study.program 一致
`study_id`	所属 study	从 study 选择	Study 选择器	可选；若选择则带出 trial/program
`submission_id`	外部 vendor submission 或送检单 ID	用户录入/选择	选择器/文本框	可选；用于实验室送检对接
`trial_id`	所属 trial	从 trial 选择或由 study 带出	Trial 选择器/只读	可选；若 study 已选，应与 study.trial 一致

录入建议

创建 plate 时，用户先选择 plate_format，系统生成孔位矩阵。
如果从 study 工作台创建，program_id、trial_id、study_id 自动带出。
如果通过实验室返回文件创建，应优先用 plate_barcode 或 client_plate_barcode 匹配。

验收标准

plate_name 和 plate_barcode 至少填写一个。
同一系统中 plate_barcode 不应重复。
选择 study 后，trial/program 自动带出且保持一致。
plate_format 为 96 时，只允许 A01-H12；384 时只允许 A01-P24。

6.2 sample 样本

业务说明

sample 是 genotyping 流程的样本入口，表示从田间、温室、实验室或库存材料中取出的一个物理生物样本，例如叶片、种子、DNA、组织、提取液等。sample 应尽可能关联 observation_unit，这样才能把表型和基因型打通。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	样本主键，系统内部唯一标识	系统生成；导入可指定	隐藏/只读	必填、唯一
`auth_user_id`	数据所属用户或租户	登录上下文自动写入	隐藏	不允许手填
`concentration`	样本浓度，如 DNA 浓度 50 ng/µL	用户录入/仪器导入	数字+单位输入	可选；建议拆分数值和单位，当前字段可暂存文本
`plate_column`	样本在 plate 中的列号	孔位选择自动生成	数字输入/孔位控件	绑定 plate 时必填或由 well 解析；范围受 plate_format 限制
`plate_row`	样本在 plate 中的行号	孔位选择自动生成	下拉/孔位控件	绑定 plate 时必填或由 well 解析；范围受 plate_format 限制
`sample_barcode`	样本条码	扫码/系统生成/导入	文本框/扫码框	可选；建议唯一
`sample_description`	样本说明	用户录入	多行文本	可选
`sample_group_db_id`	样本组 ID，用于批次、送检组或处理组	用户选择/导入	选择器/文本框	可选
`sample_name`	样本名称，如 SAMPLE-001	用户录入/系统生成	文本框	必填；同一 study 下建议唯一
`samplepui`	样本永久唯一标识	用户录入/系统生成	文本框/URL 输入框	可选；若填写建议唯一
`sample_timestamp`	采样时间	用户录入/设备带出	日期时间选择器	可选；建议必填
`sample_type`	样本类型，如 tissue、DNA、seed、leaf	用户选择	下拉框	可选；建议枚举化
`taken_by`	采样人	用户选择/登录用户带出	人员选择器/文本框	可选
`tissue_type`	组织类型，如 leaf、root、grain、stem	用户选择/录入	下拉框/文本框	可选；样本为组织时建议填写
`volume`	样本体积，如 50 µL	用户录入/仪器导入	数字+单位输入	可选；当前字段可暂存文本
`well`	孔位，如 A01、H12	孔位布局选择	孔位选择器	绑定 plate 时建议必填；同一 plate 内唯一
`observation_unit_id`	来源观测单元	从 observation_unit 选择或批量生成带出	ObservationUnit 选择器	可选但强烈建议填写；必须存在
`plate_id`	所属样本板	从 plate 选择	Plate 选择器	可选；若填写需校验孔位唯一
`program_id`	项目上下文	由 observation_unit/study 带出	只读/隐藏	可选但建议保存；需与 study 一致
`study_id`	所属 study	由 observation_unit 带出	Study 选择器/只读	可选但建议保存；若有 observation_unit 必须一致
`taxon_id_id`	分类单元 ID	从 taxon 选择	Taxon 选择器	可选
`trial_id`	所属 trial	由 observation_unit/study 带出	Trial 选择器/只读	可选但建议保存

录入建议

推荐从 observation_unit 批量生成 sample：一行 observation_unit 生成一个或多个 sample。
如果样本放入 plate，应通过孔位布局页设置 well，不建议手填 A01。
well、plate_row、plate_column 应保持一致：well=A01，则 row=A，column=1。
sample 是物理样本，不是 genotype 结果；结果必须进入 callset / allele_call。

验收标准

sample_name 必填。
同一 plate 中 well 不允许重复。
绑定 observation_unit 时，study/trial/program 自动带出。
绑定 plate 时，well 必须符合 plate_format。
样本已有 callset 时，不允许物理删除。

6.3 reference_set 参考集

业务说明

reference_set 表示一个参考基因组集合，也就是一套 reference genome assembly。它定义 variant 坐标体系。不同参考基因组版本之间的位点坐标不可随意混用。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	参考集主键	系统生成	隐藏/只读	必填、唯一
`auth_user_id`	数据所属用户或租户	登录上下文自动写入	隐藏	不允许手填
`assemblypui`	参考组装永久标识，如 DOI、INSDC accession、URI	用户录入/导入	文本框/URL 输入框	可选；建议唯一
`description`	参考集说明	用户录入	多行文本	可选
`is_derived`	是否由其他参考集派生	用户选择	开关	可选
`md5checksum`	参考集校验值	用户录入/文件计算	文本框	可选；若填写应符合 MD5 格式
`reference_set_name`	参考集名称，如 IRGSP-1.0、B73 RefGen_v5	用户录入	文本框	必填；建议唯一
`sourceuri`	参考集来源 URI 或下载地址	用户录入	URL 输入框	可选；校验 URL
`species_ontology_term`	物种本体术语名称	用户录入/选择	文本框/本体选择器	可选
`species_ontology_termuri`	物种本体 URI	用户录入/本体带出	URL 输入框	可选；校验 URL
`source_germplasm_id`	参考基因组来源材料	从 germplasm 选择	Germplasm 选择器	可选；必须引用存在 germplasm

录入建议

reference_set 是 variantset 和 variant 的上游，不能随意改。
如果导入 VCF，必须先明确该 VCF 的 reference_set。
同一 crop 可能存在多个 reference_set，应在页面上清楚显示版本和来源。

6.4 reference 参考序列

业务说明

reference 是 reference_set 中的一条参考序列，例如 chromosome、contig、scaffold。variant 的坐标通常是基于某条 reference 的位置。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	参考序列主键	系统生成	隐藏/只读	必填、唯一
`auth_user_id`	数据所属用户或租户	登录上下文自动写入	隐藏	不允许手填
`length`	序列长度	用户录入/FASTA 导入	数字输入框	必填或建议必填；非负整数
`md5checksum`	单条 reference 的 MD5 校验值	用户录入/文件计算	文本框	可选；若填写应符合 MD5 格式
`reference_name`	参考序列名称，如 chr1、1、Chr01、scaffold_001	用户录入/FASTA 导入	文本框	必填；同一 reference_set 内唯一
`source_divergence`	与来源序列的差异程度	用户录入/导入	数字输入框	可选；范围建议 0-1 或按业务定义
`reference_set_id`	所属 reference_set	从 reference_set 选择	ReferenceSet 选择器	必选

录入建议

建议通过 FASTA 索引文件批量导入 chromosome / contig。
同一 reference_set 下 reference_name 必须唯一。
variant 导入时，文件中的 CHROM 必须能匹配 reference.reference_name。

6.5 reference_bases 参考片段

业务说明

reference_bases 保存 reference 的序列片段或分页。通常不建议人工录入，而是由 FASTA 导入或接口生成。对于大型基因组，不建议把完整序列全部塞入普通业务表，除非系统确实需要序列查询。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	参考片段主键	系统生成	隐藏/只读	必填、唯一
`auth_user_id`	数据所属用户或租户	登录上下文自动写入	隐藏	不允许手填
`bases`	碱基序列片段	FASTA 导入/接口生成	多行文本/只读	必填；只能包含合法碱基字符 A/C/G/T/N 等
`page_number`	分页编号	系统生成	数字输入/只读	必填；非负整数；同一 reference 下唯一
`reference_id`	所属 reference	由导入带出	Reference 选择器/隐藏	必选

录入建议

不建议前端做手工新增入口，只提供查看和导入。
每页 bases 长度应固定或可配置，例如 2KB、10KB、100KB。
导入时校验页码连续性和字符合法性。

6.6 variantset 变异集合

业务说明

variantset 是一批 variant 和相关 call 的集合，通常对应一个 VCF 文件、一个 SNP 芯片结果、一个测序分析批次或一个 study 的基因型数据集。它必须明确 reference_set，否则 variant 坐标无意义。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	变异集合主键	系统生成	隐藏/只读	必填、唯一
`auth_user_id`	数据所属用户或租户	登录上下文自动写入	隐藏	不允许手填
`variant_set_name`	变异集合名称，如 Rice-2026-SNPSet、VCF-Run-001	用户录入/文件名带出	文本框	必填；建议唯一
`reference_set_id`	使用的参考集	从 reference_set 选择	ReferenceSet 选择器	必选
`study_id`	关联 study	从 study 选择	Study 选择器	可选；若填写，应与样本来源 study 保持一致

录入建议

导入 VCF/CSV 前必须先选择 reference_set。
如果 variantset 来源于某次 study 的样本检测，应填写 study_id。
variantset 详情页应展示：variant 数量、callset 数量、分析信息、文件格式、导入状态。

6.7 variant 变异位点

业务说明

variant 表示一个遗传序列上的位点或区间，可以是 SNP、INDEL、SV，也可以是传统 marker。它通常由 reference_set、reference_name、start/end、reference_bases、alternate_bases 共同定义。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	变异主键	系统生成/导入	隐藏/只读	必填、唯一
`auth_user_id`	数据所属用户或租户	登录上下文自动写入	隐藏	不允许手填
`created`	创建时间	系统默认/文件导入	日期时间只读	可选；默认当前时间
`variant_end`	变异结束位置	文件导入/用户录入	数字输入框	可选；非负整数；不小于 start
`filters_applied`	是否执行过过滤	文件导入/系统写入	开关/只读	可选
`filters_passed`	是否通过过滤	文件导入/系统写入	开关/只读	可选
`reference_bases`	参考等位基因或参考碱基	文件导入/用户录入	文本框	可选；合法碱基字符
`variant_start`	变异起始位置	文件导入/用户录入	数字输入框	必填；非负整数
`svlen`	结构变异长度	文件导入/用户录入	数字输入框	可选；SV 类型时建议填写
`updated`	更新时间	系统自动写入	只读日期时间	自动更新
`variant_name`	变异名称，如 SNP001、chr1_123456_A_G	用户录入/自动生成	文本框	必填或由位置自动生成；同一 variantset 下建议唯一
`variant_type`	变异类型，如 SNP、INDEL、SV、marker	用户选择/文件导入	下拉框	可选；建议枚举化
`reference_set_id`	所属参考集	从 reference_set 选择/variantset 带出	ReferenceSet 选择器/隐藏	必选；需与 variantset.reference_set 一致
`variant_set_id`	所属变异集合	从 variantset 选择	VariantSet 选择器/隐藏	必选

录入建议

大量 variant 应通过 VCF、HapMap、CSV 批量导入，不建议手工录入。
如果当前表缺少 alternate_bases、reference_name 字段，应在导入逻辑或扩展表中补齐，否则变异定义不完整。
variant 的唯一性建议使用：reference_set_id + reference_name + start + reference_bases + alternate_bases。

6.8 callset 调用集合

业务说明

callset 表示某个 sample 参与一次测序、芯片或分析事件后形成的一组 genotype calls。多数情况下，一个 sample 对应一个 callset；但如果同一个 sample 多次送检或使用不同分析流程，则可以有多个 callset。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	CallSet 主键	系统生成/导入	隐藏/只读	必填、唯一
`auth_user_id`	数据所属用户或租户	登录上下文自动写入	隐藏	不允许手填
`call_set_name`	调用集合名称，如 SAMPLE-001_Run1	用户录入/系统生成	文本框	必填；同一 sample 下建议唯一
`created`	创建时间	系统默认/导入	日期时间	默认当前时间
`updated`	更新时间	系统自动写入	只读日期时间	自动更新
`sample_id`	所属样本	从 sample 选择/导入匹配	Sample 选择器	必选

录入建议

从 genotype 文件导入时，可以按样本列自动创建 callset。
callset 需要通过 callset_variant_sets 绑定它覆盖的 variantset。
sample 详情页应展示 callset 列表和每个 callset 的 variantset、call 数量、导入时间。

6.9 callset_variant_sets 调用集合与变异集合关系

业务说明

callset_variant_sets 表示某个 callset 覆盖哪些 variantset。它是一次检测结果和一批位点集合之间的关系。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`call_sets_id`	调用集合	从 callset 选择/导入自动创建	CallSet 选择器/隐藏	必选
`variant_sets_id`	变异集合	从 variantset 选择/导入自动绑定	VariantSet 选择器/隐藏	必选

录入建议

从 variantset 导入 genotype matrix 时，系统应自动绑定所有新建 callset 到该 variantset。
同一 callset + variantset 不允许重复。

6.10 allele_call 基因型结果

业务说明

allele_call 是最终基因型事实数据，表示某个 callset 在某个 variant 上的 genotype 结果。它是 genotype matrix 的一个格子。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	基因型结果主键	系统生成/导入	隐藏/只读	必填、唯一
`auth_user_id`	数据所属用户或租户	登录上下文自动写入	隐藏	不允许手填
`genotype`	genotype 结果，如 A/G、0/1、0	1、AA、./.	文件导入/少量手工修正	文本框/基因型控件
`genotype_likelihood`	genotype likelihood，表示不同 genotype 的可能性或置信信息	文件导入	数字输入框	可选；范围和含义按导入格式定义
`phase_set`	phase set，用于 phased genotype 分组	文件导入	文本框	可选；phased 数据时使用
`read_depth`	测序深度	文件导入/用户录入	数字输入框	可选；非负整数
`call_set_id`	所属 callset	从 callset 选择/导入匹配	CallSet 选择器/隐藏	必选
`variant_id`	对应 variant	从 variant 选择/导入匹配	Variant 选择器/隐藏	必选

录入建议

allele_call 不建议大量手工新增，主入口应该是 VCF/HapMap/CSV 文件导入。
同一 call_set_id + variant_id 不应重复。
genotype 需要兼容常见格式：
- Allele 格式：A/G、C/C、T/G；
- VCF 编码：0/0、0/1、1/1、0|1；
- 缺失：./.、NA、N、--，具体缺失字符串由 variantset_format 配置。
导入后应支持按 sample/callset 或 variant 两种视角查询。

6.11 variantset_analysis 变异集合分析信息

业务说明

variantset_analysis 记录 variantset 的分析流程、软件、版本、参数、时间等信息。它是数据可追溯的重要来源。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	分析记录主键	系统生成	隐藏/只读	必填、唯一
`analysis_name`	分析名称，如 GATK SNP Calling Run 2026-01	用户录入/导入带出	文本框	必填
`created`	创建时间	系统默认	日期时间	默认当前时间
`description`	分析说明，如软件版本、过滤参数	用户录入	多行文本	可选，建议填写
`type`	分析类型，如 SNP calling、imputation、filtering、chip genotyping	用户选择/录入	下拉框/文本框	可选
`updated`	更新时间	系统自动写入	只读日期时间	自动更新
`variant_set_id`	所属 variantset	从 variantset 选择	VariantSet 选择器/隐藏	必选

录入建议

导入结果文件时，应生成或要求填写 analysis 信息。
推荐记录：软件名称、版本、参数、过滤阈值、执行人、执行日期。

6.12 variantset_format 变异集合文件格式

业务说明

variantset_format 描述 variantset 数据文件格式，例如 VCF、HapMap、CSV、TSV、DArTSeq 等。它影响 genotype 的解析方式、缺失值、phased/unphased 分隔符等。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	格式记录主键	系统生成	隐藏/只读	必填、唯一
`data_format`	数据内部结构，如 VCF、HapMap、DArTSeq、matrix	用户选择/文件识别	下拉框	可选；建议枚举化
`expand_homozygotes`	是否展开纯合 genotype，例如 A -> A/A	用户选择	开关	可选
`file_format`	文件 MIME 或外层格式，如 csv、tsv、zip、excel	用户选择/文件识别	下拉框	可选
`fileurl`	原始结果文件链接	上传后生成/用户填写	URL 输入框	可选；URL 格式校验
`sep_phased`	phased genotype 分隔符，如 `	`	用户录入/默认	文本框
`sep_unphased`	unphased genotype 分隔符，如 `/`	用户录入/默认	文本框	可选；通常为 `/`
`unknown_string`	缺失值字符串，如 `./.`、NA、--	用户录入/默认	文本框	可选；导入时用于缺失识别
`variant_set_id`	所属 variantset	从 variantset 选择	VariantSet 选择器/隐藏	必选

录入建议

文件上传时应自动识别 file_format 和 data_format。
缺失值字符串必须参与 allele_call 导入解析。
如果格式是 VCF，应支持 phased/unphased 分隔符。

6.13 genome_map 遗传图谱

业务说明

genome_map 描述遗传图谱或物理图谱。遗传图谱通常单位为 cM，物理图谱通常单位为 Mb 或 bp。它用于把 variant / marker 映射到 linkage group 上。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	图谱主键	系统生成	隐藏/只读	必填、唯一
`auth_user_id`	数据所属用户或租户	登录上下文自动写入	隐藏	不允许手填
`comments`	图谱备注	用户录入	多行文本	可选
`documentationurl`	图谱说明文档或论文链接	用户录入	URL 输入框	可选；URL 格式校验
`map_name`	图谱名称	用户录入	文本框	必填；建议唯一
`mappui`	图谱永久唯一标识	用户录入	文本框/URL 输入框	可选；若填写建议唯一
`published_date`	发布时间	用户录入	日期选择器	可选
`scientific_name`	物种学名	用户录入	文本框	可选
`type`	图谱类型，如 Genetic、Physical	用户选择	下拉框	可选；建议枚举
`unit`	图谱单位，如 cM、Mb、bp	用户选择	单位选择器	可选；Genetic 常用 cM，Physical 常用 Mb/bp
`crop_id`	所属作物	从 crop 选择	Crop 选择器	必选

录入建议

图谱命名应能体现是 consensus map、mapping population map、reference genome map 还是 pan-genome map。
图谱类型和单位必须匹配：Genetic + cM，Physical + Mb/bp。

6.14 linkage_group 连锁群

业务说明

linkage_group 是 genome_map 中的分组。它可能对应 chromosome、scaffold、contig 或传统遗传连锁群。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	连锁群主键	系统生成	隐藏/只读	必填、唯一
`auth_user_id`	数据所属用户或租户	登录上下文自动写入	隐藏	不允许手填
`linkage_group_name`	连锁群名称，如 Chr1、LG1、scaffold_001	用户录入/导入	文本框	必填；同一 genome_map 下唯一
`max_marker_position`	该连锁群最大 marker 位置	用户录入/导入计算	数字输入框	可选；非负数
`genome_map_id`	所属 genome_map	从 genome_map 选择	GenomeMap 选择器/隐藏	必选

录入建议

在 genome_map 详情页维护。
支持从 marker_position 文件批量导入时自动创建 linkage_group。
若填写 max_marker_position，marker_position.position 不得超过该值。

6.15 marker_position 图谱位置

业务说明

marker_position 把 variant 映射到某个 linkage_group 上的位置。它用于遗传图谱定位、QTL、marker 辅助选择和图谱展示。

字段说明

字段	业务意义	录入方式	控件建议	校验规则
`id`	图谱位置主键	系统生成	隐藏/只读	必填、唯一
`auth_user_id`	数据所属用户或租户	登录上下文自动写入	隐藏	不允许手填
`position`	variant 在 linkage_group 上的位置	用户录入/文件导入	数字输入框	必填；非负；不得超过 max_marker_position
`linkage_group_id`	所属 linkage_group	从 linkage_group 选择	LinkageGroup 选择器	必选
`variant_id`	对应 variant	从 variant 选择	Variant 选择器	必选

录入建议

不建议逐条手工录入，优先通过 map 文件批量导入。
同一 genome_map 下，同一 variant 不应重复映射，除非业务允许多图谱位置。

7. 跨表联动规则

场景	联动规则
从 observation_unit 生成 sample	自动带出 study、trial、program；可带出 germplasm 信息用于展示
给 sample 分配 plate	选择 well 后自动生成 plate_row、plate_column
创建 plate	选择 study 后自动带出 trial/program
创建 variantset	必须先选择 reference_set
导入 variant	variant.reference_set 必须与 variantset.reference_set 一致
创建 callset	必须选择 sample；可按 sample_name 自动生成 call_set_name
导入 allele_call	先匹配 callset，再匹配 variant；匹配不到时进入错误报告
绑定 callset_variant_sets	导入 genotype matrix 时自动绑定 callset 与 variantset
创建 genome_map	必须选择 crop
创建 marker_position	variant 与 linkage_group 最好来自同一 crop/reference 背景

8. 删除和停用规则

对象	删除限制
plate	已有 sample 时不可删除
sample	已有 callset 时不可删除
reference_set	已有 reference、variantset、variant 时不可删除
reference	已有 reference_bases 或 variant 引用时不可删除
variantset	已有 variant、callset 绑定或 allele_call 结果时不可删除
variant	已有 allele_call 或 marker_position 时不可删除
callset	已有 allele_call 时不可删除
allele_call	原始检测结果原则上不建议物理删除，应支持作废或版本化
genome_map	已有 linkage_group 时不可删除
linkage_group	已有 marker_position 时不可删除
marker_position	可删除，但需记录操作日志

9. 批量导入要求

9.1 Sample 导入模板

必需列建议：

sample_name
study_id 或 study_name

强烈建议列：

observation_unit_id 或 observation_unit_name
sample_barcode
sample_type
tissue_type
sample_timestamp
taken_by
plate_name
well

导入规则：

如果提供 observation_unit，系统自动带出 study/trial/program。
如果提供 plate + well，需校验同板孔位唯一。
如果 plate 不存在，可根据配置自动创建或报错。

9.2 Plate 导入模板

plate_name
plate_barcode
plate_format
study_name
sample_name
well

导入规则：

plate_format 决定合法 well 范围。
同一 plate + well 不允许重复。
sample_name 不存在时，可配置是否自动创建 sample。

9.3 Variant 导入模板

建议支持 VCF / HapMap / CSV。

CSV 必需列建议：

variant_name
reference_name
variant_start
reference_bases
alternate_bases
variant_type
variant_set_name
reference_set_name

导入规则：

必须先选择或创建 reference_set。
CHROM / reference_name 必须能匹配 reference。
variant_start 必须非负。
alternate_bases 不能为空，除非只是导入传统 marker。

9.4 Genotype Matrix / Allele Call 导入模板

推荐矩阵格式：

variant_name,SAMPLE-001,SAMPLE-002,SAMPLE-003
SNP001,A/G,A/A,./.
SNP002,C/C,C/T,C/C
SNP003,T/G,T/T,T/G

导入规则：

每个样本列必须能匹配 sample 或 callset。
每个 variant 行必须能匹配 variant。
每个非空 genotype 单元格生成一条 allele_call。
缺失值按 variantset_format.unknown_string 处理。
同一 callset + variant 已存在时，根据导入策略选择覆盖、跳过或报错。

9.5 Genome Map 导入模板

map_name
linkage_group_name
variant_name
position
unit

导入规则：

map_name 不存在时可配置自动创建 genome_map。
linkage_group 不存在时可配置自动创建。
variant 必须存在。
position 必须非负且不超过 max_marker_position。

10. 后端接口建议

10.1 主数据接口

GET    /plates
POST   /plates
GET    /plates/{id}
PUT    /plates/{id}
GET    /plates/{id}/layout
POST   /plates/{id}/assign-samples

GET    /samples
POST   /samples
POST   /samples/batch-from-observation-units
GET    /samples/{id}
PUT    /samples/{id}
GET    /samples/{id}/callsets

GET    /reference-sets
POST   /reference-sets
GET    /reference-sets/{id}
GET    /reference-sets/{id}/references
POST   /reference-sets/{id}/references

GET    /references
POST   /references
GET    /references/{id}/bases
POST   /references/{id}/bases/import

GET    /variantsets
POST   /variantsets
GET    /variantsets/{id}
GET    /variantsets/{id}/variants
POST   /variantsets/{id}/variants/import
GET    /variantsets/{id}/formats
POST   /variantsets/{id}/formats
GET    /variantsets/{id}/analyses
POST   /variantsets/{id}/analyses

GET    /variants
POST   /variants
GET    /variants/{id}

GET    /callsets
POST   /callsets
GET    /callsets/{id}
POST   /callsets/{id}/variantsets

GET    /allele-calls
POST   /allele-calls/import
GET    /allele-matrix

GET    /genome-maps
POST   /genome-maps
GET    /genome-maps/{id}/linkage-groups
POST   /genome-maps/{id}/linkage-groups
POST   /marker-positions/import

10.2 选择器接口

GET /selectors/plates?studyId=&keyword=
GET /selectors/samples?studyId=&plateId=&keyword=
GET /selectors/reference-sets?cropId=&keyword=
GET /selectors/references?referenceSetId=&keyword=
GET /selectors/variantsets?referenceSetId=&studyId=&keyword=
GET /selectors/variants?variantSetId=&referenceName=&start=&end=&keyword=
GET /selectors/callsets?sampleId=&variantSetId=&keyword=
GET /selectors/genome-maps?cropId=&keyword=
GET /selectors/linkage-groups?genomeMapId=&keyword=

11. 测试验收清单

创建 plate 时，plate_name 和 plate_barcode 至少填写一个。
plate_barcode 重复时提示唯一性冲突。
plate_format=96 时，只允许 A01-H12；plate_format=384 时，只允许 A01-P24。
sample_name 必填。
sample 绑定 plate 时，同一 plate + well 不允许重复。
sample 绑定 observation_unit 后，study/trial/program 自动带出。
reference_set_name 必填。
reference_name 在同一 reference_set 内不允许重复。
reference.length 必须为非负整数。
reference_bases.bases 只能包含合法碱基字符。
variantset 必须选择 reference_set。
variant.reference_set_id 必须与 variantset.reference_set_id 一致。
variant_start 必须非负。
variant_end 不得小于 variant_start。
variant_name 为空时系统能按 reference + position + allele 自动生成。
callset 必须绑定 sample。
同一 sample 下 call_set_name 不建议重复。
callset + variantset 关系不允许重复。
allele_call 必须绑定 callset 和 variant。
同一 callset + variant 不允许重复，除非系统支持版本化。
read_depth 必须为非负整数。
genotype 必须符合导入格式规则。
缺失 genotype 必须按 unknown_string 统一处理。
导入 genotype matrix 时，无法匹配的 sample、variant 必须返回错误报告。
导入失败报告必须包含行号、列名、错误原因、建议修复方式。
genome_map 必须选择 crop。
linkage_group_name 在同一 genome_map 内不允许重复。
marker_position.position 必须非负，且不超过 max_marker_position。
已有关联下游数据的 sample、variant、callset、variantset 不允许物理删除。
所有导入操作必须记录导入批次、上传人、上传时间和原始文件链接。

12. 开发实现重点

sample 是物理样本，不是基因型结果。
callset 是 sample 参与一次检测/分析形成的结果集合。
allele_call 才是某个 sample/callset 在某个 variant 上的 genotype 结果。
variantset 必须绑定 reference_set，否则位点坐标没有意义。
大量 variant 和 allele_call 不应手工录入，主入口必须是文件导入。
plate 必须做孔位布局，不要只做普通表单。
genotype matrix 页面必须支持按 sample 和按 variant 两种方向查看。
VCF/HapMap/CSV 的解析规则要独立成导入服务，不要散落在页面逻辑里。
reference_set、variantset、callset、analysis、format 都是结果可追溯的关键上下文。
已导入的基因型结果建议支持版本化或作废，不建议直接物理删除。

50 KiB Raw Permalink Blame History Unescape Escape

Genotyping 模块专业数据录入需求文档 V2

1. 文档目的

2. 模块定位

3. 核心业务主线

3.1 样本线

3.2 位点线

3.3 结果线

3.4 图谱线

4. 推荐业务流程

5. 推荐页面形态

5.1 Genotyping 工作台

5.2 Plate 孔位布局页

5.3 Genotype Matrix 结果页

6. 字段级专业录入需求

6.1 plate 样本板

业务说明

字段说明

录入建议

验收标准

6.2 sample 样本

业务说明

字段说明

录入建议

验收标准

6.3 reference_set 参考集

业务说明

字段说明

录入建议

6.4 reference 参考序列

业务说明

字段说明

录入建议

6.5 reference_bases 参考片段

业务说明

字段说明

录入建议

6.6 variantset 变异集合

业务说明

字段说明

录入建议

6.7 variant 变异位点

业务说明

字段说明

录入建议

6.8 callset 调用集合

业务说明

字段说明

录入建议

6.9 callset_variant_sets 调用集合与变异集合关系

业务说明

字段说明

录入建议

6.10 allele_call 基因型结果

业务说明

字段说明

录入建议

6.11 variantset_analysis 变异集合分析信息

业务说明

字段说明

录入建议

6.12 variantset_format 变异集合文件格式

业务说明

字段说明

录入建议

6.13 genome_map 遗传图谱

业务说明

字段说明

录入建议

6.14 linkage_group 连锁群

业务说明

字段说明

录入建议

6.15 marker_position 图谱位置

业务说明

字段说明

录入建议

7. 跨表联动规则

8. 删除和停用规则

9. 批量导入要求

50 KiB

Raw Permalink Blame History