Firescope 使用手冊

安裝

1. 從下載頁面取得 Mac 版的.dmg(可選擇 Apple Silicon / Intel)。
2. 開啟下載的 .dmg,將 Firescope 圖示拖曳到「應用程式」資料夾。
3. 從應用程式資料夾啟動 Firescope。

Windows

1. 從下載頁面取得 Firescope-Setup.exe並執行。
2. 首次執行若出現 SmartScreen 警告,請點選「其他資訊」→「仍要執行」繼續。

初始設定(語言與主題)

首次啟動時,會開啟 4 個步驟的設定畫面。首先選擇顯示語言(內建日文・English・简体中文・繁體中文・한국어・Español・Português・Français・Deutsch 共 9 種語言)。點選後畫面會立即套用,猶豫的話按按看就知道了。

接著選擇外觀主題。包含 Light / Dark 在內共 10 種,同樣點選後就能即時預覽。

連接 Firestore

連線需要 Firebase 的服務帳戶私密金鑰(JSON)。就算目前沒有,按照畫面指示操作,大約 1 分鐘就能取得。

1. 點選「開啟服務帳戶設定頁面」,會在瀏覽器開啟 Firebase 主控台的對應頁面(位置:專案設定 → 服務帳戶)。
2. 點選「產生新的私密金鑰」下載 JSON 檔。
3. 回到 Firescope,從「選擇 JSON 檔案並連線」選取剛下載的 JSON。也可以一次選取多個專案的 JSON同時連線。
4. 選擇連線的環境(開發 / 測試 / 預備 / 正式)。 會以彩色標籤顯示在側邊欄,安全防護的強度也由此標籤決定。

瀏覽資料

開啟側邊欄的連線並點擊集合,文件就會以表格顯示。每個欄位的標題都會附上型別標籤(string / int / time 等),資料的結構一看就懂。

• 點擊列,右側面板會顯示文件的所有欄位。
• 排序、顯示筆數、群組搜尋(集合群組)都可以在工具列變更。
• 讀取筆數會持續顯示在狀態列(可作為計費的參考)。

邏輯名稱(欄位名稱翻譯顯示)

可以將像 carryingOutCoffinMasterId 這樣的英文欄位名稱,改以中文等邏輯名稱顯示。透過工具列的「邏輯名稱」切換開關,隨時都能切換實際名稱⇔邏輯名稱。

• 辭典可從工具列的 📖 圖示編輯。適用範圍分為「整個連線共用」與「僅此集合(覆寫)」兩層。
• 透過「自動翻譯」,可利用內建辭典 + 免費翻譯 API 一次填入空白欄位。
• 點選「開啟 Google 翻譯」,會以英文化的欄位名稱開啟翻譯頁面,只要複製譯文回到應用程式,就能一次套用。
• 在欄標題按右鍵 →「設定邏輯名稱…」,即可立即編輯該欄位。
• 標題的型別標籤(string / int 等)可透過「顯示型別」切換開關來顯示/隱藏。

分頁與群組

在集合上按右鍵 →「在新分頁中開啟」,就能像瀏覽器一樣新增分頁。分頁可以像 Chrome 一樣整理成群組。

• 在分頁上按右鍵 →「加入新群組」建立群組,可以設定名稱與顏色。
• 點擊群組標籤即可摺疊/展開。
• 雙擊分頁即可變更名稱與背景顏色。
• 拖放即可重新排序,或加入/移出群組。
• 重新啟動後仍會還原分頁狀態(可在設定中關閉)。

分割檢視

在集合上按右鍵 →「在右側分割顯示」,即可將兩個集合左右並排。方便用來核對主檔與交易紀錄。

• 也可以從側邊欄將集合拖曳到畫面左右邊緣來分割顯示。
• 拖曳窗格的標籤,即可左右交換或取出成新分頁。
• 分割狀態會依分頁各自保留。

即時監看

點選工具列的「監看」,目前顯示集合的變更就會即時反映到表格中。即使是其他應用程式或伺服器寫入的內容,也不需重新整理就能直接顯示。

• 開始前的對話框中,可以依條件(欄位・數值)、排序、筆數縮小範圍。
• 右側的變更動態會依時間順序列出「新增 / 更新 / 刪除」,也會顯示變更的欄位名稱。
• 監看本身是唯讀的。監看期間的寫入操作,一樣會照常經過安全管線。
• 最多可同時監看 5 個項目。
• 經過指定時間後會自動停止(可在設定中變更時間),避免過度耗用讀取次數。

編輯資料

雙擊儲存格即可就地編輯。Enter 確認,Esc 取消。 int、timestamp 等型別會在寫入時保持不變。

所有寫入都會經過安全管線:

1. 確認 — 會依環境標籤 × 操作危險度顯示對話框。正式環境的破壞性操作,需要輸入專案 ID。
2. 自動備份 — 受影響的文件會在執行前建立快照。
3. 執行 — 進行寫入。
4. 操作紀錄 — 無論成功或失敗都會被記錄(可在底部列的「操作紀錄」查看)。

備份與還原

在破壞性操作前建立的快照,會累積在底部列的「備份」中。點選後會開啟還原預覽,確認重新建立 / 覆寫 / 無變更的差異後再進行還原。

• 使用 ⌘Z(或側邊欄的 ↩︎ 圖示)可以立即還原最近一次寫入。
• 快照數量超過上限後,會從最舊的開始刪除。想保留的可以釘選 📌。

主控台

側邊欄的「主控台」可以用 firebase-admin 風格的 JavaScript 撰寫查詢。按下 ⌘Enter 執行後,結果會以標註型別的表格顯示。

const snap = await db.collection('orders')
  .where('status', '==', 'paid')
  .orderBy('amount', 'desc')
  .limit(20)
  .get();
return snap.docs.map((d) => ({ id: d.id, ...d.data() }));

• 偏好用滑鼠操作的話,也有視覺化建構工具(取得 / 更新 / 新增 / 刪除)。組好的條件可透過「反映到程式碼」轉換成 JS。
• 包含寫入的程式碼,會依試跑 → 寫入預覽 → 套用的順序執行,資料不會突然被改變。
• 也支援 join(關聯)顯示。

CSV 匯入匯出

匯出

在集合工具列點選「CSV 匯出」,即可將目前顯示的查詢結果(已套用篩選與排序)儲存為 CSV。標題列會附上型別標註,之後重新匯入也不會破壞型別。

匯入

1. 點選工具列的「匯入」→ 選擇 CSV 檔案(可自動判別 Shift_JIS 編碼)。
2. 確認每欄的型別,以及模式(upsert / 僅新增 / 僅更新)。
3. 點選「確認筆數」預覽新增與覆寫的筆數。
4. 點選「執行匯入」→ 經過確認對話框後完成匯入。將被覆寫的部分,會在執行前自動備份。

結構檢查(偵測結構異常)

在集合上按右鍵 →「結構檢查…」,即可讀取整個集合,自動偵測型別混雜的欄位、僅部分文件缺少的欄位,以及可能是打字錯誤的罕見欄位(上限 20,000 筆)。

• 同一批文件中共同缺少的欄位,會彙整成一張卡片。點選「全部開啟」即可勾選所有相關列,直接進行批次刪除等操作。
• 點擊對應文件的 ID,表格會自動捲動到該列並反白顯示。
• 即使關閉精靈,結果也會被保留,可以一邊確認文件一邊反覆來回查看。
• 在Zod 結構驗證分頁中,可以貼上 Zod 結構(TypeScript)來驗證所有文件。

環境比較與複製

與其他環境比較

在集合上按右鍵 →「與其他環境比較…」,即可核對兩個環境中同名的集合(例如開發與正式)。差異(新增 / 刪除 / 變更)會以文件與欄位為單位列出。

• 可以指定像 updatedAt 這類要從比較中排除的欄位。
• 差異內容可以匯出為 CSV。

複製到其他環境

透過「複製到其他環境…」,可以將集合複製到另一個連線(環境)。執行前會預覽筆數與是否覆寫,寫入正式環境時,一樣會經過嚴格的確認防護。

Authentication 使用者

從側邊欄的「Authentication」,可以列出並管理 Firebase Authentication 的使用者。

• 以列表顯示電子郵件、顯示名稱、提供者、建立日期、最後登入時間。透過邏輯名稱切換開關,也能以中文顯示欄位名稱。
• 支援使用者的停用 / 啟用、刪除,以及發送重設密碼的電子郵件。
• 可以複製使用者的 UID,用來與 Firestore 端的文件核對。
• 破壞性操作(如刪除)會經過與 Firestore 相同的安全管線(確認 → 操作紀錄)。

更新

• 更新會每 6 小時 + 每次啟動時自動檢查(也可以在「設定 → 關於」的「檢查更新」手動確認)。
• 若釋出必要更新,啟動時的更新畫面會自動下載 → 重新啟動 → 套用,全程無需按任何按鈕。
• 只有在失敗時(例如離線),才會引導您透過瀏覽器手動下載。

價格與授權

• 從首次啟動起 14 天為試用期,可使用所有功能。免註冊、免付款資訊。
• 即使試用期結束,資料的瀏覽功能仍可繼續免費使用。
• 購買可在應用程式內完成:於右下角的 ⚙ 設定 → 授權選擇方案(Pro / TEAM,月繳 / 年繳),即會在瀏覽器開啟 Stripe 的付款頁面。付款完成後,應用程式會自動啟用授權。
• 更換到另一台 Mac 時,請先在舊機器上「解除授權」,再於新機器上啟用。

方案的詳細內容,請參閱價格頁面。

常見問題

無法連線 / 出現「驗證失敗」

請確認 JSON 是否為目標專案的服務帳戶金鑰。若重新產生過金鑰,建議先中斷舊的連線,再用新的 JSON 重新連線,較為保險。

資料會被傳送到其他地方嗎?

不會。Firescope 會從您的 Mac 直接存取 Firestore 。金鑰與資料都不會傳送到外部伺服器。

「正式環境防護」是做什麼的?

這是依連線的環境標籤與操作危險度,自動調整確認強度的機制。例如在正式環境刪除集合時,若不手動輸入專案ID 就無法執行。由於驗證是在應用程式的核心(主行程)進行,而不是 UI 上的提醒文字,因此不會因為一時疏忽而被繞過。

有 Windows 版嗎?

有的。請從下載頁面取得Firescope-Setup.exe(若出現 SmartScreen 警告,請點選「其他資訊」→「仍要執行」繼續)。

可以新增語言嗎?

可以。從設定 → 語言匯出語言包(JSON)進行翻譯,再匯入即可新增任意語言。