# 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 判斷、驗收結果、對外回報；沒有這三件事，就不算完成。**
