# Gateway / Shared Drive 更新後固定驗收操作順序單

> 目的：每次 `update / merge / restart / hotfix` 後，不用重新思考要先驗什麼、後驗什麼。照 **1 → 2 → 3 → 4** 跑，最快確認這次變更有沒有把綁定、長任務、email fallback、shared drive、短下載連結又弄壞。

---

## 適用情境
以下任一情況直接跑這張，不要靠印象：
- `hermes update`
- merge upstream / cherry-pick / refactor
- gateway / dashboard restart
- LINE / Telegram / email / OpenWebUI 交付路徑有改
- managed download / shared drive / attachment / fallback 有改

---

## Step 1：先看有沒有整片死掉（2～5 分鐘）

### 1-1. process / restart 健康
- [ ] gateway process 有起來
- [ ] dashboard / web server 可回應
- [ ] 沒有 restart loop

### 1-2. 基本介面
- [ ] 管理後台能開
- [ ] 至少一個平台狀態可讀
- [ ] 沒有整片 401 / 403 / 500

### 1-3. 若這裡失敗
先停，不要直接猜 LINE / email 壞掉。
先翻：
- `gateway-recovery-playbook.md`
- `gateway-update-restart-sop.md`

---

## Step 2：先跑最小測試集（不要改完才想到）

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

- [ ] 全數通過

### 2-2. binding / 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
```

- [ ] 全數通過

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

- [ ] 通過

### 2-4. shared drive 腳本語法檢查（有碰 shared drive / download 時必跑）
```bash
python3 -m py_compile \
  ~/.hermes/scripts/shared_drive_index_query.py \
  ~/.hermes/scripts/shared_drive_lookup.py \
  ~/.hermes/scripts/shared_drive_delivery_bundle.py \
  ~/.hermes/scripts/shared_drive_chat_workflow.py \
  ~/.hermes/scripts/shared_drive_cleanup.py
```

- [ ] 通過

---

## Step 3：固定跑 6 個實際 smoke case

> 原則：**不能只看測試綠燈**。這 6 個是每次 update 後最容易再炸的 live 路徑。

### 3-1. 綁定 smoke
- [ ] LINE 綁定 email 正確
- [ ] Telegram 綁定 email 正確
- [ ] OpenWebUI / api_server 綁定 email 正確
- [ ] system-initiated handoff 只會寄到 live bound email

### 3-2. LINE 長任務 smoke
- [ ] 觸發會超過 pending threshold 的任務
- [ ] 有 pending 流程
- [ ] `查看答案` 在 `PENDING / READY / DELIVERED` 狀態回應正確
- [ ] heartbeat / busy ack 文案不是 raw tool progress

### 3-3. LINE quota fallback → email smoke
- [ ] 模擬 LINE 無法交付
- [ ] pending 只寄一次
- [ ] final 真的寄到 verified email
- [ ] replay / postback 仍保留「已改寄 email」事實

### 3-4. Telegram generic document smoke
- [ ] 實際交付 `pptx/pdf/docx/xlsx/zip`
- [ ] 完成訊息內含 **24h 短下載連結**（`/downloads/s-<short_id>`）
- [ ] 不是只有原生附件
- [ ] 訊息中沒有 `...` / `…` 截斷 token

### 3-5. email generic document smoke
- [ ] 實際寄送 `pptx/pdf/docx/xlsx/zip`
- [ ] 信內有 **24h 短下載連結**
- [ ] 使用正式網域
- [ ] 實際可點開下載
- [ ] 若附件過大，會退成 link-only，不硬塞附件

### 3-6. shared drive bundle smoke
```bash
python3 ~/.hermes/scripts/shared_drive_chat_workflow.py bundle \
  --paths /absolute/path/to/file \
  --requester dk96@bremen.com.tw --format json
```
- [ ] `download_url` 為短碼型網址（例如 `/downloads/s-<short_id>`）
- [ ] `verification.ok = true`
- [ ] generic documents 在 Telegram / email 預設交付短下載連結
- [ ] 敏感檔會自動加密 zip

---

## Step 4：最後用這個格式回報

```md
更新後固定驗收結果：
- 狀態：PASS / FAIL / PARTIAL
- 類型：restart / update / merge / hotfix / refactor
- 版本/變更：
- Step 1 健康檢查：PASS / FAIL
- Step 2 測試集：PASS / FAIL / PARTIAL
- Step 3-1 綁定：PASS / FAIL
- Step 3-2 LINE 長任務：PASS / FAIL
- Step 3-3 LINE fallback→email：PASS / FAIL
- Step 3-4 Telegram generic-doc 短連結：PASS / FAIL
- Step 3-5 email generic-doc 短連結：PASS / FAIL
- Step 3-6 shared drive bundle：PASS / FAIL
- blocker：
- 需追修：
- 是否可交付 / 上線：可 / 不可 / 有條件
```

---

## 失敗時不要亂猜，直接對照這裡
- 綁定 / principal / email handoff：`gateway-functional-contract.md`、`gateway-recovery-playbook.md`
- LINE 長任務 / replay / fallback：`gateway-regression-matrix.md`、`gateway-recovery-playbook.md`
- managed download / 短碼下載：`gateway-change-impact-checklist.md`、`tests/hermes_cli/test_managed_downloads.py`
- shared drive：
  - `docs/shared-drive-file-access/shared-drive-file-access-validation-matrix.md`
  - `docs/shared-drive-file-access/shared-drive-file-access-reply-formats.md`
  - `docs/shared-drive-file-access/shared-drive-v2-validation-template-full.md`

---

## 一句話版本
> **每次 update 後，先看活著沒 → 再跑最小測試集 → 再跑 6 個固定 smoke → 最後照模板回報。**