fix:sample/plate 之前的开发

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

@@ -0,0 +1,755 @@
+# Core 模块业务需求文档
+
+## 1. 模块定位
+
+Core 是项目、试验、地点、人员、季节的基础上下文模块，是所有业务数据的总上游。它不是普通字典维护，而是为后续 Germplasm/Seed、Phenotyping、Genotyping 提供“这批数据属于哪个项目、哪次试验、哪个地点、哪个年度、谁负责”的业务台账。
+
+推荐先完成 Core 录入，再录入 Germplasm、Phenotyping、Genotyping。
+
+## 2. 真实业务理解
+
+Core 不只是“基础字典”，它在真实育种业务里是项目台账：回答“谁在什么项目、什么地点、什么年度、做哪一次试验”。后续所有材料、田间布置、表型采集、样本检测、基因型结果，都需要回到 Core 上下文里解释。
+
+最常见的业务链路是：
+
+```text
+crop 作物
+  -> program 长期育种项目
+  -> trial 某一批试验/区域试验
+  -> study 一次真正落地执行的试验
+```
+
+例如：
+
+```text
+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 工作台
+
+```text
+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 业务流程图
+
+```mermaid
+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 时，删除前必须提示；可先清空明细再删除 |
+
+删除失败时，后端应返回被引用对象类型和数量，前端弹窗展示，例如：
+
+```text
+该 study 已被以下数据引用，不能删除：
+- observation_unit: 120
+- observation: 560
+- sample: 96
+请先处理下游数据，或将 study 停用。
+```
+
+## 11. 导入导出需求
+
+### 11.1 导入对象
+
+Core 模块至少支持以下对象导入：
+
+```text
+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. 所有接口返回的分页字段一致，便于前端表格复用。