# Gateway 驗收模板（可直接複製）

> 用途：每次 **Hermes update / gateway restart / merge upstream / 修 bug 後**，直接複製這份，填 PASS / FAIL / PARTIAL。不要再靠回憶自由發揮。
>
> 搭配文件：
> - `gateway-update-restart-sop.md`
> - `gateway-change-impact-checklist.md`
> - `gateway-recovery-playbook.md`
> - `gateway-admin-ui-api-matrix.md`

---

## 基本資訊
- 日期：
- 執行者：
- 驗收者：
- 類型：`restart / update / merge / hotfix / refactor`
- 版本 / commit / 變更摘要：
- 是否有改 code：`是 / 否`
- 是否有碰 governance：`是 / 否`

---

## 一、這次改到哪裡
- [ ] `gateway/config.py`
- [ ] `gateway/run.py`
- [ ] `gateway/authz_mixin.py`
- [ ] `gateway/user_verification.py`
- [ ] `gateway/principal_profiles.py`
- [ ] `gateway/platforms/base.py`
- [ ] `plugins/platforms/line/adapter.py`
- [ ] `plugins/platforms/email/adapter.py`
- [ ] `hermes_cli/managed_downloads.py`
- [ ] `hermes_cli/web_server.py`
- [ ] `web/src/...`
- [ ] 其他：

---

## 二、快速健康檢查（2～5 分鐘）
- [ ] gateway 有起來
- [ ] 沒有 restart loop
- [ ] dashboard / web server 能回應
- [ ] 至少一個平台狀態可讀
- [ ] 管理平台頁面能開
- [ ] 沒有整片 401 / 403 / 500

### 結果
- 狀態：`PASS / FAIL / PARTIAL`
- 備註：

---

## 三、測試執行結果

### Tier 1：delivery 最小集
```bash
venv/bin/pytest -q \
  tests/gateway/test_line_plugin.py \
  tests/gateway/test_email.py \
  tests/gateway/test_approval_prompt_redaction.py \
  tests/gateway/test_display_config.py \
  tests/hermes_cli/test_managed_downloads.py
```
- 結果：`PASS / FAIL / NOT RUN`
- 備註：

### Tier 2：binding / principal / governance
```bash
venv/bin/pytest -q \
  tests/hermes_cli/test_web_verification_admin.py \
  tests/gateway/test_principal_profile_routing_phase1.py \
  tests/gateway/test_verified_email_handoff_guard_helpers.py
```
- 結果：`PASS / FAIL / NOT RUN`
- 備註：

### Tier 3：py_compile
```bash
python -m py_compile \
  gateway/run.py \
  gateway/config.py \
  gateway/authz_mixin.py \
  gateway/user_verification.py \
  gateway/platforms/base.py \
  plugins/platforms/line/adapter.py \
  plugins/platforms/email/adapter.py \
  hermes_cli/managed_downloads.py \
  hermes_cli/web_server.py
```
- 結果：`PASS / FAIL / NOT RUN`
- 備註：

---

## 四、核心 smoke

### 4.1 綁定 / handoff
- [ ] LINE 綁定 email 正確
- [ ] Telegram 綁定 email 正確
- [ ] OpenWebUI / api_server 綁定 email 正確
- [ ] system-initiated handoff 只會寄到 live bound email
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 4.2 principal profile routing
- [ ] verified source 吃到正確 principal profile
- [ ] quick key / session namespace 正確
- [ ] restart 後 mapping 未漂移
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 4.3 LINE 長任務
- [ ] 有 pending 流程
- [ ] `查看答案` 在 `PENDING / READY / DELIVERED` 回應正確
- [ ] heartbeat / busy ack 文案不是 raw tool progress 噪音
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 4.4 LINE quota fallback → email
- [ ] 模擬 LINE push 失敗後改寄 verified email
- [ ] pending 只寄一次
- [ ] final answer 真正寄到 email
- [ ] replay / postback 保留「已改寄 email」事實
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 4.5 email 附件 / 下載連結
- [ ] 小檔案：附件 + 下載連結
- [ ] 大檔案：只有下載連結
- [ ] 附件檔名保留副檔名
- [ ] 下載連結網域正確
- [ ] 下載連結可下載
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

---

## 五、governance / admin（有碰才填）

### 5.1 先確認你驗的是哪一種
- [ ] 後端-only API
- [ ] 已存在前端 UI
- [ ] 已對照 `gateway-admin-ui-api-matrix.md`

### 5.2 governance smoke
- [ ] `/api/admin/verification/role` 正常
- [ ] principals / identities 查得到
- [ ] quota policy / model policy 查得到
- [ ] principal usage 有資料
- [ ] audit log 查得到最近治理操作
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

---

## 六、若失敗，先定位到哪一層
- [ ] process / restart 層
- [ ] config / authz 層
- [ ] principal / session namespace 層
- [ ] delivery path 層
- [ ] governance / admin API 層
- [ ] 前端 UI / API 對接層

### 對應要翻的文件
- [ ] `gateway-recovery-playbook.md`
- [ ] `gateway-change-impact-checklist.md`
- [ ] `gateway-admin-ui-api-matrix.md`
- [ ] `gateway-functional-contract.md`

---

## 七、最終結論
- 狀態：`PASS / FAIL / PARTIAL`
- blocker：
- 需追修：
- 是否可交付 / 上線：`可 / 不可 / 有條件`

---

## 八、可直接貼回報版
```md
更新/重啟驗收結果：
- 狀態：
- 版本/變更：
- Tier 1 測試：
- Tier 2 測試：
- Tier 3 檢查：
- 綁定 smoke：
- principal profile routing smoke：
- LINE 長任務 smoke：
- quota fallback smoke：
- email 附件 / 下載連結 smoke：
- governance/admin smoke：
- blocker：
- 需追修：
- 是否可交付 / 上線：
```
