779 lines
49 KiB
Markdown
779 lines
49 KiB
Markdown
# Phenotyping 模块专业数据录入需求文档 V2
|
||
|
||
## 1. 文档目的
|
||
|
||
本文档用于指导 Phenotyping 表型模块的前端页面、后端接口、字段校验、数据导入和测试验收设计。本文档不只描述表关系，而是从真实育种表型采集业务出发，解释每个对象和字段的业务意义、录入方式、控件建议、校验规则和上下游影响。
|
||
|
||
## 2. 模块定位
|
||
|
||
Phenotyping 模块用于管理田间、温室、实验室或高通量设备采集到的表型数据。它的核心不是“录一张 observation 表”，而是完整描述：
|
||
|
||
```text
|
||
在哪个 study 里
|
||
对哪个 observation_unit
|
||
按照哪个 observation_variable
|
||
在什么时间、由谁、用什么方法
|
||
采集到了什么 value
|
||
并能关联事件、图片、坐标和上下文
|
||
```
|
||
|
||
## 3. 核心业务概念
|
||
|
||
| 概念 | 业务含义 | 关键表 |
|
||
| ---------------------------- | ---------------------------------------------------------- | ------------------------------------------------- |
|
||
| Ontology 本体 | 性状、方法、标尺、变量的术语来源，可以是本地本体或公开本体 | `ontology` |
|
||
| Trait 性状 | 测什么。例如株高、穗长、病害等级、籽粒颜色 | `trait` |
|
||
| Method 方法 | 怎么测。例如尺测、人工评分、无人机图像分析、实验室检测 | `method` |
|
||
| Scale 标尺 | 用什么单位或尺度表达。例如 cm、kg、0-5 等级、文本、布尔值 | `scale`、`scale_valid_value_category` |
|
||
| ObservationVariable 观测变量 | Trait + Method + Scale 的组合，表示一个可采集指标 | `observation_variable` |
|
||
| StudyVariable 研究采集指标 | 某个 study 计划采集哪些 observation variable | `study_variable` |
|
||
| ObservationUnit 观测单元 | 被观测对象。通常是 plot、plant、block、field、sample | `observation_unit` |
|
||
| Event 事件 | 管理动作或环境事件，如施肥、灌溉、打药、移栽、极端天气 | `event`、`event_param`、`event_observation_units` |
|
||
| Image 图像 | 田间图片、无人机图片、病害图片、长势图像等 | `image`、`image_observations` |
|
||
| Observation 观测值 | 某个观测单元在某个变量上的一次实际测量结果 | `observation` |
|
||
|
||
## 4. 推荐业务流程
|
||
|
||
```text
|
||
1. 准备 Core 上下文：crop、program、trial、study、location、season
|
||
2. 维护或导入本体 ontology
|
||
3. 定义 trait / method / scale
|
||
4. 组合 observation_variable
|
||
5. 把 observation_variable 绑定到 study_variable，形成本 study 的采集指标清单
|
||
6. 根据田间设计生成 observation_unit，例如 block / plot / plant
|
||
7. 给 observation_unit 绑定材料来源：germplasm / seed_lot / cross
|
||
8. 记录 event，例如播种、移栽、施肥、灌溉、打药、采样、极端天气
|
||
9. 通过矩阵方式批量录入 observation
|
||
10. 上传 image，并关联 observation_unit 或 observation
|
||
11. 做数据质控：缺失值、异常值、重复采集、单位和分类值校验
|
||
```
|
||
|
||
## 5. 推荐页面形态
|
||
|
||
### 5.1 Study 表型工作台
|
||
|
||
```text
|
||
Study 表型工作台
|
||
├─ 试验上下文：study / trial / program / crop / location / season
|
||
├─ 指标清单：study_variable
|
||
├─ 田间设计：observation_unit 层级、block、plot、plant、row、column
|
||
├─ 材料布置：germplasm、seed_lot、cross
|
||
├─ 表型矩阵：observation_unit × observation_variable
|
||
├─ 田间事件：event + event_param + event_observation_units
|
||
├─ 图片证据：image + image_observations
|
||
├─ 数据质控：缺失值、异常值、重复值、单位校验、分类值校验
|
||
└─ 导入导出：观测单元模板、表型采集模板、图片元数据模板
|
||
```
|
||
|
||
### 5.2 表型矩阵录入
|
||
|
||
真实采集时不应只提供单条 observation 表单，而应支持矩阵录入：
|
||
|
||
| observation_unit | germplasm | 株高 cm | 穗长 cm | 倒伏等级 | 备注 |
|
||
| ---------------- | --------- | ------: | ------: | -------: | ---------- |
|
||
| Plot-001 | 华占 | 112.5 | 24.1 | 1 | 正常 |
|
||
| Plot-002 | 抗倒伏A | 98.3 | 22.8 | 0 | 正常 |
|
||
| Plot-003 | F2-001 | 101.6 | 23.0 | 4 | 台风后倒伏 |
|
||
|
||
保存时，系统按每个非空单元格生成一条 `observation`，每一列对应一个 `observation_variable`。
|
||
|
||
---
|
||
|
||
# 6. 字段级专业录入需求
|
||
|
||
## 6.1 ontology 本体
|
||
|
||
### 业务说明
|
||
|
||
`ontology` 表示术语体系来源，用来说明 trait、method、scale、observation_variable 的定义来自哪里。它可以是本地维护的术语库，也可以是公开 Crop Ontology、Trait Ontology 或机构内部标准。
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| ------------------ | ----------------------------------------- | -------------------------------- | --------------- | -------------------------------- |
|
||
| `id` | 本体主键，系统内部唯一标识 | 新增时系统生成；导入时可允许指定 | 隐藏/只读 | 必填、唯一；编辑时不可修改 |
|
||
| `auth_user_id` | 数据所属用户或租户 | 登录上下文自动写入 | 隐藏 | 不允许前端手填 |
|
||
| `authors` | 本体作者或维护者 | 用户录入 | 文本框 | 可选；多个作者可用分号或数组扩展 |
|
||
| `copyright` | 本体版权说明 | 用户录入 | 文本框/多行文本 | 可选 |
|
||
| `description` | 本体用途说明 | 用户录入 | 多行文本 | 可选，建议填写 |
|
||
| `documentationurl` | 本体文档链接 | 用户录入 | URL 输入框 | 可选；若填写必须是合法 URL |
|
||
| `licence` | 本体许可证，例如 CC-BY、MIT、机构内部许可 | 用户录入/选择 | 文本框/下拉框 | 可选 |
|
||
| `ontology_name` | 本体名称，例如 Rice Trait Ontology | 用户录入 | 文本框 | 必填；同一用户下建议唯一 |
|
||
| `version` | 本体版本，例如 2024.1、v2.0 | 用户录入 | 文本框 | 可选；建议与外部本体版本一致 |
|
||
|
||
### 录入建议
|
||
|
||
- 若系统只是内部使用，可先创建一个“默认本体”或“本地表型本体”。
|
||
- 若对接 Crop Ontology，建议保存 ontology 名称、版本、文档 URL。
|
||
- 本体删除前必须检查是否被 trait、method、scale、observation_variable 引用。
|
||
|
||
---
|
||
|
||
## 6.2 trait 性状
|
||
|
||
### 业务说明
|
||
|
||
`trait` 描述“测什么”。例如株高、叶长、穗长、倒伏等级、病害严重度、籽粒颜色。专业上 trait 可以拆成 `entity` 和 `attribute`：
|
||
|
||
```text
|
||
Trait = Entity + Attribute
|
||
例如：grain colour
|
||
entity = grain
|
||
attribute = colour
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| ------------------- | ----------------------------------------------------- | -------------------- | ----------------- | ---------------------------------------- |
|
||
| `id` | 性状主键，系统内部唯一标识 | 系统生成；导入可指定 | 隐藏/只读 | 必填、唯一 |
|
||
| `auth_user_id` | 数据所属用户或租户 | 登录上下文自动写入 | 隐藏 | 不允许手填 |
|
||
| `attribute` | 性状属性，即被观察的特征，如 height、colour、severity | 用户录入/本体选择 | 文本框/本体选择器 | 可选；若填写 PUI，建议同步填写 attribute |
|
||
| `attributepui` | 属性永久唯一标识，通常是 URI | 用户录入/本体带出 | 文本框/URL 输入框 | 可选；若填写建议唯一 |
|
||
| `entity` | 性状实体，即观察对象部位，如 plant、leaf、grain、root | 用户录入/本体选择 | 文本框/本体选择器 | 可选 |
|
||
| `entitypui` | 实体永久唯一标识，通常是 URI | 用户录入/本体带出 | 文本框/URL 输入框 | 可选；若填写建议唯一 |
|
||
| `main_abbreviation` | 性状主缩写，如 PH、GY、DTH | 用户录入 | 文本框 | 可选；同一 ontology 下建议唯一 |
|
||
| `status` | 性状状态，如 recommended、obsolete、legacy | 用户选择 | 下拉框 | 可选；推荐使用枚举 |
|
||
| `trait_class` | 性状分类，如 phenology、morphology、disease、quality | 用户选择/录入 | 下拉框/文本框 | 可选；建议字典化 |
|
||
| `trait_description` | 性状定义和说明 | 用户录入 | 多行文本 | 可选，但专业使用强烈建议填写 |
|
||
| `trait_name` | 性状名称，给用户看的名称 | 用户录入 | 文本框 | 必填；作为下拉展示名称 |
|
||
| `traitpui` | 性状永久唯一标识 | 用户录入/本体带出 | 文本框/URL 输入框 | 可选；若填写必须唯一 |
|
||
| `ontology_id` | 所属本体 | 从 ontology 选择 | 本体选择器 | 可选；必须引用存在的 ontology |
|
||
|
||
### 录入建议
|
||
|
||
- 简单业务可只填：`trait_name`、`trait_description`、`trait_class`。
|
||
- 专业数据交换场景建议填写：`entity`、`attribute`、`traitpui`、`ontology_id`。
|
||
- 不要把单位写进 trait。比如“株高 cm”不应该作为 trait，正确拆分是 trait=株高，scale=cm。
|
||
|
||
---
|
||
|
||
## 6.3 method 方法
|
||
|
||
### 业务说明
|
||
|
||
`method` 描述“怎么测”。同一个 trait 用不同方法测，会形成不同 observation_variable。例如：
|
||
|
||
```text
|
||
Trait: plant height
|
||
Method 1: tape measure
|
||
Method 2: drone image processing
|
||
Scale: cm
|
||
```
|
||
|
||
这两个变量不能混为一谈，因为它们的数据来源、误差和可比性不同。
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| -------------- | ------------------------------------------------------------ | ------------------ | ----------------- | -------------------------------- |
|
||
| `id` | 方法主键 | 系统生成 | 隐藏/只读 | 必填、唯一 |
|
||
| `auth_user_id` | 数据所属用户或租户 | 登录上下文自动写入 | 隐藏 | 不允许手填 |
|
||
| `description` | 方法说明，如测量位置、工具、采样规则 | 用户录入 | 多行文本 | 可选；建议必填 |
|
||
| `formula` | 如果该方法通过计算得到结果，填写公式 | 用户录入 | 文本框/公式编辑器 | 可选；需要格式提示 |
|
||
| `method_class` | 方法分类，如 measurement、estimation、computed、image_analysis | 用户选择/录入 | 下拉框/文本框 | 可选；建议字典化 |
|
||
| `methodpui` | 方法永久唯一标识 | 用户录入/本体带出 | 文本框/URL 输入框 | 可选；若填写建议唯一 |
|
||
| `name` | 方法名称 | 用户录入 | 文本框 | 必填；同一 ontology 下不建议重复 |
|
||
| `reference` | 方法参考文献、SOP、标准链接 | 用户录入 | 文本框/URL 输入框 | 可选；若为 URL 需校验格式 |
|
||
| `ontology_id` | 所属本体 | 从 ontology 选择 | 本体选择器 | 可选；必须引用存在的 ontology |
|
||
|
||
### 录入建议
|
||
|
||
- 方法页面应重点让用户说明“测量步骤”，否则后续数据不可复现。
|
||
- 对于人工评分，必须在 description 中说明评分标准，并通过 scale 配置有效分类值。
|
||
- 对于高通量图像方法，reference 建议填写算法版本、模型版本或 SOP 链接。
|
||
|
||
---
|
||
|
||
## 6.4 scale 标尺
|
||
|
||
### 业务说明
|
||
|
||
`scale` 描述“用什么尺度表达结果”。它决定 observation.value 的合法值、单位、数据类型、小数位和分类值。常见类型：
|
||
|
||
```text
|
||
Numerical: 株高 cm、产量 kg/ha
|
||
Ordinal: 倒伏等级 0-5、病害等级 1-9
|
||
Categorical: 籽粒颜色 red/yellow/white
|
||
Text: 描述性备注
|
||
Boolean: 是否开花、是否倒伏
|
||
Date: 开花日期
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| ----------------- | ----------------------------------------------------- | ------------------ | ----------------- | --------------------------------- |
|
||
| `id` | 标尺主键 | 系统生成 | 隐藏/只读 | 必填、唯一 |
|
||
| `auth_user_id` | 数据所属用户或租户 | 登录上下文自动写入 | 隐藏 | 不允许手填 |
|
||
| `data_type` | 数据类型，决定 observation.value 的输入控件和校验方式 | 用户选择 | 下拉框 | 必填；使用系统枚举 |
|
||
| `decimal_places` | 小数位数 | 用户录入 | 数字输入框 | 数值型可填；必须为非负整数 |
|
||
| `scale_name` | 标尺名称，如 cm、0-5 lodging score、disease score 1-9 | 用户录入 | 文本框 | 必填；同一 ontology 下建议唯一 |
|
||
| `scalepui` | 标尺永久唯一标识 | 用户录入/本体带出 | 文本框/URL 输入框 | 可选；若填写建议唯一 |
|
||
| `units` | 单位，如 cm、mm、kg/ha、days | 用户选择/录入 | 单位选择器/文本框 | 数值型建议必填；分类型可为空 |
|
||
| `valid_value_max` | 最大有效值 | 用户录入 | 数字输入框/文本框 | 数值/等级型校验；必须大于等于 min |
|
||
| `valid_value_min` | 最小有效值 | 用户录入 | 数字输入框/文本框 | 数值/等级型校验；必须小于等于 max |
|
||
| `ontology_id` | 所属本体 | 从 ontology 选择 | 本体选择器 | 可选；必须引用存在 ontology |
|
||
|
||
### 录入建议
|
||
|
||
- `data_type` 是动态表单核心字段。前端要根据它渲染 observation.value：
|
||
- Numerical：数字输入框，按 min/max/decimal_places 校验；
|
||
- Ordinal：数字或下拉，通常有 min/max；
|
||
- Categorical：下拉框，选项来自 `scale_valid_value_category`；
|
||
- Text：文本框；
|
||
- Boolean：开关/单选；
|
||
- Date：日期选择器。
|
||
- 如果 data_type 是分类型，必须至少配置一个 `scale_valid_value_category`。
|
||
- 如果 data_type 是数值型，建议填写单位和有效范围。
|
||
|
||
---
|
||
|
||
## 6.5 scale_valid_value_category 分类有效值
|
||
|
||
### 业务说明
|
||
|
||
`scale_valid_value_category` 是分类型或等级型 scale 的合法取值表。例如倒伏等级 0-5、病害等级 1-9、颜色 red/yellow/white。
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| ---------- | --------------------------------- | --------------------------- | ----------------- | ------------------------ |
|
||
| `id` | 分类值主键 | 系统生成 | 隐藏/只读 | 必填、唯一 |
|
||
| `label` | 用户界面展示文案，如 “0 - 不倒伏” | 用户录入 | 文本框 | 必填 |
|
||
| `value` | 实际保存值，如 0、1、red | 用户录入 | 文本框 | 必填；同一 scale 内唯一 |
|
||
| `scale_id` | 所属 scale | 从 scale 选择或由详情页带出 | Scale 选择器/隐藏 | 必选；必须引用存在 scale |
|
||
|
||
### 录入建议
|
||
|
||
- 在 scale 详情页中以内嵌表格维护。
|
||
- 保存 observation 时，如果 scale 是分类型，value 必须在该表中存在。
|
||
- label 可以给用户看，value 用于保存和导出，二者可以不同。
|
||
|
||
---
|
||
|
||
## 6.6 observation_variable 观测变量
|
||
|
||
### 业务说明
|
||
|
||
`observation_variable` 是真正进入采集模板的指标。它由 trait、method、scale 组合而成。
|
||
|
||
```text
|
||
observation_variable = trait + method + scale
|
||
例如：株高 + 尺子测量 + cm = 株高-尺测法-cm
|
||
```
|
||
|
||
它不是观测结果，而是“可以被测的一列数据”。
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| ---------------------- | ------------------------------------------ | ------------------------ | ----------------- | ---------------------------------------- |
|
||
| `id` | 观测变量主键 | 系统生成 | 隐藏/只读 | 必填、唯一 |
|
||
| `auth_user_id` | 数据所属用户或租户 | 登录上下文自动写入 | 隐藏 | 不允许手填 |
|
||
| `default_value` | 默认观测值，例如默认等级、默认文本 | 用户录入 | 动态控件 | 可选；按 scale 校验 |
|
||
| `documentationurl` | 变量说明文档链接 | 用户录入 | URL 输入框 | 可选；若填写必须合法 URL |
|
||
| `growth_stage` | 建议采集生育期，如 flowering、maturity | 用户录入/选择 | 下拉框/文本框 | 可选；建议字典化 |
|
||
| `institution` | 定义该变量的机构 | 用户录入 | 文本框 | 可选 |
|
||
| `language` | 变量语言，如 zh、en | 用户选择 | 下拉框 | 可选；建议 ISO 639-1 |
|
||
| `scientist` | 提交或维护该变量的科学家/负责人 | 用户录入/人员选择 | 文本框/选择器 | 可选 |
|
||
| `status` | 变量状态，如 recommended、obsolete、legacy | 用户选择 | 下拉框 | 可选；obsolete 不建议用于新 study |
|
||
| `submission_timestamp` | 变量提交时间 | 系统默认当前时间，可调整 | 日期时间选择器 | 可选；新增默认当前时间 |
|
||
| `crop_id` | 适用作物 | 从 crop 选择 | 作物选择器 | 可选；如果填写，下游 study 应尽量同 crop |
|
||
| `method_id` | 测定方法 | 从 method 选择 | 方法选择器 | 必选 |
|
||
| `ontology_id` | 所属本体 | 从 ontology 选择 | 本体选择器 | 可选 |
|
||
| `scale_id` | 标尺 | 从 scale 选择 | 标尺选择器 | 必选 |
|
||
| `trait_id` | 被测性状 | 从 trait 选择 | 性状选择器 | 必选 |
|
||
| `name` | 变量名称，采集矩阵列名 | 自动生成后允许修改 | 文本框 | 必填；同一 crop/ontology 下建议唯一 |
|
||
| `pui` | 变量永久唯一标识 | 用户录入/本体带出 | 文本框/URL 输入框 | 可选；若填写建议唯一 |
|
||
|
||
### 录入建议
|
||
|
||
- 新建变量采用“三段式选择”：先选 trait，再选 method，再选 scale。
|
||
- 系统自动生成 name，例如：`trait_name + method_name + scale_name`，用户可修改。
|
||
- 变量详情页应展示：被哪些 study 使用、已有多少 observation、是否仍推荐使用。
|
||
- 如果变量已经产生 observation，不建议修改 trait/method/scale，只能停用旧变量并创建新变量。
|
||
|
||
---
|
||
|
||
## 6.7 study_variable 研究采集指标
|
||
|
||
### 业务说明
|
||
|
||
`study_variable` 是 study 和 observation_variable 的多对多关系，表示某个 study 计划采集哪些指标。它是“配置采集模板”的动作痕迹。
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| ---------------- | --------------------- | ---------------------------- | ----------------- | --------------------------- |
|
||
| `study_db_id` | 所属 study | 从 study 选择或由工作台带出 | Study 选择器/隐藏 | 必选；必须引用存在 study |
|
||
| `variable_db_id` | 该 study 要采集的变量 | 从 observation_variable 选择 | 变量多选器 | 必选；必须引用存在 variable |
|
||
|
||
### 录入建议
|
||
|
||
- 在 Study 表型工作台的“指标清单”Tab 中维护。
|
||
- 支持批量选择变量和从历史 study 复制变量清单。
|
||
- 若某变量已有 observation，不允许从 study_variable 中直接移除，除非先处理已有观测数据。
|
||
|
||
---
|
||
|
||
## 6.8 observation_unit 观测单元
|
||
|
||
### 业务说明
|
||
|
||
`observation_unit` 是“被观测对象”。通常是 plot 或 plant，也可以是 field、block、sub-plot、sample 等。它连接了 Core 上下文和材料来源，是表型数据的入口，也可以成为后续 genotyping sample 的来源。
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| ----------------------- | ------------------------------------ | ------------------------- | ----------------- | -------------------------------------------------- |
|
||
| `id` | 观测单元主键 | 系统生成；导入可指定 | 隐藏/只读 | 必填、唯一 |
|
||
| `auth_user_id` | 数据所属用户或租户 | 登录上下文自动写入 | 隐藏 | 不允许手填 |
|
||
| `observation_unit_name` | 观测单元名称，如 Plot-001、Plant-003 | 用户录入/批量生成 | 文本框 | 必填；同一 study 内建议唯一 |
|
||
| `observation_unitpui` | 观测单元永久唯一标识 | 用户录入/系统生成 | 文本框/URL 输入框 | 可选；若填写建议唯一 |
|
||
| `crop_id` | 作物 | 由 study 自动带出，可只读 | 作物选择器/只读 | 可选但建议有；需与 study.crop 一致 |
|
||
| `cross_id` | 材料来源 cross | 从 cross_entity 选择 | Cross 选择器 | 可选；与 germplasm/seed_lot 至少建议选一个材料来源 |
|
||
| `germplasm_id` | 材料来源 germplasm | 从 germplasm 选择 | 材料选择器 | 可选；常用字段 |
|
||
| `program_id` | 项目 | 由 study 自动带出 | 项目选择器/只读 | 可选但建议有；需与 study.program 一致 |
|
||
| `seed_lot_id` | 种子批次来源 | 从 seed_lot 选择 | SeedLot 选择器 | 可选；田间播种建议填写 |
|
||
| `study_id` | 所属 study | 从 study 选择或工作台带出 | Study 选择器/隐藏 | 必选 |
|
||
| `trial_id` | 所属 trial | 由 study 自动带出 | Trial 选择器/只读 | 可选但建议有；需与 study.trial 一致 |
|
||
|
||
### 录入建议
|
||
|
||
- 推荐从 Study 表型工作台批量生成，不建议逐条手工建。
|
||
- 必须支持田间布局字段：field、block、rep、plot、row、column、plant。若当前表没有这些字段，应通过 position/level 附属表或 additional_info 保存。
|
||
- `germplasm_id` 代表材料身份；`seed_lot_id` 代表实际播种批次；二者建议都保留。
|
||
- 选择 seed_lot 时可自动带出 germplasm，但不应强行覆盖用户选择。
|
||
|
||
### 观测层级建议
|
||
|
||
| 层级 | 含义 | 例子 |
|
||
| ------ | -------------- | ---------- |
|
||
| field | 田块或试验场 | Field-01 |
|
||
| block | 区组 | Block-01 |
|
||
| rep | 重复 | Rep-01 |
|
||
| plot | 小区 | Plot-001 |
|
||
| plant | 单株 | Plant-001 |
|
||
| sample | 样本级观测对象 | Sample-001 |
|
||
|
||
---
|
||
|
||
## 6.9 event 事件
|
||
|
||
### 业务说明
|
||
|
||
`event` 记录发生在 study 或 observation_unit 上的离散事件。它既可以是处理的一部分，也可以是影响结果的外部背景。例如播种、移栽、施肥、灌溉、打药、收获、采样、暴雨、台风、病害暴发等。
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| ------------------- | ---------------------------------------------------------- | ------------------------- | ----------------- | -------------------------- |
|
||
| `id` | 事件主键 | 系统生成 | 隐藏/只读 | 必填、唯一 |
|
||
| `auth_user_id` | 数据所属用户或租户 | 登录上下文自动写入 | 隐藏 | 不允许手填 |
|
||
| `event_description` | 事件说明，如“台风后倒伏严重” | 用户录入 | 多行文本 | 可选；异常事件建议必填 |
|
||
| `event_type` | 事件类型名称，如 fertilizer、irrigation、planting、harvest | 用户选择/录入 | 下拉框/文本框 | 必填；建议使用事件类型字典 |
|
||
| `event_type_db_id` | 事件类型 ID，可引用标准事件类型字典 | 用户选择/系统带出 | 选择器/隐藏 | 可选 |
|
||
| `study_id` | 事件所属 study | 从 study 选择或工作台带出 | Study 选择器/隐藏 | 必选 |
|
||
|
||
### 录入建议
|
||
|
||
- 在 Study 表型工作台的“事件”Tab 中维护。
|
||
- 新增事件时先选择作用范围：整个 study 或部分 observation_unit。
|
||
- 如果只作用于部分 plot/plant，必须通过 `event_observation_units` 记录范围。
|
||
- 事件发生时间字段在你当前表结构中未显式列出，但业务上非常重要；如果数据库已有 event_date/time 字段，应强制录入；如果没有，建议补字段或放入 additional_info。
|
||
|
||
---
|
||
|
||
## 6.10 event_param 事件参数
|
||
|
||
### 业务说明
|
||
|
||
`event_param` 是事件的参数明细。例如施肥事件可以有肥料类型、剂量、单位；灌溉事件可以有水量、持续时间；打药事件可以有药剂名称、浓度、剂量。
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| ------------------- | ------------------------------------- | ----------------- | ----------------- | ------------------------- |
|
||
| `id` | 事件参数主键 | 系统生成 | 隐藏/只读 | 必填、唯一 |
|
||
| `code` | 参数代码，如 N_RATE、IRR_VOL | 用户录入/字典带出 | 文本框 | 可选；同一事件内建议唯一 |
|
||
| `description` | 参数解释 | 用户录入 | 多行文本 | 可选 |
|
||
| `key` | 参数键，如 fertilizerType、dose、unit | 用户录入/字典选择 | 文本框 | 必填；同一事件内不应重复 |
|
||
| `name` | 参数名称，如 氮肥施用量 | 用户录入 | 文本框 | 可选 |
|
||
| `rdf_value` | RDF 或本体语义值 | 用户录入/系统带出 | 文本框 | 可选；普通业务可隐藏 |
|
||
| `units` | 参数单位，如 kg/ha、mm、L | 用户选择/录入 | 单位选择器 | 可选；数值参数建议必填 |
|
||
| `value` | 参数值 | 用户录入 | 动态控件 | 可选；若 key 需要值则必填 |
|
||
| `value_description` | 参数值说明 | 用户录入 | 多行文本 | 可选 |
|
||
| `event_id` | 所属事件 | 由事件详情页带出 | Event 选择器/隐藏 | 必选 |
|
||
|
||
### 录入建议
|
||
|
||
- 前端以键值表格方式维护。
|
||
- 可以为常用事件类型配置参数模板，例如 fertilizer 事件默认出现 fertilizerType、amount、units。
|
||
- 参数值是否必填取决于事件类型配置。
|
||
|
||
---
|
||
|
||
## 6.11 event_observation_units 事件作用范围
|
||
|
||
### 业务说明
|
||
|
||
`event_observation_units` 记录事件作用到哪些 observation_unit。比如一次施肥作用于整个 study，则可以不逐个绑定；如果某个处理只作用于部分 plot，则必须明确绑定。
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| ---------------------- | ------------ | --------------------------------------- | ----------------- | ------------------------ |
|
||
| `event_entity_id` | 事件 | 由事件详情页带出 | Event 选择器/隐藏 | 必选 |
|
||
| `observation_units_id` | 事件作用对象 | 从当前 study 的 observation_unit 中选择 | 多选器/表格 | 必选；必须属于同一 study |
|
||
|
||
### 录入建议
|
||
|
||
- 支持按 block、rep、plot 范围批量选择。
|
||
- 如果事件作用于整个 study，可以在 event 上记录 scope=study，不必生成大量关系记录。
|
||
- 如果 event_observation_units 有记录，所有 observation_units 必须属于 event.study_id。
|
||
|
||
---
|
||
|
||
## 6.12 image 图像
|
||
|
||
### 业务说明
|
||
|
||
`image` 用于保存图片或图片元数据。图片可以是人工拍摄、无人机、固定相机、显微图、病害图片等。图片可以直接关联 observation_unit，也可以通过 `image_observations` 关联具体 observation。
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| --------------------- | ------------------------------------- | ------------------------ | ------------------- | -------------------------------------- |
|
||
| `id` | 图片主键 | 系统生成 | 隐藏/只读 | 必填、唯一 |
|
||
| `auth_user_id` | 数据所属用户或租户 | 登录上下文自动写入 | 隐藏 | 不允许手填 |
|
||
| `copyright` | 图片版权或授权说明 | 用户录入 | 文本框 | 可选 |
|
||
| `description` | 图片说明，如“Plot-003 台风后倒伏照片” | 用户录入 | 多行文本 | 可选，建议填写 |
|
||
| `image_data` | 图片二进制内容 | 用户上传 | 文件上传 | 与 `imageurl` 至少一个；限制大小和格式 |
|
||
| `image_file_name` | 图片文件名 | 上传时自动填充 | 只读/文本框 | 可选；上传时自动生成 |
|
||
| `image_file_size` | 文件大小 | 上传时自动识别 | 只读 | 可选；应限制最大大小 |
|
||
| `image_height` | 图片高度 | 上传后自动识别 | 只读/数字框 | 可选；必须为非负整数 |
|
||
| `imagemimetype` | MIME 类型，如 image/jpeg、image/png | 上传后自动识别 | 只读/下拉框 | 可选；只允许图片 MIME 类型 |
|
||
| `imageurl` | 外部图片 URL 或对象存储 URL | 用户填写/上传后生成 | URL 输入框 | 与 `image_data` 至少一个；URL 格式校验 |
|
||
| `image_width` | 图片宽度 | 上传后自动识别 | 只读/数字框 | 可选；必须为非负整数 |
|
||
| `name` | 图片名称 | 用户录入/文件名带出 | 文本框 | 必填 |
|
||
| `time_stamp` | 拍摄或上传时间 | 用户录入/系统默认 | 日期时间选择器 | 可选；建议填写拍摄时间 |
|
||
| `coordinates_id` | 图片坐标 | 地图取点/坐标对象选择 | 地图控件/坐标选择器 | 可选；建议支持 Point/Polygon |
|
||
| `observation_unit_id` | 所属观测单元 | 从 observation_unit 选择 | 观测单元选择器 | 可选；若填写应属于同一 study 上下文 |
|
||
|
||
### 录入建议
|
||
|
||
- 推荐图片文件存对象存储，数据库只存 URL 和元数据，避免 bytea 过大。
|
||
- 手机拍照或无人机导入时，应自动提取文件名、大小、宽高、MIME、拍摄时间和 GPS 信息。
|
||
- 对无人机俯拍图，可保存图像中心点，也可保存图像覆盖范围 Polygon。
|
||
|
||
---
|
||
|
||
## 6.13 image_observations 图片与观测值关系
|
||
|
||
### 业务说明
|
||
|
||
`image_observations` 表示某张图片支持或关联哪些 observation。比如一张倒伏照片可以关联一个 plot 的倒伏等级 observation。
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| ----------------- | ---------- | ------------------- | ------------------ | ---------------------------------------- |
|
||
| `image_entity_id` | 图片 | 由图片详情页带出 | Image 选择器/隐藏 | 必选 |
|
||
| `observations_id` | 关联观测值 | 从 observation 选择 | Observation 选择器 | 必选；建议与图片的 observation_unit 一致 |
|
||
|
||
### 录入建议
|
||
|
||
- 图片详情页支持关联多个 observation。
|
||
- observation 详情页也支持反向查看相关图片。
|
||
- 如果图片已绑定 observation_unit，则关联 observation 时应过滤为同一 observation_unit 下的 observation。
|
||
|
||
---
|
||
|
||
## 6.14 observation 观测值
|
||
|
||
### 业务说明
|
||
|
||
`observation` 是 Phenotyping 模块最核心的事实表。它表示“某个 observation_unit 在某个 observation_variable 上的一次实际采集结果”。
|
||
|
||
```text
|
||
observation_unit = Plot-003
|
||
observation_variable = 株高-尺测法-cm
|
||
value = 112.5
|
||
observation_time_stamp = 2026-07-12 09:30
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 业务意义 | 录入方式 | 控件建议 | 校验规则 |
|
||
| ------------------------- | ------------------ | ---------------------------------------- | ------------------- | ------------------------------------------ |
|
||
| `id` | 观测值主键 | 系统生成；导入可指定 | 隐藏/只读 | 必填、唯一 |
|
||
| `auth_user_id` | 数据所属用户或租户 | 登录上下文自动写入 | 隐藏 | 不允许手填 |
|
||
| `collector` | 采集人 | 用户选择/登录用户带出 | 人员选择器/文本框 | 可选；人工采集建议填写 |
|
||
| `observation_time_stamp` | 观测时间 | 用户录入/采集设备带出 | 日期时间选择器 | 建议必填；按 ISO 8601 保存 |
|
||
| `uploaded_by` | 上传人 | 登录用户自动写入 | 只读 | 可选；批量导入时自动填 |
|
||
| `value` | 实际观测值 | 用户录入/导入/设备上传 | 动态控件 | 必填；按 variable.scale 校验 |
|
||
| `crop_id` | 作物上下文 | 由 observation_unit 或 study 自动带出 | 只读/隐藏 | 可选但建议保存；需与 observation_unit 一致 |
|
||
| `geo_coordinates_id` | 观测发生坐标 | 地图取点/设备 GPS | 地图控件/坐标选择器 | 可选；坐标需合法 |
|
||
| `observation_unit_id` | 被观测对象 | 从 observation_unit 选择或矩阵行带出 | 观测单元选择器/隐藏 | 必选 |
|
||
| `observation_variable_id` | 观测变量 | 从 observation_variable 选择或矩阵列带出 | 变量选择器/隐藏 | 必选 |
|
||
| `program_id` | 项目上下文 | 由 observation_unit/study 自动带出 | 只读/隐藏 | 可选但建议保存 |
|
||
| `season_id` | 季节 | 从 study season 或用户选择 | Season 选择器 | 可选；多季节 study 建议填写 |
|
||
| `study_id` | 所属 study | 由 observation_unit 自动带出 | 只读/隐藏 | 必选；需与 observation_unit.study 一致 |
|
||
| `trial_id` | 所属 trial | 由 observation_unit/study 自动带出 | 只读/隐藏 | 可选但建议保存 |
|
||
|
||
### 录入建议
|
||
|
||
- 普通录入优先走矩阵：行是 observation_unit，列是 observation_variable。
|
||
- 单条表单只用于补录、纠错、详情编辑。
|
||
- value 必须使用 observation_variable.scale 决定控件和校验：
|
||
- 数值型：数字、小数位、范围；
|
||
- 分类型：只能从 valid category 中选；
|
||
- 日期型：日期格式；
|
||
- 布尔型：true/false；
|
||
- 文本型：长度限制。
|
||
- 同一 `observation_unit_id + observation_variable_id + observation_time_stamp` 可允许重复，但必须在页面展示重复标记、采集人和上传来源。
|
||
|
||
---
|
||
|
||
# 7. 跨表联动规则
|
||
|
||
| 场景 | 联动规则 |
|
||
| ------------------------- | ------------------------------------------------------------ |
|
||
| 创建 observation_variable | 必须先选择 trait、method、scale；系统自动生成变量名称 |
|
||
| 配置 study_variable | 变量选择器优先展示同 crop 或未限定 crop 的变量 |
|
||
| 创建 observation_unit | 选择 study 后自动带出 crop、program、trial |
|
||
| 选择 seed_lot | 可自动带出 germplasm，但允许用户确认 |
|
||
| 录入 observation | 选择 observation_unit 后自动带出 study、trial、program、crop |
|
||
| 录入 observation.value | 根据 observation_variable.scale 动态渲染控件和校验 |
|
||
| 新增 event | 从 study 工作台进入时自动带出 study_id |
|
||
| 选择事件作用范围 | 只能选择同一 study 下的 observation_unit |
|
||
| 上传 image | 如果从 observation_unit 详情页上传，自动绑定 observation_unit_id |
|
||
| 关联 image_observations | 如果图片已绑定 observation_unit，只能关联同 observation_unit 的 observation |
|
||
|
||
---
|
||
|
||
# 8. 删除和停用规则
|
||
|
||
| 对象 | 删除限制 |
|
||
| -------------------- | ------------------------------------------------------------ |
|
||
| ontology | 已被 trait/method/scale/variable 引用时不可物理删除 |
|
||
| trait | 已被 observation_variable 或 germplasm_attribute_definition 引用时不可物理删除 |
|
||
| method | 已被 observation_variable 引用时不可物理删除 |
|
||
| scale | 已被 observation_variable 或 attribute definition 引用时不可物理删除 |
|
||
| observation_variable | 已产生 observation 时不可删除，只能停用或设为 obsolete |
|
||
| study_variable | 若已有该变量的 observation，不允许直接移除 |
|
||
| observation_unit | 已有 observation、image、event、sample 时不可删除 |
|
||
| event | 已有关联 event_param 或 event_observation_units 时删除需级联确认或禁止 |
|
||
| image | 已关联 observation 时不可直接删除，应先解除关系或作废 |
|
||
| observation | 原始数据原则上不建议物理删除；建议保留修改历史或作废状态 |
|
||
|
||
---
|
||
|
||
# 9. 批量导入要求
|
||
|
||
## 9.1 ObservationUnit 导入模板
|
||
|
||
必需列建议：
|
||
|
||
```text
|
||
study_id 或 study_name
|
||
observation_unit_name
|
||
observation_level_name
|
||
observation_level_code
|
||
```
|
||
|
||
强烈建议列：
|
||
|
||
```text
|
||
germplasm_id 或 germplasm_name
|
||
seed_lot_id 或 seed_lot_name
|
||
block
|
||
rep
|
||
plot
|
||
row
|
||
column
|
||
```
|
||
|
||
## 9.2 ObservationVariable 导入模板
|
||
|
||
必需列建议：
|
||
|
||
```text
|
||
trait_name
|
||
method_name
|
||
scale_name
|
||
variable_name
|
||
```
|
||
|
||
可选列：
|
||
|
||
```text
|
||
trait_pui
|
||
method_pui
|
||
scale_pui
|
||
variable_pui
|
||
crop_name
|
||
growth_stage
|
||
status
|
||
```
|
||
|
||
## 9.3 Observation 矩阵导入模板
|
||
|
||
推荐格式：
|
||
|
||
```text
|
||
observation_unit_name,germplasm_name,collection_time,collector,PlantHeight_cm,LodgingScore_0_5,DiseaseScore_1_9
|
||
Plot-001,华占,2026-07-12T09:30:00+08:00,张三,112.5,1,2
|
||
Plot-002,抗倒伏A,2026-07-12T09:35:00+08:00,张三,98.3,0,1
|
||
```
|
||
|
||
导入规则：
|
||
|
||
1. 每个变量列必须能映射到一个 observation_variable。
|
||
2. 每一行必须能匹配一个 observation_unit。
|
||
3. 每个非空单元格生成一条 observation。
|
||
4. 空值不生成 observation，除非用户选择“导入为空观测”。
|
||
5. 导入前必须预校验，错误报告包含行号、列名、错误原因、建议修复方式。
|
||
|
||
## 9.4 Image 导入模板
|
||
|
||
必需列建议：
|
||
|
||
```text
|
||
image_name
|
||
image_url 或 image_file
|
||
```
|
||
|
||
可选列：
|
||
|
||
```text
|
||
observation_unit_name
|
||
observation_id
|
||
capture_time
|
||
longitude
|
||
latitude
|
||
polygon
|
||
copyright
|
||
description
|
||
```
|
||
|
||
---
|
||
|
||
# 10. 后端接口建议
|
||
|
||
## 10.1 主数据接口
|
||
|
||
```text
|
||
GET /ontologies
|
||
POST /ontologies
|
||
GET /ontologies/{id}
|
||
PUT /ontologies/{id}
|
||
DELETE /ontologies/{id}
|
||
|
||
GET /traits
|
||
POST /traits
|
||
GET /traits/{id}
|
||
PUT /traits/{id}
|
||
|
||
GET /methods
|
||
POST /methods
|
||
GET /methods/{id}
|
||
PUT /methods/{id}
|
||
|
||
GET /scales
|
||
POST /scales
|
||
GET /scales/{id}
|
||
PUT /scales/{id}
|
||
GET /scales/{id}/valid-values
|
||
POST /scales/{id}/valid-values
|
||
|
||
GET /observation-variables
|
||
POST /observation-variables
|
||
GET /observation-variables/{id}
|
||
PUT /observation-variables/{id}
|
||
|
||
GET /studies/{studyId}/variables
|
||
POST /studies/{studyId}/variables
|
||
DELETE /studies/{studyId}/variables/{variableId}
|
||
|
||
GET /studies/{studyId}/observation-units
|
||
POST /studies/{studyId}/observation-units/batch-generate
|
||
POST /observation-units
|
||
PUT /observation-units/{id}
|
||
|
||
GET /studies/{studyId}/events
|
||
POST /studies/{studyId}/events
|
||
GET /events/{id}/params
|
||
POST /events/{id}/params
|
||
POST /events/{id}/observation-units
|
||
|
||
GET /images
|
||
POST /images
|
||
POST /images/upload
|
||
POST /images/{id}/observations
|
||
|
||
GET /observations
|
||
POST /observations
|
||
POST /observations/matrix
|
||
POST /observations/import
|
||
```
|
||
|
||
## 10.2 选择器接口
|
||
|
||
```text
|
||
GET /selectors/ontologies
|
||
GET /selectors/traits?ontologyId=&keyword=
|
||
GET /selectors/methods?ontologyId=&keyword=
|
||
GET /selectors/scales?ontologyId=&dataType=&keyword=
|
||
GET /selectors/observation-variables?cropId=&studyId=&keyword=
|
||
GET /selectors/studies?programId=&trialId=&keyword=
|
||
GET /selectors/observation-units?studyId=&level=&germplasmId=&keyword=
|
||
GET /selectors/events?studyId=&eventType=&keyword=
|
||
GET /selectors/images?observationUnitId=&keyword=
|
||
```
|
||
|
||
---
|
||
|
||
# 11. 测试验收清单
|
||
|
||
1. 创建 trait 时，`trait_name` 必填。
|
||
2. 创建 method 时，`name` 必填。
|
||
3. 创建 scale 时，`scale_name` 和 `data_type` 必填。
|
||
4. 分类型 scale 没有 valid value 时，应提示或禁止用于 observation_variable。
|
||
5. 创建 observation_variable 时，trait、method、scale 必选。
|
||
6. observation_variable 名称可自动生成，也允许用户手动修改。
|
||
7. 配置 study_variable 时，不能重复绑定同一个 variable。
|
||
8. 创建 observation_unit 时，study 必选。
|
||
9. 选择 study 后，crop、program、trial 自动带出。
|
||
10. 同一 study 内 observation_unit_name 重复时提示。
|
||
11. observation_unit 至少建议绑定 germplasm、seed_lot、cross 中一个材料来源。
|
||
12. 创建 event 时，study 和 event_type 必填。
|
||
13. event 绑定 observation_unit 时，所有 observation_unit 必须属于该 event 的 study。
|
||
14. 图片上传时，image_data 和 imageurl 至少一个存在。
|
||
15. 图片 MIME 类型必须是允许的图片类型。
|
||
16. observation 创建时，observation_unit、observation_variable、value 必填。
|
||
17. observation.value 必须按 scale.data_type 校验。
|
||
18. 数值型 value 必须在 valid_value_min 和 valid_value_max 范围内。
|
||
19. 分类型 value 必须属于 scale_valid_value_category。
|
||
20. observation 的 study/trial/program/crop 必须与 observation_unit 上下文一致。
|
||
21. 矩阵录入保存时，每个有效单元格生成一条 observation。
|
||
22. 导入失败时必须返回行号、字段、错误原因和修复建议。
|
||
23. 已产生 observation 的 observation_variable 不允许直接删除。
|
||
24. 已被 observation、image、event、sample 引用的 observation_unit 不允许物理删除。
|
||
25. 所有日期时间字段按 ISO 8601 保存，并保留时区或统一转换为 UTC。
|
||
|
||
---
|
||
|
||
# 12. 开发实现重点
|
||
|
||
1. `observation_variable` 是表型指标定义，不是观测值。
|
||
2. `observation_unit` 是被观测对象，不是实际测量值。
|
||
3. `observation` 才是真正的表型事实数据。
|
||
4. `value` 字段虽然数据库是字符串，但前端和后端必须按 scale 做类型校验。
|
||
5. `study` 是 Phenotyping 的核心上下文入口，几乎所有表型数据都应能追溯到 study。
|
||
6. 表型采集页面应优先做矩阵录入，不要只做单条 CRUD。
|
||
7. 图片不要直接塞数据库大字段为主，建议走对象存储 URL + 元数据。
|
||
8. Event 不只是备注，它是解释表型差异的重要上下文，应支持作用范围和参数化。
|
||
|