构造脱敏的统一错误响应 (body, http_status)。

按 req_id 查询决策轨迹，不存在时返回 None。

Convenience POST helper.

提交用户传输请求 - 基于实时资源占用决策

从 Response 中解析 JSON，便于断言。

创建隔离、固定种子、不启动后台线程的引擎。

工厂：创建引擎实例，可注入随机种子以保证可复现；autostart 控制是否启动后台线程。 未显式传 seed 时回退到环境变量 SMARTNODE_SEED（确定性模式）。

构造 GEO 卫星位置字典（alt 单位：米）。

追加一条决策轨迹；若缓冲满则淘汰最旧条目。

根据当前时间计算卫星位置，返回 (lat°, lon°, alt m)。 若设置了有效 TLE 且 sgp4 可用，使用 SGP4 传播；否则回退二体开普勒解析解。

创建一个固定种子、不启动后台线程的引擎。

构造地面站字典。

构造卫星位置字典（alt 单位：米）。

构造 ContentTask 并设置创建时刻。

卫星-地面站可见性：基于精确 ENU 拓扑仰角（替换大圆中心角近似）。

Convenience GET helper.

保存（或更新）一个命名场景。 Parameters ---------- name: 场景名称（<=128 字符，全库唯一）。 engine: ``SimulationEngine``

运行时覆盖（最高优先级）。

从 Response 中解析 JSON 字典。

计算当前时刻的数据价值

对仿真引擎当前状态拍快照。 Parameters ---------- engine: ``SimulationEngine`` 实例。 label: 可选的快照标签，便于人类识别（例如

计算球面大圆地心角 (Degrees)

检查卫星与地面站的可见性（仰角 >= min_elevation）。 已更新为调用 ``backend.physics.geometry.check_visibility_enu``， 基于 WGS-84 ECEF 拓扑坐标精确求仰角，替代球面正弦/大圆角近似。 对外接口与

直连链路速率 (Mbps)，由链路预算引擎驱动（含大气衰减）。 替代原 base_rate × exp(-d/k) 经验公式， 使用 FSPL/EIRP/G-T/C-N0 推导物理上准确的可达速率； 通过仰角与地面站降雨率叠加 ITU-R P.838/P.618 大气衰减。

启动 n_threads 个线程，每线程提交 per_thread 次，返回 (results, errors)。

获取GEO卫星固定位置

从快照字典恢复仿真状态，进入回放模式（主循环暂停）。 Parameters ---------- snapshot_data: 由 :meth:`snapshot` 生成的快照字典。 Returns

手动推进仿真时钟（不启动线程时需要手动推进）。

统一日志输出方法 - 支持遥测级别控制，并将调度事件发布到 SSE 总线。 Args: message: 日志消息 level: 遥测级别 ("high", "normal", "low")，映射到结构化日志级别

* Execute an HTTP request and return the parsed JSON response. * * - Injects `Authorization: Bearer <token>` when `smartnode_token` is set *

检查中继卫星带宽是否充足

Build a minimal Response-like object for fetch mocks.

直接向引擎历史队列注入一条已完成的请求（不触发真实提交流程）。

* Format transmission progress (0–100) to a percentage string. * Mirrors app.js `methods.formatProgress`.

获取卫星位置

校验快照字典的结构合法性。 Returns ------- list[str] 错误列表；空列表表示快照合法。

将请求 data_size 按其数据类型的 size_unit 统一归一到 MB。 所有换算点（进度计算、时间窗校验、吞吐累计）统一复用本函数，避免 KB/MB/GB 混算。

GEO 星间激光链路速率 (Mbps)，由激光 ISL 物理模型驱动。 使用激光通信模型：按发射功率/望远镜口径/光束发散角与两星距离计算 几何损耗与接收功率，并通过地球遮挡判定确认视线可见性。 当视线被地球遮挡时返回 0 (不可用)。 替换原来基于经验 exp

检查 LEO 与 GEO 中继星的可见性。 已更新为调用 ``backend.physics.geometry.check_geo_visibility_enu``， 基于精确仰角阈值判断，替代固定 80° 地心角近似。

* Format simulation seconds to "HH:MM:SS". * Mirrors app.js `methods.formatTime`.

从场景字典恢复引擎资源配置。 只恢复可在运行时动态调整的资源数量（地面站、LEO 卫星）。 Parameters ---------- engine: ``SimulationEngine`` 实例。

估算传输时间（秒）

⭐ 记录拒绝原因分布

LEO-GEO 可见性：基于精确仰角阈值（替换固定 80° 中心角近似）。

* Build utilization row array from resource_status.summary. * Mirrors app.js `computed.utilizationRows`.

创建含一个卫星时间池条目的 ResourceManager。

多跳中继链路速率 (Mbps) - LEO→GEO1→GEO2→地面站。 计算三段链路的链路预算，取最小值作为端到端可达速率。 GEO1→GEO2 段改用激光 ISL 物理模型，含地球遮挡判定： 若两颗 GEO 之间视线被遮挡则该中继路径不可用（返回 0）。

升交点赤经 (RAAN) 因 J2 引起的长期进动速率 (rad/s)。 公式（一阶 J2 长期项）:: dΩ/dt = -(3/2) * n * J2 * (R_e/p)² * cos(i) 其中 p = a(1 - e²) 为半通径，n 为平均角速度。

(纬度°, 经度°, 高度 m) -> ECEF(km)。

按名称加载完整场景记录。

创建可复现引擎：固定 seed、禁用后台线程、重置请求 ID 计数器。

解析 3 行格式的 TLE 文本（名称行 + 第一行 + 第二行）。 支持： - 标准 3LE（每组三行） - 2LE（无名称行，每组两行，名称设为 catnr） - 自动跳过空行与注释行（# 开头） 返回 (name, line1, line2, epo

单跳中继链路速率 (Mbps)，由链路预算引擎驱动（含大气衰减）。 分别计算 LEO→GEO 上行与 GEO→地面站下行的链路预算， 取瓶颈（可达速率最小）链路的速率；GEO→地面站下行叠加大气衰减。

计算卫星相对于地面站的精确仰角、方位角与斜距。 基于 WGS-84 椭球将双方位置转换至 ECEF，再投影到地面站 ENU 拓扑坐标框架。 参数 ---- sat_lat, sat_lon : float 卫星大地纬度、经度（度）。 sat

* Transmission method → display string. * Mirrors the inline ternary in the request-list template (app.js).

从 JSON 字符串反序列化快照字典。 Raises ------ ValueError JSON 解析失败或根对象非 dict 时抛出。

获取统计数据（用于资源利用率API）

* Filter and sort requests: exclude background tasks, sort descending by id. * Mirrors app.js `computed.requests`.

评估请求是否可以被接受 - 基于实时资源利用率和时间段决策

* 构造链路 key，镜像 updateRequestLinks 中的 `${req.id}:sat-gs` 等格式。

根据调度结果构建 DecisionTrace 实例。 Args: req: TransmissionRequest 实例。 satellite_id: 当前卫星 ID。 sim_time: 仿真时间（秒）。 all_candi

对两个场景的决策指标进行对比，返回差值分析报告。 Parameters ---------- name_a: 场景 A 的名称（通常为基线）。 name_b: 场景 B 的名称（通常为待

将快照字典序列化为 JSON 字符串。

仅保留最近 max_events 条事件（内存与文件同步），控制存储增长。

更新地面站数量

计算卫星到目标点斜距 (km)，用于链路预算。 使用球面几何近似： d = √((alt_sat - alt_tgt)² + (R_E·sin(angle))²) Parameters ---------- sat_pos : dict

更新所有传输任务的进度 (包含动态链路切换逻辑)