fix:sample/plate 之前的开发

docs/dev/04-germplasm/01-breeding_method.md

@@ -0,0 +1,37 @@
+# 04 Germplasm / Seed - breeding_method 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`breeding_method` 是育种方法字典，用来说明 germplasm 是通过什么方式形成的，例如杂交选育、回交、自交系选育、诱变、DH、克隆选择等。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `breeding_method` |
+| Java 实体 | `BreedingMethodEntity` |
+| 前置依赖 | 无 |
+| 下游引用 | `germplasm.breeding_method_id` |
+| API | `/brapi/v2/breedingmethods` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | 育种方法主键 | 系统生成；导入可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `name` | 方法名称 | 用户录入 | 必填，建议唯一 |
+| `abbreviation` | 方法缩写 | 用户录入 | 可选，建议唯一 |
+| `description` | 方法说明 | 多行文本 | 可选 |
+
+## 页面与交互
+
+- 列表页展示 name、abbreviation、description、引用 germplasm 数。
+- 新增/编辑页为简单字典表单。
+
+## 关键校验
+
+1. `name` 必填。
+2. 已被 `germplasm` 引用时不允许物理删除，只允许停用或提示引用关系。

docs/dev/04-germplasm/02-germplasm.md

@@ -0,0 +1,68 @@
+# 04 Germplasm / Seed - germplasm 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`germplasm` 是种质主表，保存 accession、PUI、分类、采集、来源、育种方法和展示名称等身份信息。它不是库存批次；库存批次由 `seed_lot` 表达。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `germplasm` |
+| Java 实体 | `GermplasmEntity` |
+| 前置依赖 | `crop`，可选 `breeding_method` |
+| 下游引用 | `germplasm_attribute_value`、`germplasm_donor`、`germplasm_institute`、`germplasm_origin`、`germplasm_synonym`、`germplasm_taxon`、`pedigree_node`、`cross_parent`、`seed_lot_content_mixture` |
+| API | `/brapi/v2/germplasm` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | germplasm 主键 | 系统生成；导入可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `germplasm_name` | 种质名称 | 用户录入/导入 | 建议必填 |
+| `default_display_name` | 默认展示名称 | 用户录入/自动生成 | 可选，缺省用 germplasm_name |
+| `germplasmpui` | 种质永久标识 | 用户录入/导入 | 可选，建议唯一 |
+| `accession_number` | accession 编号 | 用户录入/导入 | 可选，建议唯一 |
+| `crop_id` | 所属作物 | Crop 选择器 | 建议必选，若填需存在 |
+| `breeding_method_id` | 育种方法 | BreedingMethod 选择器 | 可选，若填需存在 |
+| `genus` | 属 | 用户录入 | 可选 |
+| `species` | 种 | 用户录入 | 可选 |
+| `species_authority` | 种命名人 | 用户录入 | 可选 |
+| `subtaxa` | 亚种/变种 | 用户录入 | 可选 |
+| `subtaxa_authority` | 亚种命名人 | 用户录入 | 可选 |
+| `country_of_origin_code` | 来源国家代码 | 国家选择器 | 可选 |
+| `collection` | collection | 用户录入 | 可选 |
+| `acquisition_date` | 获取日期 | 日期选择器 | 可选 |
+| `acquisition_source_code` | 获取来源编码 | 枚举选择 | 可选 |
+| `biological_status_of_accession_code` | 生物状态编码 | 枚举选择 | 可选 |
+| `mls_status` | MLS 状态 | 枚举选择 | 可选 |
+| `germplasm_preprocessing` | 种质预处理说明 | 文本 | 可选 |
+| `seed_source` | 种子来源描述字段 | 文本 | 可选，不等于 seed_lot |
+| `seed_source_description` | 种子来源补充说明 | 多行文本 | 可选 |
+| `documentationurl` | 文档链接 | URL 输入 | 可选，URL 格式校验 |
+
+## 附属信息
+
+| 附属表 | 内容 |
+| --- | --- |
+| `germplasm_donor` | donor accession、donor institute |
+| `germplasm_institute` | host、donor、breeding、collecting、redundant 等机构 |
+| `germplasm_origin` | 来源坐标和坐标不确定性 |
+| `germplasm_synonym` | 别名及别名类型 |
+| `germplasm_taxon` | taxon 来源和值 |
+| `germplasm_entity_type_of_germplasm_storage_code` | storage type code 列表 |
+
+## 页面与交互
+
+- Germplasm 列表页支持按 crop、germplasmName、accessionNumber、PUI、synonym 查询。
+- 详情页以 Tab 展示 attributes、donors、institutes、origin、synonyms、taxon、pedigree、seed lots、cross parent 记录。
+- 从 Study/ObservationUnit 或 SeedLot 进入时应能回到 germplasm 详情。
+
+## 关键校验
+
+1. `germplasm_name` 建议必填，`accession_number` 和 `germplasmpui` 建议唯一。
+2. 删除 germplasm 前必须检查属性值、seed lot 组成、cross parent、pedigree、sample/taxon 等引用。
+3. 不要用 `seed_source` 表达库存；库存必须走 `seed_lot`。

docs/dev/04-germplasm/03-germplasm_donor.md

@@ -0,0 +1,39 @@
+# 04 Germplasm / Seed - germplasm_donor 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`germplasm_donor` 记录某个 germplasm 的 donor accession 和 donor institute 信息，是 germplasm 的附属明细。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `germplasm_donor` |
+| Java 实体 | `DonorEntity` |
+| 前置依赖 | `germplasm` |
+| 下游引用 | MCPD 展示、来源追踪 |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | donor 记录主键 | 系统生成；导入可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `germplasm_id` | 所属 germplasm | Germplasm 选择器/详情页带出 | 必选，必须存在 |
+| `donor_accession_number` | donor accession 编号 | 用户录入 | 可选 |
+| `donor_institute_code` | donor 机构代码 | 用户录入/选择 | 可选 |
+| `donor_institute_name` | donor 机构名称 | 用户录入/选择 | 可选 |
+| `germplasmpui` | donor germplasm PUI | 用户录入 | 可选 |
+
+## 页面与交互
+
+- 在 Germplasm 详情页 Donor Tab 内维护。
+- 支持一条 germplasm 维护多个 donor 记录。
+
+## 关键校验
+
+1. `germplasm_id` 必须存在。
+2. 同一 germplasm 下 donor accession + institute code 不建议重复。
+3. 删除 donor 记录不应删除 germplasm 主数据。

docs/dev/04-germplasm/04-germplasm_institute.md

@@ -0,0 +1,38 @@
+# 04 Germplasm / Seed - germplasm_institute 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`germplasm_institute` 记录 germplasm 相关机构，包括 host、donor、breeding、collecting、redundant 等类型。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `germplasm_institute` |
+| Java 实体 | `GermplasmInstituteEntity` |
+| 前置依赖 | `germplasm` |
+| 下游引用 | Germplasm MCPD、机构筛选 |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | 机构记录主键 | 系统生成 | 必填、唯一 |
+| `germplasm_id` | 所属 germplasm | Germplasm 选择器/详情页带出 | 必选，必须存在 |
+| `institute_type` | 机构类型 | 枚举选择 | HOST、DONOR、BREEDING、COLLECTING、REDUNDANT |
+| `institute_code` | 机构代码 | 用户录入 | 可选 |
+| `institute_name` | 机构名称 | 用户录入 | 建议必填 |
+| `institute_address` | 机构地址 | 多行文本 | 可选 |
+
+## 页面与交互
+
+- 在 Germplasm 详情页 Institute Tab 内维护。
+- 可把 HOST institute 作为 germplasm 主信息摘要展示。
+
+## 关键校验
+
+1. `germplasm_id` 必须存在。
+2. 同一 germplasm 下同类型、同 code 的机构不建议重复。
+3. 删除 institute 记录不应删除 germplasm 主数据。

docs/dev/04-germplasm/05-germplasm_origin.md

@@ -0,0 +1,36 @@
+# 04 Germplasm / Seed - germplasm_origin 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`germplasm_origin` 记录 germplasm 的来源地坐标和坐标不确定性，适合表达采集地点或原产地的空间信息。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `germplasm_origin` |
+| Java 实体 | `GermplasmOriginEntity` |
+| 前置依赖 | `germplasm`，可选 `geojson` |
+| 下游引用 | 地理来源展示、MCPD |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | origin 记录主键 | 系统生成 | 必填、唯一 |
+| `germplasm_id` | 所属 germplasm | Germplasm 选择器/详情页带出 | 必选，必须存在 |
+| `coordinate_uncertainty` | 坐标不确定性 | 文本/数字 | 可选 |
+| `coordinates_id` | GeoJSON 坐标对象 | 地图取点/GeoJSON 导入 | 可选，若填需存在 |
+
+## 页面与交互
+
+- 在 Germplasm 详情页 Origin Tab 内维护。
+- 支持地图取点和 GeoJSON 查看。
+
+## 关键校验
+
+1. `germplasm_id` 必须存在。
+2. 坐标格式需要合法。
+3. 删除 origin 记录不应删除 germplasm 主数据。

docs/dev/04-germplasm/06-germplasm_synonym.md

@@ -0,0 +1,36 @@
+# 04 Germplasm / Seed - germplasm_synonym 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`germplasm_synonym` 记录 germplasm 的别名、旧名、商品名或本地名，用于检索和展示。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `germplasm_synonym` |
+| Java 实体 | `GermplasmSynonymEntity` |
+| 前置依赖 | `germplasm` |
+| 下游引用 | Germplasm 搜索、详情展示 |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | synonym 记录主键 | 系统生成 | 必填、唯一 |
+| `germplasm_id` | 所属 germplasm | Germplasm 选择器/详情页带出 | 必选，必须存在 |
+| `synonym` | 别名 | 用户录入 | 必填 |
+| `type` | 别名类型 | 下拉/文本 | 可选，如 local、commercial、old name |
+
+## 页面与交互
+
+- 在 Germplasm 详情页 Synonym Tab 内维护。
+- Germplasm 列表搜索应支持 synonym 命中。
+
+## 关键校验
+
+1. `germplasm_id` 必须存在。
+2. 同一 germplasm 下同一个 synonym 不应重复。
+3. 删除 synonym 不应删除 germplasm 主数据。

docs/dev/04-germplasm/07-germplasm_taxon.md

@@ -0,0 +1,36 @@
+# 04 Germplasm / Seed - germplasm_taxon 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`germplasm_taxon` 记录外部 taxon 标识和来源，用于把 germplasm 连接到分类数据库或外部生物分类体系。该表由 `TaxonEntity` 映射。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `germplasm_taxon` |
+| Java 实体 | `TaxonEntity` |
+| 前置依赖 | `germplasm` |
+| 下游引用 | `sample.taxon_id_id`、分类展示 |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | taxon 记录主键 | 系统生成 | 必填、唯一 |
+| `germplasm_id` | 所属 germplasm | Germplasm 选择器/详情页带出 | 必选，必须存在 |
+| `source_name` | taxon 来源名称 | 文本/下拉 | 可选，如 NCBI Taxonomy |
+| `taxon_id` | taxon 标识 | 用户录入 | 必填 |
+
+## 页面与交互
+
+- 在 Germplasm 详情页 Taxon Tab 内维护。
+- Sample 表可引用 taxon 记录。
+
+## 关键校验
+
+1. `germplasm_id` 必须存在。
+2. 同一 source 下 taxon_id 不建议重复。
+3. 删除 taxon 前检查 sample 引用。

docs/dev/04-germplasm/08-germplasm_attribute_definition.md

@@ -0,0 +1,55 @@
+# 04 Germplasm / Seed - germplasm_attribute_definition 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`germplasm_attribute_definition` 定义 germplasm 可维护的属性。它继承变量定义体系，可关联 crop、trait、method、scale、ontology。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `germplasm_attribute_definition` |
+| Java 实体 | `GermplasmAttributeDefinitionEntity` |
+| 前置依赖 | `crop`、`trait`、`method`、`scale`、`ontology` |
+| 下游引用 | `germplasm_attribute_value` |
+| API | `/brapi/v2/attributes` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | 属性定义主键 | 系统生成；导入可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `name` | 属性名称 | 用户录入 | 必填 |
+| `code` | 属性编码 | 用户录入 | 可选，建议唯一 |
+| `pui` | 永久标识 | 用户录入 | 可选，建议唯一 |
+| `attribute_category` | 属性分类 | 下拉/文本 | 可选 |
+| `datatype` | 数据类型 | 下拉 | 建议必填 |
+| `description` | 属性说明 | 多行文本 | 可选 |
+| `uri` | 外部 URI | URL 输入 | 可选，URL 格式校验 |
+| `crop_id` | 作物 | Crop 选择器 | 可选 |
+| `trait_id` | 性状 | Trait 选择器 | 可选 |
+| `method_id` | 方法 | Method 选择器 | 可选 |
+| `scale_id` | 标尺 | Scale 选择器 | 可选 |
+| `ontology_id` | 本体 | Ontology 选择器 | 可选 |
+| `documentationurl` | 文档链接 | URL 输入 | 可选 |
+| `status` | 状态 | 下拉/文本 | 可选 |
+| `default_value` | 默认值 | 文本 | 可选 |
+| `growth_stage` | 生育期 | 文本 | 可选 |
+| `institution` | 机构 | 文本 | 可选 |
+| `language` | 语言 | 文本 | 可选 |
+| `scientist` | 科学家/维护人 | 文本 | 可选 |
+| `submission_timestamp` | 提交时间 | 日期时间 | 可选 |
+
+## 页面与交互
+
+- Attribute Definition 列表页支持按 crop、category、datatype、keyword 查询。
+- 创建 attribute value 前必须先有 definition。
+
+## 关键校验
+
+1. `name` 必填。
+2. 已被 `germplasm_attribute_value` 引用时不允许物理删除。
+3. `datatype` 要与 value 输入控件联动。

docs/dev/04-germplasm/09-germplasm_attribute_value.md

@@ -0,0 +1,39 @@
+# 04 Germplasm / Seed - germplasm_attribute_value 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`germplasm_attribute_value` 保存某个 germplasm 在某个属性定义上的实际取值。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `germplasm_attribute_value` |
+| Java 实体 | `GermplasmAttributeValueEntity` |
+| 前置依赖 | `germplasm`、`germplasm_attribute_definition` |
+| 下游引用 | 属性查询、详情展示 |
+| API | `/brapi/v2/attributevalues` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | 属性值主键 | 系统生成；导入可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `germplasm_id` | 所属 germplasm | Germplasm 选择器/详情页带出 | 必选，必须存在 |
+| `attribute_id` | 属性定义 | Attribute 选择器 | 必选，必须存在 |
+| `value` | 属性值 | 根据 definition.datatype 选择控件 | 必填或按业务要求 |
+| `determined_date` | 测定日期 | 日期选择器 | 可选 |
+
+## 页面与交互
+
+- 在 Germplasm 详情页 Attributes Tab 维护。
+- 批量导入时按 germplasm + attribute 组成矩阵录入更高效。
+
+## 关键校验
+
+1. `germplasm_id` 与 `attribute_id` 必须存在。
+2. 同一 germplasm 下同一 attribute 不建议重复，若允许多次测定，需要用 determined_date 区分。
+3. `value` 必须符合 attribute definition 的 datatype。

docs/dev/04-germplasm/10-crossing_project.md

@@ -0,0 +1,38 @@
+# 04 Germplasm / Seed - crossing_project 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`crossing_project` 表示杂交项目，是 cross、planned cross、cross parent 和 pedigree node 的上游组织维度，通常挂在 Core 的 `program` 下。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `crossing_project` |
+| Java 实体 | `CrossingProjectEntity` |
+| 前置依赖 | `program` |
+| 下游引用 | `cross_entity`、`cross_parent`、`pedigree_node` |
+| API | `/brapi/v2/crossingprojects` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | crossing project 主键 | 系统生成；导入可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `name` | 杂交项目名称 | 用户录入 | 必填，建议同一 program 下唯一 |
+| `description` | 项目说明 | 多行文本 | 可选 |
+| `program_id` | 所属 program | Program 选择器 | 必选，必须存在 |
+
+## 页面与交互
+
+- 列表页支持按 program、keyword 查询。
+- 详情页展示 crosses、planned crosses、potential parents、pedigree nodes。
+
+## 关键校验
+
+1. `program_id` 必须存在。
+2. 删除 crossing_project 前检查 cross、cross_parent、pedigree_node 引用。
+3. 如果 program 有 crop，创建 cross 时亲本 germplasm 建议与 program crop 一致。

docs/dev/04-germplasm/11-cross_entity.md

@@ -0,0 +1,50 @@
+# 04 Germplasm / Seed - cross_entity 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`cross_entity` 是 Cross 和 PlannedCross 的统一落库表。`plannedcross` 不是独立数据库表，计划杂交通过 `planned=true` 表达；实际杂交可以通过 `planned_cross_id` 关联计划杂交。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `cross_entity` |
+| Java 实体 | `CrossEntity` |
+| 前置依赖 | `crossing_project`，可选自关联 `cross_entity` |
+| 下游引用 | `cross_parent`、`cross_pollination_event`、`seed_lot_content_mixture` |
+| API | `/brapi/v2/crosses`、`/brapi/v2/plannedcrosses` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | cross 主键 | 系统生成；导入可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `name` | cross 名称 | 用户录入/自动生成 | 建议必填 |
+| `cross_type` | 杂交类型 | 枚举选择 | 可选 |
+| `crossing_project_id` | 所属 crossing project | CrossingProject 选择器 | 建议必选，若填需存在 |
+| `status` | planned cross 状态 | 枚举选择 | 计划杂交常用 |
+| `planned` | 是否为计划杂交 | 开关 | 必填，默认 false |
+| `planned_cross_id` | 关联计划杂交 | Cross 选择器 | 可选，必须指向 `planned=true` 的 cross |
+
+## 附属集合字段
+
+| 附属表 | 内容 |
+| --- | --- |
+| `cross_entity_cross_attributes` | crossAttributes 列表 |
+| `cross_parent` | cross 的亲本 |
+| `cross_pollination_event` | 授粉事件 |
+
+## 页面与交互
+
+- Cross 列表页展示实际杂交；PlannedCross 列表页展示 `planned=true` 数据。
+- 新建实际 cross 时可选择 planned cross，并继承 planned cross 的亲本作为初始值。
+- 详情页展示 parents、pollination events 和 seed lot 组成入口。
+
+## 关键校验
+
+1. `plannedcross` 不新建表，所有 planned cross 走 `cross_entity`。
+2. `planned_cross_id` 不能指向自己。
+3. 删除 cross 前检查 `cross_parent`、`cross_pollination_event`、`seed_lot_content_mixture` 引用。

docs/dev/04-germplasm/12-cross_parent.md

@@ -0,0 +1,39 @@
+# 04 Germplasm / Seed - cross_parent 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`cross_parent` 连接 cross 与亲本来源。亲本可以是 germplasm，也可以是 observation_unit，用来表达实际田间单株或 plot 来源。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `cross_parent` |
+| Java 实体 | `CrossParentEntity` |
+| 前置依赖 | `cross_entity`、`crossing_project`、`germplasm` 或 `observation_unit` |
+| 下游引用 | 杂交亲本展示和校验 |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | cross parent 主键 | 系统生成 | 必填、唯一 |
+| `cross_id` | 所属 cross | Cross 选择器/详情页带出 | 必选，必须存在 |
+| `crossing_project_id` | 所属 crossing project | 自动带出/选择器 | 建议与 cross 一致 |
+| `germplasm_id` | 亲本 germplasm | Germplasm 选择器 | 与 observation_unit 至少填一个 |
+| `observation_unit_id` | 亲本 observation unit | ObservationUnit 选择器 | 与 germplasm 至少填一个 |
+| `parent_type` | 亲本类型 | 枚举选择 | FEMALE、MALE、SELF、POPULATION、CLONAL 等 |
+
+## 页面与交互
+
+- 在 Cross 或 PlannedCross 详情页 Parents Tab 内维护。
+- 创建 cross 时至少添加一个亲本；常见杂交需要 FEMALE 和 MALE。
+
+## 关键校验
+
+1. `cross_id` 必须存在。
+2. `germplasm_id` 和 `observation_unit_id` 至少填写一个，不建议同时为空。
+3. 同一 cross 下相同 parentType + germplasm/observationUnit 不应重复。
+4. 如果填 `crossing_project_id`，应与 `cross.crossing_project_id` 一致。

docs/dev/04-germplasm/13-cross_pollination_event.md

@@ -0,0 +1,37 @@
+# 04 Germplasm / Seed - cross_pollination_event 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`cross_pollination_event` 记录实际杂交过程中的授粉事件，包括授粉编号、时间和是否成功。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `cross_pollination_event` |
+| Java 实体 | `CrossPollinationEventEntity` |
+| 前置依赖 | `cross_entity` |
+| 下游引用 | Cross 过程追踪 |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | 授粉事件主键 | 系统生成 | 必填、唯一 |
+| `cross_id` | 所属 cross | Cross 选择器/详情页带出 | 必选，必须存在 |
+| `pollination_number` | 授粉编号 | 用户录入/自动生成 | 可选，建议同一 cross 下唯一 |
+| `pollination_successful` | 是否授粉成功 | 开关 | 可选 |
+| `pollination_time_stamp` | 授粉时间 | 日期时间选择器 | 可选 |
+
+## 页面与交互
+
+- 在 Cross 详情页 Pollination Events Tab 内维护。
+- 可以按授粉时间排序展示。
+
+## 关键校验
+
+1. `cross_id` 必须存在。
+2. 同一 cross 下 `pollination_number` 不建议重复。
+3. 删除授粉事件不应删除 cross 主数据。

docs/dev/04-germplasm/14-pedigree_node.md

@@ -0,0 +1,40 @@
+# 04 Germplasm / Seed - pedigree_node 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`pedigree_node` 表示系谱中的一个节点，一个节点通常关联一个 germplasm，并可归属 crossing_project。节点之间的 parent/child/sibling 关系由 `pedigree_edge` 记录。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `pedigree_node` |
+| Java 实体 | `PedigreeNodeEntity` |
+| 前置依赖 | `germplasm`、可选 `crossing_project` |
+| 下游引用 | `pedigree_edge` |
+| API | `/brapi/v2/pedigree` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | pedigree node 主键 | 系统生成；导入可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `germplasm_id` | 对应 germplasm | Germplasm 选择器 | 建议必选，若填需存在 |
+| `crossing_project_id` | 所属 crossing project | CrossingProject 选择器 | 可选 |
+| `crossing_year` | 杂交年份 | 年份输入 | 可选 |
+| `family_code` | 家系编号 | 文本 | 可选 |
+| `pedigree_string` | 系谱字符串 | 文本 | 可选 |
+
+## 页面与交互
+
+- 可从 Germplasm 详情页进入 Pedigree Tab。
+- 支持图谱视图和表格视图。
+
+## 关键校验
+
+1. 同一 germplasm 通常只应有一个 pedigree node。
+2. 删除 pedigree_node 前检查 `pedigree_edge` 中 this_node 和 connceted_node 引用。
+3. 导入 pedigree 时需要先创建所有节点，再创建边。

docs/dev/04-germplasm/15-pedigree_edge.md

@@ -0,0 +1,43 @@
+# 04 Germplasm / Seed - pedigree_edge 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`pedigree_edge` 描述两个 pedigree_node 之间的 parent、child 或 sibling 关系，并标注亲本类型。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `pedigree_edge` |
+| Java 实体 | `PedigreeEdgeEntity` |
+| 前置依赖 | `pedigree_node` |
+| 下游引用 | 系谱查询、亲本/后代展示 |
+| API | `/brapi/v2/pedigree` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | pedigree edge 主键 | 系统生成；导入可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `this_node_id` | 当前节点 | PedigreeNode 选择器 | 必选，必须存在 |
+| `connceted_node_id` | 关联节点 | PedigreeNode 选择器 | 必选，必须存在 |
+| `edge_type` | 关系类型 | 枚举选择 | parent、child、sibling |
+| `parent_type` | 亲本类型 | 枚举选择 | 可选，如 FEMALE、MALE |
+
+## 命名注意
+
+实体字段是 `conncetedNode`，拼写与 `connected` 不同；开发 DTO、SQL、迁移时要留意当前代码和数据库列名。
+
+## 页面与交互
+
+- 在 Germplasm/Pedigree 图谱视图中维护。
+- 创建 parent 关系时可自动补齐反向 child 关系，具体以业务实现为准。
+
+## 关键校验
+
+1. `this_node_id` 和 `connceted_node_id` 必须存在。
+2. 两个节点不能相同。
+3. 同一节点之间同一种 edge_type 不应重复。

docs/dev/04-germplasm/16-seed_lot.md

@@ -0,0 +1,46 @@
+# 04 Germplasm / Seed - seed_lot 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`seed_lot` 是真实库存批次，描述某一批种子当前数量、单位、库位和项目归属。同一个 germplasm 可以有多个 seed lot。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `seed_lot` |
+| Java 实体 | `SeedLotEntity` |
+| 前置依赖 | 可选 `location`、`program` |
+| 下游引用 | `seed_lot_content_mixture`、`seed_lot_transaction` |
+| API | `/brapi/v2/seedlots` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | seed lot 主键 | 系统生成；导入可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `name` | 批次名称 | 用户录入/自动生成 | 必填，建议同一 program 下唯一 |
+| `amount` | 当前库存数量 | 交易自动更新/用户录入初始值 | 非负 |
+| `units` | 数量单位 | 下拉/文本 | 建议必填 |
+| `created_date` | 创建时间 | 系统写入/导入 | 可选 |
+| `last_updated` | 最后更新时间 | 系统更新 | 不建议手填 |
+| `description` | 批次说明 | 多行文本 | 可选 |
+| `source_collection` | 来源 collection | 文本 | 可选 |
+| `storage_location` | 具体库位 | 文本 | 可选 |
+| `location_id` | 所在地点/库位 | Location 选择器 | 可选，若填需存在 |
+| `program_id` | 所属项目 | Program 选择器 | 可选，若填需存在 |
+
+## 页面与交互
+
+- SeedLot 列表页支持按 program、location、name、库存状态查询。
+- 详情页展示 content mixture 和 transactions。
+- 创建 seed lot 后建议至少维护一条 `seed_lot_content_mixture`。
+
+## 关键校验
+
+1. `amount` 不允许为负。
+2. 普通用户不应直接编辑 amount，库存变化应通过 `seed_lot_transaction`。
+3. 删除 seed lot 前检查组成明细和交易引用。

docs/dev/04-germplasm/17-seed_lot_content_mixture.md

@@ -0,0 +1,38 @@
+# 04 Germplasm / Seed - seed_lot_content_mixture 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`seed_lot_content_mixture` 表示 seed lot 的组成明细。它可以把 seed lot 连接到 germplasm，也可以连接到 cross_entity，适合表达混合批次或杂交产生的批次。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `seed_lot_content_mixture` |
+| Java 实体 | `SeedLotContentMixtureEntity` |
+| 前置依赖 | `seed_lot`、可选 `germplasm`、可选 `cross_entity` |
+| 下游引用 | Seed lot 组成展示 |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | 组成明细主键 | 系统生成 | 必填、唯一 |
+| `seed_lot_id` | 所属 seed lot | SeedLot 选择器/详情页带出 | 必选，必须存在 |
+| `germplasm_id` | 组成 germplasm | Germplasm 选择器 | 与 cross_id 至少填一个 |
+| `cross_id` | 组成来源 cross | Cross 选择器 | 与 germplasm_id 至少填一个 |
+| `mixture_percentage` | 组成比例 | 数字输入 | 0-100 |
+
+## 页面与交互
+
+- 在 SeedLot 详情页 Content Mixture Tab 内维护。
+- 支持多个组成明细，合计比例可展示为进度或校验提示。
+
+## 关键校验
+
+1. `seed_lot_id` 必须存在。
+2. `germplasm_id` 与 `cross_id` 至少填写一个。
+3. 同一 seed lot 下 mixture_percentage 合计建议为 100。
+4. 删除组成明细不应删除 seed lot、germplasm 或 cross 主数据。

docs/dev/04-germplasm/18-seed_lot_transaction.md

@@ -0,0 +1,43 @@
+# 04 Germplasm / Seed - seed_lot_transaction 表录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+## 录入目标
+
+`seed_lot_transaction` 记录 seed lot 之间的库存流转，例如入库、出库、转移、分装、合并或消耗。它表达 from seed lot 到 to seed lot 的数量变化。
+
+## 上下游关系
+
+| 类型 | 内容 |
+| --- | --- |
+| 表 | `seed_lot_transaction` |
+| Java 实体 | `SeedLotTransactionEntity` |
+| 前置依赖 | `from_seed_lot`、`to_seed_lot` |
+| 下游引用 | 库存追踪、库存数量更新 |
+| API | `/brapi/v2/seedlots/transactions`、`/brapi/v2/seedlots/{seedLotDbId}/transactions` |
+
+## 字段录入
+
+| 字段 | 业务意义 | 录入方式 | 校验规则 |
+| --- | --- | --- | --- |
+| `id` | transaction 主键 | 系统生成；导入可指定 | 必填、唯一 |
+| `auth_user_id` | 数据所属用户 | 登录上下文自动写入 | 不允许前端手填 |
+| `from_seed_lot_id` | 来源 seed lot | SeedLot 选择器 | 入库场景可为空，若填需存在 |
+| `to_seed_lot_id` | 目标 seed lot | SeedLot 选择器 | 出库/消耗场景可为空，若填需存在 |
+| `amount` | 流转数量 | 数字输入 | 必填，正数 |
+| `units` | 数量单位 | 下拉/文本 | 必填，应与批次单位一致或可换算 |
+| `timestamp` | 流转时间 | 日期时间选择器 | 默认当前时间 |
+| `description` | 流转说明 | 多行文本 | 可选 |
+
+## 页面与交互
+
+- 在 SeedLot 详情页 Transactions Tab 展示相关流转。
+- 新增交易后应更新 from/to seed lot 的 amount 和 last_updated。
+- 支持按时间、from/to seed lot、program、location 查询。
+
+## 关键校验
+
+1. `from_seed_lot_id` 和 `to_seed_lot_id` 至少填写一个。
+2. `from_seed_lot_id` 不能等于 `to_seed_lot_id`。
+3. 出库或转移时，来源批次数量不能被扣成负数。
+4. transaction 是业务动作痕迹，原则上不允许随意物理删除。

docs/dev/04-germplasm/README.md

@@ -0,0 +1,46 @@
+# 04 Germplasm / Seed 开发录入说明
+
+来源：`docs/architecture/04-germplasm-seed-data-flow.md`
+
+本目录按 Germplasm / Seed 模块的数据录入顺序拆分开发说明。主线是：
+
+```text
+breeding_method -> germplasm
+germplasm_attribute_definition -> germplasm_attribute_value
+program -> crossing_project -> cross_entity -> cross_parent
+germplasm / cross_entity -> seed_lot_content_mixture -> seed_lot
+seed_lot -> seed_lot_transaction
+germplasm -> pedigree_node -> pedigree_edge
+```
+
+## 文档清单
+
+| 顺序 | 文档 | 表 | 作用 |
+| --- | --- | --- | --- |
+| 01 | `01-breeding_method.md` | `breeding_method` | 育种方法字典 |
+| 02 | `02-germplasm.md` | `germplasm` | 种质主表 |
+| 03 | `03-germplasm_donor.md` | `germplasm_donor` | donor 信息 |
+| 04 | `04-germplasm_institute.md` | `germplasm_institute` | 机构信息 |
+| 05 | `05-germplasm_origin.md` | `germplasm_origin` | 来源地/坐标 |
+| 06 | `06-germplasm_synonym.md` | `germplasm_synonym` | 别名 |
+| 07 | `07-germplasm_taxon.md` | `germplasm_taxon` | taxon 标识 |
+| 08 | `08-germplasm_attribute_definition.md` | `germplasm_attribute_definition` | 属性定义 |
+| 09 | `09-germplasm_attribute_value.md` | `germplasm_attribute_value` | 属性值 |
+| 10 | `10-crossing_project.md` | `crossing_project` | 杂交项目 |
+| 11 | `11-cross_entity.md` | `cross_entity` | Cross / PlannedCross |
+| 12 | `12-cross_parent.md` | `cross_parent` | 杂交亲本 |
+| 13 | `13-cross_pollination_event.md` | `cross_pollination_event` | 授粉事件 |
+| 14 | `14-pedigree_node.md` | `pedigree_node` | 系谱节点 |
+| 15 | `15-pedigree_edge.md` | `pedigree_edge` | 系谱边 |
+| 16 | `16-seed_lot.md` | `seed_lot` | 种子库存批次 |
+| 17 | `17-seed_lot_content_mixture.md` | `seed_lot_content_mixture` | 批次组成 |
+| 18 | `18-seed_lot_transaction.md` | `seed_lot_transaction` | 批次流转 |
+
+## 全局注意点
+
+1. `plannedcross` 没有独立数据库表，统一落在 `cross_entity`，通过 `planned` 和 `planned_cross_id` 自关联表达。
+2. `germplasm.seedSource` / `seedSourceDescription` 是种质来源描述，不等于真实库存批次。
+3. 真正表达库存的是 `seed_lot`，批次与种质或杂交来源的关系在 `seed_lot_content_mixture`。
+4. `seed_lot_transaction` 表达 seed lot 到 seed lot 的流转，不直接表达 seed lot 到 germplasm。
+5. 属性定义和值要分开：`germplasm_attribute_definition` 定义“可填什么”，`germplasm_attribute_value` 记录“某个 germplasm 填了什么”。
+6. 系谱关系用 `pedigree_node` / `pedigree_edge`；杂交流程用 `cross_entity` / `cross_parent`，两条线都可以回到 `germplasm`。