refactor(arch): redesign the code structure

src/mcm26b/belief/__init__.py

@@ -0,0 +1,58 @@
+"""P3 逐频道信念状态：候选集合 K_c 维护与频道处理状态。
+
+现状：骨架（P3 起填充）。接口与不变式先行固定，防止后续实现漂移。
+
+核心不变式（验收标准）：
+- 保守性：真源永远属于维护中的候选集合；任何更新不得因误差、
+  圆弧离散或浮点容差把真点排除（自建真值案例中真源始终保留）；
+- direction 读数：K_c ⊆ Ω ∩ W(s, θ±δ) ∩ B(s, 1500)（首次测向构造见
+  geometry.planning.first_bearing_candidate_disk 的解析证书）；
+- no_signal 读数（P4，全向源）：仅可排除 B(s, 1000)；用于定向源时
+  是"位置×朝向"联合约束，单独维护空间候选会误删真源（P5 才启用）；
+- /clear 成功：状态转 CLEARED；失败只说明"该频道 20m 内无可清除源"，
+  不得直接删除超出 20m 的候选。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+from ..config import ProblemConfig
+
+
+class ChannelStatus(Enum):
+    UNKNOWN = "unknown"          # 尚无有效证据
+    DETECTED = "detected"        # 收到过 direction/near，待定位
+    LOCATED = "located"          # 候选集包围圆半径 <= 20，可清除
+    CLEARED = "cleared"          # 清除成功
+    ABSENT = "absent"            # 覆盖证明不存在（P4）
+
+
+@dataclass
+class ChannelBelief:
+    channel: int
+    status: ChannelStatus = ChannelStatus.UNKNOWN
+    measurements: list = field(default_factory=list)   # (位置, 结果, svd_deg) 记录
+
+
+class BeliefState:
+    """全部 20 个频道的信念集合。策略端唯一的事实来源。"""
+
+    def __init__(self, config: ProblemConfig = ProblemConfig()):
+        self.config = config
+        self.channels = {channel: ChannelBelief(channel)
+                         for channel in range(config.field.channel_min,
+                                              config.field.channel_max + 1)}
+
+    def update_measure(self, channel: int, position, result: str,
+                       svd_deg: float | None) -> None:
+        """按读数收敛候选集合。未实现：需要几何模块的在线圆盘角域交。"""
+        raise NotImplementedError("P3：接入 geometry 的圆盘约束角域交后实现")
+
+    def candidate_set(self, channel: int):
+        """返回该频道当前候选集合（保守外包形式）。未实现。"""
+        raise NotImplementedError("P3")
+
+    def mark_cleared(self, channel: int) -> None:
+        self.channels[channel].status = ChannelStatus.CLEARED