brapi-java/docs/requirements/01-core-data-entry-requirements.md

Core 模块业务需求文档

1. 模块定位

Core 是项目、试验、地点、人员、季节的基础上下文模块，是所有业务数据的总上游。它不是普通字典维护，而是为后续 Germplasm/Seed、Phenotyping、Genotyping 提供“这批数据属于哪个项目、哪次试验、哪个地点、哪个年度、谁负责”的业务台账。

推荐先完成 Core 录入，再录入 Germplasm、Phenotyping、Genotyping。

2. 真实业务理解

Core 不只是“基础字典”，它在真实育种业务里是项目台账：回答“谁在什么项目、什么地点、什么年度、做哪一次试验”。后续所有材料、田间布置、表型采集、样本检测、基因型结果，都需要回到 Core 上下文里解释。

最常见的业务链路是：

crop 作物
  -> program 长期育种项目
  -> trial 某一批试验/区域试验
  -> study 一次真正落地执行的试验

例如：

crop: 水稻
program: 水稻抗倒伏育种项目
trial: 2026 湖北区域试验
location: 荆门试验站
season: 2026 春季
study: 2026 荆门水稻抗倒伏田间试验

这里最关键的是 study。program 更像长期项目，trial 是试验批次，study 才是具体执行单元。后续 observation_unit、event、observation、plate、sample、variantset 都会直接或间接挂到 study 上。

3. 用户角色和使用场景

角色	主要职责	典型入口	权限重点
项目管理员	维护作物、项目、人员、地点等基础台账	crop、person、program、location 列表页	可新增/编辑基础数据，可停用未被引用的数据
试验负责人	创建 trial 和 study，维护联系人、季节、试验设计	trial 列表、study 列表、Study 工作台	可创建试验上下文，可配置 study 联系人、season、变量清单
数据录入员	进入 Study 工作台继续录观测单元、表型、样本	Study 工作台	主要使用下游入口，一般不能删除 Core 主数据
数据管理员	处理导入、导出、停用、删除校验、数据修复	导入导出页、数据质量页	可批量导入、导出、停用，有删除前引用检查权限

3.1 项目管理员场景

项目管理员先建立 crop、person、program、location。例如创建“水稻抗倒伏育种项目”，选择 crop=水稻，负责人=张三。录完后，试验负责人才能在该项目下创建 trial 和 study。

3.2 试验负责人场景

试验负责人创建“2026 湖北区域试验”和“2026 荆门水稻抗倒伏田间试验”。创建 study 时选择 program、trial、location、season，保存后进入 Study 工作台。

3.3 数据录入员场景

数据录入员通常不从 crop/program 开始，而是从 Study 工作台进入，继续录 observation unit、observation、sample 等下游数据。

3.4 数据管理员场景

数据管理员负责批量导入 Core 数据、处理重复数据、做删除/停用前检查。例如某 trial 已有关联 study 时，不允许物理删除，只能停用。

用户为什么要录 Core

用户问题	由哪些表回答	录完能做什么
我们做什么作物？	crop	限定项目、材料、变量、图谱的作物范围
谁负责项目和试验？	person、program.lead_person_id、trial_contact、study_contact	项目责任追踪、联系人展示、权限和通知
这是哪个长期育种项目？	program	聚合多个 trial/study、材料、样本、结果
这是哪一批试验？	trial	管理区域试验、年度试验、批次试验
试验在哪里、哪一季做？	location、season、study_season	支持多地点、多季节筛选和统计
哪一次试验真正落地执行？	study	进入 Study 工作台，继续录观测单元、表型、样本、基因型

6. 页面需求

Core 的核心页面不应该只是表单 CRUD，而应该围绕 study 做“Study 工作台”。

6.1 Study 工作台

Study 工作台
├─ 基本信息：名称、编号、类型、起止日期、负责人
├─ 上下文：crop、program、trial、location、season
├─ 试验设计：experimental design、observation level、growth facility
├─ 联系人/附件：study_contact、data_link、external_references
├─ 观测单元：跳转 observation_unit
├─ 表型数据：跳转 observation / matrix
├─ 样本与样本板：跳转 sample / plate
├─ 基因型数据：跳转 variantset / callset / allele_call
└─ 导入导出：按 study 导入观测单元、表型、样本、基因型

6.2 Crop 列表页

项目	需求
功能	查询 crop；新增、编辑、查看详情、停用
筛选	关键词搜索，按 crop_name 模糊匹配
表格字段	crop_name、下游 program 数、下游 study 数、状态
操作	查看、编辑、停用
验收标准	crop 已被 program/germplasm/study 引用时，不允许物理删除

6.3 Person 列表页

项目	需求
功能	查询人员；新增、编辑、查看详情、停用
筛选	姓名、邮箱、机构
表格字段	姓名、邮箱、电话、机构、负责项目数、参与 study 数
操作	查看、编辑、停用
验收标准	邮箱格式正确；作为负责人或联系人被引用时，不允许物理删除

6.4 Program 列表页

项目	需求
功能	查询 program；新增、编辑、查看详情、停用
筛选	crop、负责人、program_type、关键词
表格字段	name、abbreviation、crop、负责人、trial 数、study 数
操作	查看、编辑、停用、查看 trial、查看 study
验收标准	创建 program 时必须选择 crop；负责人来自 person 选择器

6.5 Trial 列表页

项目	需求
功能	查询 trial；新增、编辑、查看详情、停用
筛选	crop、program、active、起止日期、关键词
表格字段	trial_name、program、crop、start_date、end_date、active
操作	查看、编辑、停用、查看 study
验收标准	选择 program 后自动带出 crop；已被 study 引用时不允许物理删除

6.6 Location 列表页

项目	需求
功能	查询 location；新增、编辑、查看详情、停用
筛选	crop、program、location_type、country、关键词
表格字段	location_name、location_type、country、program、crop、父级地点
操作	查看、编辑、停用、地图查看
验收标准	父级地点不能选择自己；坐标字段格式合法

6.7 Season 列表页

项目	需求
功能	查询 season；新增、编辑、查看详情、停用
筛选	year、season
表格字段	year、season、关联 study 数
操作	查看、编辑、停用
验收标准	同一年份内 season 名称不建议重复

6.8 Study 列表页

项目	需求
功能	查询 study；新增、编辑、查看详情、停用；点击 study 名称进入 Study 工作台
筛选	crop、program、trial、location、season、active、study_type、关键词
表格字段	study_name、study_code、program、trial、location、start_date、end_date、active
操作	查看、编辑、停用、进入工作台
验收标准	选择 program 后只展示该 program 下的 trial；选择 trial 后自动带出 crop；已有 observation_unit/sample/observation 时不能物理删除

6.9 Study 新增/编辑页

区域	字段/功能	要求
基本信息	study_name、study_code、study_type、active、start_date、end_date	study_name 必填；结束日期不早于开始日期
上下文	crop、program、trial、location、season	program、trial、crop、location 必选；program -> trial 联动
说明信息	study_description、cultural_practices、observation_units_description、license、documentationurl	URL 格式校验
联系人	study_contact	多选 person，可增删
季节	study_season	可多选 season
提交后	保存成功进入 Study 工作台	新建成功后自动跳转

6.10 List 详情页

项目	需求
功能	维护 list 和 list_item
页面形态	顶部 list 基本信息，下方 list_item 表格
操作	新增 item、批量导入 item、删除 item、排序
验收标准	同一 list 内 item 不重复

哪些表是业务动作痕迹

动作	痕迹表	说明
给 trial 添加联系人	trial_contact	trial 与 person 的关系，不是独立主数据
给 study 添加联系人	study_contact	study 与 person 的关系
给 study 绑定季节	study_season	一个 study 可关联多个 season
给 study 绑定观测变量	study_variable	表示该 study 要采集哪些指标
给 trial 记录出版物	trial_publication	trial 的文献/报告引用
给 list 添加成员	list_item	list 的明细项，是分组动作留下的记录

4. 核心业务流程

4.1 新建 Core 试验上下文流程

1. 用户创建 crop。
2. 用户创建 person。
3. 用户创建 program，并选择 crop 和负责人 lead_person_id。
4. 用户创建 location，可选绑定 program 和 crop。
5. 用户创建 trial，选择 program 后自动带出 crop。
6. 用户创建 season。
7. 用户创建 study，按 program -> trial -> location -> season 的顺序选择上下文。
8. study 创建成功后，系统自动进入 Study 工作台。

4.2 业务流程图

flowchart TD
    A["创建 crop"] --> B["创建 person"]
    B --> C["创建 program<br/>选择 crop / lead person"]
    C --> D["创建 location<br/>可选 program / crop"]
    C --> E["创建 trial<br/>选择 program 自动带出 crop"]
    E --> F["创建 season"]
    D --> G["创建 study<br/>选择 program -> trial -> location -> season"]
    F --> G
    G --> H["进入 Study 工作台"]

5. 核心对象说明

5.1 crop 作物

数据库录入

项目	要求
表	crop
前置依赖	无
主要字段	作物 ID、作物名称、公共作物名、描述
下游引用	program、location、trial、study、germplasm、observation_variable、genome_map

界面形态

列表页展示作物名称、描述、更新时间、下游引用数量。新增页是轻量表单，重点是作物名称唯一校验。详情页展示该作物下的项目、试验、研究、种质、图谱入口。

校验规则

1. 作物名称必填且唯一。
2. 已被下游引用的作物不能直接删除，只允许停用或提示引用关系。

5.2 person 人员

数据库录入

项目	要求
表	person
前置依赖	无
主要字段	姓名、邮箱、机构、联系方式、角色
下游引用	program.lead_person_id、trial_contact、study_contact、list.list_owner_person_id

界面形态

列表页支持姓名、邮箱、机构筛选。新增/编辑页用联系人表单。详情页展示负责的 program、参与的 trial/study、拥有的 list。

校验规则

1. 姓名必填。
2. 邮箱格式正确。
3. 同一邮箱不建议重复录入。

5.3 program 项目

数据库录入

项目	要求
表	program
前置依赖	crop，可选 person
主要字段	项目名称、作物、负责人、缩写、目标、描述
下游引用	trial、study、location、crossing_project、seed_lot、plate、sample

界面形态

新增页分为“基本信息”和“负责人/作物”两组。作物和负责人使用搜索选择器。详情页 Tab 展示 trial、study、location、seed lot、sample。

校验规则

1. 项目名称必填。
2. 作物必选。
3. 选择负责人时必须存在于 person。

5.4 location 地点

数据库录入

项目	要求
表	location
前置依赖	可选 crop、program、父级 location、坐标
主要字段	地点名称、地点类型、国家/地区、经纬度、父级地点、所属项目
下游引用	study、seed_lot

界面形态

列表页支持地图/表格两种视图。新增页包含基本信息、行政区、坐标、父级地点。详情页展示该地点下的 study 和 seed lot。

校验规则

1. 地点名称必填。
2. 经纬度格式合法。
3. 父级地点不能选择自己。

5.5 trial 试验批次

数据库录入

项目	要求
表	trial
前置依赖	program、crop
主要字段	试验名称、项目、作物、开始/结束日期、联系人、出版物
下游引用	study、observation_unit、observation、plate、sample

界面形态

新增页包含基本信息、项目作物、联系人、出版物四个区域。联系人用可增删表格选择 person。详情页展示 study 列表和 phenotyping/genotyping 入口。

校验规则

1. 试验名称必填。
2. program 与 crop 必须匹配。
3. 结束日期不能早于开始日期。

5.6 season 季节

数据库录入

项目	要求
表	season
前置依赖	无
主要字段	季节名称、年份、开始日期、结束日期
下游引用	study_season、部分 observation

界面形态

列表页按年份和季节筛选。新增页是简单表单。详情页展示关联 study。

校验规则

1. 名称和年份必填。
2. 同一年份内季节名称不建议重复。

5.7 study 研究/试验实施单元

数据库录入

项目	要求
表	study
前置依赖	crop、program、trial、location，可选 season
主要字段	study 名称、study 类型、项目、试验、地点、季节、开始/结束日期、实验设计
下游引用	observation_unit、event、observation、plate、sample、variantset

界面形态

新增页是分组表单：基本信息、上下文、地点季节、实验设计、联系人。上下文字段按顺序联动：选择 program 后过滤 trial 和 crop，选择 trial 后带出 crop。详情页作为工作台，展示 observation unit、observation、sample、variantset。

校验规则

1. study 名称必填。
2. program、trial、crop、location 必选。
3. trial 必须属于所选 program。
4. study 是下游核心引用，删除必须强提示。

5.8 list / list_item 通用列表

数据库录入

项目	要求
表	list、list_item
前置依赖	可选 person
主要字段	列表名称、列表类型、owner、项目项 ID、项目项名称
下游引用	业务查询和分组

界面形态

列表页展示 list。详情页内嵌 list item 表格，支持手动添加、批量导入、排序。新增 item 时可选择目标类型，例如 germplasm、study、sample。

校验规则

1. list 名称必填。
2. list item 在同一 list 内不应重复。
3. 如果绑定 owner，owner 必须存在于 person。

7. 字段需求

crop

字段	类型	控件	录入说明	校验/来源
id	varchar(255)	隐藏/只读	作物主键，新增时系统生成，也可导入时指定	必填、唯一
auth_user_id	varchar(255)	隐藏	数据所属用户	登录上下文自动写入
crop_name	varchar(255)	文本框	作物名称，用于所有下拉选择展示	必填、建议唯一

person

字段	类型	控件	录入说明	校验/来源
id	varchar(255)	隐藏/只读	人员主键	必填、唯一
auth_user_id	varchar(255)	隐藏	数据所属用户	登录上下文自动写入
description	varchar(255)	多行文本	人员说明、职责补充	可选
email_address	varchar(255)	邮箱输入框	邮箱地址	邮箱格式校验，建议唯一
first_name	varchar(255)	文本框	名	与 last_name 至少填写一个
institute_name	varchar(255)	文本框/选择器	所属机构	可选
last_name	varchar(255)	文本框	姓	与 first_name 至少填写一个
mailing_address	varchar(255)	多行文本	通讯地址	可选
middle_name	varchar(255)	文本框	中间名	可选
phone_number	varchar(255)	电话输入框	联系电话	可选，格式提示
userid	varchar(255)	文本框	外部用户 ID 或登录名	可选，建议唯一

program

字段	类型	控件	录入说明	校验/来源
id	varchar(255)	隐藏/只读	项目主键	必填、唯一
auth_user_id	varchar(255)	隐藏	数据所属用户	登录上下文自动写入
abbreviation	varchar(255)	文本框	项目缩写	可选
documentationurl	varchar(255)	URL 输入框	项目文档链接	URL 格式校验
funding_information	varchar(255)	多行文本	经费来源说明	可选
name	varchar(255)	文本框	项目名称	必填
objective	varchar(255)	多行文本	项目目标	可选
program_type	integer	下拉框	项目类型枚举	可选，按 BrAPI 枚举
crop_id	varchar(255)	作物选择器	所属作物	必选，来源 crop.id
lead_person_id	varchar(255)	人员选择器	项目负责人	可选，来源 person.id

location

字段	类型	控件	录入说明	校验/来源
id	varchar(255)	隐藏/只读	地点主键	必填、唯一
auth_user_id	varchar(255)	隐藏	数据所属用户	登录上下文自动写入
abbreviation	varchar(255)	文本框	地点缩写	可选
coordinate_description	varchar(255)	多行文本	坐标描述	可选
coordinate_uncertainty	varchar(255)	文本框	坐标不确定性	可选
country_code	varchar(255)	国家代码选择器	国家代码	可选，建议 ISO 代码
country_name	varchar(255)	文本框	国家名称	可选，可由国家代码带出
documentationurl	varchar(255)	URL 输入框	地点文档链接	URL 格式校验
environment_type	varchar(255)	下拉框/文本框	环境类型	可选
exposure	varchar(255)	文本框	暴露条件	可选
institute_address	varchar(255)	多行文本	机构地址	可选
institute_name	varchar(255)	文本框	机构名称	可选
location_name	varchar(255)	文本框	地点名称	必填
location_type	varchar(255)	下拉框	地点类型，如 field、greenhouse、storage	可选
site_status	varchar(255)	下拉框	地点状态	可选
slope	varchar(255)	文本框	坡度	可选
topography	varchar(255)	文本框	地形	可选
coordinates_id	varchar(255)	坐标选择器/地图取点	坐标对象	可选，来源 geojson/coordinate
crop_id	varchar(255)	作物选择器	关联作物	可选，来源 crop.id
parent_location_id	varchar(255)	地点选择器	父级地点	可选，不能选择自己
program_id	varchar(255)	项目选择器	所属项目	可选，来源 program.id

trial

字段	类型	控件	录入说明	校验/来源
id	varchar(255)	隐藏/只读	试验主键	必填、唯一
auth_user_id	varchar(255)	隐藏	数据所属用户	登录上下文自动写入
active	boolean	开关	是否启用	默认启用
documentationurl	varchar(255)	URL 输入框	试验文档链接	URL 格式校验
end_date	timestamp	日期选择器	结束日期	不早于 start_date
start_date	timestamp	日期选择器	开始日期	可选
trial_description	varchar(255)	多行文本	试验描述	可选
trial_name	varchar(255)	文本框	试验名称	必填
trialpui	varchar(255)	文本框	试验永久标识	可选，建议唯一
crop_id	varchar(255)	作物选择器	所属作物	必选，来源 crop.id
program_id	varchar(255)	项目选择器	所属项目	必选，来源 program.id

season

字段	类型	控件	录入说明	校验/来源
id	varchar(255)	隐藏/只读	季节主键	必填、唯一
auth_user_id	varchar(255)	隐藏	数据所属用户	登录上下文自动写入
season	varchar(255)	文本框/下拉框	季节名称，如 Spring、Summer	必填
year	integer	年份选择器	年份	必填，四位年份

study

字段	类型	控件	录入说明	校验/来源
id	varchar(255)	隐藏/只读	study 主键	必填、唯一
auth_user_id	varchar(255)	隐藏	数据所属用户	登录上下文自动写入
active	boolean	开关	是否启用	默认启用
cultural_practices	varchar(255)	多行文本	栽培管理说明	可选
documentationurl	varchar(255)	URL 输入框	study 文档链接	URL 格式校验
end_date	timestamp	日期选择器	结束日期	不早于 start_date
license	varchar(255)	文本框	数据许可证	可选
observation_units_description	varchar(255)	多行文本	观测单元说明	可选
start_date	timestamp	日期选择器	开始日期	可选
study_code	varchar(255)	文本框	study 编码	可选，建议同项目内唯一
study_description	varchar(255)	多行文本	study 描述	可选
study_name	varchar(255)	文本框	study 名称	必填
studypui	varchar(255)	文本框	study 永久标识	可选，建议唯一
study_type	varchar(255)	下拉框	study 类型	可选
crop_id	varchar(255)	作物选择器	所属作物	必选，来源 crop.id
location_id	varchar(255)	地点选择器	实施地点	必选，来源 location.id
program_id	varchar(255)	项目选择器	所属项目	必选，来源 program.id
trial_id	varchar(255)	试验选择器	所属 trial	必选，来源 trial.id

list

字段	类型	控件	录入说明	校验/来源
id	varchar(255)	隐藏/只读	列表主键	必填、唯一
auth_user_id	varchar(255)	隐藏	数据所属用户	登录上下文自动写入
date_created	timestamp	只读日期时间	创建时间	系统自动写入
date_modified	timestamp	只读日期时间	修改时间	系统自动更新
description	varchar(255)	多行文本	列表描述	可选
list_name	varchar(255)	文本框	列表名称	必填
list_owner_name	varchar(255)	文本框	列表 owner 名称	可选，可由 owner person 带出
list_source	varchar(255)	文本框	列表来源	可选
list_type	integer	下拉框	列表类型	必填，按 BrAPI 枚举
list_owner_person_id	varchar(255)	人员选择器	列表 owner	可选，来源 person.id

list_item

字段	类型	控件	录入说明	校验/来源
id	varchar(255)	隐藏/只读	列表项主键	必填、唯一
item	varchar(255)	文本框/对象选择器	列表项值，可存目标对象 ID 或文本	必填，同一 list 内不重复
list_id	varchar(255)	List 选择器	所属列表	必选，来源 list.id

trial_contact

字段	类型	控件	录入说明	校验/来源
trial_db_id	varchar(255)	Trial 选择器	所属 trial	必选，来源 trial.id
person_db_id	varchar(255)	人员选择器	联系人	必选，来源 person.id

trial_publication

字段	类型	控件	录入说明	校验/来源
id	varchar(255)	隐藏/只读	出版物记录主键	必填、唯一
publicationpui	varchar(255)	文本框	出版物 PUI	可选
publication_reference	varchar(255)	文本框/URL	出版物引用	可选
trial_id	varchar(255)	Trial 选择器	所属 trial	必选，来源 trial.id

study_contact

字段	类型	控件	录入说明	校验/来源
study_db_id	varchar(255)	Study 选择器	所属 study	必选，来源 study.id
person_db_id	varchar(255)	人员选择器	联系人	必选，来源 person.id

study_season

字段	类型	控件	录入说明	校验/来源
study_db_id	varchar(255)	Study 选择器	所属 study	必选，来源 study.id
season_db_id	varchar(255)	Season 选择器	关联季节	必选，来源 season.id

8. 接口需求

接口命名可以按项目现有 BrAPI Controller 适配；本节描述前端页面需要的能力，不强制限定最终 URL 必须完全一致。

8.1 CRUD 接口

对象	接口	用途
crop	GET /crops	crop 分页查询
crop	POST /crops	新增 crop
crop	GET /crops/{id}	crop 详情
crop	PUT /crops/{id}	编辑 crop
crop	DELETE /crops/{id}	删除或停用 crop，需做引用检查
person	GET /persons	person 分页查询
person	POST /persons	新增 person
person	GET /persons/{id}	person 详情
person	PUT /persons/{id}	编辑 person
person	DELETE /persons/{id}	删除或停用 person，需做引用检查
program	GET /programs	program 分页查询
program	POST /programs	新增 program
program	GET /programs/{id}	program 详情
program	PUT /programs/{id}	编辑 program
program	DELETE /programs/{id}	删除或停用 program，需做引用检查
location	GET /locations	location 分页查询
location	POST /locations	新增 location
location	GET /locations/{id}	location 详情
location	PUT /locations/{id}	编辑 location
trial	GET /trials	trial 分页查询
trial	POST /trials	新增 trial
trial	GET /trials/{id}	trial 详情
trial	PUT /trials/{id}	编辑 trial
trial	DELETE /trials/{id}	删除或停用 trial，需检查 study 引用
season	GET /seasons	season 查询
season	POST /seasons	新增 season
season	PUT /seasons/{id}	编辑 season
study	GET /studies	study 分页查询
study	POST /studies	新增 study
study	GET /studies/{id}	study 详情
study	PUT /studies/{id}	编辑 study
study	DELETE /studies/{id}	删除或停用 study，需检查下游引用
list	GET /lists	list 查询
list	POST /lists	新增 list
list	PUT /lists/{id}	编辑 list
list item	POST /lists/{id}/items	给 list 添加 item
list item	DELETE /lists/{id}/items/{itemId}	删除 list item

8.2 详情聚合接口

接口	用途	返回重点
GET /programs/{id}/trials	查询 program 下 trial	trial 基础信息、active
GET /programs/{id}/studies	查询 program 下 study	study 基础信息、location、trial
GET /trials/{id}/studies	查询 trial 下 study	study 列表
GET /studies/{id}/workbench	Study 工作台聚合信息	study 基本信息、联系人、season、observation_unit 数、observation 数、sample 数、variantset 数
GET /studies/{id}/contacts	study 联系人	person 列表
GET /studies/{id}/seasons	study 季节	season 列表

8.3 选择器接口

接口	用途	参数
GET /selectors/crops	crop 搜索下拉	keyword
GET /selectors/persons	person 搜索下拉	keyword、instituteName
GET /selectors/programs	program 搜索下拉	keyword、cropId
GET /selectors/trials	trial 搜索下拉	keyword、programId、cropId、active
GET /selectors/locations	location 搜索下拉	keyword、programId、cropId、locationType
GET /selectors/seasons	season 搜索下拉	year、keyword
GET /selectors/studies	study 搜索下拉	keyword、programId、trialId、locationId、active

8.4 导入导出接口

接口	用途
GET /imports/templates/core/{objectType}	下载 Core 对象导入模板
POST /imports/core/{objectType}/preview	上传文件并预校验，不落库
POST /imports/core/{objectType}/commit	确认导入
GET /exports/core/{objectType}	导出当前筛选结果
GET /imports/{jobId}/errors	获取导入错误报告

9. 联动规则

场景	联动规则
创建 program	必须先选择 crop；负责人从 person 选择器选择
创建 trial	选择 program 后自动带出 crop；trial 的 crop 必须与 program.crop_id 一致
创建 location	选择 program 后可自动带出 crop，但允许地点作为公共地点不绑定 program
创建 study	先选 program，再按 program 过滤 trial；选择 trial 后自动带出 crop
创建 study	location 可按 program/crop 过滤；season 支持多选
编辑 study	如果已有 observation_unit/sample/observation，变更 program/trial/crop/location 前必须二次确认并检查一致性
Study 工作台	入口必须携带 study_id；下游新增 observation_unit、sample、variantset 默认继承该 study 上下文
外键显示	前端展示名称，提交保存 ID；表格列需要同时支持名称展示和 ID 调试查看

10. 删除/停用规则

对象	删除/停用规则
crop	已被 program、location、trial、study、germplasm、observation_variable、genome_map 引用时，不允许物理删除
person	已作为 program 负责人、trial 联系人、study 联系人、list owner 时，不允许物理删除
program	已有关联 trial、study、location、crossing_project、seed_lot、plate、sample 时，不允许物理删除
location	已被 study 或 seed_lot 引用时，不允许物理删除
trial	已被 study、observation_unit、observation、plate、sample 引用时，不允许物理删除
season	已被 study_season 或 observation 引用时，不允许物理删除
study	已被 observation_unit、event、observation、plate、sample、variantset 引用时，不允许物理删除
list	已有 list_item 时，删除前必须提示；可先清空明细再删除

删除失败时，后端应返回被引用对象类型和数量，前端弹窗展示，例如：

该 study 已被以下数据引用，不能删除：
- observation_unit: 120
- observation: 560
- sample: 96
请先处理下游数据，或将 study 停用。

11. 导入导出需求

11.1 导入对象

Core 模块至少支持以下对象导入：

crop
person
program
location
trial
season
study
list
list_item
trial_contact
study_contact
study_season

11.2 导入流程

1. 用户选择对象类型，例如 study。
2. 下载 CSV/Excel 模板。
3. 用户填写模板并上传。
4. 系统做预校验：字段完整性、必填、格式、外键是否存在、联动关系是否一致。
5. 预览页展示可导入行、错误行、警告行。
6. 用户确认后提交导入。
7. 导入完成后生成导入报告。

11.3 导入模板要求

要求	说明
字段名	使用数据库字段名作为模板列名
外键列	支持填写 ID；可额外支持名称匹配，但名称重复时必须报错
错误报告	返回行号、字段名、错误原因、建议修正方式
幂等策略	可按 ID 更新；无 ID 时新增
权限	数据录入员可导入 study 下游数据；Core 主数据导入建议仅项目管理员/数据管理员可操作

11.4 导出需求

1. 所有列表页支持导出当前筛选结果。
2. 导出文件应包含 ID 和展示名称。
3. study 导出应支持导出工作台摘要，包括联系人、season、下游数据数量。
4. 导出大数据量时应走异步任务。

12. 验收标准

12.1 前端验收标准

1. 所有列表页支持分页、关键词搜索、基础筛选。
2. 所有外键字段前端展示名称，提交保存 ID。
3. 创建 program 时，必须选择 crop。
4. 创建 trial 时，选择 program 后自动带出 crop。
5. 创建 study 时，必须选择 program、trial、crop、location。
6. Study 列表页支持按 crop、program、trial、location、season、active 筛选。
7. 点击 study 名称或“进入工作台”按钮后进入 Study 工作台。
8. Study 工作台可以看到观测单元、表型、样本、基因型入口。
9. 删除被引用数据时，前端展示引用详情，不允许静默失败。
10. 导入预校验结果能展示错误行、错误字段、错误原因。

12.2 后端验收标准

1. 创建 program 时校验 crop_id 存在。
2. 创建 trial 时校验 program_id 存在，且 trial.crop_id 与 program.crop_id 一致。
3. 创建 study 时校验 program_id、trial_id、crop_id、location_id 存在。
4. 创建 study 时校验 trial 属于所选 program。
5. 删除 crop/program/trial/study 前必须检查下游引用。
6. GET /studies/{id}/workbench 能返回工作台所需聚合数量。
7. 选择器接口支持 keyword 模糊搜索和上游过滤参数。
8. 导入接口支持 preview 和 commit 两阶段。

12.3 测试点

1. 选择 program 后，trial 下拉框只展示该 program 下的数据。
2. 选择 trial 后，系统自动带出 crop。
3. 已被 study 引用的 trial 不能直接删除。
4. 已被 observation_unit、sample、observation 引用的 study 不能直接删除。
5. study 创建成功后自动进入 Study 工作台。
6. 修改 study 的 program/trial/crop 时，如果已有下游数据，必须提示风险。
7. 导入 study 时，如果 trial 不属于 program，应报错并指出行号。
8. 导入 location 时，如果 parent_location_id 指向自己，应报错。
9. 导出列表时，筛选条件必须生效。
10. 所有接口返回的分页字段一致，便于前端表格复用。