From 72d79205341f625bb2da0c25808714367c814890 Mon Sep 17 00:00:00 2001
From: zenfun <zenfun510@gmail.com>
Date: Wed, 24 Dec 2025 15:12:06 +0800
Subject: [PATCH] doc: add admin panel map

---
 docs/admin-panel-mapping.md | 53 +++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 docs/admin-panel-mapping.md

diff --git a/docs/admin-panel-mapping.md b/docs/admin-panel-mapping.md
new file mode 100644
index 0000000..aea34ce
--- /dev/null
+++ b/docs/admin-panel-mapping.md
@@ -0,0 +1,53 @@
+# Admin Panel Mapping (Admin API)
+
+本表用于前端管理面板的「页面与接口对照」与基础交互流程说明。
+鉴权统一使用：`Authorization: Bearer <EZ_ADMIN_TOKEN>`。
+
+---
+
+## 页面与接口对照表
+
+| 页面 | 接口 | 交互要点 |
+| --- | --- | --- |
+| Dashboard / 全局概览 | `GET /admin/stats` | 展示全局统计指标 |
+| 操作日志 | `GET /admin/operation-logs` | 管理员操作审计 |
+| 租户（Masters）列表 | `GET /admin/masters` `POST /admin/masters` `POST /admin/masters/batch` | 列表 + 批量操作 |
+| 租户详情 | `GET /admin/masters/:id` `PUT /admin/masters/:id` `DELETE /admin/masters/:id` | 查看/编辑/删除 |
+| 租户实时监控 | `GET /admin/masters/:id/realtime` | 实时 QPS/用量 |
+| 租户状态管理 | `POST /admin/masters/:id/manage` | 冻结/解冻/状态切换 |
+| 租户访问权限 | `GET /admin/masters/:id/access` `PUT /admin/masters/:id/access` | 设置 namespaces/能力 |
+| 子 Key 颁发 | `POST /admin/masters/:id/keys` | 发放子 Key |
+| 子 Key 权限 | `GET /admin/keys/:id/access` `PUT /admin/keys/:id/access` | Key 级别访问控制 |
+| Namespaces | `GET /admin/namespaces` `POST /admin/namespaces` `GET /admin/namespaces/:id` `PUT /admin/namespaces/:id` `DELETE /admin/namespaces/:id` | 命名空间 CRUD |
+| Provider Groups | `GET /admin/provider-groups` `POST /admin/provider-groups` `GET /admin/provider-groups/:id` `PUT /admin/provider-groups/:id` `DELETE /admin/provider-groups/:id` | 上游组定义 |
+| API Keys | `GET /admin/api-keys` `POST /admin/api-keys` `GET /admin/api-keys/:id` `PUT /admin/api-keys/:id` `DELETE /admin/api-keys/:id` `POST /admin/api-keys/batch` | group_id 过滤、批量操作 |
+| Bindings | `GET /admin/bindings` `POST /admin/bindings` `GET /admin/bindings/:id` `PUT /admin/bindings/:id` `DELETE /admin/bindings/:id` `POST /admin/bindings/batch` | bindingKey -> group_id，多候选 + weight |
+| Models | `GET /admin/models` `POST /admin/models` `PUT /admin/models/:id` `DELETE /admin/models/:id` `POST /admin/models/batch` | 模型能力表 |
+| Feature Flags | `GET /admin/features` `PUT /admin/features` | DP 开关、日志策略等 |
+| Model Registry | `GET /admin/model-registry/status` `POST /admin/model-registry/check` `POST /admin/model-registry/refresh` `POST /admin/model-registry/rollback` | 外部模型注册表 |
+| 日志查询 | `GET /admin/logs` `DELETE /admin/logs` | 查询/清理 |
+| 日志统计 | `GET /admin/logs/stats` | 日志统计视图 |
+| 日志 Webhook | `GET /admin/logs/webhook` `PUT /admin/logs/webhook` | 告警配置 |
+| 同步快照 | `POST /admin/sync/snapshot` | 手动触发 CP -> Redis |
+
+---
+
+## 交互流程
+
+### 上游配置上线
+1. `POST /admin/provider-groups` 创建 ProviderGroup。
+2. `POST /admin/api-keys` 绑定 key（必要时多条）。
+3. `POST /admin/bindings` 建立 `bindingKey = namespace.public_model -> group_id`（可多条绑定 + weight）。
+4. `POST /admin/models` 或 `POST /admin/model-registry/refresh` 更新能力表（能力校验基于 bindingKey）。
+
+### 租户开通
+1. `POST /admin/masters` 创建租户。
+2. `PUT /admin/masters/:id/access` 设置可见 namespaces。
+3. `POST /admin/masters/:id/keys` 签发子 Key。
+4. `PUT /admin/keys/:id/access` 细化 Key 的访问范围（可选）。
+
+### 日常运维
+1. `GET /admin/logs` + `GET /admin/logs/stats` 查询异常与用量。
+2. `PUT /admin/logs/webhook` 配告警；`DELETE /admin/logs` 清理。
+3. `GET /admin/stats`、`GET /admin/masters/:id/realtime` 查看实时指标。
+4. `PUT /admin/features` 调整 DP 开关；必要时 `POST /admin/sync/snapshot` 手动同步。