6.9 KiB

Raw Blame History

Gateway Resilience 團隊使用守則

目的：把這整包 gateway-resilience 文件，從「有文件可參考」升級成「誰動 gateway 都必須照同一套做」。重點不是增加文書工作，而是 減少反覆排查、減少 token 浪費、減少修一個壞一串。

1. 適用範圍

以下任一情境，都適用這份守則：

Hermes Agent update
merge upstream / cherry-pick / refactor
gateway restart / watchdog 調整
Telegram / LINE / OpenWebUI / email 綁定邏輯修改
LINE 長任務 / pending / replay / heartbeat 修改
LINE 額度不足 fallback 到 email 修改
email 附件 / 副檔名 / 下載連結 / managed downloads 修改
principal / verification / quota / role / admin 後台修改
dashboard 前端若牽涉 governance / messaging / onboarding / delivery flow

一句話版

只要改動可能影響「綁定、長任務、fallback、檔案交付、治理後台」任何一條主線，就不能跳過這套流程。

2. 團隊規則：誰在什麼時候做什麼

2.1 開改前

改 code 前，操作者必做：

先看 gateway-functional-contract.md
再勾 gateway-change-impact-checklist.md
先說清楚這次影響哪些主線：
- 綁定
- principal profile routing
- LINE 長任務
- LINE quota fallback
- email 附件 / 下載連結
- governance / admin

禁止行為

沒先判斷 impact 就直接改
改完才回頭想要跑哪些測試
明明跨多模組，卻只跑自己最熟的一組 pytest

2.2 改動中

操作者必須遵守：

改到哪個模組，就補對應驗收責任
若修改流程順序、fallback 條件、文案或管理台能力，文件要一起改
若 live code 與文件衝突，以 live code + 測試結果為準，當次就回寫文件

原則

文件不是事後補作文，是變更的一部分。
沒有驗收責任的修復，不算完整修復。

2.3 改完後

改完後，操作者必做：

跑 gateway-update-restart-sop.md
視 impact 跑對應 Tier 1 / Tier 2 / Tier 3
做核心 smoke
若碰 governance，再做 governance 特別檢查

最低要求

有改 code：不能只看服務有起來
有 side effect：不能只看單元測試綠燈
有管理台變更：不能只看 API 200

2.4 回報時

回報分兩層：

內部完整紀錄

使用：

gateway-validation-template-full.md

對外或群組同步

使用：

gateway-validation-template-compact.md

若不確定怎麼填

先看：

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

3. 角色分工

3.1 操作者

負責：

判斷 impact
修改 code / config / docs
跑測試
跑 smoke
填完整驗收紀錄

操作者不能說的話

「我有改好，應該可以」
「我只改一點點，應該不用驗」
「pytest 有過，應該沒問題」

這三句都屬於未完成修復語。

3.2 驗收者

若是雙人流程，驗收者負責：

檢查 checklist 有沒有真的勾 impact
檢查有沒有漏跑該跑的 Tier
檢查回報是 PASS / FAIL / PARTIAL，不是模糊話術
檢查 governance 與 delivery 是否被混為一談

驗收者最重要的工作

不是再手修一遍，而是擋掉這些錯誤：

Pairing / Channels / System 被誤當成完整 governance console
routing 修好了，但 delivery 沒驗
email 有寄出，但檔名 / 副檔名 / 下載連結沒驗
LINE 有 pending，但 replay / fallback 沒驗

4. 標準作業流程（團隊版）

Step 1：先判斷是不是 gateway-resilience 範圍

如果是，就啟動這套，不准跳過。

Step 2：先勾 impact

使用：

gateway-change-impact-checklist.md

Step 3：改 code / config / docs

code 與 docs 同步
不留「晚點補文件」債

Step 4：跑 SOP

使用：

gateway-update-restart-sop.md

Step 5：留完整驗收紀錄

使用：

gateway-validation-template-full.md

Step 6：對外同步

使用：

gateway-validation-template-compact.md

Step 7：出錯就回 playbook

使用：

gateway-recovery-playbook.md

5. PASS / FAIL / PARTIAL 的團隊定義

PASS

代表：

該跑的測試有跑
該做的 smoke 有做
無 blocker
可以交付 / 上線

FAIL

代表：

有明確 blocker
重要主線失敗
不可交付 / 不可上線

PARTIAL

代表：

某一問題修好了
但不是完整 update/restart 驗收
有些 smoke / live checks 尚未補完
只能「有條件交付」

規則

不要把 PARTIAL 寫成 PASS。

這條很重要，因為很多復發就是從「其實只驗一半，但回報寫成沒問題」開始。

6. 哪些情況一定要寫 PARTIAL

以下情況，原則上不能寫 PASS：

只跑對應單元測試，沒做核心 smoke
只驗 routing，沒驗 delivery
只驗 API，沒驗管理台實際對應
只驗 email 有寄，沒驗附件 / 副檔名 / 下載連結
只驗 LINE 有 pending，沒驗 replay / fallback
只看 process 活著，沒驗主線功能

7. 文件使用對照

想知道「這功能本來應該怎樣」

看：

gateway-functional-contract.md

想知道「流程到底怎麼跑」

看：

gateway-state-and-sequence.md

想知道「改到哪裡該跑什麼」

看：

gateway-change-impact-checklist.md

想知道「完整 update / restart 後怎麼驗」

看：

gateway-update-restart-sop.md

想知道「壞了先查哪裡」

看：

gateway-recovery-playbook.md

想知道「治理後台到底是後端-only 還是有 UI」

看：

gateway-admin-ui-api-matrix.md

想留正式驗收紀錄

看：

gateway-validation-template-full.md

想快速貼回報

看：

gateway-validation-template-compact.md

8. 團隊常見錯誤清單

錯誤 1：只修 symptom，不補契約

後果：下次換個入口又壞一次。

錯誤 2：只跑 pytest，不做 smoke

後果：測試綠燈但 live delivery 還是翻車。

錯誤 3：把 governance API 存在，誤當成已有完整 UI

後果：管理台能力被高估，排查方向錯掉。

錯誤 4：把 PARTIAL 當 PASS 回報

後果：風險被隱藏，下一次又說「怎麼更新後又壞」。

錯誤 5：文件晚點再補

後果：通常就是永遠不補，然後下次再花 token 考古。

9. 團隊最低執行標準

若時間很趕，至少也不能低於這條線：

勾 gateway-change-impact-checklist.md
跑對應 pytest
跑 gateway-update-restart-sop.md 的快速健康檢查
至少驗與這次變更直接相關的主線 smoke
填 gateway-validation-template-compact.md

注意

這是最低標準，不是最佳標準。若是正式 update / merge / restart，仍應跑完整版流程。

10. 一句話版團隊政策

動 gateway，不只要修 code，還要交付 impact 判斷、驗收結果、對外回報；沒有這三件事，就不算完成。

6.9 KiB Raw Blame History Unescape Escape