Package top.wcpe.beacon.agent.api

Class CandidateView

java.lang.Object

top.wcpe.beacon.agent.api.CandidateView

public final class CandidateView
extends Object

调度候选的只读快照视图（FR-148）。

字段与控制面候选契约对齐（v2-metrics-health-scheduling §5.1）：仅 schedulable / degraded 候选进入快照。 本视图为本机缓存的一帧，非实时——最长滞后一个刷新周期。

标签字段（FR-244）：labels() 是该候选节点自己声明的键值标签 （FR-243 的写入面，见 ADR-0086），不是控制面另登记的一套。调用方可在选之前 用它自行收窄候选集合；若希望收窄发生在决策内部（"被排除的候选连被选中的机会都没有"）， 用 BeaconScheduling.acquireCandidate(String, String, AdmissionScope) 把同样的条件带进去。

Constructor Summary

Constructors

Constructor	Description
CandidateView(String serverId, String zone, int score, HealthLevel level, int onlineCount, int maxOnline)	不带标签的候选视图（既有构造器，行为逐位不变）——标签记为空 map。
CandidateView(String serverId, String zone, int score, HealthLevel level, int onlineCount, int maxOnline, Map<String,String> labels)	带节点自声明标签的候选视图（FR-244 新增构造器）。

Method Summary

Modifier and Type	Method	Description
Map<String,String>	labels()	该候选节点自己声明的键值标签（FR-243 的写入面，本仓不解释任何 key 的语义）。
HealthLevel	level()	健康等级。
int	maxOnline()	容量上限。
int	onlineCount()	在线人数（仅展示，不参与调用方决策）。
int	score()	健康分（0-100）。
String	serverId()	候选子服 serverId。
String	zone()	候选所在小区名。

Methods inherited from class java.lang.Object

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

Constructor Details

CandidateView

public CandidateView(String serverId,
 String zone,
 int score,
 HealthLevel level,
 int onlineCount,
 int maxOnline)

不带标签的候选视图（既有构造器，行为逐位不变）——标签记为空 map。

保留它是为了二进制兼容：既有调用方（含只读缓存的旧字段集）不必改动即可继续编译与运行。 空 map 的含义见 labels()：它是"本视图这一帧没有可展示的标签"， 不是对这个节点有没有声明过标签下结论。

CandidateView

public CandidateView(String serverId,
 String zone,
 int score,
 HealthLevel level,
 int onlineCount,
 int maxOnline,
 Map<String,String> labels)

带节点自声明标签的候选视图（FR-244 新增构造器）。

Parameters:

labels - 该节点自声明的键值标签；null 归为空 map，非 null 时做防御性拷贝并冻结。 空 map 的含义见 labels()

Method Details

serverId

public String serverId()

候选子服 serverId。

zone

public String zone()

候选所在小区名。

大厅成员为空串：全局大厅池（FR-281）的成员不属于任何小区，其取值是空串， 不是"未知小区"。取值与取值来源一一对应——经 ...InLobby 路径拿到的视图 zone 恒为空串。

score

public int score()

健康分（0-100）。

level

public HealthLevel level()

健康等级。

onlineCount

public int onlineCount()

在线人数（仅展示，不参与调用方决策）。

maxOnline

public int maxOnline()

容量上限。

labels

public Map<String,String> labels()

该候选节点自己声明的键值标签（FR-243 的写入面，本仓不解释任何 key 的语义）。

返回不可修改的 map：既不可增删改，也不随控制面后续数据变化。

空 map 只表示"本视图这一帧没有可展示的标签"，不是"这个节点没有声明过标签"： 它既可能来自"节点确实没有声明"，也可能来自"本帧快照来自不支持该字段的旧控制面" （甚至节点声明了空标签集）——本视图看不到这三者的差别。"这一帧到底带没带 labels 字段"由来源层判定（core 侧的 CandidateEntry.labelsPresent）， 不在这里猜。

因此不要把本方法的空 map 当成"没有声明"的判据：需要"按作用域收窄"时， 一律走 BeaconScheduling.acquireCandidate(String, String, AdmissionScope) （或 BeaconScheduling.candidatesInZone(String, AdmissionScope)）， 由实现方按可用的判据决定是"收窄后确实没有候选"还是"这一帧判不了"， 两者在返回值与异常上是分开的。

规模上限对齐 FR-227：单个 key 长度 ≤ 32、单个 value 长度 ≤ 128、 单节点标签数 ≤ 20。