轉角遇到Ubike

歡迎使用 轉角遇到Ubike！這是一個專為尋找 YouBike 2.0 站點設計的網頁應用程式，結合了即時地圖、自動定位與清楚的列表顯示。

此專案採用「前後端分離」與「中繼代理 (Proxy)」架構，讓任何人都能安全地使用自己的 TDX API 密鑰來查詢即時車輛資訊。

快速入門：網頁端功能操作

1. 📍 自動定位：
   開啟網頁時，系統會自動詢問 GPS 權限，請選擇「允許」。定位成功後，地圖會自動縮放到您目前的位置，並顯示附近的 YouBike 站點。
2. 🚴 站點資訊：
   • 地圖上的 數字圓圈 代表該站點目前的「可借車輛數」。若數量為 0 則會以灰色顯示。
   • 下方 (手機板) 或 右側 (電腦版) 的列表會列出最近的 20 個站點。
   • 每個卡片會顯示：距離、可借數量、電輔車/一般車數量、可停空位數量，以及 資料更新時間。
   • 地圖連動：點擊地圖上的站點圖示，右側列表會自動捲動並高亮對應卡片，同時在地圖上展開詳細的站點資訊。
3. 🔄 自動更新與跟隨：
   • 系統預設每 3 分鐘 (180 秒) 會自動重新抓取最新資料，以節省 TDX 基礎會員的 API 額度（限制為 5 次/分/金鑰）。若您需要即時資訊，可隨時點選右上角的「重整」按鈕手動更新。
   • 如果在自動更新時，您沒有正在操作地圖（搜尋其他區域），地圖會 自動飛回 您的最新 GPS 位置，確保導航不迷路。
4. 🔍 搜尋此區域：
   如果您手動拖曳地圖查看別處，畫面上方會出現「搜尋此區域」按鈕。點擊後，系統會鎖定該區域進行搜尋，暫時停止自動跟隨 GPS 的功能，方便您查詢異地站點。

系統架構與 API 密鑰說明

為了確保系統的穩定性與安全性，本程式需要您輸入從「交通部運輸資料流通服務 (TDX)」申請的 API 密鑰。

📝 如何申請 TDX API 密鑰？

申請過程完全免費，只需幾個簡單的步驟：

1. 前往 TDX 官網：打開 交通部運輸資料流通服務 (TDX) 網站。
2. 註冊/登入會員：點擊右上角的「登入/註冊」，可以使用 Google 等第三方帳號快速登入。
3. 進入會員中心：登入後，點擊右上角您的帳號名稱，選擇「會員中心」。
4. 建立金鑰：在左側選單選擇「資料服務」 -> 「API 金鑰」，然後點擊「新增應用程式」。
5. 取得密鑰：隨意填寫應用程式名稱與說明後送出。接著您就會在畫面上看到專屬於您的 Client ID 與 Client Secret。將這兩串字元複製起來，填入本網頁的設定視窗即可！

🔑 金鑰存在哪裡？

使用者輸入的 Client ID 和 Client Secret，是透過 JavaScript 的 localStorage 技術儲存在使用者自己的電腦/手機的瀏覽器中。這意味著：

• 這些資訊不會上傳或儲存到開發者的伺服器，也不會保存在 Google 的資料庫裡。
• 下次使用者用同一台裝置、同一個瀏覽器打開這個網頁時，瀏覽器會自動把金鑰填回去，不用重新輸入。
• 如果清除瀏覽器快取，或者換一台手機/電腦，就需要重新輸入。

🛡️ GAS 的角色是什麼？

系統後端使用 Google Apps Script (GAS) 扮演一個「中繼代理伺服器 (Proxy)」的角色。它的運作流程非常單純：

1. 接收：前端網頁把「使用者的金鑰」和「座標」打包，透過安全的 POST 請求傳給 GAS。
2. 溝通：GAS 拿著這組金鑰，轉身去向 TDX 敲門要 Token。拿到 Token 後，再向 TDX 請求附近的 UBIKE 站點和車輛資料。
3. 回傳：GAS 把 TDX 給的龐大資料整理乾淨後，原封不動地傳回給前端網頁顯示。

隱藏密技：將網頁變成手機 APP

本專案已經過 PWA (漸進式網頁應用) 優化，您可以透過手機瀏覽器將網址 (https://begin0808.github.io/ubike/) 加入主畫面，之後點擊桌面圖示就能像原生 APP 一樣享受「全螢幕」的使用體驗！

常見問題與安全須知 (Q&A)