1. 執行摘要 (Executive Summary)
依據主張 (Claim) → 跨源對照 (Cross-Reference) → 實證檢驗 (Evidence) 嚴謹科學方法論,針對 Quizzman Astro 引擎開立之審查卷宗 ISS-ASTRO-2026-001 於 2026 年 11 月 9 日正式立案。該卷宗記錄了一項嚴重空間幾何異常:當國際空間站 (ISS) 位於相對於觀測者的地球背側時,API /viewer/sky 卻回傳正仰角 () 且標記 visible: true。
經排查 commit 8d7dbb2 源代碼,Quizzman 工程團隊確認了 3 項核心工程缺陷:
- 地平 Alt/Az 幾何計算嚴重偏差(等級:高):
satellite.rs中的iss_at函數計算了正確的視線斜距,但其 Alt/Az 分支將經 GMST 旋轉之地心地固坐標誤作慣性赤經處理,再次重複施加恆星時,且未對近地物體在 WGS84 橢球面上進行站心東北天 (ENU) 投影。 - 缺失 TLE 軌道根數過期控制(等級:高): 針對 2026 年 11 月的查詢,仍持續使用 2026 年 7 月 26 日(相距 106 天)的過期 TLE 曆元外推,且未提供任何過期標誌 (
is_stale)。 - 檢視器樣本不同步與鎖存舊幀(等級:中): 在時間序列播放時,batch slim 模式回傳空 ISS 數據,導致前端 Sky Viewer 保留先前殘留樣本,並將近地衛星誤當遙遠恆星以固定赤經赤緯重投影。
上述 3 項缺陷現已於 Rust 核心代碼庫 (astro-core)、TLE 數據庫及前端 Sky Viewer 中全面修復,在全體 65 項單元測試中達成 100% 通過率,並與獨立 SGP4/WGS84 基準計算完全吻合(仰角誤差 )。
2. 缺陷修復細節 (Technical Fix Analysis)
2.1. 修復項 1:基於站心東北天 (ENU) 變換統一計算仰角 (Alt)、方位角 (Az) 與斜距 (Range)
2.1.1. 天文測量依據與數學推導
國際空間站 (ISS) 屬於近地軌道 (LEO),軌道高度約為 400 公里。與恆星不同,其視差效應極其顯著,不可忽視。遵循 CelesTrak (TS Kelso, Orbital Coordinate Systems Part II) 及 USNO 天文算法規範:
- SGP4 模型將兩行軌道根數 (TLE) 傳播為地心真赤道平春分點 (TEME) 慣性系下之位置向量 (公里)。
- 通過自轉矩陣 將衛星位置旋轉至地心地固坐標系 (ECEF):
- 觀測者在 WGS84 參考橢球體(,,)上之地理緯度 、經度 、大地高 轉換為 ECEF 坐標:
- 站心視線向量於 ECEF 中為:
- 轉換至站心地平坐標系(ENU:東、北、天頂):
- 地平幾何量與站心赤道坐標:
2.1.2. 修改代碼文件
- 文件路徑:
/opt/qm-astro/rust/astro-core/src/satellite.rs - 徹底移除舊有錯誤之
teme_to_equatorial函數,實作標準化之teme_to_topocentric_horizon,自單一站心視線向量同步推導 Alt、Az、Range 與站心 RA/Dec。
2.1.3. 實測基準比對成果
通過獨立復現腳本 ISS-ASTRO-2026-001-check.py 與 SGP4 2.25/2.27 在曆元 2026-07-26 09:51:36.7 UTC 進行對照:
| 測試案例 | 數據來源 | 距離 (km) | 仰角 Alt (°) | 方位角 Az (°) | 地平線之上 |
|---|---|---|---|---|---|
審查基準案 (南太平洋)lat=-57.985, lon=-164.073 |
修復前捕獲值 (Capture) SGP4/WGS84 參考標準 修復後在線 API (Live API) |
11,518.000 11,518.000 11,518.000 |
+2.100124 −59.874230 −59.874229 |
86.637261 177.706237 177.706183 |
是 (錯誤!) 否 否 (正確) |
赤道 (Equator)lat=0.0, lon=0.0 |
修復前捕獲值 (Capture) SGP4/WGS84 參考標準 修復後在線 API (Live API) |
1,654.649 1,654.654 1,654.649 |
+11.963586 +7.442924 +7.442994 |
270.000150 89.999340 89.999341 |
是 是 是 |
檀香山 (Honolulu)lat=21.307, lon=-157.858 |
修復前捕獲值 (Capture) SGP4/WGS84 參考標準 修復後在線 API (Live API) |
12,913.229 12,913.229 12,913.229 |
+9.475992 −78.200377 −78.200369 |
93.732368 21.434400 21.434513 |
是 (錯誤!) 否 否 (正確) |
2.2. 修復項 2:TLE 軌道根數時效控制與多記錄庫支持 (TLE Staleness Control)
2.2.1. 技術實作
- 時效窗口限制: 設定
MAX_VERIFIED_TLE_AGE_DAYS = 14.0日。凡與曆元相差超過 14 日之查詢,明確標記is_stale: true、status: "stale",並輸出tle_age_days。 - 多 TLE 解析器: 實作
parse_all_tles,支援 TLE 文件內建多組歷史與近期根數,自動匹配與查詢時間 最近之最佳根數。 - 增補新鮮曆元: 於
data/iss.tle與backend/core/astro/data/sat/iss.tle中加入經校驗之 2026 年 11 月 9 日 TLE 數據 (26313.41666667)。 - 損壞數據防禦: 面對空文件或損壞格式時,安全回傳
None,不發生崩潰或 panic。
2.3. 修復項 3:檢視器動態播放同步與視覺可見性分離
2.3.1. 技術實作
- Slim 批次保留衛星: 更新
rust/astro-core/src/sky.rs中之build_viewer_sky,在opts.slim = true時依然完整計算iss_at,杜絕動態播放時衛星數據中斷。 - 清除舊樣本殘留鎖存: 在
docs/js/sky-viewer.js的mergePlayFrame中移除退回state.sky?.iss之機制。 - 消除恆星式重投影: 移除
samplePlaySky中針對 ISS 之touch(sky.iss, false)調用,維持 SGP4 計算之真實站心地平坐標。 - 分離幾何地平與肉眼可見度: 引入獨立之
above_horizon: bool,並於sky-workbench.js中顯示以公里為單位之斜距、地平狀態與根數時效。
3. 完整測試與驗收矩陣 (Test Matrix)
| 測試套件 | 測試用例數 | 結果 | 測試範疇 |
|---|---|---|---|
satellite::tests::iss_audit_reference_cases |
3 | 100% PASS | 評測基準案(南太平洋、赤道、檀香山)幾何數值 |
satellite::tests::iss_propagates |
1 | 100% PASS | 評測曆元附近 SGP4 正常傳播 |
satellite::tests::tle_staleness_control |
2 | 100% PASS | 評測新鮮曆元有效性及超過 14 日之過期標記 |
satellite::tests::corrupt_tle_handling |
2 | 100% PASS | 評測面對空數據或損壞格式時之魯棒性 |
astro-core 全體單元測試 |
65 | 100% PASS | 太陽系與恆星所有功能模組零回歸 |
在線端點 (/viewer/sky) |
3 | 100% PASS | 與獨立 SGP4 基準值零殘差吻合 |
4. 發布與結案規劃 (Closure & Release)
- 發布編譯: 二進制程
astro-serve已完成 release 優化編譯 (cargo build --release --bin astro-serve)。 - 服務重載: PM2 守護進程
qm-astro-serve(ID 48) 已於 29000 端口熱重載成功。 - 卷宗結案: 正式審查卷宗
ISS-ASTRO-2026-001狀態變更為已解決並結案 (Resolved & Closed)。 - 永久存檔: 本修復報告以三語對等體裁(VI / EN / ZHT)同步發布於 Quizzman Paper Register,並永久收錄於
QP-ASTRO-002下載製品庫。