Bremen
/
emma-hermes
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
emma-hermes/docs/gateway-resilience/gateway-post-update-validat...

5.5 KiB
Raw Blame History

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 最小測試集

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 最小測試集（有碰綁定/治理時必跑）

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

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 時必跑）

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

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：最後用這個格式回報

更新後固定驗收結果：
- 狀態：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 → 最後照模板回報。