Gemini CLI 專案協作筆記：從 Web App 到極簡自動化的開發歷程

總覽

本專案的初始目標是建立一個具備篩選功能的使用者介面，以自動化處理貓咪住宿文件。在開發過程中，我們遭遇了數個與 Google Apps Script 環境相關的挑戰，最終透過簡化架構和採用更穩健的技術決策，成功達成目標。

第一階段：不可行方案與經驗教訓

我們首先嘗試了建立一個功能豐富的前端介面，但最終證明此路不通。（如圖一、二）

方案：獨立 Web App / 側邊欄 (Client-side UI)

嘗試過程：
1. 建立 Web App：最初構想是建立一個獨立的網頁應用程式(doGet)，提供篩選欄位和操作按鈕。（如圖三）
2. 遭遇神秘錯誤：即使提供了語法正確的現代 JavaScript (ES6+)程式碼，在執行時依然反覆出現 SyntaxError (語法錯誤)，例如Unexpected token。
3. 偵錯與降級：為了排除問題，我們將後端 Code.gs 的程式碼全部降級為相容性更強的舊版 ES5 語法。
4. 遭遇前端腳本失效：即便後端語法降級，前端網頁的按鈕依然完全沒有反應。進一步偵錯發現，無論是寫在 HTML 中的 onclick屬性，還是使用標準的 addEventListener 事件綁定，前端的 JavaScript 腳本都完全沒有被執行。（如圖四）
根本原因：

Google Apps Script 的 HtmlService 沙箱環境非常特殊且存在諸多限制。標準的網頁開發實踐（如 DOMContentLoaded 事件）可能無法運作，且 Client-side JavaScript 的執行容易受到使用者的 Google 帳號安全設定、瀏覽器版本、擴充功能等我們無法直接控制的因素干擾。
教訓：

對於 Google Apps Script 專案，其核心優勢在於與 Google 服務的後端整合。任何複雜的前端 UI 都會引入巨大的不確定性。應優先考慮純後端 (Server-side)執行，只有在絕對必要時才引入前端 UI，並要為其不穩定性做好準備。（如圖五）

第二階段：最終可行方案與設計決策

在放棄了複雜的前端 UI 後，我們回歸到最原始、最穩定的架構，並解決了資料處理中的核心難題。

方案：純後端 + 自訂選單 (Server-side Only)

設計理念：
1. 放棄所有不穩定的前端介面（Web App、側邊欄、HTML）。
2. 將所有邏輯都放在 Code.gs 中。
3. 僅透過在試算表頂端建立的自訂選單 (onOpen 函式)來觸發後端函式。
4. 這是最穩定、最可靠、最容易維護的架構。
關鍵的技術決策：
1. 語法選擇 (Syntax Choice): 由於使用現代 JavaScript (ES6+) 在該專案環境中反覆出現無法解釋的語法錯誤，最終決定全部採用舊版 ES5語法，以換取最高的相容性與穩定性。
2. 資料去重邏輯的演進 (Evolution of Deduplication Logic):
  - 目標：integrateData 函式在多次執行時，只新增真正的「新」資料，而不是重複附加。
  - 失敗的嘗試: 最初嘗試在執行時比對「來源日期」和「已存入的日期」。但因 Google 試算表會自動將「日期文字」轉換為「日期物件」，兩者在格式和精度上的微小差異導致比對永遠失敗。
  - 成功的方案：寫入「唯一識別碼」(EntryKey)
    - 在 IntegratedData 工作表中新增 EntryKey 欄位。
    - 第一次處理資料時，根據其內容產生一個標準化的字串Key（格式為手機_貓名_YYYY-MM-DD）並存入此欄。
    - 後續執行時，直接進行「字串對比字串」，徹底避免了所有資料格式轉換的問題。這是解決此類重複資料問題最專業、最可靠的方法。（如圖六、七）
3. 程式碼結構優化 (Code Structure Optimization): 為了解決因平台顯示長字串時自動換行，而導致使用者複製貼上程式碼出錯的問題，最終版本將indexOf(‘一個很長的欄位名稱’) 的寫法，全部重構為在迴圈外預先定義好所有欄位的索引變數（如 var ownerNameCol=headers.indexOf(…)）。這讓程式碼更乾淨、效率更高，也杜絕了格式問題。（如圖八）