# Gateway Regression Matrix

> 目標：把功能、模組、測試、更新後 smoke 順序對齊，讓 future update 不必重新翻整串對話試錯。

## 核心測試矩陣

| 功能/契約 | 核心模組 | 主要測試 | 至少要確認什麼 |
|---|---|---|---|
| verified email live lookup | `gateway/user_verification.py` | 相關 user verification tests + LINE 端整合測試 | active source 只能拿到自己的 verified email |
| bound email live confirm | `gateway/user_verification.py`, `plugins/platforms/line/adapter.py` | `tests/gateway/test_line_plugin.py` | 系統自動寄綁定信箱前必須 live match |
| approval 文案 redaction | `gateway/run.py`, `gateway/platforms/api_server.py` | `tests/gateway/test_approval_prompt_redaction.py` | raw command / token 不外露；文案保持對客繁中 |
| LINE pending/request cache | `plugins/platforms/line/adapter.py` | `tests/gateway/test_line_plugin.py` | `PENDING -> READY -> DELIVERED / ERROR` 正常 |
| LINE postback replay | `plugins/platforms/line/adapter.py` | `tests/gateway/test_line_plugin.py` | `show_response` 對應正確 state，replay 不失真 |
| LINE quota fallback | `plugins/platforms/line/adapter.py` | `tests/gateway/test_line_plugin.py` | push 失敗時改寄 verified email，並保留 fallback notice |
| fallback pending 去重 | `plugins/platforms/line/adapter.py` | `tests/gateway/test_line_plugin.py` | pending email notice 不重複狂寄 |
| fallback final + post-stream files | `plugins/platforms/line/adapter.py`, `gateway/platforms/base.py` | `tests/gateway/test_line_plugin.py` | final 已轉 email 後，附件不再回頭走 LINE |
| email MIME attachment | `plugins/platforms/email/adapter.py` | `tests/gateway/test_email.py` | 附件存在、副檔名保留、content-type/disposition 正確 |
| email HTML clickable links | `plugins/platforms/email/adapter.py` | `tests/gateway/test_email.py` | URL 變成可點連結 |
| large attachment link-only fallback | `plugins/platforms/line/adapter.py`, `plugins/platforms/email/adapter.py` | `tests/gateway/test_line_plugin.py` | 過大時只保留下載連結，不狂寄多封 |
| LINE 預設安靜文案 | `gateway/display_config.py`, `gateway/run.py` | `tests/gateway/test_display_config.py` | `busy_ack_detail=false`, `long_running_notifications=generic` |
| managed download URL | `hermes_cli/managed_downloads.py` | `tests/hermes_cli/test_managed_downloads.py` | URL 走正式網域下載路徑 |
| managed download route | `hermes_cli/web_server.py` | `tests/hermes_cli/test_managed_downloads.py` | `/downloads/{token}` 真能回檔案 |
| shared drive search candidates | `~/.hermes/scripts/shared_drive_lookup.py`, `~/.hermes/scripts/shared_drive_chat_workflow.py` | shared-drive workflow smoke | 候選含 `file_id`，可進入下一步 |
| shared drive folder children | `~/.hermes/scripts/shared_drive_index_query.py`, `~/.hermes/scripts/shared_drive_chat_workflow.py` | shared-drive workflow smoke | 資料夾可展開，列出最多 10 檔可選項 |
| shared drive bundle verify | `~/.hermes/scripts/shared_drive_delivery_bundle.py`, `~/.hermes/scripts/shared_drive_chat_workflow.py` | shared-drive workflow smoke | 24h link 可用，敏感檔自動加密，`verification.ok = true` |
| principal live binding guard（Telegram/OpenWebUI） | `gateway/user_verification.py`, `plugins/platforms/telegram/adapter.py`, `gateway/platforms/api_server.py` | `tests/gateway/test_verified_email_handoff_guard_helpers.py` | 非使用者明指的 system handoff 不得寄到錯 email |
| principal profile routing | `gateway/principal_profiles.py`, `gateway/user_verification.py`, `gateway/run.py` | `tests/gateway/test_principal_profile_routing_phase1.py` | 同一 principal 穩定對應同一 profile，不因更新漂移 |
| dashboard role bootstrap / assignment | `hermes_cli/web_server.py`, `gateway/user_verification.py` | `tests/hermes_cli/test_web_verification_admin.py` | loopback 預設 admin；role round-trip 正常 |
| governance identities / principals / audit | `hermes_cli/web_server.py`, `gateway/user_verification.py` | `tests/hermes_cli/test_web_verification_admin.py` | force-bind 後能查 principals / identities / audit |
| quota policy / model policy / principal usage | `hermes_cli/web_server.py`, `gateway/user_verification.py`, `gateway/run.py` | `tests/hermes_cli/test_web_verification_admin.py` | policy 可 round-trip、usage 能對帳到 email 與 limit |

---

## 目前實跑狀態（這次盤點）

- `tests/hermes_cli/test_web_verification_admin.py`：通過
- `tests/gateway/test_verified_email_handoff_guard_helpers.py`：通過
- `tests/gateway/test_principal_profile_routing_phase1.py`：通過

本次已修復：
- `GatewayConfig` 已接上 `principal_profile_routing`
- `GatewayConfig` 已接上 `principal_profile_map_path`
- `_handle_message(...)` 會在 session lookup 前先對 verified source 套用 principal profile routing
- verified source 會被視為授權來源，不再卡在未授權分支

所以 **principal profile routing 目前可視為綠燈 coverage**，但未來只要改到 `gateway/config.py`、`gateway/run.py`、`gateway/authz_mixin.py`、`gateway/principal_profiles.py`，仍必須重跑這組測試。

---

## 更新後建議最小測試集

### Tier 1：只要碰到 gateway 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
```

### Tier 2：若有改綁定 / principal / admin 流程，再加跑
- 與 `gateway/user_verification.py`
- `hermes_cli/web_server.py`
- principal / verification admin 相關測試

```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
```

### Tier 3：基本語法與匯入檢查
```bash
python -m py_compile \
  gateway/run.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
```

---

## 建議 smoke 測試順序

### 1. 綁定與 guard
- 從 LINE / Telegram / OpenWebUI 各確認目前綁定 email
- 驗證 system-initiated handoff 只會寄到 live bound email

### 2. LINE 長任務
- 觸發一個會超過 pending threshold 的任務
- 確認有 pending 機制
- 確認文案不是工程英文噴滿版

### 3. LINE quota fallback
- 模擬 push quota 失敗
- 確認 pending / final 都會保留「改寄 email」事實
- 確認 `查看答案` replay 仍說明 email fallback

### 4. Email 附件
- 小檔案：確認 MIME attachment + 下載連結
- 大檔案：確認只有下載連結，不會多封連發

### 5. Managed downloads
- 從實際 email 或訊息點下載連結
- 確認是正式網域
- 確認可下載、重啟後仍有效（在有效期限內）

### 5.5 Shared drive workflow
- 跑 `shared_drive_chat_workflow.py search <query>`
- 跑 `shared_drive_chat_workflow.py children <folder_file_id>`
- 跑 `shared_drive_chat_workflow.py bundle --file-ids ... --requester <email>`
- 確認敏感檔會自動加密、manifest 有 `verification.ok = true`
- 驗證以真實 GET 為準，不用 HEAD 當成功判準

### 6. 權限與額度治理
- 從管理後台/API 確認 principal / identity list 還在
- 確認 dashboard role 沒被洗掉
- 確認 quota policy / model policy 查得到
- 確認 principal usage 仍會累積

---

## 變更影響對照

| 你改了哪裡 | 最少要補跑哪些 |
|---|---|
| `gateway/user_verification.py` | binding guard 相關測試 + line fallback 整合測試 |
| `gateway/principal_profiles.py` | `test_principal_profile_routing_phase1.py` |
| `plugins/platforms/line/adapter.py` | `test_line_plugin.py`, `test_display_config.py` |
| `plugins/platforms/email/adapter.py` | `test_email.py`, `test_line_plugin.py` |
| `gateway/platforms/base.py` | `test_line_plugin.py`（特別是 post-stream files） |
| `gateway/run.py` | `test_approval_prompt_redaction.py`, `test_display_config.py`, 長任務 smoke |
| `hermes_cli/managed_downloads.py` / `web_server.py` | `test_managed_downloads.py` + live GET |
| `~/.hermes/scripts/shared_drive_*` | shared-drive workflow smoke + `python3 -m py_compile` |
| `hermes_cli/web_server.py` governance/admin 區塊 | `test_web_verification_admin.py` |

---

## 維護規則

每次新增一個「曾經修過、未來很可能再壞」的路徑，就把它補進：
1. 本 matrix
2. 對應 live smoke case
3. 對應 regression test

如果一個關鍵行為還沒有測試，就先把它列在這份矩陣裡標成缺口，不要假裝 coverage 已完整。
