# 数据录入需求总览

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

```text
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 |

## 总体录入链路

```mermaid
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。