269 lines
8.6 KiB
Markdown
269 lines
8.6 KiB
Markdown
# Gateway Governance / Admin Platform
|
||
|
||
> 目標：把 **額度、權限、principal 治理、以及目前管理平台實際可用能力** 單獨固化，避免未來 update 後又忘記「現在到底有哪些後端能力、哪些前端已露出、哪些只是資料表存在」。
|
||
|
||
## 實際程式碼再確認
|
||
|
||
這份文件依下列 live 落點整理：
|
||
|
||
- `gateway/user_verification.py`
|
||
- `gateway/principal_profiles.py`
|
||
- `gateway/run.py`
|
||
- `hermes_cli/web_server.py`
|
||
- `web/src/lib/api.ts`
|
||
- `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`
|
||
|
||
---
|
||
|
||
## 1. 目前治理資料模型
|
||
|
||
`GatewayUserStore` 目前至少維護這些核心資料：
|
||
|
||
- `principals`
|
||
- 主帳號/主體
|
||
- 核心欄位：`principal_id`, `email`, `status`
|
||
- `external_identities`
|
||
- 各平台 identity 與 principal 的綁定
|
||
- 核心欄位：`platform`, `external_user_id`, `verified_email`, `principal_id`
|
||
- `identity_enforcement`
|
||
- 綁定驗證狀態機
|
||
- 核心欄位：`state`, `failure_cycles`, `blocked_until`, `pending_email`
|
||
- `quota_policies`
|
||
- 額度規則
|
||
- 核心欄位：`daily_message_limit`, `daily_token_limit`, `notes`
|
||
- `model_policies`
|
||
- principal 模型規則
|
||
- 核心欄位：`allowed_models_json`, `default_model`
|
||
- `dashboard_roles`
|
||
- 管理平台角色
|
||
- 核心欄位：`email`, `role`, `updated_by`
|
||
- `principal_usage_daily`
|
||
- 每日用量統計
|
||
- 核心欄位：`message_count`, `input_tokens`, `output_tokens`, `total_tokens`, `last_model`
|
||
- `admin_audit_logs`
|
||
- 管理操作審計記錄
|
||
|
||
---
|
||
|
||
## 2. 目前已確認存在的治理能力
|
||
|
||
### 2.1 identity / principal 治理
|
||
已確認可做：
|
||
- 查 identities
|
||
- 查 principals
|
||
- force bind identity → principal
|
||
- unbind identity
|
||
- block / unblock identity
|
||
- resend verification email
|
||
|
||
對應 API：
|
||
- `GET /api/admin/verification/identities`
|
||
- `GET /api/admin/verification/principals`
|
||
- `POST /api/admin/verification/force-bind`
|
||
- `POST /api/admin/verification/unbind`
|
||
- `POST /api/admin/verification/block`
|
||
- `POST /api/admin/verification/unblock`
|
||
- `POST /api/admin/verification/resend`
|
||
|
||
### 2.2 dashboard role / 權限治理
|
||
已確認可做：
|
||
- 查目前 session 的 verification role
|
||
- 查角色名單
|
||
- 指派角色
|
||
|
||
對應 API：
|
||
- `GET /api/admin/verification/role`
|
||
- `GET /api/admin/verification/roles`
|
||
- `POST /api/admin/verification/roles`
|
||
|
||
角色等級：
|
||
- `viewer`
|
||
- `operator`
|
||
- `admin`
|
||
|
||
### 2.3 quota / model / usage 治理
|
||
已確認可做：
|
||
- 查 quota policies
|
||
- 寫 quota policies
|
||
- 查 model policies
|
||
- 寫 model policies
|
||
- 查 principal 每日 usage
|
||
|
||
對應 API：
|
||
- `GET /api/admin/quota-policies`
|
||
- `POST /api/admin/quota-policies`
|
||
- `GET /api/admin/model-policies`
|
||
- `POST /api/admin/model-policies`
|
||
- `GET /api/admin/principal-usage`
|
||
|
||
### 2.4 audit 治理
|
||
已確認可做：
|
||
- 查最近治理操作 audit log
|
||
|
||
對應 API：
|
||
- `GET /api/admin/verification/audit`
|
||
|
||
---
|
||
|
||
## 3. 目前已被測試釘住的事實
|
||
|
||
由 `tests/hermes_cli/test_web_verification_admin.py` 已確認：
|
||
|
||
- force-bind 後，identity list 查得到綁定結果
|
||
- unbind 後，state 會回到 `new`
|
||
- resend verification endpoint 會實際走寄信流程
|
||
- public verify endpoint 可接受 token
|
||
- loopback 模式下，role endpoint 預設回 `admin`
|
||
- dashboard role assignment 可 round-trip
|
||
- quota policy / model policy 可 round-trip
|
||
- principal usage 可累積並查回 email 與 limit
|
||
- principals endpoint 可查到某 principal 底下有哪些 identities
|
||
- audit endpoint 可查到 `force_bind_identity`
|
||
|
||
由 `tests/gateway/test_principal_profile_routing_phase1.py` 已確認：
|
||
- verified principal 可穩定映射到對應 principal profile
|
||
- `principal_profile_map.json` 會寫入 mapping
|
||
- live bound email guard 會擋下錯誤系統 handoff
|
||
|
||
由 `tests/gateway/test_verified_email_handoff_guard_helpers.py` 已確認：
|
||
- Telegram / OpenWebUI 的 verified-email handoff guard 都會做 live 綁定確認
|
||
- 只有使用者明確指定其他 email 時，才可 override
|
||
|
||
## 3.1 本次實跑測試發現的現況警示
|
||
|
||
本次我另外實跑了：
|
||
|
||
```bash
|
||
venv/bin/pytest -q \
|
||
tests/hermes_cli/test_web_verification_admin.py \
|
||
tests/gateway/test_verified_email_handoff_guard_helpers.py
|
||
```
|
||
|
||
結果：`13 passed`
|
||
|
||
再加上：
|
||
|
||
```bash
|
||
venv/bin/pytest -q tests/gateway/test_principal_profile_routing_phase1.py
|
||
```
|
||
|
||
目前已通過，代表：
|
||
- `GatewayConfig` 已接上 `principal_profile_routing`
|
||
- `GatewayConfig` 已接上 `principal_profile_map_path`
|
||
- verified source 進入 `_handle_message(...)` 時，會在 session lookup 前先吃到 principal profile routing
|
||
- verified source 也已納入授權判定，不會先死在 unauthorized 分支
|
||
|
||
所以更精確的現況應寫成：
|
||
- **principal profile routing 的輔助模組、config 接線、以及 phase1 測試目前已打通**
|
||
- **它現在可視為健康功能，但屬高耦合路徑：一旦改 config / authz / run / principal mapping 任一端，都要重跑 phase1 測試**
|
||
|
||
---
|
||
|
||
## 4. 目前不要誤判成「已完整存在」的能力
|
||
|
||
這幾點要特別小心，不然以後很容易又踩坑：
|
||
|
||
### 4.1 quota policy ≠ 已完整 runtime enforcement
|
||
目前我在 live code 裡確認到的是：
|
||
- policy 可存
|
||
- usage 可記
|
||
- admin 可查
|
||
|
||
但我**沒有把它寫成「所有 gateway runtime path 都已經會依 quota 強制拒絕」**，因為這次檢查沒有看到足夠證據可以這樣宣稱。
|
||
|
||
所以比較準確的描述是：
|
||
- 現況已具備 **治理資料層、查詢層、對帳層**
|
||
- 若要保證 **強制執行層** 無誤，仍需額外補 runtime 驗證與測試矩陣
|
||
|
||
### 4.2 model policy ≠ 已完整 routing enforcement
|
||
同理：
|
||
- `allowed_models` / `default_model` 已可保存與查詢
|
||
- 但若要聲稱「某 principal 一定只能用某些模型」，仍需 runtime enforcement 證據
|
||
|
||
### 4.3 有 admin API ≠ 前端 UI 全部可用
|
||
我這次有在 `web/src/lib/api.ts` 看到 dashboard 是一個 **machine-level management surface** 的設定，也看得到一般 dashboard/messaging/platform 管理 API。
|
||
|
||
但對於上述 governance API：
|
||
- 我沒有在這次檢查中找到足夠明確的前端頁面證據，能證明這些治理能力全部已有完整 SPA 操作頁
|
||
|
||
所以務實說法是：
|
||
- **governance 後端 API 已存在且有測試覆蓋**
|
||
- **前端是否完整提供這些治理操作，需要再做一次 UI 對照盤點**
|
||
|
||
---
|
||
|
||
## 5. 目前管理平台能力盤點（保守版說法）
|
||
|
||
如果要寫給未來維護者，我建議用這種保守但準確的說法：
|
||
|
||
### 5.1 已確認的後端治理能力
|
||
- 身分綁定治理
|
||
- principal 治理
|
||
- verification resend
|
||
- dashboard role 治理
|
||
- quota / model policy 治理
|
||
- principal usage 查詢
|
||
- admin audit 查詢
|
||
|
||
### 5.2 已確認的一般管理平台能力
|
||
從 `web/src/lib/api.ts` 可看出 dashboard 還有這些一般管理能力：
|
||
- management profile scope 切換
|
||
- skills / toolsets 管理
|
||
- messaging platforms 管理
|
||
- Telegram / WhatsApp onboarding
|
||
- gateway restart / Hermes update / action status
|
||
- dashboard plugins 管理
|
||
- OAuth provider 管理
|
||
|
||
### 5.3 尚需另外盤點 / 驗證的部分
|
||
- governance 專用前端頁面是否完整存在
|
||
- 權限畫面是否有完整角色操作 UI
|
||
- quota / model / usage 是否已有完整表格與編輯互動
|
||
- admin audit 是否已有前端可視化
|
||
|
||
---
|
||
|
||
## 6. 更新後必做 governance smoke
|
||
|
||
每次 Hermes update、gateway restart、或改動 `gateway/user_verification.py` / `hermes_cli/web_server.py` 後，至少確認：
|
||
|
||
### 6.1 API / data smoke
|
||
- [ ] `GET /api/admin/verification/role`
|
||
- [ ] `GET /api/admin/verification/identities`
|
||
- [ ] `GET /api/admin/verification/principals`
|
||
- [ ] `GET /api/admin/quota-policies`
|
||
- [ ] `GET /api/admin/model-policies`
|
||
- [ ] `GET /api/admin/principal-usage`
|
||
- [ ] `GET /api/admin/verification/audit`
|
||
|
||
### 6.2 行為 smoke
|
||
- [ ] force-bind 一筆測試 identity 後查得到
|
||
- [ ] role assignment round-trip 正常
|
||
- [ ] quota policy round-trip 正常
|
||
- [ ] model policy round-trip 正常
|
||
- [ ] usage 仍會隨一次真實對話累積
|
||
- [ ] Telegram / OpenWebUI / LINE 的 live bound-email guard 仍正常
|
||
- [ ] principal profile mapping 未漂移
|
||
|
||
---
|
||
|
||
## 7. 推薦後續補件
|
||
|
||
接下來若要把這包文件做得更抗更新，我建議再補兩份：
|
||
|
||
1. `gateway-change-impact-checklist.md`
|
||
- 改哪個模組，就強制勾哪些治理/交付驗收
|
||
|
||
2. `gateway-admin-ui-inventory.md`
|
||
- 真正盤點：
|
||
- 哪些治理能力只有 API
|
||
- 哪些已有完整 UI
|
||
- 哪些只有半套頁面
|
||
|
||
這樣未來就不會再發生：
|
||
- 以為有 quota 治理，其實只有表
|
||
- 以為有權限治理，其實 UI 沒接
|
||
- 以為有管理平台功能，其實只有 API 還沒露出來
|