fix:sample/plate 之前的开发

2026-05-28 11:56:17 +08:00
parent fc36bc83e3
commit 8b65de36b8
367 changed files with 57752 additions and 947 deletions
--- a/docs/dev/01-core/01-crop.md
+++ b/docs/dev/01-core/01-crop.md
@@ -0,0 +1,67 @@
+# 01 Core - crop 表录入说明
+
+来源：`docs/requirements/01-core-data-entry-requirements.md`
+
+## 录入目标
+
+`crop` 记录项目涉及的作物范围，是 Core 上下文的起点。后续 program、trial、study、germplasm、observation_variable、genome_map 等数据都需要回到作物维度筛选和解释。
+
+## 前置依赖和下游引用
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `crop` |
+| 前置依赖 | 无 |
+| 下游引用 | `program`、`location`、`trial`、`study`、`germplasm`、`observation_variable`、`genome_map` |
+
+## 页面入口
+
+| 页面 | 录入要求 |
+| --- | --- |
+| Crop 列表页 | 支持关键词查询、新增、编辑、查看详情、停用 |
+| Crop 新增/编辑页 | 轻量表单，重点录入作物名称 |
+| Crop 详情页 | 展示该作物下的项目、试验、研究、种质、图谱入口 |
+
+列表页表格字段：`crop_name`、下游 program 数、下游 study 数、状态。
+
+## 字段录入
+
+| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
+| --- | --- | --- | --- | --- |
+| `id` | varchar(255) | 隐藏/只读 | 作物主键，新增时系统生成，也可导入时指定 | 必填、唯一 |
+| `auth_user_id` | varchar(255) | 隐藏 | 数据所属用户 | 登录上下文自动写入 |
+| `crop_name` | varchar(255) | 文本框 | 作物名称，用于所有下拉选择展示 | 必填、建议唯一 |
+
+## 校验规则
+
+1. `crop_name` 必填。
+2. `crop_name` 建议唯一，新增和编辑时需要做重复提示。
+3. 已被下游引用的作物不能物理删除，只能停用或提示引用关系。
+
+## 接口能力
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /crops` | crop 分页查询 |
+| `POST /crops` | 新增 crop |
+| `GET /crops/{id}` | crop 详情 |
+| `PUT /crops/{id}` | 编辑 crop |
+| `DELETE /crops/{id}` | 删除或停用 crop，需做引用检查 |
+| `GET /selectors/crops` | crop 搜索下拉，参数 `keyword` |
+
+## 导入导出
+
+1. 支持通过 Core 导入流程导入 `crop`。
+2. 模板列名使用数据库字段名。
+3. 可按 `id` 幂等更新；无 `id` 时新增。
+4. 列表页支持导出当前筛选结果，导出文件应包含 ID 和展示名称。
+
+## 删除/停用
+
+当 `crop` 已被 `program`、`location`、`trial`、`study`、`germplasm`、`observation_variable`、`genome_map` 引用时，不允许物理删除。后端需要返回引用对象类型和数量，前端弹窗展示后引导用户停用。
+
+## 验收点
+
+1. Crop 列表页支持分页、关键词搜索和基础筛选。
+2. 外键选择器展示作物名称，提交保存 `crop.id`。
+3. 被引用的 crop 删除失败时，前端展示引用详情。
--- a/docs/dev/01-core/02-person.md
+++ b/docs/dev/01-core/02-person.md
@@ -0,0 +1,76 @@
+# 01 Core - person 表录入说明
+
+来源：`docs/requirements/01-core-data-entry-requirements.md`
+
+## 录入目标
+
+`person` 记录项目负责人、trial 联系人、study 联系人和 list owner。它支撑责任追踪、联系人展示、权限和通知。
+
+## 前置依赖和下游引用
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `person` |
+| 前置依赖 | 无 |
+| 下游引用 | `program.lead_person_id`、`trial_contact`、`study_contact`、`list.list_owner_person_id` |
+
+## 页面入口
+
+| 页面 | 录入要求 |
+| --- | --- |
+| Person 列表页 | 支持姓名、邮箱、机构筛选；新增、编辑、查看详情、停用 |
+| Person 新增/编辑页 | 使用联系人表单维护人员信息 |
+| Person 详情页 | 展示负责的 program、参与的 trial/study、拥有的 list |
+
+列表页表格字段：姓名、邮箱、电话、机构、负责项目数、参与 study 数。
+
+## 字段录入
+
+| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
+| --- | --- | --- | --- | --- |
+| `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 或登录名 | 可选，建议唯一 |
+
+## 校验规则
+
+1. 姓名必填，`first_name` 与 `last_name` 至少填写一个。
+2. `email_address` 需要校验邮箱格式。
+3. 同一邮箱不建议重复录入。
+4. 作为负责人或联系人被引用时，不允许物理删除。
+
+## 接口能力
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /persons` | person 分页查询 |
+| `POST /persons` | 新增 person |
+| `GET /persons/{id}` | person 详情 |
+| `PUT /persons/{id}` | 编辑 person |
+| `DELETE /persons/{id}` | 删除或停用 person，需做引用检查 |
+| `GET /selectors/persons` | person 搜索下拉，参数 `keyword`、`instituteName` |
+
+## 导入导出
+
+1. 支持通过 Core 导入流程导入 `person`。
+2. 模板列名使用数据库字段名。
+3. 可按 `id` 幂等更新；无 `id` 时新增。
+4. 列表页支持导出当前筛选结果，导出文件应包含 ID 和展示名称。
+
+## 删除/停用
+
+当 `person` 已作为 program 负责人、trial 联系人、study 联系人或 list owner 时，不允许物理删除。后端需要返回引用对象类型和数量，前端展示后引导用户停用。
+
+## 验收点
+
+1. Person 列表页支持分页、关键词搜索和机构筛选。
+2. 邮箱格式错误时不能提交。
+3. 作为负责人或联系人被引用的 person 删除失败时，前端展示引用详情。
--- a/docs/dev/01-core/03-program.md
+++ b/docs/dev/01-core/03-program.md
@@ -0,0 +1,77 @@
+# 01 Core - program 表录入说明
+
+来源：`docs/requirements/01-core-data-entry-requirements.md`
+
+## 录入目标
+
+`program` 表示长期育种项目，是多个 trial、study、材料、样本和结果的聚合维度。创建 program 时必须明确所属 crop，可选负责人。
+
+## 前置依赖和下游引用
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `program` |
+| 前置依赖 | `crop`，可选 `person` |
+| 下游引用 | `trial`、`study`、`location`、`crossing_project`、`seed_lot`、`plate`、`sample` |
+
+## 页面入口
+
+| 页面 | 录入要求 |
+| --- | --- |
+| Program 列表页 | 支持 crop、负责人、program_type、关键词筛选；新增、编辑、查看详情、停用 |
+| Program 新增/编辑页 | 分为“基本信息”和“负责人/作物”两组 |
+| Program 详情页 | Tab 展示 trial、study、location、seed lot、sample |
+
+列表页表格字段：`name`、`abbreviation`、crop、负责人、trial 数、study 数。
+
+## 字段录入
+
+| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
+| --- | --- | --- | --- | --- |
+| `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` |
+
+## 校验规则
+
+1. `name` 必填。
+2. `crop_id` 必选，且必须引用已存在的 `crop.id`。
+3. 选择负责人时，`lead_person_id` 必须引用已存在的 `person.id`。
+4. `documentationurl` 需要做 URL 格式校验。
+
+## 接口能力
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /programs` | program 分页查询 |
+| `POST /programs` | 新增 program |
+| `GET /programs/{id}` | program 详情 |
+| `PUT /programs/{id}` | 编辑 program |
+| `DELETE /programs/{id}` | 删除或停用 program，需做引用检查 |
+| `GET /programs/{id}/trials` | 查询 program 下 trial |
+| `GET /programs/{id}/studies` | 查询 program 下 study |
+| `GET /selectors/programs` | program 搜索下拉，参数 `keyword`、`cropId` |
+
+## 导入导出
+
+1. 支持通过 Core 导入流程导入 `program`。
+2. 外键列支持填写 ID；可额外支持名称匹配，但名称重复时必须报错。
+3. 可按 `id` 幂等更新；无 `id` 时新增。
+4. 列表页支持导出当前筛选结果，导出文件应包含 ID 和展示名称。
+
+## 删除/停用
+
+当 `program` 已有关联 `trial`、`study`、`location`、`crossing_project`、`seed_lot`、`plate`、`sample` 时，不允许物理删除。后端需要返回引用对象类型和数量，前端展示后引导用户停用。
+
+## 验收点
+
+1. 创建 program 时必须选择 crop。
+2. 负责人选择器只能保存已存在的 person ID。
+3. Program 详情页能进入该项目下的 trial 和 study。
--- a/docs/dev/01-core/04-location.md
+++ b/docs/dev/01-core/04-location.md
@@ -0,0 +1,86 @@
+# 01 Core - location 表录入说明
+
+来源：`docs/requirements/01-core-data-entry-requirements.md`
+
+## 录入目标
+
+`location` 记录试验实施地点，可作为公共地点，也可绑定 program 和 crop。study 创建时必须选择实施地点。
+
+## 前置依赖和下游引用
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `location` |
+| 前置依赖 | 可选 `crop`、`program`、父级 `location`、坐标 |
+| 下游引用 | `study`、`seed_lot` |
+
+## 页面入口
+
+| 页面 | 录入要求 |
+| --- | --- |
+| Location 列表页 | 支持 crop、program、location_type、country、关键词筛选；新增、编辑、查看详情、停用、地图查看 |
+| Location 新增/编辑页 | 包含基本信息、行政区、坐标、父级地点 |
+| Location 详情页 | 展示该地点下的 study 和 seed lot |
+
+列表页支持地图/表格两种视图。列表页表格字段：`location_name`、location_type、country、program、crop、父级地点。
+
+## 字段录入
+
+| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
+| --- | --- | --- | --- | --- |
+| `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` |
+
+## 校验规则
+
+1. `location_name` 必填。
+2. 坐标字段格式合法。
+3. `parent_location_id` 不能选择自己。
+4. 选择 program 后可自动带出 crop，但允许地点作为公共地点不绑定 program。
+5. `documentationurl` 需要做 URL 格式校验。
+
+## 接口能力
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /locations` | location 分页查询 |
+| `POST /locations` | 新增 location |
+| `GET /locations/{id}` | location 详情 |
+| `PUT /locations/{id}` | 编辑 location |
+| `GET /selectors/locations` | location 搜索下拉，参数 `keyword`、`programId`、`cropId`、`locationType` |
+
+## 导入导出
+
+1. 支持通过 Core 导入流程导入 `location`。
+2. 导入时如果 `parent_location_id` 指向自己，应报错并指出行号。
+3. 外键列支持填写 ID；可额外支持名称匹配，但名称重复时必须报错。
+4. 列表页支持导出当前筛选结果，导出文件应包含 ID 和展示名称。
+
+## 删除/停用
+
+当 `location` 已被 `study` 或 `seed_lot` 引用时，不允许物理删除。后端需要返回引用对象类型和数量，前端展示后引导用户停用。
+
+## 验收点
+
+1. Location 列表页支持表格视图和地图查看。
+2. 父级地点不能选择自己。
+3. Study 新增时 location 选择器可按 program/crop 过滤。
--- a/docs/dev/01-core/05-trial.md
+++ b/docs/dev/01-core/05-trial.md
@@ -0,0 +1,78 @@
+# 01 Core - trial 表录入说明
+
+来源：`docs/requirements/01-core-data-entry-requirements.md`
+
+## 录入目标
+
+`trial` 表示某一批试验、区域试验或年度试验，位于 program 与 study 之间。创建 trial 时选择 program，并自动带出或校验 crop。
+
+## 前置依赖和下游引用
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `trial` |
+| 前置依赖 | `program`、`crop` |
+| 下游引用 | `study`、`observation_unit`、`observation`、`plate`、`sample` |
+
+## 页面入口
+
+| 页面 | 录入要求 |
+| --- | --- |
+| Trial 列表页 | 支持 crop、program、active、起止日期、关键词筛选；新增、编辑、查看详情、停用 |
+| Trial 新增/编辑页 | 包含基本信息、项目作物、联系人、出版物四个区域 |
+| Trial 详情页 | 展示 study 列表和 phenotyping/genotyping 入口 |
+
+列表页表格字段：`trial_name`、program、crop、`start_date`、`end_date`、active。
+
+## 字段录入
+
+| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
+| --- | --- | --- | --- | --- |
+| `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` |
+
+## 校验规则
+
+1. `trial_name` 必填。
+2. `program_id` 必选且必须存在。
+3. `crop_id` 必选且必须与 `program.crop_id` 一致。
+4. `end_date` 不能早于 `start_date`。
+5. `documentationurl` 需要做 URL 格式校验。
+
+## 接口能力
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /trials` | trial 分页查询 |
+| `POST /trials` | 新增 trial |
+| `GET /trials/{id}` | trial 详情 |
+| `PUT /trials/{id}` | 编辑 trial |
+| `DELETE /trials/{id}` | 删除或停用 trial，需检查 study 引用 |
+| `GET /trials/{id}/studies` | 查询 trial 下 study |
+| `GET /selectors/trials` | trial 搜索下拉，参数 `keyword`、`programId`、`cropId`、`active` |
+
+## 导入导出
+
+1. 支持通过 Core 导入流程导入 `trial`。
+2. 外键列支持填写 ID；可额外支持名称匹配，但名称重复时必须报错。
+3. 导入时必须校验 trial 的 crop 与 program 的 crop 一致。
+4. 列表页支持导出当前筛选结果，导出文件应包含 ID 和展示名称。
+
+## 删除/停用
+
+当 `trial` 已被 `study`、`observation_unit`、`observation`、`plate`、`sample` 引用时，不允许物理删除。后端需要返回引用对象类型和数量，前端展示后引导用户停用。
+
+## 验收点
+
+1. 创建 trial 时，选择 program 后自动带出 crop。
+2. Trial 列表页支持按 crop、program、active、日期筛选。
+3. 已被 study 引用的 trial 不能直接删除。
--- a/docs/dev/01-core/06-season.md
+++ b/docs/dev/01-core/06-season.md
@@ -0,0 +1,66 @@
+# 01 Core - season 表录入说明
+
+来源：`docs/requirements/01-core-data-entry-requirements.md`
+
+## 录入目标
+
+`season` 记录年度和季节，用于 study 的季节绑定，以及部分 observation 的季节维度统计。
+
+## 前置依赖和下游引用
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `season` |
+| 前置依赖 | 无 |
+| 下游引用 | `study_season`、部分 `observation` |
+
+## 页面入口
+
+| 页面 | 录入要求 |
+| --- | --- |
+| Season 列表页 | 支持 year、season 筛选；新增、编辑、查看详情、停用 |
+| Season 新增/编辑页 | 简单表单 |
+| Season 详情页 | 展示关联 study |
+
+列表页表格字段：`year`、`season`、关联 study 数。
+
+## 字段录入
+
+| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
+| --- | --- | --- | --- | --- |
+| `id` | varchar(255) | 隐藏/只读 | 季节主键 | 必填、唯一 |
+| `auth_user_id` | varchar(255) | 隐藏 | 数据所属用户 | 登录上下文自动写入 |
+| `season` | varchar(255) | 文本框/下拉框 | 季节名称，如 Spring、Summer | 必填 |
+| `year` | integer | 年份选择器 | 年份 | 必填，四位年份 |
+
+## 校验规则
+
+1. `season` 必填。
+2. `year` 必填，使用四位年份。
+3. 同一年份内 season 名称不建议重复。
+
+## 接口能力
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /seasons` | season 查询 |
+| `POST /seasons` | 新增 season |
+| `PUT /seasons/{id}` | 编辑 season |
+| `GET /selectors/seasons` | season 搜索下拉，参数 `year`、`keyword` |
+
+## 导入导出
+
+1. 支持通过 Core 导入流程导入 `season`。
+2. 模板列名使用数据库字段名。
+3. 可按 `id` 幂等更新；无 `id` 时新增。
+4. 列表页支持导出当前筛选结果，导出文件应包含 ID 和展示名称。
+
+## 删除/停用
+
+当 `season` 已被 `study_season` 或 `observation` 引用时，不允许物理删除。后端需要返回引用对象类型和数量，前端展示后引导用户停用。
+
+## 验收点
+
+1. Season 列表页支持按 year 和 season 筛选。
+2. 同一年份内重复季节名称需要提示。
+3. Study 新增/编辑页可以多选 season。
--- a/docs/dev/01-core/07-study.md
+++ b/docs/dev/01-core/07-study.md
@@ -0,0 +1,103 @@
+# 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 不能直接删除。
--- a/docs/dev/01-core/08-list.md
+++ b/docs/dev/01-core/08-list.md
@@ -0,0 +1,73 @@
+# 01 Core - list 表录入说明
+
+来源：`docs/requirements/01-core-data-entry-requirements.md`
+
+## 录入目标
+
+`list` 是通用分组列表的主表，用于维护一组业务对象或文本项。`list` 负责列表基本信息，`list_item` 负责列表明细。
+
+## 前置依赖和下游引用
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `list` |
+| 前置依赖 | 可选 `person` |
+| 下游引用 | `list_item`、业务查询和分组 |
+
+## 页面入口
+
+| 页面 | 录入要求 |
+| --- | --- |
+| List 列表页 | 展示 list，支持查询、新增、编辑 |
+| List 详情页 | 顶部展示 list 基本信息，下方内嵌 list_item 表格 |
+
+List 详情页支持新增 item、批量导入 item、删除 item、排序。同一 list 内 item 不重复。
+
+## 字段录入
+
+| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
+| --- | --- | --- | --- | --- |
+| `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` |
+
+## 校验规则
+
+1. `list_name` 必填。
+2. `list_type` 必填，按 BrAPI 枚举选择。
+3. 如果绑定 owner，`list_owner_person_id` 必须引用已存在的 `person.id`。
+4. `date_created`、`date_modified` 由系统维护，前端只读。
+
+## 接口能力
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /lists` | list 查询 |
+| `POST /lists` | 新增 list |
+| `PUT /lists/{id}` | 编辑 list |
+| `POST /lists/{id}/items` | 给 list 添加 item |
+| `DELETE /lists/{id}/items/{itemId}` | 删除 list item |
+
+## 导入导出
+
+1. 支持通过 Core 导入流程导入 `list`。
+2. 模板列名使用数据库字段名。
+3. 外键列支持填写 `list_owner_person_id`；可额外支持名称匹配，但名称重复时必须报错。
+4. 列表页支持导出当前筛选结果，导出文件应包含 ID 和展示名称。
+
+## 删除/停用
+
+当 `list` 已有 `list_item` 时，删除前必须提示。可以先清空明细再删除 list。
+
+## 验收点
+
+1. List 详情页顶部展示 list 基本信息，下方展示 list_item 表格。
+2. 同一 list 内 item 不重复。
+3. 绑定 owner 时只能保存已存在的 person ID。
--- a/docs/dev/01-core/09-list_item.md
+++ b/docs/dev/01-core/09-list_item.md
@@ -0,0 +1,62 @@
+# 01 Core - list_item 表录入说明
+
+来源：`docs/requirements/01-core-data-entry-requirements.md`
+
+## 录入目标
+
+`list_item` 是 list 的明细项，是“给 list 添加成员”这个动作留下的记录。它可以保存目标对象 ID 或文本值，用于业务查询和分组。
+
+## 前置依赖和下游引用
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `list_item` |
+| 前置依赖 | `list` |
+| 下游引用 | 业务查询和分组 |
+
+## 页面入口
+
+| 页面 | 录入要求 |
+| --- | --- |
+| List 详情页 | 在 list 基本信息下方内嵌 list_item 表格 |
+| 批量导入 | 支持给指定 list 批量导入 item |
+
+新增 item 时可选择目标类型，例如 germplasm、study、sample。
+
+## 字段录入
+
+| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
+| --- | --- | --- | --- | --- |
+| `id` | varchar(255) | 隐藏/只读 | 列表项主键 | 必填、唯一 |
+| `item` | varchar(255) | 文本框/对象选择器 | 列表项值，可存目标对象 ID 或文本 | 必填，同一 list 内不重复 |
+| `list_id` | varchar(255) | List 选择器 | 所属列表 | 必选，来源 `list.id` |
+
+## 校验规则
+
+1. `list_id` 必选，且必须引用已存在的 `list.id`。
+2. `item` 必填。
+3. 同一 `list_id` 内 `item` 不应重复。
+
+## 接口能力
+
+| 接口 | 用途 |
+| --- | --- |
+| `POST /lists/{id}/items` | 给 list 添加 item |
+| `DELETE /lists/{id}/items/{itemId}` | 删除 list item |
+
+## 导入导出
+
+1. 支持通过 Core 导入流程导入 `list_item`。
+2. 导入时需要校验 `list_id` 是否存在。
+3. 导入时需要校验同一 list 内 item 是否重复。
+4. 错误报告返回行号、字段名、错误原因、建议修正方式。
+
+## 删除/停用
+
+`list_item` 是明细记录，可从 List 详情页删除。删除前需要确认，删除后不影响 list 基本信息。
+
+## 验收点
+
+1. List 详情页可新增 item、批量导入 item、删除 item、排序。
+2. 同一 list 内重复 item 不能提交。
+3. 批量导入错误能定位到行号和字段名。
--- a/docs/dev/01-core/10-trial_contact.md
+++ b/docs/dev/01-core/10-trial_contact.md
@@ -0,0 +1,57 @@
+# 01 Core - trial_contact 表录入说明
+
+来源：`docs/requirements/01-core-data-entry-requirements.md`
+
+## 录入目标
+
+`trial_contact` 是给 trial 添加联系人的关系表，不是独立主数据。它记录 trial 与 person 的多对多关系，用于试验责任追踪、联系人展示、权限和通知。
+
+## 前置依赖和下游引用
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `trial_contact` |
+| 前置依赖 | `trial`、`person` |
+| 下游引用 | trial 联系人展示、权限和通知 |
+
+## 页面入口
+
+| 页面 | 录入要求 |
+| --- | --- |
+| Trial 新增/编辑页 | 联系人区域使用可增删表格选择 `person` |
+| Trial 详情页 | 展示 trial 联系人 |
+| 批量导入 | 支持通过 Core 导入流程导入 trial 联系人关系 |
+
+## 字段录入
+
+| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
+| --- | --- | --- | --- | --- |
+| `trial_db_id` | varchar(255) | Trial 选择器 | 所属 trial | 必选，来源 `trial.id` |
+| `person_db_id` | varchar(255) | 人员选择器 | 联系人 | 必选，来源 `person.id` |
+
+## 校验规则
+
+1. `trial_db_id` 必选，且必须引用已存在的 `trial.id`。
+2. `person_db_id` 必选，且必须引用已存在的 `person.id`。
+3. 同一 trial 下不建议重复添加同一个 person。
+
+## 接口能力
+
+本文档原始需求未强制限定 trial_contact 的独立 URL。实现时可以随 trial 新增/编辑一起保存，也可以提供 trial 联系人子资源接口；前端需要具备新增、删除、查询 trial 联系人的能力。
+
+## 导入导出
+
+1. 支持通过 Core 导入流程导入 `trial_contact`。
+2. 外键列支持填写 ID；可额外支持名称匹配，但名称重复时必须报错。
+3. 导入时需要校验 trial 和 person 是否存在。
+4. 错误报告返回行号、字段名、错误原因、建议修正方式。
+
+## 删除/停用
+
+`trial_contact` 是关系记录，可在 Trial 新增/编辑页或详情页移除。删除关系不应删除 `trial` 或 `person` 主数据。
+
+## 验收点
+
+1. Trial 新增/编辑页可增删联系人。
+2. 联系人选择器展示 person 名称，提交保存 `person.id`。
+3. 删除 trial_contact 后，person 主数据仍保留。
--- a/docs/dev/01-core/11-trial_publication.md
+++ b/docs/dev/01-core/11-trial_publication.md
@@ -0,0 +1,56 @@
+# 01 Core - trial_publication 表录入说明
+
+来源：`docs/requirements/01-core-data-entry-requirements.md`
+
+## 录入目标
+
+`trial_publication` 是给 trial 记录出版物、报告或文献引用的痕迹表。它挂在 trial 下，用于说明试验相关的外部文献和永久标识。
+
+## 前置依赖和下游引用
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `trial_publication` |
+| 前置依赖 | `trial` |
+| 下游引用 | trial 出版物/报告展示 |
+
+## 页面入口
+
+| 页面 | 录入要求 |
+| --- | --- |
+| Trial 新增/编辑页 | 出版物区域可增删 publication 记录 |
+| Trial 详情页 | 展示 trial 的出版物、报告或引用 |
+
+## 字段录入
+
+| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
+| --- | --- | --- | --- | --- |
+| `id` | varchar(255) | 隐藏/只读 | 出版物记录主键 | 必填、唯一 |
+| `publicationpui` | varchar(255) | 文本框 | 出版物 PUI | 可选 |
+| `publication_reference` | varchar(255) | 文本框/URL | 出版物引用 | 可选 |
+| `trial_id` | varchar(255) | Trial 选择器 | 所属 trial | 必选，来源 `trial.id` |
+
+## 校验规则
+
+1. `id` 必填且唯一，新增时可由系统生成。
+2. `trial_id` 必选，且必须引用已存在的 `trial.id`。
+3. `publication_reference` 如果录入 URL，需要做 URL 格式校验。
+4. `publicationpui` 建议唯一。
+
+## 接口能力
+
+本文档原始需求未强制限定 trial_publication 的独立 URL。实现时可以随 trial 新增/编辑一起保存，也可以提供 trial 出版物子资源接口；前端需要具备新增、删除、查询 trial 出版物的能力。
+
+## 导入导出
+
+原始导入对象清单未单独列出 `trial_publication`，但字段需求中包含该表。若纳入 Core 导入，应遵循通用导入流程：模板列名使用数据库字段名，外键校验 `trial_id`，错误报告返回行号、字段名和错误原因。
+
+## 删除/停用
+
+`trial_publication` 是 trial 的明细记录，可在 Trial 新增/编辑页或详情页移除。删除 publication 记录不应删除 `trial` 主数据。
+
+## 验收点
+
+1. Trial 新增/编辑页可维护出版物记录。
+2. `trial_id` 不存在时不能提交。
+3. 删除 publication 记录后，trial 主数据仍保留。
--- a/docs/dev/01-core/12-study_contact.md
+++ b/docs/dev/01-core/12-study_contact.md
@@ -0,0 +1,61 @@
+# 01 Core - study_contact 表录入说明
+
+来源：`docs/requirements/01-core-data-entry-requirements.md`
+
+## 录入目标
+
+`study_contact` 是给 study 添加联系人的关系表，不是独立主数据。它记录 study 与 person 的多对多关系，用于 Study 工作台联系人展示、责任追踪、权限和通知。
+
+## 前置依赖和下游引用
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `study_contact` |
+| 前置依赖 | `study`、`person` |
+| 下游引用 | Study 工作台联系人展示、权限和通知 |
+
+## 页面入口
+
+| 页面 | 录入要求 |
+| --- | --- |
+| Study 新增/编辑页 | 联系人区域多选 person，可增删 |
+| Study 工作台 | 展示 study 联系人 |
+| 批量导入 | 支持通过 Core 导入流程导入 study 联系人关系 |
+
+## 字段录入
+
+| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
+| --- | --- | --- | --- | --- |
+| `study_db_id` | varchar(255) | Study 选择器 | 所属 study | 必选，来源 `study.id` |
+| `person_db_id` | varchar(255) | 人员选择器 | 联系人 | 必选，来源 `person.id` |
+
+## 校验规则
+
+1. `study_db_id` 必选，且必须引用已存在的 `study.id`。
+2. `person_db_id` 必选，且必须引用已存在的 `person.id`。
+3. 同一 study 下不建议重复添加同一个 person。
+
+## 接口能力
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /studies/{id}/contacts` | study 联系人，返回 person 列表 |
+
+本文档原始需求未强制限定 study_contact 的写入 URL。实现时可以随 study 新增/编辑一起保存，也可以提供 study 联系人子资源接口；前端需要具备新增、删除、查询 study 联系人的能力。
+
+## 导入导出
+
+1. 支持通过 Core 导入流程导入 `study_contact`。
+2. 外键列支持填写 ID；可额外支持名称匹配，但名称重复时必须报错。
+3. 导入时需要校验 study 和 person 是否存在。
+4. 错误报告返回行号、字段名、错误原因、建议修正方式。
+
+## 删除/停用
+
+`study_contact` 是关系记录，可在 Study 新增/编辑页或工作台移除。删除关系不应删除 `study` 或 `person` 主数据。
+
+## 验收点
+
+1. Study 新增/编辑页可增删联系人。
+2. Study 工作台能展示联系人列表。
+3. 删除 study_contact 后，person 主数据仍保留。
--- a/docs/dev/01-core/13-study_season.md
+++ b/docs/dev/01-core/13-study_season.md
@@ -0,0 +1,61 @@
+# 01 Core - study_season 表录入说明
+
+来源：`docs/requirements/01-core-data-entry-requirements.md`
+
+## 录入目标
+
+`study_season` 是给 study 绑定 season 的关系表。一个 study 可以关联多个 season，用于多季节筛选、统计和 Study 工作台上下文展示。
+
+## 前置依赖和下游引用
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `study_season` |
+| 前置依赖 | `study`、`season` |
+| 下游引用 | Study 工作台季节展示、多季节筛选和统计 |
+
+## 页面入口
+
+| 页面 | 录入要求 |
+| --- | --- |
+| Study 新增/编辑页 | 季节区域多选 season |
+| Study 工作台 | 展示 study 关联 season |
+| 批量导入 | 支持通过 Core 导入流程导入 study 与 season 关系 |
+
+## 字段录入
+
+| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
+| --- | --- | --- | --- | --- |
+| `study_db_id` | varchar(255) | Study 选择器 | 所属 study | 必选，来源 `study.id` |
+| `season_db_id` | varchar(255) | Season 选择器 | 关联季节 | 必选，来源 `season.id` |
+
+## 校验规则
+
+1. `study_db_id` 必选，且必须引用已存在的 `study.id`。
+2. `season_db_id` 必选，且必须引用已存在的 `season.id`。
+3. 同一 study 下不建议重复绑定同一个 season。
+
+## 接口能力
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /studies/{id}/seasons` | study 季节，返回 season 列表 |
+
+本文档原始需求未强制限定 study_season 的写入 URL。实现时可以随 study 新增/编辑一起保存，也可以提供 study season 子资源接口；前端需要具备新增、删除、查询 study season 的能力。
+
+## 导入导出
+
+1. 支持通过 Core 导入流程导入 `study_season`。
+2. 外键列支持填写 ID；可额外支持名称匹配，但名称重复时必须报错。
+3. 导入时需要校验 study 和 season 是否存在。
+4. 错误报告返回行号、字段名、错误原因、建议修正方式。
+
+## 删除/停用
+
+`study_season` 是关系记录，可在 Study 新增/编辑页或工作台移除。删除关系不应删除 `study` 或 `season` 主数据。
+
+## 验收点
+
+1. Study 新增/编辑页可多选 season。
+2. Study 工作台能展示关联 season。
+3. 删除 study_season 后，season 主数据仍保留。