fix:sample/plate 之前的开发
This commit is contained in:
彭帅
210
docs/architecture/core-data-flow.md
Normal file
210
docs/architecture/core-data-flow.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# Core 模块数据流与表关系
|
||||
|
||||
本文档分析 `brapi-java` 项目 core 模块的数据录入顺序、主表关系，以及初始化脚本中的实际数据流。
|
||||
|
||||
## 结论
|
||||
|
||||
Core 模块的数据主线是：
|
||||
|
||||
```text
|
||||
crop -> person -> program -> location -> trial -> season -> study -> study 附属信息
|
||||
```
|
||||
|
||||
`list` 是相对独立的列表能力，可以较早录入；如果需要绑定列表所有人，则依赖 `person`。
|
||||
|
||||
初始化脚本实际执行顺序是：
|
||||
|
||||
```text
|
||||
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` 还可以同时录入：
|
||||
|
||||
```text
|
||||
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` 时通常需要已有：
|
||||
|
||||
```text
|
||||
crop
|
||||
program
|
||||
trial
|
||||
location
|
||||
```
|
||||
|
||||
`study` 是 core 模块向 pheno/geno 数据扩展的关键节点。后续 observation、observation_unit、sample、plate、variantset 等很多模块都会引用 `study`。
|
||||
|
||||
### 7. 录入 Study 附属信息
|
||||
|
||||
录入 study 后，再录入依赖 `study_id` 的附属表：
|
||||
|
||||
```text
|
||||
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 数据流图
|
||||
|
||||
```mermaid
|
||||
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 关系图
|
||||
|
||||
```mermaid
|
||||
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`。
|
||||
|
||||
Reference in New Issue
Block a user