Bremen
/
emma-hermes
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
emma-hermes/docs/gateway-resilience/README.md

5.5 KiB
Raw Blame History

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，不再自由發揮

  1. gateway-validation-template-full.md

    • 完整版驗收模板
    • 適合內部工程驗收、保留詳細記錄

  2. gateway-validation-template-compact.md

    • 精簡版驗收模板
    • 適合 Telegram / LINE / email 快速回報

  3. examples-principal-profile-routing-validation-full.md

    • 這次 principal_profile_routing 修復的完整版驗收範例
    • 示範怎麼把真實測試結果填進模板

  4. examples-principal-profile-routing-validation-compact.md

    • 同一案例的精簡回報範例
    • 可直接仿照格式貼回 Telegram / LINE / email

  5. gateway-team-usage-policy.md

    • 團隊使用守則 / 執行政策
    • 把 impact 判斷、驗收、回報制度化，避免文件存在但沒人照做

  6. gateway-entrypoint.md

    • 首頁索引 / 單頁入口
    • 不知道先看哪份時，先看這頁就能導到正確文件

  7. 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 條主線：

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

注意

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