emma-hermes/docs/gateway-resilience/gateway-admin-ui-api-matrix.md

Gateway Admin UI / API 對照盤點表

目標：把 目前管理平台前端實際有露出的功能、後端其實已存在但前端未接的 API、以及 之後 update / refactor 時應如何核對 一次寫清楚，避免未來又出現「以為後台有 / 其實只有 API」或「以為前端有接 / 其實沒接」的落差。

實際程式碼再確認

本文件依下列 live 落點整理：

後端

• hermes_cli/web_server.py
• gateway/user_verification.py

前端

• web/src/lib/api.ts
• web/src/App.tsx
• web/src/pages/SystemPage.tsx
• web/src/pages/ChannelsPage.tsx
• web/src/pages/PairingPage.tsx
• web/src/components/OAuthProvidersCard.tsx
• web/src/components/PlatformsCard.tsx

已確認的關鍵事實

1. web_server.py 已有完整 governance/admin API：

   • /api/admin/verification/role
   • /api/admin/verification/roles
   • /api/admin/verification/identities
   • /api/admin/verification/principals
   • /api/admin/verification/force-bind
   • /api/admin/verification/unbind
   • /api/admin/verification/unblock
   • /api/admin/verification/block
   • /api/admin/verification/resend
   • /api/admin/verification/audit
   • /api/admin/quota-policies
   • /api/admin/model-policies
   • /api/admin/principal-usage

2. web/src/lib/api.ts 目前沒有 對上述 governance API 的 wrapper。

3. web/src 目前已明確有接的管理平台功能，集中在：

   • messaging platforms / onboarding
   • gateway restart / Hermes update / action status
   • dashboard plugins
   • OAuth providers
   • pairing
   • 一般系統 / 設定 / skills / profiles / sessions / models / MCP 等 machine-level management

4. 也就是說：

   • 治理後端能力：有
   • 治理專用前端 UI：目前在這份 tree 內看不到明確落地

---

1. 路由 / 頁面現況（前端）

由 web/src/App.tsx 可確認目前內建頁面包含：

• /sessions
• /files
• /analytics
• /models
• /logs
• /cron
• /skills
• /plugins
• /mcp
• /pairing
• /channels
• /webhooks
• /system
• /profiles
• /config
• /env
• /docs

重要觀察

目前 沒有 看見像這種明確治理頁路由：

• /governance
• /admin/verification
• /principals
• /quota
• /audit

所以若未來有人說「管理平台本來就有 principal / quota / audit UI」，需要先釐清：

• 是指 後端 API 有
• 還是指 前端頁面真的存在

這兩件事目前不是同一件事。

---

2. UI / API 對照矩陣

功能面	後端 API 狀態	前端 api.ts wrapper	明確 UI 頁面/元件	目前判定
verification role 查詢	有	無	無	後端-only
dashboard role 管理	有	無	無	後端-only
identities 列表	有	無	無	後端-only
principals 列表	有	無	無	後端-only
force-bind / unbind	有	無	無	後端-only
block / unblock	有	無	無	後端-only
resend verification	有	無	無	後端-only
verification audit	有	無	無	後端-only
quota policies	有	無	無	後端-only
model policies	有	無	無	後端-only
principal usage	有	無	無	後端-only
Pairing pending / approve / revoke	有	有	PairingPage.tsx	UI 已存在
Messaging platforms 管理	有	有	ChannelsPage.tsx	UI 已存在
Telegram onboarding	有	有	ChannelsPage.tsx	UI 已存在
WhatsApp onboarding	有	有	ChannelsPage.tsx	UI 已存在
OAuth provider 管理	有	有	OAuthProvidersCard.tsx	UI 已存在
Gateway restart / stop / start	有	有	SystemPage.tsx, ChannelsPage.tsx	UI 已存在
Hermes update / update check	有	有	SystemPage.tsx	UI 已存在
Dashboard plugins	有	有	PluginsPage.tsx + plugin 系統	UI 已存在
Downloads route / backup download	有	有（部分）	SystemPage.tsx 等	UI/流程已存在

---

3. 三種狀態定義

A. 後端-only

意思是：

• API 已存在
• 權限邏輯也存在
• 測試也存在
• 但目前這份前端 tree 內看不到對應頁面 / wrapper / 操作元件

目前屬於這類的主要是：

• principal / identity 治理
• quota / model policy 治理
• dashboard role 治理
• admin audit / principal usage 檢視

B. UI 已存在

意思是：

• 前端 api.ts 有呼叫
• 頁面或元件有實際使用
• 使用者可在 dashboard 內操作

目前明確屬於這類的主要是：

• Channels / messaging platforms
• Telegram / WhatsApp onboarding
• Pairing
• OAuth providers
• Gateway lifecycle / update
• Plugins

C. 名義上相近，但不是同一件事

這一類很容易搞混：

Pairing UI ≠ governance principal binding UI

PairingPage.tsx 管的是：

• pending pairing requests
• approve / revoke pairing

它不是：

• verified email / principal 綁定治理 console
• identities / principals / force-bind / quota / audit UI

Channels UI ≠ principal governance UI

ChannelsPage.tsx 管的是：

• 平台啟用/停用
• token/env config
• onboarding
• gateway restart

它不是：

• principal 查詢
• role / quota / audit 治理

SystemPage ≠ governance console

SystemPage.tsx 管的是：

• system actions
• backups
• updates
• ops / hooks / diagnostics
• memory / portal / curator 等

它不是完整的 verification / quota / role / audit 治理頁。

---

4. 目前最準確的結論

4.1 已可對外說「管理平台有」的部分

可以保守而正確地說：

• 有 dashboard / management surface
• 有 Channels 頁面管理 messaging platforms 與 onboarding
• 有 Pairing 頁面
• 有 System 頁面管理 gateway lifecycle / update / ops
• 有 OAuth providers 管理
• 有 Plugins / Profiles / Skills / Config / Sessions 等一般管理能力

4.2 不應直接說「管理平台已完整提供」的部分

目前不應直接聲稱 dashboard 已有完整可視化治理介面來操作：

• principal / identity admin
• dashboard role admin
• quota policy admin
• model policy admin
• principal usage viewer
• verification audit viewer

因為目前證據顯示：

• 這些後端 API 有
• 但前端 page / api wrapper / UI controls 在這份 tree 內沒有明確落地

---

5. 未來更新時該怎麼核對

5.1 若你改的是後端 governance API

至少要核對：

• tests/hermes_cli/test_web_verification_admin.py 通過
• API 路徑、request body、response shape 沒改壞
• 若之後已補前端 wrapper，前端也要跟著更新
• 文件要同步標明是「後端-only」還是「UI 已存在」

5.2 若你新增 governance 前端 UI

至少要補：

• web/src/lib/api.ts wrapper
• 新頁面或元件落點
• App route / nav 入口
• 權限不足 / 401 / 403 文案
• smoke：viewer/operator/admin 三種角色都驗一次
• 這份對照表要把狀態從「後端-only」改成「UI 已存在」

5.3 若你只改 Channels / System / Pairing 頁面

要小心不要誤宣稱連帶補齊 governance console。 這些頁面雖然都算管理平台的一部分，但治理層級不同。

---

6. 建議的下一步（若要把治理真正做成可見後台）

若下一階段要把治理後台真正補齊，我建議最小 MVP 順序：

Phase A：只做 read-only governance views

1. verification role 顯示
2. identities list
3. principals list
4. audit list
5. principal usage list

Phase B：再做 operator actions

1. force-bind
2. unbind
3. block / unblock
4. resend verification
5. quota policy / model policy 編輯

Phase C：最後做 admin-only role assignment

1. dashboard roles list
2. set role
3. audit trail 明確顯示 actor

這樣比較不會一口氣把治理面與高風險修改面全攪在一起。

---

7. 驗收結論（本次盤點）

本次已確認

• web_server.py 的 governance/admin API 存在且測試存在
• web/src/lib/api.ts 已明確接了：
  • messaging platforms
  • onboarding
  • OAuth providers
  • gateway restart / Hermes update
  • dashboard plugins
• App.tsx 目前沒有明確 governance console 路由
• web/src 內查無 /api/admin/verification*、/api/admin/quota-policies、/api/admin/model-policies、/api/admin/principal-usage 的前端呼叫落點

所以目前最準確的判定

治理後端能力已存在，但治理專用前端 UI 在目前這份 tree 內尚未明確落地；現有 dashboard 是一般管理平台，不等於已完整提供 principal / quota / role / audit 的操作後台。