emma-hermes/docs/gateway-resilience

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 + 測試結果為準，並立刻回寫文件。