# 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 的操作後台。**
