座標幾何：距離與地理圍欄語意

先看座標欄位：兩個運算元的 system、有序軸與 length-unit selector 必須相容。API 邊界的分量是精確小數字串，核心內則是正規化的 Decimal。不會自動做笛卡兒／地理或單位換算。

距離度量

笛卡兒權重必須非負，未指定軸預設為一，也可為零。Euclidean／squared 乘的是差值平方，Manhattan／Chebyshev 乘的是絕對差值。未知軸的權重或地理距離的權重會被拒絕。平方距離與一般半徑不同維度，不要把 squared 直接代入公尺半徑政策。

地理距離以公尺計算，預設忽略海拔。函式庫明訂的 include_altitude 選項用地表距離與海拔差計算斜距，要求兩點都有 alt 軸。這個函式庫選項不代表所有公開 operator 都接受。

決定性與顯示 scale

函式庫只用標準庫 Decimal，採私有固定 context：笛卡兒累加 192 位，地理／開根號運算 50 位。不依賴呼叫者 decimal context、二進位浮點數、平台 math 實作或第三方測地線套件。

• 地理距離輸出預設三位小數（毫米）。
• 笛卡兒輸出預設為正規化運算元中最大的分量 scale。
• 明訂且受支援的輸出 scale 為整數 0–18，預設 rounding 是 half_even。
• 距離運算元為 null 時，在驗證選項後傳遞 null 結果。
• 地理初始方位角以度表示，範圍 [0, 360)、六位小數；重合點方位角為零。

決定性的四捨五入輸出不表示物理測量精準到毫米。Geolocation accuracy 是另一份證據。

含邊界判斷使用未四捨五入距離

Predicate 比較內部未四捨五入的距離與半徑，包含邊界：

忽略精度：unrounded_distance <= radius
嚴格精度：unrounded_distance + reported_accuracy_m <= radius

strict 要求精度值，不會悄悄退回忽略精度。Null 點不在圍欄內；非法選項或格式錯誤的 origin 仍會驗證失敗，不會變成成功的 null 結果。顯示 rounding 不能把外部點變成內部：顯示 "100.000" 的距離在 rounding 前仍可能大於 "100" 半徑。

within_any 最多評估 50 個 origin，每個有自己的半徑。它選最近的合格 origin，未四捨五入距離相等時依 origin ID 字典序決勝。較近但半徑較小而失敗的 origin，不會排擠較遠但合格的 origin。未匹配時沒有選定 origin 或距離，不構成「最近被拒絕據點」的曝光契約。

in_box 檢查含邊界的軸向 box，下界不能大於上界。經度不會隱式跨界：跨越國際換日線的 box 不能靠顛倒經度 min／max 表示。

擷取品質與權限是不同 gates

距離本身不會授權打卡。使用它的規則也要檢查伺服器來源標記、回報精度、擷取時間與員工可用的 origin。另行核對原始碼的運算子及出勤準備稿說明這些 binding 與待驗收／可攜性邊界。

精確位置是個資。請使用一般欄位可見性，由管理員控制員工據點指派，不要透過錯誤文字或推導輸出洩露隱藏 origin、位置值或最近被拒絕據點。隱藏一個座標欄不代表所有推導距離或選定據點都可安全公開；那些欄位要獨立授權。

索引 cell 只是候選，不是幾何答案

函式庫提供地理線性經緯度 quadkey，不是 Web Mercator tile，level 為 0–24。笛卡兒索引 cell 需要明訂有效界線，最多三維。Cover 採保守包含且有上限；超過 cell cap 會拒絕，不會悄悄回傳截斷 cover。候選紀錄仍要做精確 predicate。

自 backend 5.21.0 起，伺服器把這些 cell 存入座標查詢使用的持久化索引（未宣告 bounds 的 Cartesian 欄，由軸的 precision 與 scale 推得範圍；只儲存偶數層級 0、2、… 24）；cell 仍只是候選篩選，仍由精確 predicate 決定。不能由 cell helper 推定讀取權限、完整 query coverage 或部署。

幾何錯誤

公開 wrapper 可能轉成各介面自己的錯誤格式，不要假定函式庫例外全都對應同一 HTTP status。