Package top.wcpe.beacon.agent.api

Class ScheduleResult

java.lang.Object

top.wcpe.beacon.agent.api.ScheduleResult

public final class ScheduleResult
extends Object

一次 acquireCandidate 的决策结果（FR-148）。

无论控制面在线决策还是降级本地决策，future 均正常完成（fail-static，不因控制面不可达而异常完成）； 调用方以 chosen() 是否为 null 判断本次是否取到候选。

三态结论（FR-244）：chosen() == null 这一个事实承载了两种方向相反的处境—— 「本次作用域内确实没有候选」（稳定事实，重试无用）与「决策没做成、结论未知」（当前状态，可重试）。 调用方一律读 state() 区分，不要从 failReason() 的字符串去猜。

Constructor Summary

Constructors

Constructor	Description
ScheduleResult(CandidateView chosen, String traceId, DecisionSource source, String failReason)	既有构造器（行为逐位不变）：结论类别按 chosen 推导—— 选中了即 ScheduleState.CHOSEN，未选中即 ScheduleState.NO_CANDIDATE。
ScheduleResult(CandidateView chosen, String traceId, DecisionSource source, String failReason, ScheduleState state)	带三态结论的构造器（FR-244 新增）。
ScheduleResult(CandidateView chosen, String traceId, DecisionSource source, String failReason, ScheduleState state, int admissionExcludedCount)	带三态结论与作用域排除台数的构造器（FR-244）。

Method Summary

Modifier and Type	Method	Description
int	admissionExcludedCount()	本次因准入作用域被排除的候选台数（FR-244）；没带作用域、或带了但一台都没被排除时为 0。
CandidateView	chosen()	选中的候选；为 null 表示本次调度失败（见 failReason() 与 state()）。
String	failReason()	失败原因码（如 no_candidate / no_candidate_in_scope / zone_not_found）； 成功为 null。
DecisionSource	source()	决策来源。
ScheduleState	state()	本次结论的类别（FR-244）：ScheduleState.CHOSEN / ScheduleState.NO_CANDIDATE （稳定事实）/ ScheduleState.UNAVAILABLE（当前状态、可重试）。
String	traceId()	决策唯一标识：控制面决策为服务端 traceId，本地降级为本地 traceId。

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ScheduleResult

public ScheduleResult(CandidateView chosen,
 String traceId,
 DecisionSource source,
 String failReason)

既有构造器（行为逐位不变）：结论类别按 chosen 推导—— 选中了即 ScheduleState.CHOSEN，未选中即 ScheduleState.NO_CANDIDATE。

保留它是为了二进制兼容既有调用方。它表达不了 ScheduleState.UNAVAILABLE （"决策没做成"）——那需要实现方显式用 ScheduleResult(CandidateView, String, DecisionSource, String, ScheduleState) 说出来； 用本构造器报"没做成"会把一次可重试的处境印成稳定结论。

ScheduleResult

public ScheduleResult(CandidateView chosen,
 String traceId,
 DecisionSource source,
 String failReason,
 ScheduleState state)

带三态结论的构造器（FR-244 新增）。

Parameters:

state - 结论类别；实现方必须如实给出，不得把"决策没做成"报成 ScheduleState.NO_CANDIDATE（那是另一类结论，恢复动作方向相反）； null 按 chosen 兜底推导（见 ScheduleResult(CandidateView, String, DecisionSource, String, ScheduleState, int)）

Throws:

IllegalArgumentException - state 与 chosen 自相矛盾（一致性校验见 6 参构造器）

ScheduleResult

public ScheduleResult(CandidateView chosen,
 String traceId,
 DecisionSource source,
 String failReason,
 ScheduleState state,
 int admissionExcludedCount)

带三态结论与作用域排除台数的构造器（FR-244）。

三态一致性校验：三态的价值就在于"取值即事实"，故本构造器拒绝自相矛盾的组合—— ScheduleState.CHOSEN 必须带选中候选，ScheduleState.NO_CANDIDATE / ScheduleState.UNAVAILABLE 必须不带。否则调用方按 state() 读到的结论 与 chosen() 表达的结论会打架，而两个读数都是一眼可信的， 谁也不会想到要去交叉验证。state 为 null 时仍按 chosen 兜底推导 （选中了即 CHOSEN，未选中即 NO_CANDIDATE），故 null 不参与一致性校验。

Parameters:

admissionExcludedCount - 本次因准入作用域被排除的候选台数；< 0 归 0。 它只统计**作用域那一类**排除（健康原因不算），故调用方可以据此 确定地说"这次收窄真的发生了"——那是"决策阶段收窄"在来源侧可读的痕迹

Throws:

IllegalArgumentException - state 与 chosen 自相矛盾（见上的一致性校验）

Method Details

chosen

public CandidateView chosen()

选中的候选；为 null 表示本次调度失败（见 failReason() 与 state()）。

traceId

public String traceId()

决策唯一标识：控制面决策为服务端 traceId，本地降级为本地 traceId。

source

public DecisionSource source()

决策来源。

failReason

public String failReason()

失败原因码（如 no_candidate / no_candidate_in_scope / zone_not_found）； 成功为 null。

它是给人读的诊断串，不是判据：需要区分"空结果"与"没做成"一律读 state()。

state

public ScheduleState state()

本次结论的类别（FR-244）：ScheduleState.CHOSEN / ScheduleState.NO_CANDIDATE （稳定事实）/ ScheduleState.UNAVAILABLE（当前状态、可重试）。

它与 chosen() 不会互相矛盾：CHOSEN 时 chosen() 恒非 null， 另两态时 chosen() 恒为 null（构造时即校验）。

admissionExcludedCount

public int admissionExcludedCount()

本次因准入作用域被排除的候选台数（FR-244）；没带作用域、或带了但一台都没被排除时为 0。

它是"决策阶段确实收窄了"在调用方这一侧可直接读到的痕迹：> 0 时调用方可以 留一条读数行（本仓接入方就是这么用的），而不必去猜"对端到底有没有按作用域收窄"。 健康原因造成的排除不计入本数。