brapi-java/docs/architecture/core-data-flow.md

Core 模块数据流与表关系

本文档分析 brapi-java 项目 core 模块的数据录入顺序、主表关系，以及初始化脚本中的实际数据流。

结论

Core 模块的数据主线是：

crop -> person -> program -> location -> trial -> season -> study -> study 附属信息

list 是相对独立的列表能力，可以较早录入；如果需要绑定列表所有人，则依赖 person。

初始化脚本实际执行顺序是：

R__init_data_01_crops.sql
R__init_data_02_lists.sql
R__init_data_03_locations.sql
R__init_data_04_people.sql
R__init_data_05_programs.sql
R__init_data_06_trials.sql
R__init_data_07_seasons.sql
R__init_data_08_studies.sql

其中 R__init_data_05_programs.sql 会插入 program 负责人到 person 表，并回填部分 location.program_id/crop_id。

核心表说明

表	作用	主要上游依赖	主要下游
crop	作物字典，Core 主根数据之一	无	program、location、trial、study
person	人员、联系人、负责人	无	program.lead_person_id、trial_contact、study_contact、list.list_owner_person_id
program	育种项目/业务项目	crop、可选 person	trial、study、location
location	地点/试验点	可选 crop、program、父级 location、geojson	study
trial	试验批次/试验项目	crop、program	study、trial_contact、trial_publication、trial_dataset_authorship
season	季节/年度区间字典	无	study_season、部分 observation
study	具体研究/试验实施单元	crop、program、trial、location	study_contact、study_season、study_data_link、study_observation_level 等
list	通用列表	可选 person	list_item
list_item	列表明细项	list	无

建议录入顺序

1. 录入基础字典

先录入 crop 和 person。

crop 是作物维度根数据，后续 program、trial、study 都会挂到它下面。person 是人员基础资料，后续会作为项目负责人、试验联系人、研究联系人、列表负责人使用。

2. 录入地点

录入 location，如果地点有坐标，需要先录入 geojson 和 coordinate。

地点可以先不绑定 program/crop，初始化脚本里就是先插入地点，再在 program 初始化阶段回填 program_id 和 crop_id。

3. 录入项目 Program

录入 program 时需要已有 crop。如果有负责人，需要已有 person。

程序层面 ProgramEntity.setCrop(...) 直接绑定作物；后续 trial/study 设置 program 时，会同步继承 program 的 crop。

4. 录入 Trial

录入 trial 时需要已有 program 和 crop。

trial 还可以同时录入：

trial_contact
trial_dataset_authorship
trial_publication
trial_additional_info
trial_external_references

其中 trial_contact 是 trial 和 person 的多对多关系表。

5. 录入 Season

录入 season。它本身相对独立，但后续 study 会通过 study_season 关联多个 season。

6. 录入 Study

录入 study 时通常需要已有：

crop
program
trial
location

study 是 core 模块向 pheno/geno 数据扩展的关键节点。后续 observation、observation_unit、sample、plate、variantset 等很多模块都会引用 study。

7. 录入 Study 附属信息

录入 study 后，再录入依赖 study_id 的附属表：

study_contact
study_data_link
study_environment_parameter
study_experimental_design
study_growth_facility
study_last_update
study_observation_level
study_season
study_variable
study_additional_info
study_external_references

Core 数据流图

flowchart TD
    A["1. crop 作物字典"] --> C["3. program 项目"]
    B["2. person 人员"] --> C
    B --> L["list 列表负责人，可选"]
    L --> LI["list_item 列表项"]

    G["geojson / coordinate 坐标"] --> D["2. location 地点"]
    A --> D
    C --> D
    D --> E["6. study 研究"]

    C --> F["4. trial 试验"]
    A --> F
    B --> FC["trial_contact 试验联系人"]
    F --> FC
    F --> FP["trial_publication / trial_dataset_authorship"]

    S["5. season 季节"] --> SS["study_season 研究季节"]
    F --> E
    C --> E
    A --> E
    E --> SS
    E --> SC["study_contact 研究联系人"]
    B --> SC
    E --> SA["study_data_link / environment / design / growth_facility / last_update / observation_level"]

    E --> P1["pheno: observation_unit / observation"]
    E --> G1["geno: sample / plate / variantset"]

Core ER 关系图

erDiagram
    crop ||--o{ program : "crop_id"
    crop ||--o{ location : "crop_id"
    crop ||--o{ trial : "crop_id"
    crop ||--o{ study : "crop_id"

    person ||--o{ program : "lead_person_id"
    person ||--o{ trial_contact : "person_db_id"
    person ||--o{ study_contact : "person_db_id"
    person ||--o{ list : "list_owner_person_id"

    program ||--o{ location : "program_id"
    program ||--o{ trial : "program_id"
    program ||--o{ study : "program_id"

    location ||--o{ location : "parent_location_id"
    location ||--o{ study : "location_id"

    trial ||--o{ study : "trial_id"
    trial ||--o{ trial_contact : "trial_db_id"
    trial ||--o{ trial_publication : "trial_id"
    trial ||--o{ trial_dataset_authorship : "trial_id"

    study ||--o{ study_contact : "study_db_id"
    study ||--o{ study_season : "study_db_id"
    season ||--o{ study_season : "season_db_id"

    study ||--o{ study_data_link : "study_id"
    study ||--o{ study_environment_parameter : "study_id"
    study ||--o{ study_experimental_design : "study_id"
    study ||--o{ study_growth_facility : "study_id"
    study ||--o{ study_last_update : "study_id"
    study ||--o{ study_observation_level : "study_id"

    list ||--o{ list_item : "list_id"

API 与表的对应关系

API	主表	说明
GET /brapi/v2/commoncropnames	crop	查询作物名称列表
GET/POST/PUT /brapi/v2/people	person	人员查询、新增、修改；无删除接口
GET/POST/PUT /brapi/v2/programs	program	项目依赖 crop，可关联 lead person
GET/POST/PUT /brapi/v2/locations	location	地点可关联 crop、program、parent location、geojson
GET/POST/PUT /brapi/v2/trials	trial	试验依赖 program/crop，可关联 contacts/publications
GET/PUT /brapi/v2/seasons	season	季节字典
GET/POST/PUT /brapi/v2/studies	study	研究依赖 trial/program/crop/location
GET/POST/PUT /brapi/v2/lists	list、list_item	列表及列表项

关键注意点

1. crop 是最重要的根字典之一，许多业务表都有 crop_id。
2. program 是承上启下的业务节点，它依赖 crop，并被 trial、study、location 引用。
3. trial 是 study 的上级试验组织，study 是后续表型、基因型数据的核心入口。
4. person 与 trial/study 是多对多关系，通过 trial_contact、study_contact 连接。
5. study_season 是 study 和 season 的多对多关系。
6. additional_info 和 external_reference 是通用扩展表，core 主表通过各自的 *_additional_info、*_external_references 关联它们。
7. 初始化脚本中 list 早于 person 插入，是因为初始 list 数据主要使用文本 owner 字段；如果业务上要设置 list_owner_person_id，应先有 person。