brapi-java/docs/requirements/00-data-entry-requirements-overview.md

数据录入需求总览

本文档基于 docs/architecture 下 5 份架构文档拆解，目标是把 BrAPI Test Server 的数据录入需求按上游到下游梳理清楚：

Core 基础数据 -> Germplasm/Seed 种质种子 -> Phenotyping 表型 -> Genotyping 基因型

文档索引

顺序	文档	说明
1	01-core-data-entry-requirements.md	crop、person、program、location、trial、season、study、list
2	02-germplasm-seed-entry-requirements.md	breeding_method、germplasm、attribute、cross、seed_lot、pedigree
3	03-phenotyping-entry-requirements.md	ontology、trait、method、scale、observation_variable、observation_unit、event、image、observation
4	04-genotyping-entry-requirements.md	plate、sample、reference、variantset、variant、callset、allele_call、genome_map

总体录入链路

flowchart TD
    CROP["crop 作物"] --> PROGRAM["program 项目"]
    PERSON["person 人员"] --> PROGRAM
    PROGRAM --> TRIAL["trial 试验批次"]
    PROGRAM --> LOCATION["location 地点"]
    TRIAL --> STUDY["study 研究/试验单元"]
    LOCATION --> STUDY

    CROP --> BM["breeding_method 育种方法"]
    BM --> G["germplasm 种质"]
    G --> GAV["germplasm_attribute_value 种质属性值"]
    PROGRAM --> CP["crossing_project 杂交项目"]
    CP --> CROSS["cross_entity Cross/PlannedCross"]
    G --> CROSSP["cross_parent 亲本"]
    CROSS --> CROSSP
    G --> MIX["seed_lot_content_mixture 批次组成"]
    CROSS --> MIX
    MIX --> SL["seed_lot 种子批次"]

    STUDY --> OU["observation_unit 观测单元"]
    G --> OU
    SL --> OU
    CROSS --> OU
    OU --> OBS["observation 观测值"]

    OU --> SAMPLE["sample 样本"]
    STUDY --> SAMPLE
    SAMPLE --> CALLSET["callset 调用集合"]
    VARIANT["variant 变异位点"] --> CALL["allele_call 基因型结果"]
    CALLSET --> CALL

全局界面原则

页面类型	用途	建议界面
列表页	查询、筛选、分页、批量操作	顶部筛选区 + 表格 + 新增按钮 + 行内查看/编辑
新增/编辑页	单表主数据录入	分组表单，必填字段靠前，外键使用搜索选择器
详情页	查看主表及下游数据	顶部摘要 + Tab：基本信息、关联数据、扩展信息、外部引用
关系选择器	选择上游依赖	支持按 ID、名称、作物、项目、study 搜索
批量导入	初始化和大批量数据	上传 CSV/Excel + 字段映射 + 预校验 + 导入结果

全局字段规则

字段类型	录入规则
id / DbId	系统生成或用户提供；必须唯一；编辑时不可随意修改
名称字段	必填或强建议必填；用于下拉选择展示
外键字段	页面展示名称，提交保存实际 ID
枚举字段	使用下拉框或单选控件
日期时间	使用日期/时间选择器，保存前统一格式
additional_info	作为高级配置，用键值编辑器录入
external_references	作为外部系统引用，用可增删表格录入

总体录入顺序

1. 录入 Core：crop、person、program、location、trial、season、study、list。
2. 录入 Germplasm/Seed：breeding_method、germplasm_attribute_definition、germplasm、germplasm_attribute_value、crossing_project、cross_entity、cross_parent、pedigree_node、pedigree_edge、seed_lot、seed_lot_content_mixture、seed_lot_transaction。
3. 录入 Phenotyping：ontology、trait、method、scale、observation_variable、observation_unit、event、image、observation。
4. 录入 Genotyping：plate、sample、reference_set、reference、reference_bases、variantset、variant、callset、allele_call、genome_map、linkageGroup、marker_position。

通用验收标准

1. 每张表都有列表、新增、编辑、详情能力。
2. 每个外键字段都能通过名称搜索选择，而不是要求用户手填数据库 ID。
3. 下游表新增时必须校验上游数据是否存在。
4. 删除或禁用上游数据时，需要提示被哪些下游表引用。
5. 支持按模块导入 CSV/Excel，并在导入前给出错误行和错误原因。
6. 详情页能看到关键下游关联，例如 study 下的 observation unit、sample、variantset。