Bremen
/
emma-hermes
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
emma-hermes/docs/gateway-resilience/examples-principal-profile-...

6.2 KiB
Raw Blame History

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：是

一、這次改到哪裡

  • 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/...
  • 其他：docs/gateway-resilience/*.md 文件狀態同步更新

二、快速健康檢查（2～5 分鐘）

  • gateway 有起來
  • 沒有 restart loop
  • dashboard / web server 能回應
  • 至少一個平台狀態可讀
  • 管理平台頁面能開
  • 沒有整片 401 / 403 / 500

結果

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

三、測試執行結果

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

Tier 2：binding / principal / 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
  • 結果：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

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

  • verified source 吃到正確 principal profile
  • quick key / session namespace 正確
  • 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 先確認你驗的是哪一種

  • 後端-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 查得到最近治理操作
  • 結果：PARTIAL
  • 備註：本次以 test_web_verification_admin.py 綠燈確認 governance 後端未被 routing 修復破壞；未逐條做 live API smoke

六、若失敗，先定位到哪一層

  • 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
  • blocker：無
  • 需追修：將本次成功修復納入正式 update/restart SOP 的完整 smoke 範本，避免之後只修 routing 不驗 delivery
  • 是否可交付 / 上線：有條件

八、可直接貼回報版

更新/重啟驗收結果：
- 狀態：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
- 是否可交付 / 上線：有條件