# Hermes Gateway Resilience Pack

這一包文件的目的不是寫漂亮說明，而是把 **容易因更新 / 重啟 / refactor 再次壞掉的 gateway 行為** 固化成可核對、可驗收、可快速修復的契約。

## 文件地圖

1. `gateway-functional-contract.md`
   - 功能清單 / 行為契約
   - 說明哪些行為必須成立，否則視為回歸

2. `gateway-state-and-sequence.md`
   - 順序清單 / 狀態機 / Mermaid 流程圖
   - 說明綁定、長任務、LINE quota fallback、email 檔案交付的實際流向

3. `gateway-regression-matrix.md`
   - 功能 → 模組 → 測試對應矩陣
   - 方便更新後快速核對 coverage 與 smoke 順序

4. `gateway-recovery-playbook.md`
   - 異常時的定位與修復路徑
   - 先看哪個模組、哪個 log、先跑哪些測試

5. `gateway-governance-admin-platform.md`
   - 額度、權限、principal 治理與目前管理平台能力盤點
   - 說明哪些是已有後端能力、哪些已被測試、哪些仍缺 UI/整合驗收

6. `gateway-change-impact-checklist.md`
   - 變更影響檢查表：改到哪個模組，就必跑哪些測試與 smoke
   - 用在 update / merge / restart / refactor 前後，避免遺漏關鍵驗收

7. `gateway-admin-ui-api-matrix.md`
   - 管理平台 UI / API 對照盤點
   - 明確區分哪些功能已有 dashboard UI、哪些目前仍是後端-only API

8. `gateway-update-restart-sop.md`
   - 固定更新 / 重啟後驗收 SOP
   - 把快速健康檢查、分層測試、核心 smoke、治理後台檢查串成固定順序

9. `gateway-post-update-validation-order.md`
   - 更新後固定驗收操作順序單
   - 用 1 → 2 → 3 → 4 的順序把健康檢查、最小測試集、固定 smoke、回報格式排好

10. `gateway-validation-template.md`
   - 可直接複製的 markdown 驗收模板
   - 每次 update / restart / merge 後填 PASS/FAIL/PARTIAL，不再自由發揮

11. `gateway-validation-template-full.md`
    - 完整版驗收模板
    - 適合內部工程驗收、保留詳細記錄

12. `gateway-validation-template-compact.md`
    - 精簡版驗收模板
    - 適合 Telegram / LINE / email 快速回報

13. `examples-principal-profile-routing-validation-full.md`
    - 這次 `principal_profile_routing` 修復的完整版驗收範例
    - 示範怎麼把真實測試結果填進模板

14. `examples-principal-profile-routing-validation-compact.md`
    - 同一案例的精簡回報範例
    - 可直接仿照格式貼回 Telegram / LINE / email

15. `gateway-team-usage-policy.md`
    - 團隊使用守則 / 執行政策
    - 把 impact 判斷、驗收、回報制度化，避免文件存在但沒人照做

16. `gateway-entrypoint.md`
    - 首頁索引 / 單頁入口
    - 不知道先看哪份時，先看這頁就能導到正確文件

17. `gateway-team-announcement.md`
    - 可直接貼給團隊的公告文
    - 正式宣布這套規格包啟用，並說明最短使用方式

## 使用方式

### 更新前
- 先看 `gateway-functional-contract.md`
- 確認這次變更是否碰到：
  - principal / verified email 綁定
  - 長任務 heartbeat / pending
  - LINE quota fallback
  - email 附件 / 下載連結 / managed downloads
  - shared drive 查找 / 展開 / 選檔 / 打包 workflow
  - quota / model policy / dashboard role / admin audit

### 更新後
- 先跑 `gateway-regression-matrix.md` 裡列出的最小測試集
- 再做 `gateway-recovery-playbook.md` 的 smoke checklist
- 若這次有實際改 code，務必再勾 `gateway-change-impact-checklist.md`
- 若要整體照表操課，直接跑 `gateway-update-restart-sop.md`
- 若要最省腦、照 `1 → 2 → 3 → 4` 固定跑，直接看 `gateway-post-update-validation-order.md`
- 若要留正式驗收紀錄，直接複製 `gateway-validation-template.md`
- 若要分長短兩版使用：內部用 `gateway-validation-template-full.md`，對外回報用 `gateway-validation-template-compact.md`
- 若要看真實填寫示例，先看 `examples-principal-profile-routing-validation-full.md` 與 `examples-principal-profile-routing-validation-compact.md`
- 若要把這套真正落地成團隊規範，直接看 `gateway-team-usage-policy.md`
- 若只想要一頁式入口，不想先記整包檔名，直接看 `gateway-entrypoint.md`
- 若要直接發公告給團隊，貼 `gateway-team-announcement.md`

### 出錯時
- 先用 `gateway-state-and-sequence.md` 找出壞的是哪一段流程
- 再用 `gateway-recovery-playbook.md` 對照模組與 log
- 若問題涉及治理後台，先看 `gateway-admin-ui-api-matrix.md`，不要把 Pairing / Channels / System 頁面誤當成完整 governance console

## 範圍

這一版先聚焦目前最常回歸、且已實際修補過的四條主線：

1. Telegram / LINE / OpenWebUI / email 與 principal / verified email 綁定
2. LINE 長任務與 pending / postback / heartbeat
3. LINE 額度不足時的 email fallback
4. Email 檔案交付：附件、副檔名、大小限制、正式網域下載連結
5. Shared drive 對話式下載流程：候選查找、資料夾展開、最多 10 檔選取、敏感檔加密與 24h 連結

另外已補入第 6 條主線：

6. 額度與權限治理、以及目前管理平台（governance/admin surface）實際可做的事情

## 注意

- 本包以目前 repo 內實作為準，對應檔案見各文件「實際程式碼再確認」章節。
- 這些文件不是永久真理；每次調整流程、模組或測試後，應同步更新。
- 若文件與 live code 衝突，以 live code + 測試結果為準，並立刻回寫文件。
