# 01 Core - study 表录入说明

来源：`docs/requirements/01-core-data-entry-requirements.md`

## 录入目标

`study` 是一次真正落地执行的试验，是 Core 模块最关键的上下文单元。后续 observation_unit、event、observation、plate、sample、variantset 都会直接或间接挂到 study 上。

## 前置依赖和下游引用

| 类型 | 内容 |
| --- | --- |
| 表 | `study` |
| 前置依赖 | `crop`、`program`、`trial`、`location`，可选 `season` |
| 下游引用 | `observation_unit`、`event`、`observation`、`plate`、`sample`、`variantset` |

## 页面入口

| 页面 | 录入要求 |
| --- | --- |
| Study 列表页 | 支持 crop、program、trial、location、season、active、study_type、关键词筛选；新增、编辑、查看详情、停用 |
| Study 新增/编辑页 | 分组表单：基本信息、上下文、地点季节、实验设计、联系人 |
| Study 工作台 | 点击 study 名称或“进入工作台”后进入，展示下游业务入口和聚合数量 |

Study 列表页表格字段：`study_name`、`study_code`、program、trial、location、`start_date`、`end_date`、active。

## 字段录入

| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
| --- | --- | --- | --- | --- |
| `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` |

## 新增/编辑分区

| 区域 | 字段/功能 | 要求 |
| --- | --- | --- |
| 基本信息 | 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 工作台 | 新建成功后自动跳转 |

## 校验规则

1. `study_name` 必填。
2. `program_id`、`trial_id`、`crop_id`、`location_id` 必选且必须存在。
3. `trial_id` 必须属于所选 `program_id`。
4. 选择 program 后过滤 trial；选择 trial 后自动带出 crop。
5. `end_date` 不能早于 `start_date`。
6. 编辑 study 时，如果已有 observation_unit、sample、observation，变更 program/trial/crop/location 前必须二次确认并检查一致性。
7. study 是下游核心引用，删除必须强提示。

## 接口能力

| 接口 | 用途 |
| --- | --- |
| `GET /studies` | study 分页查询 |
| `POST /studies` | 新增 study |
| `GET /studies/{id}` | study 详情 |
| `PUT /studies/{id}` | 编辑 study |
| `DELETE /studies/{id}` | 删除或停用 study，需检查下游引用 |
| `GET /studies/{id}/workbench` | Study 工作台聚合信息 |
| `GET /studies/{id}/contacts` | study 联系人 |
| `GET /studies/{id}/seasons` | study 季节 |
| `GET /selectors/studies` | study 搜索下拉，参数 `keyword`、`programId`、`trialId`、`locationId`、`active` |

## 导入导出

1. 支持通过 Core 导入流程导入 `study`。
2. 导入时必须校验字段完整性、必填、格式、外键是否存在、联动关系是否一致。
3. 如果 trial 不属于 program，应报错并指出行号。
4. study 导出应支持工作台摘要，包括联系人、season、下游数据数量。
5. 大数据量导出时应走异步任务。

## 删除/停用

当 `study` 已被 `observation_unit`、`event`、`observation`、`plate`、`sample`、`variantset` 引用时，不允许物理删除。后端需要返回引用对象类型和数量，前端弹窗展示后引导用户停用。

## 验收点

1. Study 列表页支持按 crop、program、trial、location、season、active 筛选。
2. 点击 study 名称或“进入工作台”按钮后进入 Study 工作台。
3. Study 工作台可以看到观测单元、表型、样本、基因型入口。
4. study 创建成功后自动进入 Study 工作台。
5. 已被 observation_unit、sample、observation 引用的 study 不能直接删除。