checkpoint: 统计分析文档化——操作手册与技术说明双文档

按用户澄清的「操作手册与技术说明分开」落地：操作手册面向育种团队（20 个核心分析
四段式：目的/数据准备/操作步骤/结果解读），技术说明面向方法学/开发者（模型公式、
输入依赖与降级、落库表、API 索引）。常用核心表型分析优先，分子类第二批。

doc/桃育种系统统计分析技术说明.md

@@ -0,0 +1,284 @@
+# 桃育种系统统计分析技术说明
+
+> 版本：v1.0（2026-08-07）
+> 面向读者：**统计方法学 / 研发与维护人员**（需了解混合线性模型、REML、基因组选择的背景）
+> 配套文档：使用操作见《桃育种系统统计分析操作手册》；逐版本迭代记录见《桃育种系统统计引擎实施记录》；运行维护见《桃育种系统生产上线与运营手册》。
+
+本文说明每个统计分析的**模型与公式、参数与边界、输入数据依赖、结果落库与接口**，是操作手册的底层技术对位。
+
+---
+
+## 一、总体架构
+
+### 1.1 任务系统
+
+重计算分析（ABLUP/EBV、配合力、交叉验证、稳定性、遗传相关、Type-B、基因组选择、GWAS）以**异步任务**方式执行，任务记录落 `bre_statistics_job`：
+
+- 状态：`SUCCESS` / `FAILED`（`error_msg` 携带失败原因）；
+- 调度 jobstore 持久化到 PostgreSQL（`apscheduler_jobs`），重启自动恢复；
+- 轻量计算（描述统计、ANOVA、选择指数、聚类、数据质量、ΔG、选配、MABC、决选预览、公平性、模型健康）同步直出。
+
+### 1.2 确定性
+
+统计引擎输入顺序敏感性已收口：`blup._order_pedigree` 对 base 与同世代并列个体一律按 **id 确定性排序**（`sorted(key=str)`），系谱与表型键空间以统一 `_tree_individual_keys` 生成。服务层构建系谱不再受 DB 行序影响，同输入必同输出（复现性 / MLOps input_hash 语义的前提）。
+
+### 1.3 MLOps
+
+每次批次落库 `input_hash`（输入快照哈希）：漂移检测重算当前哈希对比；相邻批次对比输出 h² 跌幅 / EBV 排名翻转 / 可靠性变化（模型健康）；手动重训同参数重跑、版本回滚把指定批次设为当前生效版本（同性状其余 inactive）。
+
+---
+
+## 二、输入数据依赖
+
+### 2.1 硬依赖（缺则报错）
+
+| 数据 | 表 | 说明 |
+|---|---|---|
+| 性状 | `bre_trait` | 核心数值性状（统计下拉仅列 core 性状） |
+| 观测 | `bre_trait_observation` | 逐株观测值，是建模的 y |
+| 树 | `bre_tree` | 个体身份（单株/克隆/家系/区组），是建模的单位 |
+| 基因型调用 | 基因型四表 + `bre_genotyping_dataset` | **仅分子分析**（GBLUP/ssGBLUP/rrBLUP/BayesB/GWAS/QTL/MAS）硬依赖；缺则报"基因型数据集不存在"/"该数据集无基因型调用记录" |
+
+### 2.2 可选增强（缺则静默降级，不阻断）
+
+| 数据 | 表 | 降级行为 |
+|---|---|---|
+| 系谱 | `parent_of` 亲子关系 | 无系谱 A → 按单株独立建模；近交/亲缘/ΔG 的 σ_A 不可用 |
+| 种质 | `germplasm` | 无种质编号回显；配合力亲本、S-等位过滤不可用 |
+| 克隆 | `clone` | 无无性系级聚合/EBV 排行 |
+| 砧木 | `rootstock` | G×R 不可用 |
+| 研究点 | `trial_study` | G×E（site）、稳定性环境表不可用 |
+
+### 2.3 数据就绪门禁（G1）
+
+`data_gate=true` 时对每 clone/家系最小 n（`min_clone_n`）、系谱完整率（`min_pedigree_rate`）、缺失率（`max_missing_rate`）做前置校验，不达标返回明确拒绝原因。
+
+---
+
+## 三、模型与算法
+
+### 3.1 ABLUP / EBV（混合线性模型）
+
+模型（以克隆随机效应为例，含固定环境效应与协变量）：
+
+```
+y = Xβ + Z₁u_clone + e,   u_clone ~ N(0, Aσ²a)（有系谱）或 N(0, Iσ²a)（无系谱）
+```
+
+- 求解：MME，`solve`（稠密）/ `solve_spatial` / `solve_multi` 分派；结果落 `bre_prediction`（批次级：h²、σ²a、σ²e、PA）+ `bre_prediction_value`（逐树 EBV / reliability / PA / rank）。
+- **发育阶段拆分**：`stage=juvenile|evaluation` 只取该阶段观测建模并拆独立批次（避免童期/成株混合）。
+- 协变量：`crop_load`（负载量）等用于 BLUP 校正。
+
+### 3.2 MET 扩展（G×E / G×R / AR1×AR1 / 区组）——四者互斥
+
+| 选项 | 加入项 | 前置 |
+|---|---|---|
+| `gxe` | clone×site（或组合×site；`gxe_env=site|year`）随机互作 | trial_study / 年份维度 |
+| `gxr` | 砧木×接穗随机互作（rootstock 由固定效应升入随机效应，占用第二随机效应槽 Z₂，故与 G×E **互斥**） | rootstock |
+| `spatial` | 残差 AR1×AR1：`R_ij = ρ_row^(|Δrow|) · ρ_col^(|Δcol|)`（1.4.0 起 aniso 双参 ρ_row/ρ_col，纯 numpy eigh REML） | 观测株均有 row_no/col_no |
+| `block` | `bre_tree.block_no` 作第二随机效应（不完全区组/增广/α-格子），需 ≥2 区组 | block_no 已生成 |
+
+### 3.3 ANOVA / 广义遗传力
+
+单因素方差分解 + `block=true` 走 RCBD 双因素（从残差析出区组效应）；输出 F、p、σ²g、σ²e、家系均值、广义遗传力 H²。**试验设计生成**（`trial-design`）三种：
+
+- `rcbd`：随机完全区组；
+- `augmented`：增广——对照种质每区组重复、新品系不重复（`check_germplasm_ids`）；
+- `alpha`：α-格子——`block_no` 复合编码 `rep*100+block`，区组大小 k、重复 r。
+
+### 3.4 配合力 GCA / SCA
+
+交配设计 `design_type`：
+
+- `full_diallel` 完全双列 / `partial_diallel` 部分双列；
+- `line_tester`：line×tester（NCII）；
+- `nciii`：NCIII 测交。
+
+输出 GCA（亲本）+ SCA（组合）+ ANOVA 摘要，落 `bre_combining_ability`。
+
+### 3.5 遗传相关（MT-BLUP 成对双性状）
+
+对选入性状**两两**跑双性状 BLUP，逐对 REML 估计 `r_g = σa₁₂ / √(σa₁·σa₂)`，同时给出 σa₁、σa₂、σe₁、σe₂、共同个体数 `n_common`、收敛标记 `converged`，落 `bre_genetic_corr_result`（矩阵 JSON）。
+
+### 3.6 Type-B 多环境遗传相关
+
+把**环境当"性状"**，同一性状逐对双性状 BLUP 估 `r_B`；`env_dim`：
+
+- `site`：跨研究点一致性（r_B→1 则 G×E 弱）；
+- `year`：跨年份；
+- `stage`：童期-成株遗传相关（幼年选择有效性）。
+
+方法 `reml` / `calo`；结果含热图数据，落 `bre_type_b_result`。
+
+### 3.7 选择指数
+
+| 方法 | 权重向量 |
+|---|---|
+| `zsum` | 加权标准分：`I = Σ w_i·z_i` |
+| `smith_hazel` | 真 Smith-Hazel：`b = P⁻¹·G·a`（P=表型协方差，G=遗传协方差，a=经济权重） |
+| `restricted` | 受限指数：`b = P⁻¹G(I−M)a`，其中 `M = C'(CG·P⁻¹G·C')⁻¹·CG·P⁻¹G`（C 为受限性状约束行），使受限性状 ΔG = 0（机器精度） |
+
+- `g_method`：遗传相关来源 `calo`（可靠性校正 EBV 相关）/ `mtblup`（成对双性状 REML），smith_hazel / restricted 生效；
+- `economic_weights`：绝对尺度经济权重（不归一化，未列性状按 0）；
+- `auto_weights`：按实测 h² 生成权重（强制 `use_h2=False` 防双重相乘，缺省 `default_h2=0.1` 兜底）；
+- `aggregate=clone|tree`：聚合层级；
+- 结果落 `bre_selection_index`；`apply` 前 N 名写决选 `bre_selection_result`（EBV 可靠性低于 `min_reliability` 跳过）。
+
+### 3.8 交叉验证（k-fold）
+
+- 表型模式：ABLUP 模型 k 折（k=2~10）**掩蔽留出**（masked leave-out），评估 EBV 外部预测准确度；
+- GS 模式：`dataset_id` + `method`（gblup/ssgblup/rrblup/bayesb）+ `maf_min` + `split`：
+  - `random`：固定种子随机分层（可复现）；
+  - `family`：家系阻塞折——同父半同胞同折，**防亲缘泄漏**。
+- 输出：`mean_pearson` / `mean_rmse` / `pooled_*` / `cv_accuracy` / `h2`，落 `bre_cv_result` + 折明细 `bre_cv_fold`。
+
+### 3.9 稳定性 AMMI / Finlay-Wilkinson
+
+基于两因素均值表（genotype × environment）：
+
+- **AMMI**：主效应 + 乘性互作项分解，输出 IPC1/IPC2、`ASV = √(IPC1² + IPC2²)`、ecovalence（互作方差）、ASV 排名；`ipc_variance` 给出各 IPC 占比；
+- **FW**：基因型对**环境指数**回归 `y = a + b·x`，输出斜率 b、截距、r²、`se_b`、`dev_ms`、`flag_stable`（b≈1 稳定型）。
+
+结果落 `bre_stability_result`（detail_json）。
+
+### 3.10 UPGMA 层次聚类
+
+`distance=corr|euclidean`，`mode=pheno|genetic`，`entity_type=tree|clone`；k 空时按合并距离最大跳变自动定类；计算端点，**不落库**。
+
+### 3.11 数据质量（离群值诊断）
+
+- 缺失率统计；
+- IQR 超界；
+- MAD 稳健 z 双通道；
+- **方向语义**：同向偏离 = 精英（高值方向离群）；反向偏离 = 疑似记录错误。
+
+### 3.12 遗传增益 ΔG
+
+`ΔG = k · r_g · σ_A`，逐批次投影：
+- `k`：截断选择强度，标准正态分位数 φ 经 **Acklam 算法近似 Φ⁻¹**（无 scipy 依赖）由 top_p / top_n 换算；
+- `r_g`：预测准确性（取批次 PA）；
+- `σ_A`：遗传标准差。
+
+`ΔG` 是期望投影，前提为模型无偏、无近交负效应累积。
+
+### 3.13 近交 / 亲缘 / 近交衰退
+
+- 系谱 A 矩阵（`relationship_matrix`）→ 近交系数 `F = A_ii − 1`、个体对亲缘 `A_ij`；阈值预警，落亲缘分析结果；
+- **近交衰退**：`F → 表型` 线性回归（`lstsq`），斜率即衰退代价；`inbreeding` 字典只含 F>0 个体，样本为空时兜底为 0 处理。
+
+### 3.14 主动选配推荐
+
+评分 `EBV 互补 − w_kin·亲缘惩罚`，过滤逻辑：
+
+- **S-等位不相容硬过滤**（germplasm.s_alleles + 交配兼容性 409/半兼容）；
+- **花期软警示**四态：overlap（花期重叠）/ store（花粉库存可用）/ offset（花期错开，需贮藏）/ unknown（花期未知），overlap 不进 flags、不硬阻断；
+- 亲缘多源解析（系谱 + 分子指纹），EBV 缺失时回退方法学（direct 优先 / 子代测验降权）。
+
+**OCS 最优贡献选择**：`max Σcᵢ·ebvᵢ − λ·c'Ac`，约束 `Σc = n_select`、`c ≥ 0`，投影梯度求解，纯计算不落库。
+
+### 3.15 MABC 标记辅助回交
+
+前景面板命中数 + 背景面板恢复率 + 回交代建议（`generation` 判定是否该继续回交 / `background_target`），纯计算不落库；前景/背景面板来自 MAS 面板数据。
+
+### 3.16 基因组选择（GBLUP / ssGBLUP / rrBLUP / BayesB）
+
+- **GBLUP**：dosage 0/1/2 → VanRaden **G 矩阵** → `u ~ N(0, Gσ²a)` 求解 MME；
+- **ssGBLUP**：单步法，H 矩阵合并系谱 A 与基因型 G（非基因型亲属通过系谱信息参与）；
+- **rrBLUP**：岭回归逐标记（与 GBLUP **对偶**——EBV 逐位一致），输出标记效应；
+- **BayesB**：Gibbs 采样 + 确定性 `seed`（可复现），可变选择（大部分标记效应收缩为 0）。
+
+参数：`maf_min`、`seed`；结果统一落 `bre_prediction`（method=GBLUP/ssGBLUP/RRBLUP/BayesB）+ `bre_prediction_value`。大群体走稀疏生产档（索引化 Z / 稀疏 A⁻¹ / EM-REML / 精确迹二分，可靠性分档：n≤1000 稠密逆精确、n 大 Hutchinson 近似）。
+
+### 3.17 GWAS / QTL / MAS
+
+- **GLM+PC 求解器**：纯 numpy，显著性经 `fdist` 计算；共线时岭回归兜底；
+- **EMMAX**：零模型 `_profile_solve + eigh` 估方差分量再逐标记检验（gwas 1.1.0）；
+- **ssGWAS**：单步 GWAS，MEM 对角近似（gwas 1.2.0）；
+- **QTL×E 分层 GWAS**：按环境分层分别关联；
+- **MAS 面板**：显著标记构建面板（`bre_mas_panel` + `bre_mas_panel_marker`），供 MABC 前景/背景选择与决策预览（童期幼苗可标记辅助选入）。
+
+> 数据设计教训：PC 数量过大会**吞噬 QTL 信号**，需控制协变量维度。
+
+---
+
+## 四、结果数据表（落库）
+
+| 表 | 内容 |
+|---|---|
+| `bre_prediction` | 育种值批次（ABLUP / GXEBLUP / GXRBLUP / GBLUP / ssGBLUP / RRBLUP / BayesB）；h²、σ²、PA、input_hash、engine_version、is_active |
+| `bre_prediction_value` | 逐树 EBV / reliability / PA / rank |
+| `bre_combining_ability` | 配合力 GCA/SCA 结果 |
+| `bre_selection_index` | 选择指数批次 |
+| `bre_selection_result` | 决选写入（前 N 名） |
+| `bre_anova_result` | ANOVA / H² |
+| `bre_cv_result` / `bre_cv_fold` | 交叉验证批次 + 折明细 |
+| `bre_statistics_job` | 异步任务记录（状态 / error_msg / result_ref） |
+| `bre_genetic_corr_result` | 遗传相关矩阵 |
+| `bre_type_b_result` | Type-B 多环境遗传相关 |
+| `bre_stability_result` | AMMI / FW 稳定性 |
+| `bre_gwas_result` / `bre_gwas_snp` / `bre_qtl` | GWAS 结果、SNP、QTL 定位 |
+| `bre_mas_panel` / `bre_mas_panel_marker` | MAS 面板与标记 |
+
+---
+
+## 五、API 索引
+
+统一前缀 `/bre/statistics`（前端 `frontend/web/src/api/module_bre/statistics.ts`）：
+
+| 端点 | 方法 | 说明 |
+|---|---|---|
+| `/describe` | GET | 描述性统计（均值/标准差/CV/极值/缺失） |
+| `/trait-values` | GET | 统一性状值长表视图 |
+| `/correlation` | GET | 相关性矩阵（pheno/genetic） |
+| `/ablup/run` | POST | ABLUP/EBV（异步，MET/G×E/G×R/空间/区组/stage） |
+| `/predictions` | GET | 育种值批次列表 |
+| `/predictions/{id}/values` | GET | EBV 排行 |
+| `/predictions/{id}/clones` | GET | 无性系级 EBV 排行 |
+| `/predictions/{id}/compare` | GET | 模型健康（相邻批次对比） |
+| `/combining/run` | POST | 配合力 GCA/SCA（异步） |
+| `/combining` / `/combining/{id}` | GET | 配合力列表 / 详情 |
+| `/anova/run` | POST | ANOVA / H²（同步） |
+| `/anova` / `/anova/{id}` | GET | ANOVA 列表 / 详情 |
+| `/trial-design` | POST | 试验设计生成（RCBD/增广/α-格子） |
+| `/cv/run` | POST | 交叉验证（异步，ABLUP/GS） |
+| `/cv` / `/cv/{id}` | GET | CV 列表 / 详情（含折明细） |
+| `/stability/run` | POST | 稳定性 AMMI/FW（异步） |
+| `/stability` / `/stability/{id}` | GET | 稳定性列表 / 详情 |
+| `/genetic-corr/run` | POST | 遗传相关（异步） |
+| `/genetic-corr` / `/genetic-corr/{id}` | GET | 遗传相关列表 / 详情 |
+| `/type-b-heredity` | POST | Type-B（异步） |
+| `/type-b` / `/type-b/{id}` | GET | Type-B 列表 / 详情 |
+| `/selection-index` | POST | 选择指数（同步） |
+| `/selection-index` | GET | 指数批次列表 |
+| `/selection-index/{id}/apply` | POST | 写入决选 |
+| `/cluster` | POST | UPGMA 聚类（不落库） |
+| `/combination-funnel` | GET | 组合得失漏斗 |
+| `/data-quality` | POST | 数据质量诊断 |
+| `/inbreeding-depression` | POST | 近交衰退回归 |
+| `/genetic-gain` | POST | ΔG 投影 |
+| `/kinship` | POST | 亲缘/近交 |
+| `/mating-recommend` | POST | 主动选配推荐 |
+| `/ocs` | POST | OCS 最优贡献选择（不落库） |
+| `/mabc-progress` | POST | MABC 进度（不落库） |
+| `/gblup/run` | POST | GBLUP/ssGBLUP/rrBLUP/BayesB（异步） |
+| `/gblup/datasets` | GET | 基因型数据集列表 |
+| `/decision-preview` | POST | 决选预览 |
+| `/fairness` | GET | 按 site 公平性报告 |
+| `/jobs` / `/jobs/{id}` | GET | 任务列表 / 状态 |
+| `/traits` | GET | 可用性状下拉（core/selection） |
+| `/model/drift` | GET | 漂移检测 |
+| `/model/retrain` | POST | 手动重训 |
+| `/model/activate/{id}` | POST | 版本回滚/设当前 |
+
+GWAS/QTL/MAS（独立页面，`frontend/web/src/api/module_bre/gwas.ts`）：`/bre/statistics/gwas/run`、`/qtl`、`/mas-panel`、`/gwas-qtl-x-e`。
+
+---
+
+## 六、数值与工程注意事项
+
+1. **引擎版本**：blup 1.6.0、genomic 1.4.0、gwas 1.2.0；`_DATA_VERSION` 随结构演进（当前 v2.14+），input_hash 语义一致。
+2. **确定性**：任何新增走系谱/表型键的求解必须经 `_order_pedigree`（id 排序）与 `_tree_individual_keys` 收口，禁止依赖 DB 行序。
+3. **互斥约束**：G×E / G×R / AR1×AR1 / 区组四选项互斥（第二随机效应槽 Z₂ 与残差结构 R 只能择一）。
+4. **分子分析前置**：GBLUP/GWAS 等必须先有基因型数据集与调用记录；基因型四表与表型观测的键空间必须对齐（`_tree_individual_keys`）。
+5. **数值坑**：numeric 列量化（如 `numeric(12,4)`）会引入舍入差；跨端比对注意服务层 3 位舍入 vs 引擎高精度。
+6. **回归基线**：全量回归 `run_regression`（72 套）串行跑，均写真 PG。

doc/桃育种系统统计分析操作手册.md

@@ -0,0 +1,317 @@
+# 桃育种系统统计分析操作手册
+
+> 版本：v1.0（2026-08-07）
+> 面向读者：**育种团队 / 试验管理人员**（无需编程背景）
+> 配套文档：方法学与接口细节见《桃育种系统统计分析技术说明》；系统运行维护见《桃育种系统生产上线与运营手册》。
+
+本手册按「目的 → 所需数据 → 操作步骤 → 结果解读」四段式讲解每个常用分析，帮助育种人员在系统里正确、完整地完成一次统计分析。
+
+---
+
+## 一、总体说明
+
+### 1.1 入口
+
+统计功能集中在左侧菜单 **统计计算** 模块，页面为「统计分析」主页（含 24 个分析页签）：
+
+- 顶部工具条：**运行 ABLUP / EBV**、**运行配合力 GCA/SCA**、**运行 ANOVA / H²** 三个主按钮；**刷新批次**；**组合得失漏斗**。
+- 页签（按使用频度排序）：模型批次 / EBV 排行 / 配合力 / 描述统计 / 相关性 / ANOVA·H² / 多环境 GxE / 决选预览 / 模型健康 / 无性系排行 / 交叉验证 / 公平性报告 / 选择指数 / 亲缘·近交 / 稳定性 AMMI·FW / 遗传相关 MT-BLUP / Type-B 多环境遗传相关 / UPGMA 聚类 / 基因组选择 GBLUP / 数据质量 / 遗传增益 ΔG / 选配推荐 / 回交 MABC。
+
+基因组方向的分析（GWAS / QTL / MAS 面板 / QTL×E）在独立的「GWAS」页面，见第 4 节。
+
+### 1.2 同步与异步任务
+
+| 类型 | 分析 | 结果何时可见 |
+|---|---|---|
+| **异步任务** | ABLUP/EBV、配合力、交叉验证、稳定性、遗传相关、Type-B、基因组选择 GBLUP | 提交后到「模型批次 / 任务状态」查看进度，完成后自动刷新批次 |
+| **同步直出** | 描述统计、相关性、ANOVA/H²、选择指数、聚类、数据质量、ΔG、选配、MABC、决选预览、公平性报告、模型健康 | 点击后直接出结果 |
+
+异步任务结束后在「模型批次」页签的**任务状态**表里可见：`SUCCESS` / `FAILED`（含失败原因 `error_msg`）。
+
+### 1.3 分析前请先确认（数据就绪门禁 G1）
+
+多数建模分析带**数据就绪门禁**开关，勾选后若基础数据不达标会**拒绝运行**并给出原因：
+
+- 每个 clone / 家系最少观测株数（`min_clone_n`，默认通常为 3）；
+- 系谱完整率（`min_pedigree_rate`）；
+- 缺失率上限（`max_missing_rate`）。
+
+不勾选门禁也可运行，但结果可靠性无法保证。**强烈建议正式分析一律开启门禁。**
+
+---
+
+## 二、数据准备
+
+### 2.1 表型分析的硬性前提（缺一不可）
+
+| 数据 | 说明 | 未准备好时的表现 |
+|---|---|---|
+| **性状表** `bre_trait` | 分析对象（单果重、可溶性固形物等核心数值性状） | 性状下拉为空，无法选性状 |
+| **观测表** `bre_trait_observation` | 逐株性状观测值 | 提示"该性状无观测数据" |
+| **树表** `bre_tree` | 每株树的身份信息 | 无法关联单株、克隆、家系 |
+
+### 2.2 增强数据（有则分析更强，缺则自动降级，不影响运行）
+
+| 数据 | 增强什么 |
+|---|---|
+| **系谱**（parent_of 亲子关系） | ABLUP 的系谱 A 矩阵、近交系数、亲缘分析、ΔG 的 σ_A |
+| **种质**（germplasm） | 种质编号/名称回显、配合力亲本、S-等位选配过滤 |
+| **克隆**（clone） | 无性系级 EBV 排行、克隆作为随机效应 |
+| **砧木**（rootstock） | G×R 砧木×接穗互作随机效应 |
+| **研究点**（trial_study） | G×E 环境维度（site）、稳定性分析的环境均值表 |
+
+> 结论：**表型分析只依赖「性状 + 观测 + 树」三张核心表**；空的研究点、缺系谱等都不阻断分析，只是对应的高级功能（G×E、近交、亲缘）不可用或降级。
+
+### 2.3 分子分析的硬性前提
+
+基因组选择（GBLUP/ssGBLUP/rrBLUP/BayesB）、GWAS、QTL、MAS 都要求先创建**基因型数据集**并导入**基因型调用记录**，否则会提示"基因型数据集不存在"或"该数据集无基因型调用记录"。分子分析见第 4 节。
+
+---
+
+## 三、常用核心分析操作说明
+
+### 3.1 描述性统计
+
+**目的**：快速体检一批观测数据——均值、标准差、变异系数、极值、缺失率，判断数据是否可用、是否异常。
+
+**所需数据**：性状 + 观测（即可运行）。
+
+**操作**：
+1. 顶部工具条左侧勾选 1 个或多个性状；
+2. 「描述统计」页签直接展示均值/标准差/变异系数/极值/缺失统计。
+
+**结果解读**：
+- 变异系数（CV）过高 → 该性状田间差异大，检查是否有测定误差或环境不均；
+- 缺失率过高 → 影响建模，考虑补测或剔除。
+
+### 3.2 相关性矩阵
+
+**目的**：性状间表型相关或**遗传相关**，辅助选育目标取舍（如两性状强正相关可只选其一）。
+
+**所需数据**：性状 + 观测；`genetic` 模式另需系谱或足够数据支撑成对双性状 BLUP。
+
+**操作**：「相关性」页签选性状 → 模式 `pheno`（皮尔逊表型相关）或 `genetic`（遗传相关）→ 查看矩阵。
+
+### 3.3 ABLUP / EBV 育种值估计（核心）
+
+**目的**：从表型观测中剔除非遗传因素（环境、区组、协变量等），估计每株树的**育种值 EBV** 与**遗传力 h²**，这是单株/无性系入选和排名的依据。
+
+**所需数据**：
+- 硬性：性状 + 观测 + 树；
+- 增强：系谱（A 矩阵，缺则按单株独立建模降级）、克隆、研究点（G×E）、砧木（G×R）。
+
+**操作**：
+1. 顶部「**运行 ABLUP / EBV**」→ 对话框：
+   - 性状（自动带出 trait_id）、年份（可空，空=全部年份）；
+   - 固定效应：trial_study（多环境）/ rootstock；
+   - 协变量：crop_load（负载量）等，用于 BLUP 校正；
+   - **阶段拆分**：juvenile（童期）/ evaluation（成株），给定则只取该阶段观测建模；
+   - **数据就绪门禁**：勾选；
+2. 提交 → 异步任务，到「模型批次」看状态；
+3. 完成后「EBV 排行」页签选批次 → 逐树 EBV 表；「无性系排行」页签 → 无性系级均值。
+
+**结果解读**：
+- **h²（遗传力）**：0.1~0.3 低、0.3~0.5 中、0.5+ 高；越低越依赖加大观测量与系谱信息；
+- **EBV**：相对值，正负无绝对意义，**只在同批次内比大小**；
+- **可靠性（Reliability）**：越高越可信，入选决策时建议设门槛（如 ≥0.5）。
+
+### 3.4 多环境 G×E / G×R / 空间 / 区组模型（MET 扩展）
+
+**目的**：当同一批材料跨研究点/年份观测时，评估**基因型×环境互作**，识别"平均好但某地不稳"的材料；或加入空间（AR1×AR1）、砧木互作、区组效应提高精度。
+
+**所需数据**：
+- G×E：研究点（site）或年份（year）维度；
+- G×R：砧木信息；
+- 空间：观测株均需 `row_no` / `col_no`；
+- 区组：树表 `block_no`（≥2 区组）。
+
+**操作**：「多环境 GxE」页签 → 性状/年份/固定效应 → 勾选 G×E（选环境维度）或 G×R 或 AR1×AR1 空间或区组随机效应（**四者互斥**）→ 运行，结果写「模型批次」。
+
+**结果解读**：互作显著时，注意看 G×E 模式（配合「公平性报告」按 site 看 EBV 偏差）。
+
+### 3.5 配合力 GCA / SCA
+
+**目的**：对交配组合亲本评估**一般配合力 GCA**（亲本平均表现）与**特殊配合力 SCA**（特定组合偏离亲本平均的部分），指导亲本选配与杂交组合决策。
+
+**所需数据**：性状 + 观测 + 杂交组合（亲本可识别）+ **交配设计信息**（在参数里声明）。
+
+**操作**：
+1. 顶部「**运行配合力 GCA/SCA**」→ 对话框选**交配设计**：完全双列（full_diallel）/ 部分双列（partial_diallel）/ line×tester NCII / NCIII 测交；
+2. 提交 → 异步；「配合力」页签查看：GCA 亲本表 + SCA 组合表 + ANOVA 摘要。
+
+**结果解读**：
+- GCA 高的亲本 → 可作核心亲本推广；
+- SCA 高而 GCA 一般的组合 → 特定互补，可重点观察；
+- 结合 ANOVA 摘要看各效应显著性。
+
+### 3.6 ANOVA / 广义遗传力 H²
+
+**目的**：方差分解，检验性状在遗传型/区组间是否显著差异，估计**广义遗传力 H²**。
+
+**所需数据**：性状 + 观测 + 试验设计（建议先做试验设计生成）。
+
+**操作**：
+1. 「ANOVA/H²」页签：选研究点 + 设计类型 → **生成试验设计**（RCBD 随机完全区组 / 增广 augmented / α-格子，见 3.7）；
+2. 再选性状、年份；若 RCBD 可勾「区组校正」（从残差析出区组效应）；
+3. 「**运行 ANOVA / H²**」（同步）→ 结果含 H²、F、p、σ²g、σ²e、家系均值。
+
+**结果解读**：p<0.05 说明遗传型间差异显著；H² 高说明表型差异主要来自遗传。
+
+### 3.7 试验设计生成
+
+**目的**：为研究点内参试条目生成**区组随机分派**，保证田间布局可分析。
+
+**操作**：「ANOVA/H²」页签 → 研究点 + 设计类型 → 生成：
+- **RCBD**：随机完全区组；
+- **增广 augmented**：对照种质每区组重复、新品系不重复（需勾选对照种质列表）；
+- **α-格子**：区组大小 k、重复数 r（block_no 复合编码 重复×100+区组）。
+
+**结果**：落库 `entry.block_no`，作为后续 ANOVA/区组模型的数据基础。
+
+### 3.8 遗传相关（MT-BLUP 成对双性状）
+
+**目的**：估计两两性状间的**遗传相关 r_g**（剔除环境协方差后的遗传层面相关），用于指数构建、间接选择、童期-成株相关评估。
+
+**所需数据**：≥2 个核心性状 + 观测。
+
+**操作**：「遗传相关 MT-BLUP」页签 → 选 ≥2 性状 → 运行（异步）→ r_g 矩阵表（含每对的遗传方差、环境方差、共同个体数、收敛标记）。
+
+**结果解读**：
+- |r_g| 接近 1 的性状 → 遗传上高度关联，可合并或作间接选择；
+- `converged=false` 或样本不足的对 → 谨慎采信。
+
+### 3.9 Type-B 多环境遗传相关
+
+**目的**：把**环境当"性状"**，估计同一性状在不同环境/阶段间的遗传相关 r_B：
+- `site`：跨研究点一致性（越接近 1 说明基因型×环境互作越弱，越可多点合并分析）；
+- `year`：跨年份稳定性；
+- `stage`：**童期-成株遗传相关**（幼年选择是否有效）。
+
+**操作**：「Type-B 多环境遗传相关」页签 → 性状 + 环境维度 site/year/stage + 方法（REML / calo）→ 运行 → r_B 热图（ECharts）。
+
+### 3.10 选择指数
+
+**目的**：把**多性状 EBV 综合成一个指数**，按综合值排名选优（比单一性状更符合育种目标）。
+
+**所需数据**：参与指数的性状 + 观测（或指定 ABLUP 批次用 EBV）；遗传相关模式需 `g_method` 来源。
+
+**操作**：「选择指数」页签 → 方法（见下）→ 性状权重/经济权重 → 聚合层级（clone/tree）→ TopN → 计算（同步）→ 结果列表；可「**写入决选**」（前 N 名写入决选结果 `bre_selection_result`，可靠性低于门槛自动跳过）。
+
+**方法**：
+- `zsum`：加权标准分（Z 值加权求和），快速直观；
+- `smith_hazel`：**真 Smith-Hazel 指数**，按遗传-表型协方差结构最优组合权重；
+- `restricted`：**受限指数**，指定性状遗传增益约束为 0（其余性状自由响应），如"果重不降低的前提下提高糖度"；
+- `auto_weights`：按实测遗传力自动生成权重。
+
+**结果解读**：看综合指数排名 + 各性状对指数的贡献；入选前结合 EBV 可靠性门槛。
+
+### 3.11 交叉验证（k-fold）
+
+**目的**：评估**预测准确度**——用部分个体建模、预测其余个体，看 EBV 与实测的相关（cv_accuracy/pearson）与误差（RMSE），防止模型过拟合。
+
+**所需数据**：性状 + 观测；GS 模式还需基因型数据集。
+
+**操作**：「交叉验证」页签 → 性状 → 模式：
+- **ABLUP**：表型模型 k-fold（k=2~10，掩蔽留出）；
+- **GS**：选基因型数据集 + 方法（GBLUP/ssGBLUP/rrBLUP/BayesB）+ MAF + 折划分（random 固定种子随机分层 / family 家系阻塞折，**防亲缘泄漏**）+ seed（固定可复现）。
+
+运行（异步）→ 列表 + 折明细（每折 n_train/n_test、pearson、RMSE）。
+
+**结果解读**：
+- `cv_accuracy` / 平均 pearson 越高越好（0.5+ 实用、0.7+ 良好）；
+- family 折比 random 折通常低一些属正常（随机折可能泄漏同亲缘个体）。
+
+### 3.12 稳定性 AMMI / Finlay-Wilkinson
+
+**目的**：评估材料跨环境的**稳定性**——高产且稳定 vs 高产但波动大，指导区域推广。
+
+**所需数据**：性状 + 观测 + 环境维度（site/year）两因素均值表。
+
+**操作**：「稳定性 AMMI/FW」页签 → 性状 + 环境维度（site/year）+ 方法（AMMI 和/或 Finlay-Wilkinson）→ 运行（异步）→：
+- **AMMI**：ASV 稳定性值、ecovalence（互作方差）、IPC1/IPC2、ASV 排名；
+- **FW**：回归斜率 b、决定系数 r²（b≈1 且 r² 高 → 平均稳定型）。
+
+**结果解读**：ASV/ecovalence 越小越稳定；FW 的 b 偏离 1 越多 → 对环境越敏感（b>1 在高产环境优势明显，b<1 在低产环境抗逆）。
+
+### 3.13 UPGMA 聚类
+
+**目的**：按多性状相似度把单株/无性系分层聚类（树状图），看群体结构、划分类群。
+
+**操作**：「UPGMA 聚类」页签 → ≥2 性状 → 实体类型（tree/clone）→ 模式（pheno 表型 / genetic EBV）→ 距离（corr/euclidean）→ k 类数（空=按合并距离跳变自动选）→ 树状图。
+
+### 3.14 数据质量检查
+
+**目的**：定位**离群观测株**（缺失率 + IQR 超界 + MAD 稳健 z 双通道），按方向区分——**同向偏离 = 可能的精英**，**反向偏离 = 疑似记录错误**。
+
+**操作**：「数据质量」页签 → 性状（+年份/研究点）→ 运行 → 离群株列表与标记。
+
+**建议**：正式建模前先跑此分析，把"疑似错误"方向的数据核实后再建模。
+
+### 3.15 遗传增益 ΔG
+
+**目的**：估算**选择后遗传增益**——ΔG = k·r_g·σ_A（截断选择强度 × 预测准确性 × 遗传标准差），用于设定选择强度与周期预期。
+
+**操作**：「遗传增益 ΔG」页签 → 性状 → 指定 ABLUP 批次（取 PA 与 σ_A）→ 入选比例 top_p 或人数 top_n → 世代间隔 → 逐批次投影。
+
+**注意**：ΔG 是**期望值/投影**，前提是模型正确、无近交负效应累积。
+
+### 3.16 亲缘 / 近交分析
+
+**目的**：系谱 A 矩阵估计**近交系数 F**、个体间**亲缘关系**，预警近交风险；**近交衰退**端点把 F 对表型做回归，量化近交代价。
+
+**操作**：「亲缘·近交」页签 → 阈值 → 运行 → 近交预警 / F 系数 / A 矩阵；「近交衰退」另端点输入性状运行。
+
+### 3.17 主动选配推荐 / OCS
+
+**目的**：在满足**S-等位不相容硬过滤**的前提下，按 **EBV 互补 − 近交惩罚**推荐亲本配对（含花期软警示：重叠/错开/库存/未知），避免近交、保证可配；**OCS** 做群体级配种贡献优化（max Σc·ebv − λ·c'Ac）。
+
+**操作**：「选配推荐」页签 → 候选种质 → 预测批次（EBV）→ 亲缘阈值/权重/最大配对数 → 推荐表；OCS 在「OCS」分块输入候选 + 选配数 n_select + 惩罚 λ。
+
+### 3.18 决选预览
+
+**目的**：把**选择规则**应用到表型/EBV 上，逐树预览命中/淘汰，EBV 可靠性低于门槛视为"证据不足"。
+
+**操作**：「决选预览」页签 → 选择规则（可空）→ 预测批次/年份 → 预览逐树结果。
+
+### 3.19 模型健康监控 / MLOps
+
+**目的**：相邻两轮 ABLUP 对比，监控 **h² 跌幅 / EBV 排名翻转 / 可靠性变化**——数据或流程若有异常会在此暴露。
+
+**操作**：「模型健康」页签选批次（可指定上一批对比）→ 漂移检测 / 手动重训 / 版本回滚 / 设当前版本。
+
+### 3.20 组合得失漏斗
+
+**目的**：花 → 果 → 种 → 苗 → 定植 → 树 → 入选的**逐环节数量漏斗**，看哪个环节损耗最大、投入产出比。
+
+**操作**：顶部「组合得失漏斗」→ 只读视图。
+
+---
+
+## 四、分子类分析（第二批，本手册从略）
+
+- **基因组选择**：「基因组选择 GBLUP」页签内直接运行 GBLUP / ssGBLUP / rrBLUP / BayesB（需基因型数据集 + 基因型调用记录）；也可在交叉验证选 GS 模式评估其预测准确度。
+- **GWAS / QTL / MAS / QTL×E**：独立「GWAS」页面（曼哈顿图/QQ 图、QTL 定位、MAS 面板、QTL×E 分层），MAS 面板可在本页「回交 MABC」里做前景/背景选择。
+
+分子分析各功能的目的、数据准备、操作与解读，将在后续专门文档补全。
+
+---
+
+## 五、常见问题 FAQ
+
+**Q1：提交后一直 pending / FAILED？**
+→ 「模型批次」页签任务状态看 `error_msg`。最常见：数据就绪门禁不通过（样本量不足/系谱缺失率高）、该性状无观测、分子分析未建基因型数据集。
+
+**Q2：为什么有些分析（G×E、亲缘、近交）提示不可用？**
+→ 缺增强数据（研究点/系谱/砧木）。补录后即可用；不影响其他表型分析。
+
+**Q3：EBV 为什么有时是负的？**
+→ EBV 是**相对值**（群体均值为参考），正负无绝对好坏，只看同批次内排名。
+
+**Q4：选择指数写入决选时个别树被跳过？**
+→ EBV 可靠性低于设定的 `min_reliability` 门槛，系统视为证据不足自动跳过。
+
+**Q5：刷新后批次/结果还在吗？**
+→ 在。异步结果落库（预测批次、配合力、CV、稳定性、遗传相关、Type-B、GWAS 等），重启系统不丢，任务存储也已持久化到数据库。
+
+**Q6：列显示设置保存了但刷新失效？**
+→ 已修复（2026-08-07，`useTableColumns` 深度监听）。若仍异常请反馈：哪个列表页 + 浏览器控制台报错。