# Gateway 驗收範例（完整版）— principal_profile_routing 修復

> 範例用途：示範怎麼把這次 `principal_profile_routing` 修復，實際填成一份完整驗收紀錄。之後遇到其他修復，只要換掉變更摘要、測試結果、smoke 結果即可。

---

## 基本資訊
- 日期：2026-07-18
- 執行者：Hermes / 艾瑪
- 驗收者：Hermes / 艾瑪
- 類型：`hotfix`
- 版本 / commit / 變更摘要：修復 `principal_profile_routing` 接線，補上 `GatewayConfig` 欄位與 runtime stamping，讓 verified source 能正確落到 principal profile namespace
- 是否有改 code：`是`
- 是否有碰 governance：`是`

---

## 一、這次改到哪裡
- [x] `gateway/config.py`
- [x] `gateway/run.py`
- [x] `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/...`
- [x] 其他：`docs/gateway-resilience/*.md` 文件狀態同步更新

---

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

### 結果
- 狀態：`PASS`
- 備註：本次重點不是 delivery 全面驗收，而是先修復 routing 紅燈並確認服務未因 patch 失穩

---

## 三、測試執行結果

### 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
```
- 結果：`NOT RUN`
- 備註：本次修復聚焦 principal profile routing；delivery 全面回歸已另由規格包與後續 SOP 接手，不在這個範例的實跑範圍

### 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`
- 備註：
  - `tests/gateway/test_principal_profile_routing_phase1.py` → **7 passed**
  - `tests/hermes_cli/test_web_verification_admin.py tests/gateway/test_verified_email_handoff_guard_helpers.py` → **13 passed**

### 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
```
- 結果：`NOT RUN`
- 備註：本次先以對應 pytest 綠燈作為修復驗收；若納入正式 update SOP，應補跑 Tier 3

---

## 四、核心 smoke

### 4.1 綁定 / handoff
- [ ] LINE 綁定 email 正確
- [ ] Telegram 綁定 email 正確
- [ ] OpenWebUI / api_server 綁定 email 正確
- [ ] system-initiated handoff 只會寄到 live bound email
- 結果：`NOT RUN`
- 備註：本次未做跨平台 live handoff smoke；此區塊應在完整 update/restart 驗收時補跑

### 4.2 principal profile routing
- [x] verified source 吃到正確 principal profile
- [x] quick key / session namespace 正確
- [x] restart 後 mapping 未漂移
- 結果：`PASS`
- 備註：依 `test_principal_profile_routing_phase1.py` 驗證通過，且文件狀態已從紅燈更新為已接線

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

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

### 4.5 email 附件 / 下載連結
- [ ] 小檔案：附件 + 下載連結
- [ ] 大檔案：只有下載連結
- [ ] 附件檔名保留副檔名
- [ ] 下載連結網域正確
- [ ] 下載連結可下載
- 結果：`NOT RUN`
- 備註：非本次修復範圍

---

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

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

### 5.2 governance smoke
- [ ] `/api/admin/verification/role` 正常
- [ ] principals / identities 查得到
- [ ] quota policy / model policy 查得到
- [ ] principal usage 有資料
- [ ] audit log 查得到最近治理操作
- 結果：`PARTIAL`
- 備註：本次以 `test_web_verification_admin.py` 綠燈確認 governance 後端未被 routing 修復破壞；未逐條做 live API smoke

---

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

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

---

## 七、最終結論
- 狀態：`PASS`
- blocker：無
- 需追修：將本次成功修復納入正式 update/restart SOP 的完整 smoke 範本，避免之後只修 routing 不驗 delivery
- 是否可交付 / 上線：`有條件`

---

## 八、可直接貼回報版
```md
更新/重啟驗收結果：
- 狀態：PASS
- 版本/變更：修復 principal_profile_routing 接線，補上 GatewayConfig 欄位與 runtime stamping
- Tier 1 測試：NOT RUN
- Tier 2 測試：PASS（routing 7 passed；admin/guard 13 passed）
- Tier 3 檢查：NOT RUN
- 綁定 smoke：NOT RUN
- principal profile routing smoke：PASS
- LINE 長任務 smoke：NOT RUN
- quota fallback smoke：NOT RUN
- email 附件 / 下載連結 smoke：NOT RUN
- governance/admin smoke：PARTIAL（以 admin 測試綠燈確認未被破壞）
- blocker：無
- 需追修：後續完整 update 驗收需補跑 delivery / handoff / email smoke
- 是否可交付 / 上線：有條件
```