手上有統編、發票號或半個名字，都查得到同一個客戶

週二上午，一句「訂閱還在嗎」查了十幾分鐘

情境改寫：依這類查詢常見的狀況整理，細節為示意。

週二上午，群組裡有人問：「這家客戶的訂閱還在嗎？」問的人手上只有一個記得一半的客戶名稱。先打開計費系統後台，用名稱搜尋，沒有結果，因為後台的公司名稱欄只能從開頭比對，而他記錯了前半。接著改用發票號碼試，對不上。最後只能換到別的畫面一個一個比，前後大約十幾分鐘，大半時間花在切換畫面。

這一次還查得到。下一次換一個人、換一種線索，還是得從頭來。

人工查，為什麼總卡在同一個地方？

計費系統認人的方式只有它自己給的客戶 ID。同事手上通常是四種線索：招牌上的名字、合約上的營業登記名稱、統一編號、發票號碼。系統對這四種的支援程度不一樣。vat_number（統一編號欄位）完全不能用來篩選；公司名稱只支援 starts_with（只能比對開頭），只記得一半的名稱查出來是空的；登記名稱在資料模型裡沒有對應的欄位。

不能要求同事先學會系統的 ID 規則，所以缺的那幾個維度只能從外面補。人工查慢還是其次，更麻煩的是每種線索都要換一個入口，每換一次就要重新判斷這條線索屬於哪一種。

六個入口，各自接到同一個客戶 ID

六種線索各自接到計費系統的客戶 ID 上。有的能直接問系統，有的得先經過本地對照表。

← 左右滑動看完整的圖，點圖可放大

圖：六種線索經過的入口不同，最後都停在同一個客戶總覽。

對照表要怎麼讀，表變長後才不會壞？

對照表的欄位是 branch ID | 統編 | 客戶名稱 | 營業登記名稱，前四個查詢角度都靠它把線索解析回分支 ID。

讀表有兩種做法：整張載入記憶體一次比對，或逐行搜尋。這裡選逐行搜尋。Apps Script 的 CacheService 單一值上限是 100KB，表一長，整張載入很容易撐爆快取。逐行搜尋慢一些，但表變長後不會突然失效。

分支 ID 寫法不一，容錯要放在哪一層？

同一個分支，同事貼進來的寫法可能是 -AbC123、AbC123，或標準的 B-AbC123。計費系統慣用的是 B-AbC123。程式認得這些寫法，收斂回標準形，同事就不必為了格式去改寫。下面是簡化過的示意寫法：

function normalizeBranchId(input) {
const id = input.trim().replace(/^-+/, '');  // 去掉多打的減號
return id.startsWith('B-') ? id : 'B-' + id; // 補上 B- 前綴
}
// normalizeBranchId('-AbC123')  -> 'B-AbC123'
// normalizeBranchId('AbC123')   -> 'B-AbC123'
// normalizeBranchId('B-AbC123') -> 'B-AbC123'

轉換完成後，BillingClient.fetchAll() 會同時發出客戶基本資料、訂閱、發票三個 GET 請求，三個一起等，不必等客戶資料回來才發下一個。事件時間線（/events）沒有放進這一批，因為它的 content_snapshot 欄位很肥，常常失敗。如果把它放進同一批，一個 events 失敗就會連累整個總覽，所以它獨立取得，失敗時只影響時間線那一區。

快取多久，重試幾次？

TTL（快取的有效秒數，過了就重新向系統拿）依資料變動速度分兩級。所有快取 key 都帶固定前綴，不同查詢條件換不同 key，結果不會互相污染。搜尋與客戶總覽變動快，設 300 秒；發票對應、明細與 VAT／統一發票索引變動慢，設 1800 秒。

重試的分界線是錯誤碼。網路失敗、429、5xx 做三層重試，延遲依序是 5、10、15 秒。4xx（429 除外）立刻拋錯。示意如下：

const RETRY_DELAYS = [5, 10, 15];           // 秒，最多三層
function shouldRetry(status) {
if (status === 429 || status >= 500) return true; // 對方忙，過幾秒再送可能成功
return false;                                    // 4xx：我方送錯，重送一樣錯
}

誰查得到，出錯時誰先知道？

前端用一個 DOM 工廠函式建立節點，所有文字都用 textContent 寫入，所以計費系統回傳的資料不會被當成 HTML 插進頁面，也就沒有 XSS（惡意程式碼注入）的入口。

網頁入口有網域閘，只放行公司網域的帳號，其餘回傳 403。每個 API 入口再經過 assertAuthorized_() 檢查，並包進共用 Apps Script 函式庫的 tryRun()。出錯時，錯誤會自動送進 Slack，所以頁面出狀況時，維護者會先收到通知，不必等同事來反映。

查不到的客戶，要從哪裡找？

代價也要說清楚：客戶名稱、營業登記名稱、統一編號與統一發票號四個角度，完整度就等於對照表的完整度。沒有被加進對照表的客戶，從這四個角度查不到，只能改用發票號或分支 ID。發票號與分支 ID 不依賴對照表，所以這兩條路永遠可用。

查詢省下多少時間沒有量測，目前是尚未實測。能確定的是同一個問題不再需要轉手：以前同事問不到就要去問維護者，現在多數情況自己就查完了。