前言
今天要把「一定要有、不能為空、長甚麼樣」寫成一份清單，之後不管誰都可以照這張表檢查，確保三支 API 的資料都能穩定顯示而且好看。
一、三支 API 的「一定要有」欄位
1. /bus/routes（路線清單，固定）
• 不可為空：routeId、routeName.zh、updateTime（ISO 8601＋時區）
• 可選：routeName.en、hasWheelchair
• 不接受：routeId 為 null、routeName 為空物件、updateTime 沒時區
2. /bus/stops（站點清單，固定）
• 不可為空：routeId、direction（0/1）、stops 陣列、stops[].stopId、stops[].stopName.zh、stops[].sequence、updateTime
• 可選：stopName.en、lat／lon（若來源沒有就先不強制）
• 不接受：stops 為 null、stops 為空陣列但沒說明、direction 為 3 或 -1、sequence 為 0
3. /bus/eta（到站預估，即時）
• 不可為空：routeId、stopId、updateTime
• estimateSeconds 與 stopStatus 至少要有一個（查不到時間就用狀態字說明）
• 不接受：estimateSeconds 為 -1、estimateSeconds 為 null 且沒有 stopStatus、stopStatus 不在 normal/last/suspended/noData 之內、updateTime 沒時區
二、單位與範圍的規範
• 1. 時間（updateTime）：必須是 ISO 8601，例 2025-10-30T08:29:00+08:00，要含時區。
• 2. 倒數（estimateSeconds）：單位為「秒」，0～3600 之間為主，不接受負數、小數、字串秒數。
• 3. 座標（lat／lon）：型別為 number，台北約 lat 24～26、lon 120～122，超出可視為異常。
• 4. 方向（direction）：只能是 0（去程）、1（返程），不接受 "0"、"1"、2、-1。
三、欄位不可為空清單
• /bus/routes：routeId、routeName.zh、updateTime
• /bus/stops：routeId、direction、stops[]、stops[].stopId、stops[].stopName.zh、stops[].sequence、updateTime
• /bus/eta：routeId、stopId、updateTime，另外在 estimateSeconds 跟 stopStatus 至少要有一個
• 固定寫法：時間一律用 updateTime、倒數一律用 estimateSeconds、狀態一律用 stopStatus
四、收到壞資料時要怎麼辦
• 缺 estimateSeconds 但有 stopStatus → 顯示「暫無到站資訊」，並標「更新於 HH:MM」。
• estimateSeconds 超出合理值 → 顯示「時間僅供參考」。
• updateTime 太舊 → 顯示「資料稍舊」。
• 必填欄位整筆沒回 → 顯示「暫無更新，稍後再試」，並記錄 log。