276 lines
6.9 KiB
Markdown
276 lines
6.9 KiB
Markdown
# 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 前，操作者必做：
|
||
|
||
1. 先看 `gateway-functional-contract.md`
|
||
2. 再勾 `gateway-change-impact-checklist.md`
|
||
3. 先說清楚這次影響哪些主線：
|
||
- 綁定
|
||
- principal profile routing
|
||
- LINE 長任務
|
||
- LINE quota fallback
|
||
- email 附件 / 下載連結
|
||
- governance / admin
|
||
|
||
### 禁止行為
|
||
- 沒先判斷 impact 就直接改
|
||
- 改完才回頭想要跑哪些測試
|
||
- 明明跨多模組，卻只跑自己最熟的一組 pytest
|
||
|
||
---
|
||
|
||
## 2.2 改動中
|
||
操作者必須遵守：
|
||
|
||
1. 改到哪個模組，就補對應驗收責任
|
||
2. 若修改流程順序、fallback 條件、文案或管理台能力，文件要一起改
|
||
3. 若 live code 與文件衝突，以 live code + 測試結果為準，當次就回寫文件
|
||
|
||
### 原則
|
||
- **文件不是事後補作文，是變更的一部分。**
|
||
- **沒有驗收責任的修復，不算完整修復。**
|
||
|
||
---
|
||
|
||
## 2.3 改完後
|
||
改完後，操作者必做：
|
||
|
||
1. 跑 `gateway-update-restart-sop.md`
|
||
2. 視 impact 跑對應 Tier 1 / Tier 2 / Tier 3
|
||
3. 做核心 smoke
|
||
4. 若碰 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. 團隊最低執行標準
|
||
|
||
若時間很趕，至少也不能低於這條線：
|
||
|
||
1. 勾 `gateway-change-impact-checklist.md`
|
||
2. 跑對應 pytest
|
||
3. 跑 `gateway-update-restart-sop.md` 的快速健康檢查
|
||
4. 至少驗與這次變更直接相關的主線 smoke
|
||
5. 填 `gateway-validation-template-compact.md`
|
||
|
||
### 注意
|
||
這是**最低標準**，不是最佳標準。
|
||
若是正式 update / merge / restart，仍應跑完整版流程。
|
||
|
||
---
|
||
|
||
## 10. 一句話版團隊政策
|
||
|
||
> **動 gateway，不只要修 code，還要交付 impact 判斷、驗收結果、對外回報；沒有這三件事，就不算完成。**
|