PlantAI-dev/docs/subfamily_species_selection_unified_revision_plan_2026-05-27.md

亚家族分类物种选择统一修订方案（2026-05-27）

1. 修订目的

统一“亚家族分类分析”中待分类物种的选择、计划字段和前端展示，避免同一次请求中出现：

• 顶层 plan 是一组物种；
• stage.params 是另一组物种；
• identifySpeciesSelection.defaultSelected 又回到 config 默认物种；
• 前端摘要、批量确认、阶段确认显示不一致。

本次修订不改变生物学分析方法，只统一 planning/API/frontend 的物种选择契约。

2. 当前真实 job 状态

job_id: job_1779806881787_16006d Family: SPL

config 分组：

角色	物种
target	Dl, Lc
comparative	Cp, Os, PPY, Sl
reference	At

当前亚家族状态：

物种	状态
Lc	confirmed_valid
PPY	confirmed_valid
Dl	missing_identify
Cp	missing_identify
Os	missing_identify
Sl	missing_identify

因此当前“剩余物种”应为：Dl, Cp, Os, Sl。

3. 请求类型矩阵

类型	示例	应选待分类物种
显式单物种	执行 Lc 的亚家族分类	Lc
显式比较物种单物种	执行 PPY 的亚家族分类	PPY
显式多物种	执行 Cp Os Sl Dl 的亚家族分类	Cp, Os, Sl, Dl
目标物种	执行目标物种的亚家族分类	Dl, Lc
比较物种	执行比较物种的亚家族分类	Cp, Os, PPY, Sl
剩余物种	执行剩余物种的亚家族分类	Dl, Cp, Os, Sl
剩余目标物种	执行剩余目标物种的亚家族分类	Dl
剩余比较物种	执行剩余比较物种的亚家族分类	Cp, Os, Sl

说明：用户说“目标物种/比较物种”时按 config 角色选全部；只有出现“剩余/未完成”等词时才排除已完成确认物种。

4. 字段同步契约

后端必须把唯一权威物种列表写入以下所有字段：

• plan.target_species
• plan.params.targetSpecies
• intent.target_species
• intent.params.targetSpecies
• stages_detail[*].params.targetSpecies
• stages_detail[*].params.identifySpeciesSelection.defaultSelected

阶段规则：

阶段	targetSpecies	referenceSpecies	comparativeSpecies	scopeMode
identify	待分类物种	[]	[]	target_only
phylogeny	待分类物种	At	[]	target_plus_reference
reference_classification	待分类物种	At	[]	target_plus_reference

即使待分类物种来自 comparative 角色，也写入 targetSpecies，因为在本次分析中它是“待分类目标”。原始 config 角色只用于选择物种，不用于 stage 执行参数中的 comparativeSpecies。

5. 当前问题根因

1. 后端没有统一的 subfamily species selector。
2. identifySpeciesSelection.defaultSelected 在部分路径仍保留 config 默认 Dl, Lc。
3. 前端 formatPlanSummary() 用空数组阻断 fallback，导致摘要可显示“未选择”。
4. 前端 applyIdentifySelectionGroups() 会基于 defaultSelected 反向覆盖 targetSpecies，导致批量弹窗回到旧默认。

6. 修订方案

6.1 后端

在 apps/web/vue3/main.py 中新增：

• _subfamily_role_species(selection, role)：读取 target/comparative/other 分组。
• _select_subfamily_classification_species(job_id, family, selection, message, current_targets)：按请求类型返回待分类物种与选择模式。
• _with_identify_default(selection, selected_species, message)：生成 defaultSelected 已同步的 selection。
• _sync_subfamily_plan_species(...)：统一写入 plan/intent/stages_detail 的所有目标物种字段。

调用点：

• deterministic subfamily plan 分支；
• orchestrator_v2 plan 后处理分支，在 requirements_report 前、stage params enrich 前完成同步。

6.2 前端

在 apps/web/vue3/index.html 中：

• 增加 firstNonEmptyList()；
• formatPlanSummary() 只用非空数组，空数组继续 fallback；
• applyIdentifySelectionGroups() 不应在已有 targetSpecies 时使用旧 defaultSelected 覆盖权威列表；
• 批量确认、阶段确认只展示后端已同步的 targetSpecies。

7. 验证矩阵

必须验证以下请求：

1. 帮我执行Lc的亚家族分类分析
2. 帮我执行PPY的亚家族分类分析
3. 帮我执行Cp Os Sl Dl的亚家族分类分析
4. 帮我执行目标物种的亚家族分类分析
5. 帮我执行比较物种的亚家族分类分析
6. 帮我执行剩余物种的亚家族分类分析
7. 帮我执行剩余目标物种的亚家族分类分析
8. 帮我执行剩余比较物种的亚家族分类分析

每个请求检查：

• plan.target_species
• plan.params.targetSpecies
• plan.params.identifySpeciesSelection.defaultSelected
• stages_detail[*].params.targetSpecies
• stages_detail[*].params.identifySpeciesSelection.defaultSelected
• identify 阶段 scopeMode=target_only/referenceSpecies=[]
• phylogeny/reference_classification 阶段 scopeMode=target_plus_reference/referenceSpecies=[At]

通过后再重启 7880，并用真实接口验证页面可访问。