dpb/doc/桃育种系统模块扩展需求规格.v1.0.md

# 桃育种系统 · 模块扩展需求规格（V2 草案）

> 编制日期：2026-07-28
> 依据：通用育种软件功能清单（用户提供） + 国际成熟方案（BrAPI / BMS·Breedbase / RosBREED / MIAPPE） + `doc\果树所\育种\yz.sql` 真实桃性状 + 现有 14 个 breeding 域
> 状态：**草案，待评审**。字段取值/枚举以「待确认」标注处需与业务方对齐后再落地（遵循"不确定不擅自动手"准则）。

---

## 0. 设计原则（本规格的宪法）

1. **性状与观测分离（对标 BrAPI `ObservationVariable` + `Observation`）**：所有表型（含物候）走 `trait`（性状字典）+ `observation`（通用测量值），**不再把性状写死成列**。新增桃性状只加字典、不动表结构。这是与现有 `tree_evaluation` 架构最大的升级，也是统计/决策层能成立的前提。
2. **Program/Trial/Study 三层（对标 BrAPI）**：把"多年多点试验"从 site/plot 里抽象出来，支持同一品系跨生态点、跨年同步试验（MET, Multi-Environment Trial）。
3. **桃语义而非大田语义**：清单里的「P/F1/F2 世代、拔节期/抽穗期、播种季节、随机区组/间比」是按一年生大田作物（玉米/小麦）写的，**对桃（多年生无性繁殖果树）必须语义替换**（见 §1）。
4. **砧木–接穗建模**：桃特有的「嫁接繁殖」维度，现有系统完全缺失，必须补齐。
5. **预留分子层**：`marker`/`genotype_sample`/`genotype_call` 对齐 BrAPI `Sample`+`Calls`，未来接 GBS / PeachSNP170K 做基因组选择（GS）不改骨架。
6. **统计与决策是地基不是补丁**：上面的数据模型必须能让 V1.1 统计引擎（R `sommer`/`lme4` 做 ABLUP/EBV、选择指数）与 V3.0 AI 决策直接消费，不做"先堆数据再补分析"的短视设计。

---

## 1. 桃育种语义替换表（清单 → 桃）

| 清单原文（大田作物语境） | 桃系统应改为 | 落点 |
|---|---|---|
| P / F1 / F2 世代 | **选择阶段 stage**：杂交实生苗 → 初选株 → 复选株 → 品系 → 区试品系 → 新品种 | germplasm/tree/cross/selection 统一 `stage` |
| 拔节期 / 抽穗期 | 桃物候：萌芽 / 开花(初花·盛花) / 坐果 / 果实发育 / 成熟 / 落叶 | `observation`（物候类变量） |
| 播种季节 | 桃用**嫁接 / 定植**（砧木 + 接穗），非播种 | planting.rootstock_id |
| 自交系 | 桃为**克隆（无性繁殖）**，入选株 = 待审定克隆，需砧木关联 | germplasm.is_rootstock / tree.rootstock_id |
| 随机区组 / 间比试验 | 桃果园株数少，简化为 **区组 + 重复 + 对照**轻量设计 | trial.design_type |
| 材料编号 |  accession_no（唯一 accession 编号） | germplasm.accession_no |

**stage 枚举（提案，待确认）**：`germplasm_seed`（种质资源）/ `parent`（亲本）/ `seedling_pop`（杂交实生群体）/ `SP`（初选株 Single Plant）/ `AP`（复选株 Advanced）/ `line`（品系）/ `regional_trial`（区试品系）/ `released`（新品种）。*注：RosBREED 用 DNA-informed 多周期筛选，实际取值以业务方口径为准。*

---

## 2. 目标模块总览（共 21 个）

**A. 现有 14 域（保留 + 字段调整）**
germplasm / site / plot / target / cross_combination / pollination / seed_treatment / seedling / planting / tree / tree_evaluation / tree_photo / selection_result / personnel

**B. 新增 7 个业务模块（P0–P2）**
| 模块 | 表名 | BrAPI 映射 | 优先级 |
|---|---|---|---|
| trait（性状字典） | breeding_trait | ObservationVariable | P0 地基 |
| observation（通用观测） | breeding_observation | Observation | P0 地基 |
| field_operation（农事操作） | breeding_field_operation | Event | P0 |
| trial（多年多点试验） | breeding_trial + breeding_trial_study | Trial / Study | P1 |
| group（分组/标签） | breeding_group + breeding_group_member | List | P1 |
| statistics（统计报表） | breeding_report（配置）+ 聚合端点 | — | P2 |
| 分子基因型层 | breeding_marker / breeding_genotype_sample / breeding_genotype_call | Sample / Calls / Marker | V2.0（地基先建） |

**重要简化（避免模块膨胀）**
- **物候期不单列模块** → 只是 `observation` 中「物候类变量」的观测。
- **系谱树不单列模块** → 靠 `cross_combination.parent_combination_id` 自链 + `germplasm.pedigree` 字符串 + 前端 D3 树图 + `/pedigree/{id}` 聚合端点。

---

## 3. 新模块字段规格

### 3.1 breeding_trait（性状字典，P0）
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | int PK | | |
| trait_code | varchar(64) | UNIQUE, NOT NULL | 如 `brix`、`fruit_weight`、`bloom_date` |
| trait_name | varchar(128) | NOT NULL | 中文名：可溶性固形物、单果重… |
| category | varchar(32) | NOT NULL | fruit/flower/plant/disease/phenology/yield/quality/rootstock |
| data_type | varchar(16) | NOT NULL | numeric / categorical / date / boolean |
| unit | varchar(32) | | g、%、°Brix、mm、date |
| method | varchar(256) | | 测定方法（如折射仪、游标卡尺） |
| scale_json | jsonb | | 量表/选项（categorical 时存选项数组；numeric 时存 min/max/step） |
| is_preset | bool | default false | 是否系统内置（种子数据） |
| remark | varchar(512) | | |
| created_time / updated_time / is_deleted | 标准 | | 来自 ModelMixin |

**种子数据来源**：`doc\果树所\育种\yz.sql` 的 `pa_four`（~40 字段：单果重/果形/果核/可溶性固形物/成熟期/离粘核/风味…）与物候类变量，导入为 `is_preset=true` 的桃专用性状字典。

### 3.2 breeding_observation（通用观测，P0）
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | int PK | | |
| unit_type | varchar(16) | NOT NULL | tree / plot / combination（观测单元类型，多态） |
| unit_id | int | NOT NULL | 对应单元 id（tree_id / plot_id / combination_id） |
| trait_id | int FK→breeding_trait | NOT NULL | 测了哪个性状 |
| value_numeric | numeric(12,4) | | data_type=numeric 时 |
| value_text | varchar(512) | | categorical / boolean 存此 |
| value_date | date | | data_type=date 时 |
| obs_year | int | | 观测年份（MET 聚合键） |
| obs_date | date | | 具体日期 |
| site_id | int FK→breeding_site | | 观测地点 |
| person_id | int FK→breeding_personnel | | 观测人 |
| remark | varchar(512) | | |

**索引**：`(unit_type, unit_id, trait_id)` 复合索引；`(obs_year)`、`(trait_id)`。
**语义**：单株评价、物候期、小区测定**全部走这张表**，取代 `tree_evaluation` 的硬编码列（见 §4 过渡方案）。

### 3.3 breeding_field_operation（农事操作，P0）
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | int PK | | |
| op_type | varchar(32) | NOT NULL | 施肥/灌溉/植保/除草/修剪/病害防治/其他 |
| unit_type | varchar(16) | NOT NULL | tree / plot |
| unit_id | int | NOT NULL | 作用对象 id |
| op_date | date | NOT NULL | 操作日期 |
| material | varchar(128) | | 药剂/肥料名 |
| dosage | varchar(64) | | 用量 |
| method | varchar(128) | | 方式（叶面/根施…） |
| operator_id | int FK→breeding_personnel | | 操作人 |
| site_id / plot_id | int FK | | 定位 |
| remark | varchar(512) | | |
**索引**：`(unit_type, unit_id)`、`(op_date)`。

### 3.4 breeding_trial + breeding_trial_study（多年多点试验，P1）
**breeding_trial**
| 字段 | 类型 | 说明 |
|---|---|---|
| id | int PK | |
| trial_code | varchar(64) UNIQUE | 试验编号 |
| trial_name | varchar(128) NOT NULL | |
| target_id | int FK→breeding_breeding_target | 关联育种目标 |
| design_type | varchar(32) | 随机区组/对比/间比/简约 |
| description | varchar(512) | |
| years | varchar(64) | 跨年计划，如 2026-2028 |
| remark | varchar(512) | |

**breeding_trial_study**（Trial×Location×Year）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | int PK | |
| trial_id | int FK→breeding_trial | |
| site_id | int FK→breeding_site | 试验点 |
| year | int | 年份 |
| replicate | int | 重复次数 |
| control_germplasm_id | int FK→breeding_germplasm | 对照品种 |
| layout_json | jsonb | 田间种植图（小区排布坐标） |
| remark | varchar(512) | |

> 试验单元（哪株种在哪）复用 `breeding_tree` + `plot`，通过 `trial_study` 关联；布局图由前端可视化 + 轻量排布算法生成（不照搬大田作物复杂设计）。

### 3.5 breeding_group + breeding_group_member（分组/标签，P1）
**breeding_group**
| 字段 | 类型 | 说明 |
|---|---|---|
| id | int PK | |
| group_name | varchar(128) NOT NULL | |
| group_type | varchar(32) | 项目/品系群/目标/临时选系集（待确认维度） |
| target_id | int FK | 关联育种目标（可选） |
| owner_team | varchar(64) | 归属团队 |
| description | varchar(512) | |

**breeding_group_member**
| 字段 | 类型 | 说明 |
|---|---|---|
| id | int PK | |
| group_id | int FK→breeding_group | |
| germplasm_id | int FK→breeding_germplasm | 成员种质 |
| tree_id | int FK→breeding_tree | 或成员单株 |
| note | varchar(256) | |

> 分组维度（group_type 取值）**待确认**：按项目 / 品系群 / 育种目标 / 临时选系集。不臆造，等对齐。

### 3.6 breeding_report（统计报表配置，P2）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | int PK | |
| report_name | varchar(128) NOT NULL | 报表名 |
| report_type | varchar(32) | 育种进度/世代汇总/杂交组合统计/材料库存/MET分析 |
| query_json | jsonb | 报表查询参数（保存配置，便于复用） |
| created_by | varchar(64) | |

**配套**：只读聚合端点（不建大表）：
- `GET /breeding/statistics/progress` 育种进度
- `GET /breeding/statistics/generation-summary` 世代汇总
- `GET /breeding/statistics/cross-stats` 杂交组合统计
- `GET /breeding/statistics/inventory` 材料库存
- `GET /breeding/statistics/met` 多年多点分析（钩子，V1.1 R 引擎）

### 3.7 分子基因型层（V2.0，地基先建）
**breeding_marker**（标记/位点）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | int PK | |
| marker_name | varchar(64) UNIQUE | 如 SNP_Chr01_123456 |
| chromosome | varchar(16) | 染色体 |
| position | int | 物理位置 |
| marker_type | varchar(16) | SSR / SNP / InDel |
| remark | varchar(512) | |

**breeding_genotype_sample**（基因型样品）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | int PK | |
| source_type | varchar(16) | germplasm / tree |
| source_id | int | 来源 id |
| sample_type | varchar(16) | DNA / leaf |
| sample_date | date | |
| method | varchar(64) | 测序/芯片（GBS / PeachSNP170K） |
| lab | varchar(128) | 检测单位 |
| remark | varchar(512) | |

**breeding_genotype_call**（基因型调用）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | int PK | |
| sample_id | int FK→breeding_genotype_sample | |
| marker_id | int FK→breeding_marker | |
| allele | varchar(32) | 基因型编码（AA/AT/TT 或 0/1/2） |
| remark | varchar(256) | |

**索引**：`(sample_id, marker_id)` 复合唯一。

---

## 4. 现有模块字段调整（非新增模块）

| 模块 | 新增字段 | 说明 |
|---|---|---|
| germplasm | accession_no(varchar UNIQUE)、pedigree(varchar 系谱串)、stage(varchar 选择阶段)、storage_type(varchar 田间/离体/种子/DNA)、is_rootstock(bool)、rootstock_id(int FK 自关联) | 种质档案补全 + 桃特有维度 |
| cross_combination | cross_type(varchar 杂交/自交/开放)、parent_combination_id(int 自链 FK)、reason(varchar 选配理由)、stage | 系谱链 + 选配理由 |
| pollination | bagging_date(date 套袋)、emasculation_date(date 去雄) | 田间杂交登记补全 |
| planting | rootstock_id(int FK→germplasm) | 砧木–接穗建模 |
| tree | stage(varchar 选择阶段)、rootstock_id(int FK→germplasm) | 世代/阶段标记（4.x 全流程依赖） |
| site | soil_type(varchar 土壤类型) | 试验地块补全 |
| selection_result | 对齐 stage 晋级流转（建议加 from_stage/to_stage + approved_by） | 晋级审批流 |

**tree_evaluation 定位（复审定稿：混合模型）**：`tree_evaluation` **保留并作为固定列「评分卡」**（承载桃稳定高频的 ~30–40 个果实质/农艺性状，源自 `yz.sql` 的 `pa_four`），这是 90% 报表与 SQL 聚合的主路径；`observation` 仅作为**扩展层**承载物候期时序观测 + 字典中标记为 `is_core=false` 的新增/临时性状。详见 §8.4。*原则修订：§0「性状与观测分离」对单作物程序过严，改为「核心性状固定列 + 扩展性状 EAV」。*

---

## 5. 统计分析与决策地基（关键要求）

用户明确要求"统计分析与决策，需要基础能够支持"。数据模型须满足：

1. **任意性状可聚合**：`observation` 通用表使「按性状×年份×地点×阶段」的切片聚合无需改表——这是 ABLUP/EBV 与选择指数的输入。
2. **MET 结构就绪**：`trial/trial_study` 提供 environment(地点×年) 维度，V1.1 用 `sommer`/`lme4` 做混合模型 BLUP，输出单株 EBV。
3. **选择指数可计算**：`observation`(表型) + `genotype_call`(基因型) → 多维选择指数（RosBREED DNA-informed 思路），按 `stage` 分层筛选。
4. **决策支撑**：`selection_result`(晋级/淘汰) + `stage` 流转 + EBV 排名 → 前端决策视图（哪些株晋级/淘汰、依据的 EBV）。
5. **溯源闭环**：`tree→combination→父/母本 germplasm` + `observation/field_operation/pollination` 全 FK → 任意品系反向追溯（需求 7.1）。

---

## 6. 实施路线（建议）

| 阶段 | 内容 |
|---|---|
| 地基（先做） | trait + observation + 现有模块 stage/rootstock/accession_no/pedigree 字段；数据权限/options 沿用现有生成器 |
| P0 | field_operation |
| P1 | trial(+study)、group(+member) |
| P2 | statistics 聚合端点 |
| V2.0 | marker + genotype_sample + genotype_call（地基先建表，分析后置） |
| V1.1 | R 统计引擎接入 observation/trial 做 BLUP/EBV |
| V3.0 | AI 决策（Agno + DeepSeek）消费 EBV/选择指数 |

**工程约定**：新模块按现有 `_gen_specs.py` 的 `MOD` 规格 + 生成器产出（6 文件 + 菜单 + options），与 14 域完全一致；改字段后跑 `deploy.bat migrate`（`fix_breeding_columns.py`）再重启后端。

---

## 7. 待用户确认项（不臆造）

1. **stage 具体取值清单**（§1 提案为草案，以业务方口径为准）。
2. **group_type 分组维度**（项目/品系群/目标/临时选系集）。
3. **tree_evaluation 过渡策略**（同步落 observation / 弃用迁移）。
4. **trait 字典首批字段**：是否直接以 `yz.sql` 的 `pa_four` ~40 字段为种子，哪些 category 划分。
5. **design_type 试验设计类型**在桃场景下的具体取值（简化到哪几种）。

---

## 8. 复审补充：遗漏与替代思路（2026-07-28 复审）

> 本节为第一稿（§0–§7）的批判性复审结论，针对"还有哪些遗漏 / 不同思路"自省。改变范围的项标注「待拍板」。

### 8.1 原稿遗漏的关键项
1. **`generation`（遗传世代）与 `selection_stage`（选择阶段）混为一谈**：桃虽以无性选择为主，但回交转育（BC1/BC2）、自交分离（F2）仍是真实遗传世代，与"选到第几轮"是两回事。建议拆字段：`generation`（F1/BC1/BC2…，跟 `cross_type` 联动）+ `selection_stage`（实生苗/初选株/复选株/品系/区试/新品种）。
2. **缺"树→种质"晋升链路（克隆生命周期）**：入选株应晋升为 clone/accession（germplasm）被命名扩繁。需 `tree.germplasm_id`，否则基因型（测在 germplasm）与表型（测在 tree）无法在 GS 中拼接。
3. **原清单 1.4「按团队权限隔离」无 team 实体**：现有 `_build_conditions` 仅按 `created_id` 过滤，系统无 team/organization。若需多团队数据隔离，须新增 `team` 模块 + 用户-团队映射，数据权限改按 `owner_team` 隔离。【待拍板】
4. **"材料库存"被弱化成纯报表**：库存是事务性的（种子批/ lot、在圃株数、离体/DNA 管数、活力）。应加 `germplasm_stock`/`seed_lot` 表（数量、批次、位置、活力、出入库），报表只是视图。【待拍板】
5. **缺环境/气象数据（G×E 统计地基）**：多年多点分析核心是基因型×环境互作，无环境协变量（site×year 的需冷量/积温/降雨）BLUP 只能粗估。建议加 `environment_condition`（site×year），可复用 `yz.sql` 的"天气"字段。
6. **分子层缺"预测模型"表（GS 反馈环断裂）**：RosBREED 是闭环（表型+基因型→训练模型→输出 EBV→指导下轮选配）。需 `breeding_prediction`（模型/性状/精度 accuracy/预测日期/被预测个体）。
7. **克隆繁殖/苗圃未建模（桃主繁殖方式）**：现有 `seedling`/`seed_treatment` 仅种子实生苗；桃入选后主要靠嫁接/芽接扩繁，缺 `propagation`（接穗来源→成活→出圃）。【待拍板】
8. **统一修改日志/审计缺失**：晋级审批、全程可追溯需"谁/何时/改了什么"轨迹，现有仅 `updated_time`。建议轻量 `breeding_audit_log`（或接系统操作日志）。
9. **小遗漏**：`tree_photo` 应可关联 `observation`（某次测量的果实照片，为 CV/AI 预留）；`observation` 应可挂 `trial_study_id`（区分试验观测 vs 果园日常观测）；编号生成策略未定义（`accession_no`/`combination_code`/`tree_no`/`trial_code` 需统一自动编号服务）。

### 8.2 替代思路与推荐
- **A. EAV 纯通用 vs 混合固定列 → 推荐混合固定列**（详 §8.4）。理由：桃果实质性状稳定且高频（yz.sql 已验证 40 固定字段沿用多年）、报表是核心需求（固定列 SQL 聚合极快）、现有 `tree_evaluation` 已在工作——纯 EAV 会牺牲报表性能并浪费已建代码。
- **B. 分组 vs 标签 → 建议并行**：`group`（正式项目组/品系群）+ 自由 `tag`（多对多，如"抗褐腐""高Brix""区试备选"）。
- **C. 直接对齐 BrAPI API（战略级）**：当前自定义 `/breeding/...`；若未来对接 Breedbase/Flapjack/国际交换，实现 BrAPI 兼容端点可省适配。数据模型已对齐 BrAPI，是铺路，不一定要现在做。
- **D. MIAPPE 合规（远期）**：若数据要共享/投稿，Investigation/Study/Assessment 三层对齐 MIAPPE 比自定 trial 抽象更标准，作一致性检查项。

### 8.3 复审后模块清单（原 21 模块基础上）
- 新增：`team`（若多团队隔离）、`germplasm_stock`/`seed_lot`（库存批次）、`environment_condition`（site×year 环境因子，统计地基）、`breeding_prediction`（GS 模型/育种值，V2.0）、`propagation`（克隆扩繁/苗圃）、`breeding_audit_log`（审计）。
- 字段细化：`tree.germplasm_id` + `generation` 字段；`observation.trial_study_id`；`tree_photo.observation_id`；统一编号生成服务。
- 物候期仍走 `observation`（时序，非固定列）；系谱树仍靠 `cross_combination.parent_combination_id` 自链 + 前端树图。

### 8.4 EAV 决策详述（对应 §4 tree_evaluation）
**结论：混合固定列（Hybrid）。**
- **固定列层 = `tree_evaluation`**：承载桃稳定高频的 ~30–40 个核心果实质/农艺性状（单果重、果形、果核、可溶性固形物、成熟期、离粘核、风味、硬度…，源自 `yz.sql` `pa_four`）。一树一年一行，表单/报表直读，SQL 聚合无需 pivot。
- **EAV 扩展层 = `observation`**：仅承载①物候期时序观测（萌芽/开花/坐果/成熟，一树多期，天然时序）②`trait` 字典中 `is_core=false` 的新增/临时性状。
- **防双源规则**：`trait.is_core` 标志——核心性状只存固定列，非核心只存 observation，禁止同一性状两处重复记录。
- **对统计引擎（V1.1）**：读取两者——核心性状走固定列、扩展性状走 observation，统计层归一化后做 BLUP/EBV。
- **对 GS/决策**：表型来自固定列 + observation，基因型来自 `genotype_call`，经 `tree.germplasm_id` 桥接，由 `breeding_prediction` 输出育种值。
- **代价**：新增核心性状需改表（但低频，且走 `migrate` 脚本已固化）；换来报表性能与已建代码保留。对本单作物程序，此代价可接受。

---

确认后据此实施，不先行编码。