diff --git a/Docs/API-渠道合作伙伴平台文档.md b/Docs/API-渠道合作伙伴平台文档.md deleted file mode 100644 index fb455a2..0000000 --- a/Docs/API-渠道合作伙伴平台文档.md +++ /dev/null @@ -1,1383 +0,0 @@ -# 渠道合作伙伴平台 API 接口文档 - -> 版本: v1.1 -> 更新时间: 2026-01-06 -> 基础路径: `/api` - ---- - -## 目录 - -1. [概述](#概述) -2. [认证模块](#一认证模块) -3. [租户管理模块](#二租户管理模块) -4. [资源管理模块](#三资源管理模块) -5. [资源申请模块](#四资源申请模块) -6. [平台 Agent 管理模块](#五平台-agent-管理模块) -7. [计费统计模块](#六计费统计模块) -8. [管理员管理模块](#七管理员管理模块) -9. [数据模型](#八数据模型) -10. [错误码](#九错误码) -11. [权限矩阵](#十权限矩阵) - ---- - -## 概述 - -### 平台信息 - -| 项目 | 说明 | -|------|------| -| 平台名称 | 渠道合作伙伴平台 (Channel Partner Portal) | -| 访问路径 | `/channel/dashboard/` | -| 登录入口 | `/channel/login/` | -| API 基础路径 | `/api` | - -### 目标用户 - -| 角色 | 角色标识 | 说明 | -|------|----------|------| -| 超级管理员 | `super_admin` | 平台超级管理员，可操作所有渠道（需指定 channel_id） | -| 渠道管理员 | `channel_admin` | 渠道的主管理员，拥有完整权限 | -| 计费管理员 | `billing_admin` | 渠道下的计费管理员，管理租户计费 | -| 运营管理员 | `operations_admin` | 渠道下的运营管理员，只读权限 | - -### ⚠️ 超级管理员特殊说明 - -超级管理员（`super_admin`）操作渠道端接口时，**必须提供 `channel_id` 参数**： - -| 接口类型 | channel_id 参数位置 | -|---------|-------------------| -| GET 请求 | Query 参数 `?channel_id=xxx` | -| POST 请求（创建租户） | 请求体 `channelId` 字段 | -| PUT/DELETE 请求 | Query 参数 `?channel_id=xxx` | - -**错误响应示例**（超级管理员未提供 channel_id）: -```json -{ - "detail": "超级管理员必须提供 channel_id 参数" -} -``` - -### 认证方式 - -所有 API 请求需要在 Header 中携带 JWT Token： - -``` -Authorization: Bearer -``` - -### 通用响应格式 - -**成功响应**: -```json -{ - "success": true, - "data": { ... }, - "message": "操作成功" -} -``` - -**错误响应**: -```json -{ - "success": false, - "error": { - "code": "ERROR_CODE", - "message": "错误描述" - } -} -``` - ---- - -## 一、认证模块 - -### 1.1 渠道登录 - -**接口**: `POST /api/auth/login` - -**描述**: 渠道合作伙伴通过邮箱和密码登录系统 - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| email | string | 是 | 邮箱地址 | -| password | string | 是 | 密码 | -| role | string | 是 | 固定值 `"channel"` | - -**请求示例**: -```json -{ - "email": "channel@example.com", - "password": "password123", - "role": "channel" -} -``` - -**响应示例**: -```json -{ - "success": true, - "data": { - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", - "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", - "user": { - "id": "uuid-string", - "name": "渠道名称", - "email": "channel@example.com", - "role": "channel_admin", - "channelId": "uuid-string" - } - } -} -``` - -**Token 存储**: 前端应将 token 存储在 `channel_token` (localStorage + Cookie) - ---- - -### 1.2 退出登录 - -**接口**: `POST /api/auth/logout` - -**描述**: 清除认证状态，退出系统 - -**请求头**: 需要 Authorization - -**响应示例**: -```json -{ - "success": true, - "message": "登出成功" -} -``` - ---- - -### 1.3 刷新令牌 - -**接口**: `POST /api/auth/refresh` - -**描述**: 刷新访问令牌 - -**请求头**: 需要 Authorization - -**响应示例**: -```json -{ - "success": true, - "data": { - "token": "new-jwt-token", - "refreshToken": "new-refresh-token" - } -} -``` - ---- - -### 1.4 修改密码 - -**接口**: `PUT /api/auth/password` - -**描述**: 修改当前用户密码 - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| old_password | string | 是 | 旧密码 | -| new_password | string | 是 | 新密码 | - -**响应示例**: -```json -{ - "success": true, - "message": "密码修改成功" -} -``` - ---- - -## 二、租户管理模块 - -### 2.1 获取租户列表 - -**接口**: `GET /api/channel/tenants` - -**描述**: 获取渠道下的所有租户列表 - -**权限**: `view:tenants` (super_admin, channel_admin, billing_admin, operations_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID（超级管理员必填，其他管理员自动使用所属渠道） | - -**响应示例**: -```json -{ - "success": true, - "data": { - "tenants": [ - { - "id": "uuid-string", - "name": "租户名称", - "email": "tenant@example.com", - "subscriptionTier": "professional", - "balance": 1000.00, - "creditLimit": 500.00, - "status": "active", - "createdAt": "2026-01-01T00:00:00Z" - } - ] - } -} -``` - ---- - -### 2.2 创建租户 - -**接口**: `POST /api/channel/tenants/create` - -**描述**: 为渠道创建新的租户账号 - -**权限**: `manage:tenants` (super_admin, channel_admin, billing_admin) - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| name | string | 是 | 租户名称/公司名称 | -| email | string | 是 | 登录邮箱 | -| password | string | 是 | 登录密码 | -| subscriptionTier | string | 否 | 订阅等级: `free`/`pro`/`enterprise`，默认 `free` | -| channelId | string | 超级管理员必填 | 渠道ID（超级管理员必填，其他管理员自动使用所属渠道） | - -**请求示例**: -```json -{ - "name": "新租户公司", - "email": "newtenant@example.com", - "password": "securePassword123", - "subscriptionTier": "pro" -} -``` - -**超级管理员请求示例**: -```json -{ - "name": "新租户公司", - "email": "newtenant@example.com", - "password": "securePassword123", - "subscriptionTier": "pro", - "channelId": "8a9958a4-3d53-469b-923f-c3cb21cfc675" -} -``` - -**响应示例**: -```json -{ - "success": true, - "data": { - "id": "uuid-string", - "name": "新租户公司", - "email": "newtenant@example.com" - }, - "message": "租户创建成功" -} -``` - ---- - -### 2.3 删除租户 - -**接口**: `DELETE /api/channel/tenants/{tenant_id}` - -**描述**: 删除租户（软删除，标记为 inactive） - -**权限**: `manage:tenants` (super_admin, channel_admin, billing_admin) - -**路径参数**: - -| 参数 | 类型 | 说明 | -|------|------|------| -| tenant_id | string | 租户 ID | - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**注意**: 如果租户还有余额，需要先处理余额后才能删除 - -**响应示例**: -```json -{ - "success": true, - "data": { - "id": "uuid-string", - "name": "租户名称" - }, - "message": "租户已删除" -} -``` - ---- - -### 2.4 更新租户状态 - -**接口**: `PUT /api/channel/tenants/{tenant_id}/status` - -**描述**: 更新租户状态 - -**权限**: `manage:tenants` (super_admin, channel_admin, billing_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| status | string | 是 | 状态: active/inactive/suspended | - -**状态说明**: - -| 状态 | 说明 | -|------|------| -| active | 正常使用 | -| inactive | 已停用（软删除） | -| suspended | 暂停使用（临时停用，可恢复） | - -**响应示例**: -```json -{ - "success": true, - "data": { - "tenantId": "uuid-string", - "name": "租户名称", - "oldStatus": "active", - "newStatus": "suspended" - }, - "message": "租户状态已更新为 suspended" -} -``` - ---- - -### 2.5 分配资源给租户 - -**接口**: `PUT /api/channel/tenants/{tenant_id}/resources` - -**描述**: 为租户分配 Agent 配额和模型配额 - -**权限**: `manage:resources` (super_admin, channel_admin, billing_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| agents | array | 否 | Agent 配额列表 | -| models | array | 否 | 模型配额列表 | -| customAgentQuota | object | 否 | 自定义 Agent 资源配额 | - -**agents 数组元素**: - -| 字段 | 类型 | 说明 | -|------|------|------| -| agentId | string | Agent ID | -| quantity | integer | 分配数量 | - -**models 数组元素**: - -| 字段 | 类型 | 说明 | -|------|------|------| -| modelName | string | 模型名称，如 gpt-4, claude-3 | -| rpm | integer | 每分钟请求数限制 | -| tpm | integer | 每分钟令牌数限制 | - -**customAgentQuota 对象**: - -| 字段 | 类型 | 说明 | -|------|------|------| -| cpuQuota | number | CPU 配额（核心数） | -| memoryQuota | number | 内存配额（GB） | - -**请求示例**: -```json -{ - "agents": [ - { "agentId": "agent-uuid", "quantity": 5 } - ], - "models": [ - { "modelName": "gpt-4", "rpm": 100, "tpm": 100000 } - ], - "customAgentQuota": { - "cpuQuota": 4.0, - "memoryQuota": 8.0 - } -} -``` - -**响应示例**: -```json -{ - "success": true, - "message": "资源分配成功" -} -``` - ---- - -### 2.6 为租户充值 - -**接口**: `POST /api/channel/tenants/{tenant_id}/recharge` - -**描述**: 为租户账户充值余额 - -**权限**: `manage:billing` (super_admin, channel_admin, billing_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| amount | number | 是 | 充值金额（USD） | - -**快捷金额建议**: $50, $100, $500, $1000 - -**请求示例**: -```json -{ - "amount": 500.00 -} -``` - -**响应示例**: -```json -{ - "success": true, - "data": { - "tenantId": "uuid-string", - "newBalance": 1500.00, - "rechargeAmount": 500.00 - } -} -``` - ---- - -### 2.7 设置授信额度 - -**接口**: `PUT /api/channel/tenants/{tenant_id}/credit` - -**描述**: 设置租户授信额度，允许租户在余额不足时继续使用服务 - -**权限**: `manage:billing` (super_admin, channel_admin, billing_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| creditLimit | number | 是 | 授信额度（USD） | - -**快捷金额建议**: $500, $1000, $5000, $10000 - -**响应示例**: -```json -{ - "success": true, - "data": { - "tenantId": "uuid-string", - "creditLimit": 1000.00 - } -} -``` - ---- - -### 2.8 更新计费设置 - -**接口**: `PUT /api/channel/tenants/{tenant_id}/billing` - -**描述**: 设置租户的订阅层级和折扣比例 - -**权限**: `manage:billing` (super_admin, channel_admin, billing_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| subscriptionTier | string | 是 | 订阅层级: `free`/`pro`/`enterprise` | -| discount | number | 是 | 折扣比例 (0-100) | - -**订阅层级说明**: - -| 层级 | 价格 | 说明 | -|------|------|------| -| free | $0/月 | 基础功能 | -| pro | $1,800/月 | 适合中小企业 | -| enterprise | $3,200/月 | 无限制 | - -**响应示例**: -```json -{ - "success": true, - "message": "计费设置更新成功" -} -``` - ---- - -### 2.9 更新租户权限 - -**接口**: `PUT /api/channel/tenants/{tenant_id}/permissions` - -**描述**: 配置租户可使用的功能权限 - -**权限**: `manage:tenants` (super_admin, channel_admin, billing_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| permissions | array | 是 | 权限列表 | - -**可配置权限**: - -| 权限 | 说明 | -|------|------| -| use:platform_agents | 使用平台 Agent | -| use:custom_agents | 使用自定义 Agent | -| create:agents | 创建 Agent | -| read:billing | 查看计费信息 | -| export:data | 导出数据 | - -**请求示例**: -```json -{ - "permissions": ["use:platform_agents", "use:custom_agents", "read:billing"] -} -``` - -**响应示例**: -```json -{ - "success": true, - "data": { - "tenantId": "uuid-string", - "name": "租户名称", - "permissions": ["use:platform_agents", "use:custom_agents", "read:billing"] - }, - "message": "租户权限已更新" -} -``` - ---- - -### 2.10 重置租户密码 - -**接口**: `PUT /api/channel/tenants/{tenant_id}/password` - -**描述**: 管理员为租户重置密码 - -**权限**: `manage:tenants` (super_admin, channel_admin, billing_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| newPassword | string | 是 | 新密码 | - -**响应示例**: -```json -{ - "success": true, - "data": { - "tenantId": "uuid-string", - "name": "租户名称" - }, - "message": "租户密码已重置" -} -``` - ---- - -### 2.11 获取租户自定义 Agent 配额 - -**接口**: `GET /api/channel/tenants/{tenant_id}/custom-agent-quota` - -**描述**: 获取租户的自定义 Agent 配额使用情况 - -**权限**: `view:resources` (super_admin, channel_admin, billing_admin, operations_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**响应示例**: -```json -{ - "success": true, - "data": { - "tenantId": "uuid-string", - "tenantName": "租户名称", - "cpuQuota": 8.0, - "memoryQuota": 16.0, - "cpuUsed": 2.5, - "memoryUsed": 4.0, - "cpuRemaining": 5.5, - "memoryRemaining": 12.0, - "agentCount": 3 - } -} -``` - ---- - -## 三、资源管理模块 - -### 3.1 获取模型供应商列表 - -**接口**: `GET /api/channel/providers` - -**描述**: 获取所有可用的模型供应商列表，并标注该渠道是否已获得授权 - -**权限**: `view:resources` (channel_admin, billing_admin, operations_admin) - -**响应示例**: -```json -{ - "success": true, - "data": { - "providers": [ - { - "id": "uuid-string", - "name": "OpenAI GPT-4", - "provider": "openai", - "supportedModels": ["gpt-4", "gpt-4-turbo", "gpt-3.5-turbo"], - "rpm": 1000, - "tpm": 100000, - "status": "active", - "hasAccess": true, - "accessStatus": "active", - "rpmLimit": 500, - "tpmLimit": 50000, - "pendingApplication": false - }, - { - "id": "uuid-string", - "name": "Anthropic Claude", - "provider": "anthropic", - "supportedModels": ["claude-3-opus", "claude-3-sonnet"], - "rpm": 500, - "tpm": 50000, - "status": "active", - "hasAccess": false, - "accessStatus": null, - "rpmLimit": null, - "tpmLimit": null, - "pendingApplication": true - } - ] - } -} -``` - ---- - -### 3.2 获取已授权供应商列表 - -**接口**: `GET /api/channel/providers/access` - -**描述**: 获取渠道已获得授权的供应商列表 - -**权限**: `view:resources` (channel_admin, billing_admin, operations_admin) - -**响应示例**: -```json -{ - "success": true, - "data": { - "accessList": [ - { - "id": "uuid-string", - "providerId": "uuid-string", - "providerName": "OpenAI GPT-4", - "provider": "openai", - "supportedModels": ["gpt-4", "gpt-4-turbo"], - "status": "active", - "rpmLimit": 500, - "tpmLimit": 50000, - "approvedAt": "2026-01-01T00:00:00Z", - "expiresAt": null - } - ] - } -} -``` - ---- - -### 3.3 查看可用平台 Agent - -**接口**: `GET /api/channel/available-platform-agents` - -**描述**: 查看所有可用的平台 Agent 模板，以及渠道的配额情况 - -**权限**: `view:resources` (channel_admin, billing_admin, operations_admin) - -**响应示例**: -```json -{ - "success": true, - "data": { - "templates": [ - { - "name": "gpt-assistant", - "displayName": "GPT 智能助手", - "description": "基于 GPT 的通用智能助手，支持多轮对话和任务执行", - "category": "assistant", - "version": "1.0.0", - "cpuRequest": "100m", - "cpuLimit": "500m", - "memoryRequest": "128Mi", - "memoryLimit": "512Mi", - "imageUrl": "acr.taiji-ai.com/agents/gpt-assistant:latest", - "status": "available", - "hasAccess": true, - "podQuota": 10, - "podUsed": 3, - "podRemaining": 7, - "pendingApplication": false - }, - { - "name": "code-reviewer", - "displayName": "代码审查助手", - "description": "专业的代码审查 Agent，支持多种编程语言", - "category": "development", - "version": "1.0.0", - "cpuRequest": "200m", - "cpuLimit": "1000m", - "memoryRequest": "256Mi", - "memoryLimit": "1Gi", - "imageUrl": "acr.taiji-ai.com/agents/code-reviewer:latest", - "status": "available", - "hasAccess": false, - "podQuota": 0, - "podUsed": 0, - "podRemaining": 0, - "pendingApplication": true - } - ] - } -} -``` - ---- - -## 四、资源申请模块 - -### 4.1 申请模型供应商 - -**接口**: `POST /api/channel/providers/apply` - -**描述**: 申请使用某个模型供应商，需要管理员审批 - -**权限**: `view:applications` (channel_admin, billing_admin, operations_admin) - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| providerId | string | 是 | 供应商 ID | -| requestedRpm | integer | 是 | 申请的 RPM 配额 | -| requestedTpm | integer | 是 | 申请的 TPM 配额 | -| reason | string | 否 | 申请理由 | - -**请求示例**: -```json -{ - "providerId": "uuid-string", - "requestedRpm": 500, - "requestedTpm": 50000, - "reason": "业务扩展需要更多模型调用配额" -} -``` - -**响应示例**: -```json -{ - "success": true, - "data": { - "id": "uuid-string", - "providerId": "uuid-string", - "providerName": "OpenAI GPT-4", - "status": "pending" - }, - "message": "申请已提交，等待管理员审批" -} -``` - ---- - -### 4.2 获取供应商申请列表 - -**接口**: `GET /api/channel/providers/applications` - -**描述**: 获取渠道的供应商申请记录 - -**权限**: `view:applications` (channel_admin, billing_admin, operations_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| status | string | 否 | 状态筛选: pending/approved/rejected | - -**响应示例**: -```json -{ - "success": true, - "data": { - "applications": [ - { - "id": "uuid-string", - "providerId": "uuid-string", - "providerName": "OpenAI GPT-4", - "requestedRpm": 500, - "requestedTpm": 50000, - "reason": "业务扩展需要", - "status": "pending", - "createdAt": "2026-01-01T00:00:00Z", - "reviewedAt": null, - "reviewReason": null - } - ] - } -} -``` - ---- - -### 4.3 申请平台 Agent - -**接口**: `POST /api/channel/applications/platform-agents` - -**描述**: 申请使用某个平台 Agent 模板，需要管理员审批 - -**权限**: `view:applications` (channel_admin, billing_admin, operations_admin) - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| templateName | string | 是 | 模板名称 | -| requestedPodQuota | integer | 是 | 申请的 Pod 配额 | -| reason | string | 否 | 申请理由 | - -**请求示例**: -```json -{ - "templateName": "gpt-assistant", - "requestedPodQuota": 10, - "reason": "需要为多个租户提供智能助手服务" -} -``` - -**响应示例**: -```json -{ - "success": true, - "data": { - "id": "uuid-string", - "templateName": "gpt-assistant", - "templateDisplayName": "GPT 智能助手", - "requestedPodQuota": 10, - "status": "pending" - }, - "message": "申请已提交，等待管理员审批" -} -``` - ---- - -### 4.4 获取平台 Agent 申请列表 - -**接口**: `GET /api/channel/applications/platform-agents` - -**描述**: 获取渠道的平台 Agent 申请记录 - -**权限**: `view:applications` (channel_admin, billing_admin, operations_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| status | string | 否 | 状态筛选: pending/approved/rejected | - -**响应示例**: -```json -{ - "success": true, - "data": { - "applications": [ - { - "id": "uuid-string", - "channelId": "uuid-string", - "channelName": "渠道名称", - "resourceType": "platform_agent", - "templateName": "gpt-assistant", - "templateDisplayName": "GPT 智能助手", - "requestedPodQuota": 10, - "approvedPodQuota": null, - "reason": "需要为多个租户提供服务", - "status": "pending", - "reviewReason": null, - "reviewedAt": null, - "createdAt": "2026-01-01T00:00:00Z" - } - ] - } -} -``` - ---- - -### 4.5 通用资源申请 - -**接口**: `POST /api/channel/resources/apply` - -**描述**: 通用资源申请接口（模型或 Agent） - -**权限**: `view:applications` (channel_admin, billing_admin, operations_admin) - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| type | string | 是 | 申请类型: model/agent | -| modelName | string | 否 | 模型名称（type=model 时必填） | -| rpm | integer | 否 | RPM 配额（type=model 时） | -| tpm | integer | 否 | TPM 配额（type=model 时） | -| agentType | string | 否 | Agent 类型（type=agent 时必填） | -| quantity | integer | 否 | 申请数量（type=agent 时） | -| reason | string | 否 | 申请理由 | - -**响应示例**: -```json -{ - "success": true, - "data": { - "id": "uuid-string", - "status": "pending" - }, - "message": "申请已提交，等待审批" -} -``` - ---- - -## 五、平台 Agent 管理模块 - -### 5.1 查看渠道平台 Agent 配额 - -**接口**: `GET /api/channel/platform-agents` - -**描述**: 查看渠道已获得的所有平台 Agent 配额信息 - -**权限**: `view:resources` (channel_admin, billing_admin, operations_admin) - -**响应示例**: -```json -{ - "success": true, - "data": { - "quotas": [ - { - "templateName": "gpt-assistant", - "templateDisplayName": "GPT 智能助手", - "podQuota": 10, - "podUsed": 3, - "podRemaining": 7, - "allocatedAt": "2026-01-01T00:00:00Z" - } - ] - } -} -``` - ---- - -### 5.2 分配平台 Agent 给租户 - -**接口**: `POST /api/channel/tenants/{tenant_id}/platform-agents` - -**描述**: 将渠道的平台 Agent 配额分配给租户 - -**权限**: `manage:resources` (super_admin, channel_admin, billing_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| templateName | string | 是 | 模板名称 | -| podQuota | integer | 是 | 分配的 Pod 配额 | - -**响应示例**: -```json -{ - "success": true, - "data": { - "tenantId": "uuid-string", - "tenantName": "租户名称", - "templateName": "gpt-assistant", - "templateDisplayName": "GPT 智能助手", - "podQuota": 3 - }, - "message": "平台 Agent 配额分配成功" -} -``` - ---- - -### 5.3 查看租户平台 Agent 使用情况 - -**接口**: `GET /api/channel/tenants/{tenant_id}/platform-agents/usage` - -**描述**: 查看租户的平台 Agent 配额和使用情况 - -**权限**: `view:resources` (super_admin, channel_admin, billing_admin, operations_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**响应示例**: -```json -{ - "success": true, - "data": { - "tenantId": "uuid-string", - "tenantName": "租户名称", - "quotas": [ - { - "templateName": "gpt-assistant", - "templateDisplayName": "GPT 智能助手", - "podQuota": 3, - "podUsed": 1, - "podRemaining": 2, - "allocatedAt": "2026-01-01T00:00:00Z" - } - ] - } -} -``` - ---- - -## 六、计费统计模块 - -### 6.1 获取计费统计 - -**接口**: `GET /api/channel/billing/stats` - -**描述**: 获取渠道下租户的计费统计数据 - -**权限**: `view:billing` (channel_admin, billing_admin, operations_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| startTime | string | 是 | 开始时间 (ISO 8601) | -| endTime | string | 是 | 结束时间 (ISO 8601) | -| tenantName | string | 否 | 按租户名称筛选 | -| minCalls | integer | 否 | 最小调用次数 | -| maxCalls | integer | 否 | 最大调用次数 | -| export | string | 否 | 导出格式: excel/csv/pdf | - -**响应示例**: -```json -{ - "success": true, - "data": { - "tenantStats": [ - { - "tenantId": "uuid-string", - "tenantName": "租户A", - "calls": 1500, - "totalEU": 150.5, - "totalCost": 75.25 - } - ], - "callRecords": [ - { - "id": "uuid-string", - "timestamp": "2026-01-01T10:30:00Z", - "tenantName": "租户A", - "agentName": "gpt-assistant", - "duration": 120, - "eu": 12.0, - "cost": 6.00 - } - ] - } -} -``` - ---- - -### 6.2 获取 Agent 计费统计 - -**接口**: `GET /api/channel/agent-billing/stats` - -**描述**: 获取渠道的 Agent 使用费用统计 - -**权限**: `view:billing` (channel_admin, billing_admin, operations_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| startTime | string | 是 | 开始时间 (ISO 8601) | -| endTime | string | 是 | 结束时间 (ISO 8601) | -| agentType | string | 否 | Agent 类型: platform/custom | -| templateName | string | 否 | 模板名称 | -| tenantId | string | 否 | 租户 ID | - ---- - -### 6.3 获取 Agent 计费历史 - -**接口**: `GET /api/channel/agent-billing/history` - -**描述**: 获取渠道的 Agent 计费详细记录（分页） - -**权限**: `view:billing` (channel_admin, billing_admin, operations_admin) - -**查询参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| startTime | string | 是 | 开始时间 (ISO 8601) | -| endTime | string | 是 | 结束时间 (ISO 8601) | -| page | integer | 否 | 页码，默认 1 | -| pageSize | integer | 否 | 每页数量，默认 20 | - ---- - -### 6.4 获取租户计费汇总 - -**接口**: `GET /api/channel/agent-billing/tenant-summary` - -**描述**: 获取渠道下各租户的 Agent 计费汇总 - -**权限**: `view:billing` (channel_admin, billing_admin, operations_admin) - ---- - -## 七、管理员管理模块 - -### 7.1 获取管理员列表 - -**接口**: `GET /api/channel/admins` - -**描述**: 获取渠道下的所有管理员 - -**权限**: `view:admins` (channel_admin) - ---- - -### 7.2 创建管理员 - -**接口**: `POST /api/channel/admins/create` - -**描述**: 创建渠道下的管理员 - -**权限**: `manage:admins` (channel_admin) - -**请求参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| name | string | 是 | 管理员姓名 | -| email | string | 是 | 登录邮箱 | -| password | string | 是 | 登录密码 | -| role | string | 是 | 角色: billing_admin/operations_admin | - ---- - -## 八、权限矩阵 - -| 操作 | channel_admin | billing_admin | operations_admin | -|------|---------------|---------------|------------------| -| 查看租户列表 | ✅ | ✅ | ✅ | -| 创建/删除租户 | ✅ | ✅ | ❌ | -| 分配资源 | ✅ | ✅ | ❌ | -| 租户充值 | ✅ | ✅ | ❌ | -| 查看供应商 | ✅ | ✅ | ✅ | -| 申请资源 | ✅ | ✅ | ✅ | -| 查看计费统计 | ✅ | ✅ | ✅ | -| 管理管理员 | ✅ | ❌ | ❌ | - ---- - -## 九、API 接口汇总 - -### 认证相关 - -| 方法 | 路径 | 说明 | -|------|------|------| -| POST | `/api/auth/login` | 用户登录 | -| POST | `/api/auth/logout` | 用户登出 | -| POST | `/api/auth/refresh` | 刷新令牌 | -| PUT | `/api/auth/password` | 修改密码 | - -### 租户管理 - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/api/channel/tenants` | 获取租户列表 | -| POST | `/api/channel/tenants/create` | 创建租户 | -| DELETE | `/api/channel/tenants/{id}` | 删除租户 | -| PUT | `/api/channel/tenants/{id}/status` | 更新状态 | -| PUT | `/api/channel/tenants/{id}/resources` | 分配资源 | -| POST | `/api/channel/tenants/{id}/recharge` | 充值 | -| PUT | `/api/channel/tenants/{id}/credit` | 设置授信 | -| PUT | `/api/channel/tenants/{id}/billing` | 更新计费 | -| PUT | `/api/channel/tenants/{id}/permissions` | 更新权限 | -| PUT | `/api/channel/tenants/{id}/password` | 重置密码 | - -### 资源管理 - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/api/channel/providers` | 获取供应商列表 | -| GET | `/api/channel/providers/access` | 获取已授权供应商 | -| GET | `/api/channel/available-platform-agents` | 获取可用平台 Agent | -| GET | `/api/channel/platform-agents` | 获取渠道 Agent 配额 | - -### 资源申请 - -| 方法 | 路径 | 说明 | -|------|------|------| -| POST | `/api/channel/providers/apply` | 申请供应商 | -| GET | `/api/channel/providers/applications` | 获取申请列表 | -| POST | `/api/channel/applications/platform-agents` | 申请平台 Agent | - -### 计费统计 - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/api/channel/billing/stats` | 获取计费统计 | -| GET | `/api/channel/agent-billing/stats` | Agent 计费统计 | -| GET | `/api/channel/agent-billing/history` | Agent 计费历史 | -| GET | `/api/channel/agent-billing/tenant-summary` | 租户计费汇总 | - -### 管理员管理 - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/api/channel/admins` | 获取管理员列表 | -| POST | `/api/channel/admins/create` | 创建管理员 | - ---- - -## 更新日志 - -### v1.1 (2026-01-06) - -**文档一致性修复**: -- 🔄 修复 `subscriptionTier` 可选值：`professional` → `pro`（与代码一致） -- 🔄 添加超级管理员（`super_admin`）权限说明 -- 🔄 所有租户操作接口添加 `channel_id` 参数说明（超级管理员必填） -- 🔄 更新权限列表，添加 `super_admin` 角色 - -**受影响的接口**: -| 接口 | 变更 | -|------|------| -| `GET /api/channel/tenants` | 添加 `channel_id` 查询参数 | -| `POST /api/channel/tenants/create` | 添加 `channelId` 请求体字段 | -| `DELETE /api/channel/tenants/{id}` | 添加 `channel_id` 查询参数 | -| `PUT /api/channel/tenants/{id}/status` | 添加 `channel_id` 查询参数 | -| `PUT /api/channel/tenants/{id}/resources` | 添加 `channel_id` 查询参数 | -| `POST /api/channel/tenants/{id}/recharge` | 添加 `channel_id` 查询参数 | -| `PUT /api/channel/tenants/{id}/credit` | 添加 `channel_id` 查询参数 | -| `PUT /api/channel/tenants/{id}/billing` | 添加 `channel_id` 查询参数 | -| `PUT /api/channel/tenants/{id}/permissions` | 添加 `channel_id` 查询参数 | -| `PUT /api/channel/tenants/{id}/password` | 添加 `channel_id` 查询参数 | -| `GET /api/channel/tenants/{id}/custom-agent-quota` | 添加 `channel_id` 查询参数 | -| `POST /api/channel/tenants/{id}/platform-agents` | 添加 `channel_id` 查询参数 | -| `GET /api/channel/tenants/{id}/platform-agents/usage` | 添加 `channel_id` 查询参数 | - ---- - -### v1.0 (2026-01-05) - -**初始版本**: -- ✨ 认证模块：登录、登出、刷新令牌、修改密码 -- ✨ 租户管理：创建、删除、状态管理、资源分配、充值、授信 -- ✨ 资源管理：供应商列表、平台 Agent 列表 -- ✨ 资源申请：供应商申请、平台 Agent 申请 -- ✨ 平台 Agent 管理：配额查看、分配给租户、使用情况查询 -- ✨ 计费统计：计费统计、Agent 计费、租户汇总 -- ✨ 管理员管理：列表、创建 - ---- - -*文档生成时间: 2026-01-06* -*基于 MCP Server 代码版本分析* \ No newline at end of file diff --git a/Docs/API-超级管理员控制平台完整接口文档.md b/Docs/API-超级管理员控制平台完整接口文档.md deleted file mode 100644 index c6e56e1..0000000 --- a/Docs/API-超级管理员控制平台完整接口文档.md +++ /dev/null @@ -1,2170 +0,0 @@ -# 管理平台完整API接口文档 - -> **版本**: v1.3.0 -> **更新时间**: 2026-01-06 -> **基础URL**: `http://mcp-server:8000` - ---- - -## 目录 - -1. [认证与授权](#认证与授权) -2. [Agent 类型说明](#agent-类型说明) -3. [概览模块](#概览模块) -4. [渠道管理模块](#渠道管理模块) -5. [资源管理模块](#资源管理模块)（仅模型供应商管理） -6. [资源申请审批模块](#资源申请审批模块) -7. [平台 Agent 管理模块](#平台-agent-管理模块)（Agent 全生命周期管理） -8. [Agent 计费模块](#agent-计费模块) -9. [监控模块](#监控模块)（系统级监控） -10. [计费模块](#计费模块) -11. [设置模块](#设置模块) - ---- - -## 认证与授权 - -### 认证方式 - -所有API请求需要在Header中携带JWT Token： - -``` -Authorization: Bearer -``` - -### 角色权限说明 - -| 角色 | 代码 | 权限范围 | -|------|------|---------| -| 超级管理员 | `super_admin` | 所有权限 | -| 计费管理员 | `billing_admin` | 完整写入权限（渠道级别） | -| 运维管理员 | `operations_admin` | 只读权限（渠道级别） | -| 渠道管理员 | `channel_admin` | 渠道内部管理权限 | - ---- - -## Agent 类型说明 - -系统中的 Agent 分为两种类型： - -### 1. 平台端 Agent（Platform Agent） - -| 属性 | 说明 | -|------|------| -| **来源** | agent-manager 服务（K8s 部署） | -| **管理方式** | 平台打镜像到 agent-manager 仓库，使用 K8s 进行部署 | -| **分配流程** | 管理员 → 分配给渠道 → 渠道分配给租户 | -| **资源配置** | 由平台统一配置（cpu_request, cpu_limit, memory_request, memory_limit） | - -### 2. 自定义 Agent（Custom Agent） - -| 属性 | 说明 | -|------|------| -| **来源** | 用户端自己创建 | -| **管理方式** | 渠道分配资源配额（CPU/内存），租户在配额内上传自己的程序运行 | -| **分配流程** | 管理员分配配额给渠道 → 渠道分配配额给租户 → 租户创建 Agent | -| **资源配置** | 在分配的配额范围内由租户自行配置 | - -### 数据来源 - -| API | 平台端 Agent | 自定义 Agent | 说明 | -|-----|-------------|-------------|------| -| `/api/admin/dashboard/stats` | agent-manager (K8s) | 数据库 | 仪表板统计数据 | -| `/api/admin/platform-agents/status` | agent-manager (K8s) | - | **主接口**：查看平台 Agent 状态和监控 | - -> **注意**: v1.3.0 版本整合了重复接口，`/api/admin/platform-agents/status` 现在是查看平台 Agent 的唯一接口。 - ---- - -## 概览模块 - -> **模块职责**: 仪表板数据展示（统计数据、最近登录） - -### 1. 获取平台统计数据 - -**接口**: `GET /api/admin/dashboard/stats` - -**权限**: 所有管理员 - -**描述**: 获取平台级别的关键统计指标，包括平台端 Agent 和自定义 Agent 的分类统计 - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| totalChannels | int | 渠道总数 | -| totalTenants | int | 租户总数 | -| totalAgents | int | Agent总数（平台端 + 自定义） | -| totalCalls | int | 调用总数 | -| totalRevenue | float | 总收入 | -| totalAllocatedCpu | float | 平台总分配CPU（核）= 平台端 + 自定义 | -| totalAllocatedMemory | float | 平台总分配内存（GB）= 平台端 + 自定义 | -| platformAgents | object | 平台端 Agent 统计 | -| platformAgents.count | int | 平台端 Agent 数量（从 K8s 获取） | -| platformAgents.cpu | float | 平台端 Agent CPU 总量（核） | -| platformAgents.memory | float | 平台端 Agent 内存总量（GB） | -| customAgents | object | 自定义 Agent 统计 | -| customAgents.count | int | 自定义 Agent 数量（从数据库获取） | -| customAgents.cpu | float | 自定义 Agent CPU 总量（核） | -| customAgents.memory | float | 自定义 Agent 内存总量（GB） | - -**响应示例**: -```json -{ - "success": true, - "data": { - "totalChannels": 2, - "totalTenants": 4, - "totalAgents": 6, - "totalCalls": 0, - "totalRevenue": 0.0, - "totalAllocatedCpu": 3.0, - "totalAllocatedMemory": 3.0, - "platformAgents": { - "count": 6, - "cpu": 3.0, - "memory": 3.0 - }, - "customAgents": { - "count": 0, - "cpu": 0, - "memory": 0 - } - } -} -``` - -**说明**: -- `platformAgents`: 从 agent-manager (K8s) 获取的平台端 Agent 统计 -- `customAgents`: 从数据库获取的自定义 Agent 统计 -- `totalAllocatedCpu`: 平台端 + 自定义 Agent 的 CPU 总和 -- `totalAllocatedMemory`: 平台端 + 自定义 Agent 的内存总和 - ---- - -### 2. 获取系统监控指标 - -**接口**: `GET /api/v1/monitoring/metrics` - -**权限**: 所有管理员 - -**描述**: 获取系统CPU、内存、磁盘使用率等实时指标 - -**响应示例**: -```json -{ - "cpu_usage": 45.2, - "memory_usage": 62.8, - "disk_usage": 38.5, - "active_agents": 12 -} -``` - ---- - -### 3. 获取最近登录记录 - -**接口**: `GET /api/admin/dashboard/recent-logins` - -**权限**: 所有管理员 - -**描述**: 获取最近登录的租户列表，按登录时间倒序排列 - -**查询参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| limit | int | 否 | 返回数量，默认10，范围1-50 | - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| recentTenants | array | 最近登录的租户列表 | -| recentTenants[].id | string | 租户ID | -| recentTenants[].name | string | 租户名称 | -| recentTenants[].email | string | 租户邮箱 | -| recentTenants[].channelId | string | 所属渠道ID | -| recentTenants[].channelName | string | 所属渠道名称 | -| recentTenants[].lastLoginAt | string | 最后登录时间（ISO 8601格式） | -| recentTenants[].status | string | 账号状态 | - -**响应示例**: -```json -{ - "success": true, - "data": { - "recentTenants": [ - { - "id": "80de6724-9931-4b3b-9d80-e6d1347d57b0", - "name": "张三", - "email": "zhangsan@example.com", - "channelId": "8a9958a4-3d53-469b-923f-c3cb21cfc675", - "channelName": "渠道A", - "lastLoginAt": "2026-01-04T03:24:01.796611", - "status": "active" - }, - { - "id": "90ef7834-1042-5c4d-8e91-f7e2458e68c1", - "name": "李四", - "email": "lisi@example.com", - "channelId": "8a9958a4-3d53-469b-923f-c3cb21cfc675", - "channelName": "渠道A", - "lastLoginAt": "2026-01-04T02:15:30.123456", - "status": "active" - } - ] - } -} -``` - -**使用示例**: -```bash -# 获取默认10条记录 -curl http://localhost:8002/api/admin/dashboard/recent-logins \ - -H "Authorization: Bearer $TOKEN" - -# 获取20条记录 -curl "http://localhost:8002/api/admin/dashboard/recent-logins?limit=20" \ - -H "Authorization: Bearer $TOKEN" -``` - -**说明**: -- 登录时间在租户每次登录时自动更新 -- 仅返回有登录记录的租户（`lastLoginAt`不为空） -- 按`lastLoginAt`降序排列，最近登录的排在前面 -- 可用于监控平台活跃度 - ---- - -## 渠道管理模块 - -### 1. 获取渠道列表 - -**接口**: `GET /api/admin/channels` - -**权限**: 所有管理员 - -**查询参数**: -- `include_inactive` (可选): 是否包含已删除的渠道，默认false - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| id | string | 渠道ID | -| name | string | 渠道名称 | -| email | string | 渠道邮箱 | -| status | string | 状态（active/inactive/suspended） | -| commissionRate | float | 佣金比例（0-100） | -| channelCredit | float | 渠道授信额度 | -| customAgentCpu | float | 自定义Agent CPU配置 | -| customAgentMemory | float | 自定义Agent内存配置 | -| tenantCount | int | 渠道下租户总数 | -| totalAllocatedCpu | float | 渠道分配的总CPU（核） | -| totalAllocatedMemory | float | 渠道分配的总内存（GB） | -| createdAt | string | 创建时间 | - -**响应示例**: -```json -{ - "success": true, - "data": { - "channels": [ - { - "id": "8a9958a4-3d53-469b-923f-c3cb21cfc675", - "name": "渠道A", - "email": "channel-a@example.com", - "status": "active", - "commissionRate": 0.15, - "channelCredit": 100000.00, - "customAgentCpu": 2.0, - "customAgentMemory": 4.0, - "tenantCount": 25, - "totalAllocatedCpu": 50.0, - "totalAllocatedMemory": 100.0, - "createdAt": "2025-01-01T00:00:00Z" - } - ] - } -} -``` - -**说明**: -- `tenantCount`: 统计该渠道下所有租户数量（role='user'） -- `totalAllocatedCpu`: 统计该渠道所有资源分配的CPU总和 -- `totalAllocatedMemory`: 统计该渠道所有资源分配的内存总和 -- 资源统计包括通过ResourceAllocation分配给渠道的所有Agent资源 - ---- - -### 2. 创建渠道 - -**接口**: `POST /api/admin/channels/create` - -**权限**: `super_admin` - -**请求体**: -```json -{ - "name": "新渠道", - "email": "channel@example.com", - "password": "SecurePass123", - "commissionRate": 0.15 -} -``` - -**响应示例**: -```json -{ - "success": true, - "data": { - "id": "uuid", - "name": "新渠道", - "email": "channel@example.com" - }, - "message": "渠道创建成功" -} -``` - ---- - -### 3. 编辑渠道信息 - -**接口**: `PUT /api/admin/channels/{channel_id}` - -**权限**: `super_admin`, `billing_admin` - -**请求字段**: -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| name | string | 否 | 渠道名称 | -| email | string | 否 | 渠道邮箱 | -| commissionRate | float | 否 | 佣金比例（0-100） | -| status | string | 否 | 状态（active/inactive） | - -**请求体**: -```json -{ - "name": "更新后的渠道名", - "email": "newemail@channel.com", - "commissionRate": 0.18, - "status": "active" -} -``` - ---- - -### 4. 删除渠道 - -**接口**: `DELETE /api/admin/channels/{channel_id}` - -**权限**: `super_admin` - -**说明**: 软删除，要求渠道下无活跃租户 - ---- - -### 5. 获取渠道资源配置 ✨新增 - -**接口**: `GET /api/admin/channels/{channel_id}/resources` - -**权限**: 所有管理员 - -**描述**: 获取渠道的模型供应商、Agent配额、自定义Agent资源、授信额度配置 - -**响应示例**: -```json -{ - "success": true, - "data": { - "models": ["model-id-1", "model-id-2"], - "agents": [ - { - "agentId": "agent-id-1", - "quantity": 10 - } - ], - "customAgentResources": { - "cpu": 2.0, - "memory": 4.0 - }, - "channelCredit": 100000.00, - "commissionRate": 0.15 - } -} -``` - ---- - -### 6. 更新渠道资源配置 - -**接口**: `PUT /api/admin/channels/{channel_id}/resources` - -**权限**: `super_admin`, `billing_admin` - -**请求体**: -```json -{ - "models": ["model-id-1", "model-id-2"], - "agents": [ - { - "agentId": "agent-id-1", - "quantity": 10 - } - ], - "customAgentResources": { - "cpu": 2.0, - "memory": 4.0 - }, - "channelCredit": 100000.00 -} -``` - ---- - -### 7. 更新渠道佣金 ✨新增 - -**接口**: `PUT /api/admin/channels/{channel_id}/commission` - -**权限**: `super_admin`, `billing_admin` - -**请求体**: -```json -{ - "commissionRate": 0.18 -} -``` - -**响应示例**: -```json -{ - "success": true, - "data": { - "channelId": "uuid", - "commissionRate": 0.18 - }, - "message": "渠道佣金比例已更新" -} -``` - ---- - -### 8. 获取渠道租户列表 ✨更新 - -**接口**: `GET /api/channel/tenants` - -**权限**: `super_admin`, `channel_admin`, `billing_admin`, `operations_admin` - -**描述**: 获取指定渠道下的所有租户 - -**权限说明**: -- **超级管理员** (`super_admin`): **必须提供 `channel_id` 查询参数** -- **其他管理员**: 自动使用所属渠道 - -**查询参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID（超级管理员必填，其他管理员自动使用所属渠道） | -| status | string | 否 | 筛选状态 `active|inactive|suspended` | - -**使用示例**: -```bash -# 超级管理员查看指定渠道的租户（必须指定 channel_id） -curl "http://localhost:8002/api/channel/tenants?channel_id=xxx" \ - -H "Authorization: Bearer $SUPER_ADMIN_TOKEN" - -# 渠道管理员查看（自动过滤到本渠道） -curl http://localhost:8002/api/channel/tenants \ - -H "Authorization: Bearer $CHANNEL_ADMIN_TOKEN" -``` - -**错误响应**: -```json -// 超级管理员未提供 channel_id -{ - "detail": "超级管理员必须提供 channel_id 参数" -} -``` - ---- - -### 9. 创建租户 ✨更新 - -**接口**: `POST /api/channel/tenants/create` - -**权限**: `super_admin`, `channel_admin`, `billing_admin` - -**权限说明**: -- **超级管理员** (`super_admin`): **必须在请求体中提供 `channelId` 字段** -- **其他管理员**: 自动使用所属渠道 - -**请求体**: -```json -{ - "name": "租户名称", - "email": "tenant@example.com", - "password": "SecurePass123", - "subscriptionTier": "premium", - "channelId": "uuid" // 超级管理员必填 -} -``` - -**使用示例**: -```bash -# 超级管理员创建租户（必须指定 channelId） -curl -X POST http://localhost:8002/api/channel/tenants/create \ - -H "Authorization: Bearer $SUPER_ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "新租户", - "email": "tenant@example.com", - "password": "SecurePass123", - "channelId": "8a9958a4-3d53-469b-923f-c3cb21cfc675" - }' - -# 渠道管理员创建租户（自动使用本渠道） -curl -X POST http://localhost:8002/api/channel/tenants/create \ - -H "Authorization: Bearer $CHANNEL_ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "新租户", - "email": "tenant@example.com", - "password": "SecurePass123" - }' -``` - -**错误响应**: -```json -// 超级管理员未提供 channelId -{ - "detail": "超级管理员必须提供 channelId" -} -``` - ---- - -### 10. 更新租户状态 ✨更新 - -**接口**: `PUT /api/channel/tenants/{tenant_id}/status` - -**权限**: `channel_admin`, `billing_admin`, `super_admin` - -**权限说明**: -- **超级管理员** (`super_admin`): **必须提供 `channel_id` 查询参数** -- **其他管理员**: 自动使用所属渠道 - -**查询参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**请求体**: -```json -{ - "status": "suspended" -} -``` - -**状态值**: `active`, `inactive`, `suspended` - ---- - -### 11. 更新租户权限 ✨更新 - -**接口**: `PUT /api/channel/tenants/{tenant_id}/permissions` - -**权限**: `channel_admin`, `billing_admin`, `super_admin` - -**权限说明**: -- **超级管理员** (`super_admin`): **必须提供 `channel_id` 查询参数** -- **其他管理员**: 自动使用所属渠道 - -**查询参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**请求体**: -```json -{ - "permissions": [ - "use:platform_agents", - "use:custom_agents", - "create:agents", - "read:billing", - "export:data" - ] -} -``` - ---- - -### 12. 租户密码重置 ✨更新 - -**接口**: `PUT /api/channel/tenants/{tenant_id}/password` - -**权限**: `channel_admin`, `billing_admin`, `super_admin` - -**权限说明**: -- **超级管理员** (`super_admin`): **必须提供 `channel_id` 查询参数** -- **其他管理员**: 自动使用所属渠道 - -**查询参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**请求体**: -```json -{ - "newPassword": "NewSecurePass123" -} -``` - -**响应示例**: -```json -{ - "success": true, - "data": { - "tenantId": "uuid", - "name": "租户名称" - }, - "message": "租户密码已重置" -} -``` - ---- - -### 13. 删除租户 ✨更新 - -**接口**: `DELETE /api/channel/tenants/{tenant_id}` - -**权限**: `channel_admin`, `billing_admin`, `super_admin` - -**权限说明**: -- **超级管理员** (`super_admin`): **必须提供 `channel_id` 查询参数** -- **其他管理员**: 自动使用所属渠道 - -**查询参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**说明**: 软删除 - ---- - -### 14. 获取供应商授权列表 - -**接口**: `GET /api/admin/providers/access` - -**权限**: 所有管理员 - -**查询参数**: -- `channel_id` (可选): 筛选指定渠道 -- `status` (可选): 筛选状态 - -**响应示例**: -```json -{ - "success": true, - "data": { - "access": [ - { - "id": "uuid", - "channelId": "uuid", - "channelName": "渠道A", - "providerId": "uuid", - "providerName": "OpenAI", - "providerType": "openai", - "rpmLimit": 1000, - "tpmLimit": 100000, - "status": "active", - "grantedAt": "2025-01-01T00:00:00Z" - } - ] - } -} -``` - ---- - -### 15. 撤销供应商授权 - -**接口**: `DELETE /api/admin/providers/access/{access_id}` - -**权限**: `super_admin`, `billing_admin` - -**说明**: 将授权状态改为suspended - ---- - -### 16. 获取供应商申请列表 - -**接口**: `GET /api/admin/providers/applications` - -**权限**: 所有管理员 - -**查询参数**: -- `status` (可选): `pending|approved|rejected` -- `channel_id` (可选): 筛选指定渠道 - ---- - -### 17. 审批供应商申请 - -**接口**: `PUT /api/admin/providers/applications/{application_id}/review` - -**权限**: `super_admin`, `billing_admin` - -**请求体**: -```json -{ - "approved": true, - "reason": "批准理由" -} -``` - -**说明**: 批准后自动创建ChannelProviderAccess记录 - ---- - -### 18. 获取渠道管理员列表 - -**接口**: `GET /api/admin/channels/{channel_id}/admins` - -**权限**: 所有管理员 - -**响应示例**: -```json -{ - "success": true, - "data": { - "channelId": "uuid", - "channelName": "渠道A", - "admins": [ - { - "id": "uuid", - "name": "管理员张三", - "email": "admin@channel.com", - "role": "billing_admin", - "status": "active", - "createdAt": "2025-01-01T00:00:00Z" - } - ] - } -} -``` - ---- - -## 资源管理模块 - -> **模块职责**: 模型供应商管理（Agent 管理已移至"平台 Agent 管理模块"） - -### 1. 获取模型供应商列表 - -**接口**: `GET /api/providers/models` - -**权限**: `super_admin`, `provider_admin` - ---- - -### 2. 创建模型供应商 - -**接口**: `POST /api/providers/models/create` - -**权限**: `super_admin`, `provider_admin` - -**请求体**: -```json -{ - "name": "OpenAI", - "provider": "openai", - "apiKey": "sk-...", - "apiUrl": "https://api.openai.com/v1", - "supportedModels": ["gpt-4", "gpt-3.5-turbo"], - "rpm": 1000, - "tpm": 100000 -} -``` - -**说明**: API密钥会自动加密存储 - ---- - -### 3. 更新模型供应商 - -**接口**: `PUT /api/providers/models/{provider_id}` - -**权限**: `super_admin`, `provider_admin` - ---- - -### 4. 删除模型供应商 - -**接口**: `DELETE /api/providers/models/{provider_id}` - -**权限**: `super_admin` - ---- - -### 5. 测试供应商连接 - -**接口**: `POST /api/providers/models/{provider_id}/test` - -**权限**: `super_admin`, `provider_admin` - -**响应示例**: -```json -{ - "success": true, - "data": { - "status": "connected", - "latency": 125, - "message": "连接成功" - } -} -``` - ---- - -## 资源申请审批模块 - -### 1. 查看平台 Agent - -**接口**: `GET /api/channel/available-platform-agents` - -**权限**: `channel_admin`, `billing_admin`, `operations_admin` - -**描述**: 查看所有可用的平台 Agent 模板，以及渠道是否已获得使用权限 - -**响应示例**: -```json -{ - "success": true, - "data": { - "templates": [ - { - "name": "gpt-assistant", - "displayName": "GPT 智能助手", - "description": "基于 GPT 的通用智能助手", - "category": "assistant", - "version": "1.0.0", - "cpuRequest": "100m", - "cpuLimit": "500m", - "memoryRequest": "128Mi", - "memoryLimit": "512Mi", - "imageUrl": "acr.taiji-ai.com/agents/gpt-assistant:latest", - "status": "available", - "hasAccess": true, - "podQuota": 5, - "podUsed": 2, - "podRemaining": 3, - "pendingApplication": false - } - ] - } -} -``` - ---- - -### 2. 渠道申请平台 Agent - -**接口**: `POST /api/channel/applications/platform-agents` - -**权限**: `channel_admin`, `billing_admin`, `operations_admin` - -**描述**: 渠道申请使用某个平台 Agent 模板 - -**请求体**: -```json -{ - "templateName": "gpt-assistant", - "requestedPodQuota": 5, - "reason": "业务需要使用 GPT 智能助手" -} -``` - -**请求字段说明**: -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| templateName | string | 是 | 平台 Agent 模板名称 | -| requestedPodQuota | int | 是 | 申请的 Pod 配额（1-100） | -| reason | string | 是 | 申请理由（1-500字符） | - -**响应示例**: -```json -{ - "success": true, - "data": { - "id": "uuid", - "templateName": "gpt-assistant", - "templateDisplayName": "GPT 智能助手", - "requestedPodQuota": 5, - "status": "pending" - }, - "message": "申请已提交，等待管理员审批" -} -``` - ---- - -### 3. 查看渠道的申请列表 - -**接口**: `GET /api/channel/applications/platform-agents` - -**权限**: `channel_admin`, `billing_admin`, `operations_admin` - -**查询参数**: -- `status` (可选): 筛选状态 `pending|approved|rejected` - -**响应示例**: -```json -{ - "success": true, - "data": { - "applications": [ - { - "id": "uuid", - "channelId": "uuid", - "channelName": "渠道A", - "resourceType": "platform_agent", - "templateName": "gpt-assistant", - "templateDisplayName": "GPT 智能助手", - "requestedPodQuota": 5, - "approvedPodQuota": null, - "reason": "业务需要", - "status": "pending", - "reviewReason": null, - "reviewedAt": null, - "createdAt": "2026-01-05T02:53:22Z" - } - ] - } -} -``` - ---- - -### 4. 管理员获取平台 Agent 申请列表 - -**接口**: `GET /api/admin/applications/platform-agents` - -**权限**: `super_admin`, `billing_admin` - -**查询参数**: -- `status` (可选): 筛选状态 `pending|approved|rejected` - ---- - -### 5. 管理员审批平台 Agent 申请 - -**接口**: `PUT /api/admin/applications/platform-agents/{application_id}/review` - -**权限**: `super_admin`, `billing_admin` - -**请求体**: -```json -{ - "action": "approve", - "podQuota": 5, - "reviewReason": "批准使用" -} -``` - -**请求字段说明**: -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| action | string | 是 | 审批动作：`approve` 或 `reject` | -| podQuota | int | approve 时必填 | 批准的 Pod 配额（≥0） | -| reviewReason | string | 否 | 审批意见（最多500字符） | - -**响应示例**: -```json -{ - "success": true, - "application_id": "uuid", - "status": "approved", - "message": "申请已通过" -} -``` - ---- - -## 平台 Agent 管理模块 - -### 1. 获取平台 Agent 模板列表 - -**接口**: `GET /api/admin/platform-agents/templates` - -**权限**: 所有管理员 - -**描述**: 获取所有可用的平台 Agent 模板，包含管理员配置的资源参数 - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| name | string | 模板名称（唯一标识） | -| displayName | string | 显示名称 | -| description | string | 模板描述 | -| category | string | 分类（assistant/search/database/development/testing） | -| version | string | 版本号 | -| cpuRequest | string | CPU 请求量（如 "100m"），未配置时为 null | -| cpuLimit | string | CPU 上限（如 "500m"），未配置时为 null | -| memoryRequest | string | 内存请求量（如 "128Mi"），未配置时为 null | -| memoryLimit | string | 内存上限（如 "512Mi"），未配置时为 null | -| maxPods | int | 最大 Pod 数量，未配置时为 0 | -| isConfigured | bool | 是否已配置资源参数 | -| status | string | 状态：available（已配置）/ not_configured（未配置） | - -**响应示例**: -```json -{ - "success": true, - "data": { - "templates": [ - { - "name": "echo_agent", - "displayName": "Echo 测试服务", - "description": "简单的 Echo 服务，用于测试和调试", - "category": "testing", - "version": "1.0.0", - "cpuRequest": "100m", - "cpuLimit": "500m", - "memoryRequest": "128Mi", - "memoryLimit": "512Mi", - "maxPods": 10, - "isConfigured": true, - "status": "available" - }, - { - "name": "chat_agent", - "displayName": "聊天对话服务", - "description": "智能聊天对话 Agent，支持多轮对话", - "category": "assistant", - "version": "1.0.0", - "cpuRequest": null, - "cpuLimit": null, - "memoryRequest": null, - "memoryLimit": null, - "maxPods": 0, - "isConfigured": false, - "status": "not_configured" - } - ] - } -} -``` - -**说明**: -- `isConfigured: false` 表示管理员尚未配置该模板的资源参数 -- 未配置的模板无法被渠道申请使用 -- 管理员需要先通过配置 API 设置资源参数后，模板才可用 - ---- - -### 1.1 配置平台 Agent 模板 ✨新增 - -**接口**: `PUT /api/admin/platform-agents/templates/{name}/config` - -**权限**: `super_admin`, `billing_admin` - -**描述**: 管理员配置平台 Agent 模板的资源参数。这些参数将用于启动 Pod 时的 K8s 资源配置。 - -**路径参数**: -| 参数 | 类型 | 说明 | -|------|------|------| -| name | string | 模板名称（如 echo_agent） | - -**请求体**: -```json -{ - "cpuRequest": "100m", - "cpuLimit": "500m", - "memoryRequest": "128Mi", - "memoryLimit": "512Mi", - "maxPods": 10, - "isEnabled": true, - "displayName": "Echo 测试服务", - "description": "简单的 Echo 服务，用于测试和调试" -} -``` - -**请求字段说明**: -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| cpuRequest | string | 否 | CPU 请求量，K8s 格式（如 "100m" = 0.1 核） | -| cpuLimit | string | 否 | CPU 上限，K8s 格式（如 "500m" = 0.5 核） | -| memoryRequest | string | 否 | 内存请求量，K8s 格式（如 "128Mi" = 128 MiB） | -| memoryLimit | string | 否 | 内存上限，K8s 格式（如 "512Mi" = 512 MiB） | -| maxPods | int | 否 | 最大 Pod 数量，默认 0（无限制） | -| isEnabled | bool | 否 | 是否启用，默认 true | -| displayName | string | 否 | 显示名称 | -| description | string | 否 | 模板描述 | - -**K8s 资源单位说明**: - -| 资源类型 | 单位 | 示例 | 说明 | -|---------|------|------|------| -| CPU | m (millicores) | 100m | 0.1 核 CPU | -| CPU | 核 | 1 | 1 核 CPU | -| 内存 | Mi (MiB) | 128Mi | 128 MiB ≈ 134 MB | -| 内存 | Gi (GiB) | 1Gi | 1 GiB ≈ 1.07 GB | - -**响应示例**: -```json -{ - "success": true, - "data": { - "templateName": "echo_agent", - "cpuRequest": "100m", - "cpuLimit": "500m", - "memoryRequest": "128Mi", - "memoryLimit": "512Mi", - "maxPods": 10, - "displayName": "Echo 测试服务", - "description": "简单的 Echo 服务，用于测试和调试", - "isEnabled": true, - "configuredAt": "2026-01-06T05:20:00Z" - }, - "message": "模板配置已保存" -} -``` - -**使用示例**: -```bash -curl -X PUT "http://localhost:8002/api/admin/platform-agents/templates/echo_agent/config" \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "cpuRequest": "100m", - "cpuLimit": "500m", - "memoryRequest": "128Mi", - "memoryLimit": "512Mi", - "maxPods": 10 - }' -``` - ---- - -### 1.2 获取平台 Agent 模板配置 ✨新增 - -**接口**: `GET /api/admin/platform-agents/templates/{name}/config` - -**权限**: 所有管理员 - -**描述**: 获取指定模板的资源配置详情 - -**路径参数**: -| 参数 | 类型 | 说明 | -|------|------|------| -| name | string | 模板名称 | - -**响应示例**: -```json -{ - "success": true, - "data": { - "templateName": "echo_agent", - "cpuRequest": "100m", - "cpuLimit": "500m", - "memoryRequest": "128Mi", - "memoryLimit": "512Mi", - "maxPods": 10, - "displayName": "Echo 测试服务", - "description": "简单的 Echo 服务，用于测试和调试", - "isEnabled": true, - "configuredAt": "2026-01-06T05:20:00Z", - "configuredBy": "admin@example.com" - } -} -``` - -**错误响应**（模板未配置）: -```json -{ - "success": true, - "data": { - "templateName": "chat_agent", - "isConfigured": false, - "message": "该模板尚未配置资源参数" - } -} -``` - ---- - -### 2. 获取平台 Agent 分配情况 - -**接口**: `GET /api/admin/platform-agents/allocations` - -**权限**: 所有管理员 - -**描述**: 查看平台 Agent 在各渠道和租户的分配情况 - -**响应示例**: -```json -{ - "success": true, - "data": { - "allocations": [ - { - "channelId": "uuid", - "channelName": "渠道A", - "templateName": "gpt-assistant", - "templateDisplayName": "GPT 智能助手", - "podQuota": 10, - "podUsed": 3, - "podRemaining": 7, - "tenants": [ - { - "tenantId": "uuid", - "tenantName": "租户1", - "podQuota": 5, - "podUsed": 2 - } - ] - } - ] - } -} -``` - ---- - -### 3. 获取平台 Agent 运行状态 - -**接口**: `GET /api/admin/platform-agents/status` - -**权限**: 所有管理员 - -**描述**: 从 agent-manager (K8s) 获取所有平台 Agent 的运行状态 - -**响应示例**: -```json -{ - "success": true, - "data": { - "agents": [ - { - "name": "jina-search-agent-44e817f3", - "template": "jina_search_agent", - "status": "Running", - "podName": "", - "podIp": "10.244.1.191", - "namespace": "ai-agents", - "cpuUsage": 0.0, - "memoryUsage": 0.0, - "createdAt": "2025-12-31T07:22:21+00:00" - } - ], - "summary": { - "total": 6, - "running": 6, - "pending": 0, - "error": 0 - } - } -} -``` - ---- - -### 4. 直接分配平台 Agent 配额给渠道 ✨新增 - -**接口**: `POST /api/admin/platform-agents/allocate` - -**权限**: `super_admin`, `billing_admin` - -**描述**: 管理员直接给渠道分配平台 Agent 配额，无需渠道提交申请审批流程 - -**查询参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 是 | 渠道 ID | -| template_name | string | 是 | 模板名称（如 gpt-assistant） | -| pod_quota | int | 是 | Pod 配额数量（≥1） | - -**请求示例**: -```bash -curl -X POST "http://localhost:8002/api/admin/platform-agents/allocate?channel_id=xxx&template_name=gpt-assistant&pod_quota=5" \ - -H "Authorization: Bearer $TOKEN" -``` - -**响应示例**: -```json -{ - "success": true, - "data": { - "channelId": "8a9958a4-3d53-469b-923f-c3cb21cfc675", - "channelName": "渠道A", - "templateName": "gpt-assistant", - "templateDisplayName": "GPT 智能助手", - "podQuota": 5 - }, - "message": "平台 Agent 配额分配成功" -} -``` - -**说明**: -- 如果渠道已有该模板的配额记录，会更新配额数量 -- 如果渠道没有该模板的配额记录，会创建新记录 -- 此接口绕过申请审批流程，适用于管理员主动分配资源 - ---- - -### 5. 撤销渠道的平台 Agent 配额 ✨新增 - -**接口**: `DELETE /api/admin/platform-agents/allocate` - -**权限**: `super_admin`, `billing_admin` - -**描述**: 管理员撤销渠道的平台 Agent 配额 - -**查询参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 是 | 渠道 ID | -| template_name | string | 是 | 模板名称 | - -**请求示例**: -```bash -curl -X DELETE "http://localhost:8002/api/admin/platform-agents/allocate?channel_id=xxx&template_name=gpt-assistant" \ - -H "Authorization: Bearer $TOKEN" -``` - -**响应示例**: -```json -{ - "success": true, - "data": { - "channelId": "8a9958a4-3d53-469b-923f-c3cb21cfc675", - "channelName": "渠道A", - "templateName": "gpt-assistant" - }, - "message": "平台 Agent 配额已撤销" -} -``` - -**错误响应**: -```json -{ - "detail": "渠道正在使用 3 个 Pod，无法撤销配额" -} -``` - -**说明**: -- 如果渠道正在使用该模板的 Pod（pod_used > 0），无法撤销配额 -- 需要先停止所有使用中的 Pod 实例，才能撤销配额 - ---- - -### 6. 渠道查看平台 Agent 配额 - -**接口**: `GET /api/channel/platform-agents` - -**权限**: `channel_admin`, `billing_admin`, `operations_admin` - -**描述**: 查看渠道已获得的平台 Agent 配额 - -**响应示例**: -```json -{ - "success": true, - "data": { - "quotas": [ - { - "templateName": "gpt-assistant", - "templateDisplayName": "GPT 智能助手", - "podQuota": 5, - "podUsed": 0, - "podRemaining": 5, - "allocatedAt": "2026-01-05T02:54:33Z" - } - ] - } -} -``` - ---- - -### 7. 渠道分配平台 Agent 给租户 - -**接口**: `POST /api/channel/tenants/{tenant_id}/platform-agents` - -**权限**: `channel_admin`, `billing_admin` - -**请求体**: -```json -{ - "templateName": "gpt-assistant", - "podQuota": 3 -} -``` - -**请求字段说明**: -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| templateName | string | 是 | 平台 Agent 模板名称 | -| podQuota | int | 是 | 分配的 Pod 配额（1-50） | - -**响应示例**: -```json -{ - "success": true, - "data": { - "tenantId": "uuid", - "tenantName": "租户A", - "templateName": "gpt-assistant", - "templateDisplayName": "GPT 智能助手", - "podQuota": 3 - }, - "message": "平台 Agent 配额分配成功" -} -``` - ---- - -### 8. 租户查看可用平台 Agent - -**接口**: `GET /api/user/platform-agents/available` - -**权限**: `user` - -**描述**: 租户查看自己可用的平台 Agent 配额 - ---- - -### 9. 租户使用平台 Agent - -**接口**: `POST /api/user/platform-agents/use` - -**权限**: `user` - -**请求体**: -```json -{ - "templateName": "gpt-assistant", - "agentType": "chat" -} -``` - -**响应示例**: -```json -{ - "success": true, - "data": { - "instanceName": "gpt-assistant-abc123", - "templateName": "gpt-assistant", - "status": "starting", - "endpoint": "http://gpt-assistant-abc123.agents.svc.cluster.local" - }, - "message": "平台 Agent 启动中" -} -``` - ---- - -### 10. 租户停止平台 Agent - -**接口**: `DELETE /api/user/platform-agents/{instance_name}` - -**权限**: `user` - ---- - -### 11. 租户查看平台 Agent 实例列表 - -**接口**: `GET /api/user/platform-agents/instances` - -**权限**: `user` - ---- - -## Agent 计费模块 - -### 计费模型说明 - -| Agent 类型 | 计费方式 | 价格 | -|-----------|---------|------| -| 平台 Agent | 按模板固定价格计费 | gpt-assistant: 0.5元/小时, code-reviewer: 0.8元/小时 | -| 自定义 Agent | 按资源使用计费 | CPU: 0.1元/核/小时, 内存: 0.05元/GB/小时 | - -**EU 计算**: 1 EU = 10 秒运行时间 - ---- - -### 1. 用户 Agent 计费统计 - -**接口**: `GET /api/user/agent-billing/stats` - -**权限**: `user` - -**查询参数**: -- `startTime` (必填): 开始时间 ISO8601格式 -- `endTime` (必填): 结束时间 ISO8601格式 -- `agentType` (可选): Agent 类型 `platform|custom` - -**响应示例**: -```json -{ - "success": true, - "data": { - "totalCost": 15.50, - "totalDurationSeconds": 36000, - "totalRequests": 100, - "byAgentType": { - "platform": { - "cost": 10.00, - "durationSeconds": 20000, - "requests": 50 - }, - "custom": { - "cost": 5.50, - "durationSeconds": 16000, - "requests": 50 - } - } - } -} -``` - ---- - -### 2. 用户 Agent 计费历史 - -**接口**: `GET /api/user/agent-billing/history` - -**权限**: `user` - -**查询参数**: -- `startTime` (必填): 开始时间 -- `endTime` (必填): 结束时间 -- `agentType` (可选): Agent 类型 -- `page` (可选): 页码，默认1 -- `pageSize` (可选): 每页数量，默认20 - ---- - -### 3. 渠道 Agent 计费统计 - -**接口**: `GET /api/channel/agent-billing/stats` - -**权限**: `channel_admin`, `billing_admin`, `operations_admin` - -**查询参数**: -- `startTime` (必填): 开始时间 -- `endTime` (必填): 结束时间 -- `agentType` (可选): Agent 类型 -- `templateName` (可选): 模板名称 -- `tenantId` (可选): 租户 ID - -**响应示例**: -```json -{ - "success": true, - "data": { - "totalCost": 0, - "totalDurationSeconds": 0, - "totalRequests": 0, - "byUser": [] - } -} -``` - ---- - -### 4. 渠道 Agent 计费历史 - -**接口**: `GET /api/channel/agent-billing/history` - -**权限**: `channel_admin`, `billing_admin`, `operations_admin` - -**查询参数**: -- `startTime` (必填): 开始时间 -- `endTime` (必填): 结束时间 -- `agentType` (可选): Agent 类型 -- `templateName` (可选): 模板名称 -- `tenantId` (可选): 租户 ID -- `page` (可选): 页码 -- `pageSize` (可选): 每页数量 - -**响应示例**: -```json -{ - "success": true, - "data": { - "records": [ - { - "id": "uuid", - "timestamp": "2026-01-05T10:00:00Z", - "tenantId": "uuid", - "tenantName": "租户A", - "agentType": "platform", - "templateName": "gpt-assistant", - "agentName": "gpt-assistant-abc123", - "durationSeconds": 3600, - "cpuSeconds": 1800, - "memoryGbSeconds": 1800, - "requestCount": 10, - "cost": 0.50, - "periodStart": "2026-01-05T10:00:00Z", - "periodEnd": "2026-01-05T11:00:00Z" - } - ], - "pagination": { - "page": 1, - "pageSize": 20, - "total": 1, - "totalPages": 1 - } - } -} -``` - ---- - -### 5. 渠道租户计费汇总 - -**接口**: `GET /api/channel/agent-billing/tenant-summary` - -**权限**: `channel_admin`, `billing_admin`, `operations_admin` - -**查询参数**: -- `startTime` (必填): 开始时间 -- `endTime` (必填): 结束时间 - -**响应示例**: -```json -{ - "success": true, - "data": { - "tenants": [ - { - "tenantId": "uuid", - "tenantName": "租户A", - "platformAgent": { - "count": 5, - "totalDuration": 18000, - "totalRequests": 50, - "totalCost": 2.50 - }, - "customAgent": { - "count": 2, - "totalDuration": 7200, - "totalRequests": 20, - "totalCost": 1.20 - }, - "total": { - "count": 7, - "totalDuration": 25200, - "totalRequests": 70, - "totalCost": 3.70 - } - } - ], - "channelTotal": { - "platformAgent": { - "count": 5, - "totalDuration": 18000, - "totalRequests": 50, - "totalCost": 2.50 - }, - "customAgent": { - "count": 2, - "totalDuration": 7200, - "totalRequests": 20, - "totalCost": 1.20 - }, - "total": { - "count": 7, - "totalDuration": 25200, - "totalRequests": 70, - "totalCost": 3.70 - } - }, - "period": { - "startTime": "2026-01-01T00:00:00", - "endTime": "2026-01-31T23:59:59" - } - } -} -``` - ---- - -## 监控模块 - -> **模块职责**: 系统级监控（Agent 监控请使用 `/api/admin/platform-agents/status`） - -### 1. 获取监控仪表板 - -**接口**: `GET /api/v1/monitoring/dashboard` - -**权限**: 所有管理员 - -**描述**: 聚合返回健康状态、系统指标、统计数据、告警信息 - ---- - -## 计费模块 - -### 1. 获取三维度计费统计 - -**接口**: `GET /api/admin/billing/overview` - -**权限**: 所有管理员 - -**查询参数**: -- `startTime` (必填): 开始时间 ISO8601格式 -- `endTime` (必填): 结束时间 ISO8601格式 -- `channelName` (可选): 筛选渠道名 -- `tenantName` (可选): 筛选租户名 -- `minCalls` (可选): 最小调用次数 -- `maxCalls` (可选): 最大调用次数 -- `export` (可选): 导出格式 `excel|csv|pdf` - -**响应示例（不导出）**: -```json -{ - "success": true, - "data": { - "channelStats": [ - { - "channelId": "uuid", - "channelName": "渠道A", - "calls": 50000, - "totalEU": 125000.5, - "totalCost": 25000.00 - } - ], - "tenantStats": [ - { - "tenantId": "uuid", - "tenantName": "租户A", - "channelName": "渠道A", - "calls": 1000, - "totalEU": 2500.0, - "totalCost": 500.00 - } - ], - "callRecords": [ - { - "id": "uuid", - "timestamp": "2025-12-20T10:30:00Z", - "channelName": "渠道A", - "tenantName": "租户A", - "agentName": "Agent-X", - "duration": 120, - "eu": 25, - "cost": 5.00 - } - ] - } -} -``` - -**响应示例（导出）**: -```json -{ - "success": true, - "data": { - "fileUrl": "/api/admin/billing/exports/billing_20260104120000.xlsx", - "format": "excel", - "expiresAt": "2026-01-05T12:00:00Z", - "message": "导出功能开发中，当前返回占位URL" - } -} -``` - -**说明**: 导出功能目前返回占位URL，实际文件生成需要补充实现 - ---- - -## 设置模块 - -### 1. 获取管理员列表 - -**接口**: `GET /api/admin/admins` - -**权限**: `super_admin` - -**描述**: 获取所有活跃的系统管理员（billing_admin, operations_admin） - ---- - -### 2. 创建管理员 - -**接口**: `POST /api/admin/admins/create` - -**权限**: `super_admin` - -**请求体**: -```json -{ - "name": "管理员姓名", - "email": "admin@example.com", - "password": "SecurePass123", - "role": "billing_admin", - "channelId": "uuid" -} -``` - -**说明**: -- `role` 可选值: `billing_admin`, `operations_admin` -- `channelId` 可选，如果提供则创建渠道管理员 - ---- - -### 3. 删除管理员 - -**接口**: `DELETE /api/admin/admins/{admin_id}` - -**权限**: `super_admin` - -**说明**: 软删除，将status改为inactive - ---- - -### 4. 获取角色列表 - -**接口**: `GET /api/admin/roles` - -**权限**: 所有管理员 - -**响应示例**: -```json -{ - "success": true, - "data": { - "roles": [ - { - "id": "super_admin", - "name": "超级管理员", - "description": "拥有系统所有权限", - "permissions": ["*"] - }, - { - "id": "billing_admin", - "name": "计费管理员", - "description": "完整写入权限", - "permissions": ["read:*", "write:channels", "write:tenants", "write:billing"] - } - ] - } -} -``` - ---- - -## 错误响应格式 - -所有错误响应遵循统一格式： - -```json -{ - "success": false, - "error": { - "code": "ERROR_CODE", - "message": "详细错误信息" - } -} -``` - -### 常见错误码 - -| HTTP状态码 | 错误码 | 说明 | -|-----------|--------|------| -| 400 | BAD_REQUEST | 请求参数错误 | -| 401 | UNAUTHORIZED | 未认证 | -| 403 | FORBIDDEN | 权限不足 | -| 404 | NOT_FOUND | 资源不存在 | -| 500 | INTERNAL_ERROR | 服务器内部错误 | - ---- - -## 更新日志 - -### v1.3.0 (2026-01-06) - -**接口整合与模块职责明确** 🔄重构: - -本版本对重复接口进行了整合，明确了各模块的职责边界： - -**删除的重复接口**: -| 原接口 | 替代接口 | 说明 | -|-------|---------|------| -| `GET /api/admin/tenants` | `GET /api/channel/tenants` | 租户列表统一使用渠道接口 | -| `GET /api/admin/resources/agents` | `GET /api/admin/platform-agents/status` | Agent 资源查看统一使用平台 Agent 模块 | -| `GET /api/admin/resources/allocation-stats` | `GET /api/admin/platform-agents/status` | 资源统计合并到平台 Agent 状态接口 | -| `PUT /api/admin/resources/agents/{id}/config` | `PUT /api/admin/platform-agents/templates/{name}/config` | Agent 配置统一使用模板配置接口 | -| `DELETE /api/admin/resources/agents/{id}` | - | 通过 K8s 管理，无需单独删除接口 | -| `GET /api/admin/channels/applications` | `GET /api/admin/applications/platform-agents` | 申请审批统一使用资源申请审批模块 | -| `PUT /api/admin/channels/applications/{id}/review` | `PUT /api/admin/applications/platform-agents/{id}/review` | 审批统一使用资源申请审批模块 | -| `GET /api/admin/monitoring/agents` | `GET /api/admin/platform-agents/status` | Agent 监控统一使用平台 Agent 状态接口 | - -**模块职责明确**: -| 模块 | 职责 | -|------|------| -| 概览模块 | 仪表板数据展示（统计数据、最近登录） | -| 渠道管理模块 | 渠道 CRUD、租户管理、供应商授权 | -| 资源管理模块 | **仅模型供应商管理**（Agent 管理已移至平台 Agent 管理模块） | -| 资源申请审批模块 | 渠道申请平台 Agent、管理员审批 | -| 平台 Agent 管理模块 | **Agent 全生命周期管理**（模板配置、状态监控、配额分配） | -| 监控模块 | **系统级监控**（Agent 监控请使用平台 Agent 管理模块） | - -**接口编号调整**: -- 渠道管理模块：删除 16-17（申请审批），18→16, 19→17, 20→18 -- 资源管理模块：删除 1-4（Agent 相关），5→1, 6→2, 7→3, 8→4, 9→5 -- 监控模块：删除 1（Agent 监控），2→1 - -**迁移指南**: -- 查看平台 Agent 状态：使用 `GET /api/admin/platform-agents/status` -- 配置 Agent 资源：使用 `PUT /api/admin/platform-agents/templates/{name}/config` -- 查看租户列表：使用 `GET /api/channel/tenants?channel_id=xxx` -- 审批 Agent 申请：使用 `PUT /api/admin/applications/platform-agents/{id}/review` - ---- - -### v1.2.8 (2026-01-06) - -**文档与代码一致性修复** 🐛修复: -- 🐛 删除概览模块中重复的 "获取Agent资源统计" 接口定义（该接口已在资源管理模块中定义） -- 🐛 修正资源管理模块接口编号：3→4（删除Agent资源）、4→5（获取模型供应商列表）、5→6、6→7、7→8、8→9 -- 🐛 修正资源申请审批模块接口编号：5→4（管理员获取平台 Agent 申请列表）、6→5（管理员审批平台 Agent 申请） -- 🐛 修正平台 Agent 管理模块接口编号：5→7、6→8、7→9、8→10、9→11 -- 🐛 **修正审批请求参数**：`approved: bool` + `reason` → `action: string` + `podQuota: int` + `reviewReason: string` - - `action`: 审批动作，值为 `approve` 或 `reject` - - `podQuota`: 批准时必填，批准的 Pod 配额 - - `reviewReason`: 审批意见 - ---- - -### v1.2.7 (2026-01-06) - -**命名规范统一** 🔄更新: -- 🔄 **所有接口请求/响应字段统一使用 camelCase 格式** -- 🔄 平台 Agent 模板配置请求字段：`cpuRequest`, `cpuLimit`, `memoryRequest`, `memoryLimit`, `maxPods`, `isEnabled`, `displayName` -- 🔄 平台 Agent 申请请求字段：`templateName`, `requestedPodQuota`, `reason` -- 🔄 平台 Agent 审批请求字段：`action`, `podQuota`, `reviewReason` -- 🔄 分配平台 Agent 给租户请求字段：`templateName`, `podQuota` -- 🔄 所有响应字段统一使用 camelCase - -**修改的文件**: -- `services/mcp-server/app/routes/platform_agent_quota.py` - 所有 Pydantic 模型字段改为 camelCase - ---- - -### v1.2.6 (2026-01-06) - -**文档与代码一致性修复** 🐛修复: -- 🐛 修复渠道列表响应字段：移除不存在的 `contactPerson`, `contactPhone`, `contactEmail`, `monthlyRevenue` 字段 -- 🐛 修复编辑渠道请求字段：更正为 `name`, `email`, `commissionRate`, `status`（移除不存在的 `contactPerson`, `contactEmail`, `contactPhone`） - ---- - -### v1.2.6 (2026-01-06) - -**资源使用量格式转换** 🔄更新: -- 🔄 `GET /api/admin/monitoring/agents` - cpuUsage 和 memoryUsage 字段现在返回易读格式 -- 🔄 `GET /api/admin/platform-agents/status` - cpuUsage 和 memoryUsage 字段现在返回易读格式 - -**格式转换说明**: -| 原始格式 | 转换后格式 | 说明 | -|---------|-----------|------| -| "830511n" | "0.83m" | CPU: nanocores → millicores | -| "41416Ki" | "40.4Mi" | 内存: KiB → MiB | - -**转换规则**: -- CPU: nanocores (n) 除以 1,000,000 转换为 millicores (m) -- 内存: KiB (Ki) 除以 1024 转换为 MiB (Mi) - ---- - -### v1.2.5 (2026-01-06) - -**Agent 监控接口增强** 🔄更新: -- 🔄 `GET /api/admin/monitoring/agents` - 新增实时资源监控字段，数据从 K8s metrics-server 获取 - -**新增响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| cpuUsage | string | 实时 CPU 使用量（如 "0.83m"，millicores 单位） | -| memoryUsage | string | 实时内存使用量（如 "40.4Mi"，MiB 单位） | -| cpuRequest | string | CPU 请求量（Pod spec 配置） | -| cpuLimit | string | CPU 上限（Pod spec 配置） | -| memoryRequest | string | 内存请求量（Pod spec 配置） | -| memoryLimit | string | 内存上限（Pod spec 配置） | -| cpuUtilization | float | CPU 使用率百分比（相对于 limit） | -| memoryUtilization | float | 内存使用率百分比（相对于 limit） | -| hasRealtimeMetrics | bool | 是否有实时 metrics 数据 | -| metricsTimestamp | string | metrics 数据时间戳 | - -**资源单位说明**: -- CPU 使用量单位：`n` (nanocores)，1核 = 1,000,000,000n -- CPU 配置单位：`m` (millicores)，1核 = 1000m -- 内存使用量单位：`Ki` (KiB) -- 内存配置单位：`Mi` (MiB) - -**Bug 修复**: -- 🐛 修复监控接口返回硬编码资源值的问题，现在返回 metrics-server 的实时数据 - ---- - -### v1.2.4 (2026-01-06) - -**平台 Agent 模板配置** ✨新增: -- ✨ `PUT /api/admin/platform-agents/templates/{name}/config` - 管理员配置平台 Agent 模板资源参数 -- ✨ `GET /api/admin/platform-agents/templates/{name}/config` - 获取平台 Agent 模板配置详情 -- 🔄 `GET /api/channel/available-platform-agents` - 返回管理员配置的资源参数，未配置的模板显示 `isConfigured: false` - -**K8s 资源配置参数说明**: -| 参数 | 说明 | 示例 | -|------|------|------| -| cpuRequest | Pod 启动时保证获得的 CPU | 100m = 0.1 核 | -| cpuLimit | Pod 最多能使用的 CPU | 500m = 0.5 核 | -| memoryRequest | Pod 启动时保证获得的内存 | 128Mi = 128 MiB | -| memoryLimit | Pod 最多能使用的内存 | 512Mi = 512 MiB | -| maxPods | 该模板最大 Pod 数量限制 | 10 | - -**Bug 修复**: -- 🐛 修复渠道分配平台 Agent 给租户时，渠道的 `podUsed` 未正确更新的问题 -- 🐛 修复 `available-platform-agents` 接口返回硬编码资源配置的问题，现在返回管理员配置的值 - ---- - -### v1.2.3 (2026-01-05) - -**租户管理权限变更（完整）** 🔄更新: - -超级管理员操作租户时，**所有接口都必须提供 `channel_id` 参数**，确保租户管理的渠道隔离性： - -| 接口 | 方法 | channel_id 参数位置 | -|------|------|-------------------| -| `/api/admin/tenants` | GET | Query 参数 | -| `/api/channel/tenants` | GET | Query 参数 | -| `/api/channel/tenants/create` | POST | 请求体 `channelId` 字段 | -| `/api/channel/tenants/{id}/resources` | PUT | Query 参数 | -| `/api/channel/tenants/{id}/billing` | PUT | Query 参数 | -| `/api/channel/tenants/{id}/recharge` | POST | Query 参数 | -| `/api/channel/tenants/{id}/credit` | PUT | Query 参数 | -| `/api/channel/tenants/{id}` | DELETE | Query 参数 | -| `/api/channel/tenants/{id}/status` | PUT | Query 参数 | -| `/api/channel/tenants/{id}/permissions` | PUT | Query 参数 | -| `/api/channel/tenants/{id}/password` | PUT | Query 参数 | -| `/api/channel/tenants/{id}/custom-agent-quota` | GET | Query 参数 | -| `/api/channel/tenants/{id}/platform-agents` | POST | Query 参数 | -| `/api/channel/tenants/{id}/platform-agents/usage` | GET | Query 参数 | - -**错误响应示例**: -```json -{ - "detail": "超级管理员必须提供 channel_id 参数" -} -``` - ---- - -### v1.2.2 (2026-01-05) - -**租户管理权限变更** 🔄更新: -- 🔄 `GET /api/admin/tenants` - 超级管理员必须提供 `channel_id` 参数才能查看租户 -- 🔄 `GET /api/channel/tenants` - 超级管理员必须提供 `channel_id` 参数才能查看租户 -- 🔄 `POST /api/channel/tenants/create` - 超级管理员必须在请求体中提供 `channelId` 字段 - -**说明**: 超级管理员现在与渠道管理员一样，必须指定渠道才能查看、创建、修改租户。这确保了租户管理的渠道隔离性。 - ---- - -### v1.2.1 (2026-01-05) - -**平台 Agent 直接分配** ✨新增: -- ✨ `POST /api/admin/platform-agents/allocate` - 管理员直接分配平台 Agent 配额给渠道（无需申请审批） -- ✨ `DELETE /api/admin/platform-agents/allocate` - 管理员撤销渠道的平台 Agent 配额 - -**说明**: 新增的直接分配接口允许管理员绕过申请审批流程，直接给渠道分配或撤销平台 Agent 配额。 - ---- - -### v1.2 (2026-01-05) - -**资源申请审批模块** ✨新增: -- ✨ `GET /api/channel/available-platform-agents` - 渠道查看可用平台 Agent -- ✨ `POST /api/channel/applications/platform-agents` - 渠道申请平台 Agent -- ✨ `POST /api/channel/applications/custom-agent-quota` - 渠道申请自定义 Agent 配额 -- ✨ `GET /api/channel/applications/platform-agents` - 查看渠道的申请列表 -- ✨ `GET /api/admin/applications/platform-agents` - 管理员获取平台 Agent 申请列表 -- ✨ `PUT /api/admin/applications/platform-agents/{id}/review` - 管理员审批平台 Agent 申请 -- ✨ `GET /api/admin/applications/custom-agent-quota` - 管理员获取自定义 Agent 配额申请列表 -- ✨ `PUT /api/admin/applications/custom-agent-quota/{id}/review` - 管理员审批自定义 Agent 配额申请 - -**平台 Agent 管理模块** ✨新增: -- ✨ `GET /api/admin/platform-agents/templates` - 获取平台 Agent 模板列表 -- ✨ `GET /api/admin/platform-agents/allocations` - 获取平台 Agent 分配情况 -- ✨ `GET /api/admin/platform-agents/status` - 获取平台 Agent 运行状态 -- ✨ `GET /api/channel/platform-agents` - 渠道查看平台 Agent 配额 -- ✨ `POST /api/channel/tenants/{id}/platform-agents` - 渠道分配平台 Agent 给租户 -- ✨ `GET /api/user/platform-agents/available` - 租户查看可用平台 Agent -- ✨ `POST /api/user/platform-agents/use` - 租户使用平台 Agent -- ✨ `DELETE /api/user/platform-agents/{instance_name}` - 租户停止平台 Agent -- ✨ `GET /api/user/platform-agents/instances` - 租户查看平台 Agent 实例列表 - -**Agent 计费模块** ✨新增: -- ✨ `GET /api/user/agent-billing/stats` - 用户 Agent 计费统计 -- ✨ `GET /api/user/agent-billing/history` - 用户 Agent 计费历史 -- ✨ `GET /api/channel/agent-billing/stats` - 渠道 Agent 计费统计 -- ✨ `GET /api/channel/agent-billing/history` - 渠道 Agent 计费历史 -- ✨ `GET /api/channel/agent-billing/tenant-summary` - 渠道租户计费汇总 - -**权限更新**: -- 🔄 `channel_admin` 角色新增 `view:applications`, `view:agents`, `view:monitoring`, `manage:agents` 权限 - -**计费模型**: -- 平台 Agent: 按模板固定价格计费（如 gpt-assistant: 0.5元/小时） -- 自定义 Agent: 按资源使用计费（CPU: 0.1元/核/小时，内存: 0.05元/GB/小时） -- EU 计算: 1 EU = 10 秒运行时间 - ---- - -### v1.1 (2026-01-04) - -**Agent 系统重构**: -- ✨ 新增 Agent 类型说明文档（平台端 Agent vs 自定义 Agent） -- 🔄 `GET /api/admin/dashboard/stats` - 新增 `platformAgents` 和 `customAgents` 分类统计 -- 🔄 `GET /api/admin/resources/agents` - 从 agent-manager (K8s) 获取平台端 Agent，从数据库获取自定义 Agent -- 🔄 `GET /api/admin/monitoring/agents` - 支持按 Agent 类型和健康状态筛选，新增汇总统计 -- 🔄 `GET /api/admin/resources/allocation-stats` - 从 K8s 获取平台端 Agent 资源统计 - -**数据来源说明**: -- 平台端 Agent：从 agent-manager 服务（K8s）实时获取 -- 自定义 Agent：从本地数据库获取 -- 所有 Agent 相关 API 现在同时展示两种类型的 Agent - ---- - -### v1.0 (2026-01-04) - -**新增API**: -- ✨ `GET /api/admin/tenants` - 超级管理员租户列表 -- ✨ `GET /api/admin/channels/{channel_id}/resources` - 获取渠道资源配置 -- ✨ `PUT /api/admin/channels/{channel_id}/commission` - 更新渠道佣金 -- ✨ `PUT /api/channel/tenants/{tenant_id}/password` - 租户密码重置 - -**改进**: -- 完善计费数据导出功能的返回格式 -- 增强权限控制说明 - ---- - -## 附录：权限矩阵 - -| 操作 | super_admin | billing_admin | operations_admin | channel_admin | -|------|-------------|---------------|------------------|---------------| -| 查看所有数据 | ✅ | ✅ | ✅ | ❌ | -| 创建/编辑渠道 | ✅ | ✅ | ❌ | ❌ | -| 管理租户 | ✅ | ✅ | ❌ | ✅ (本渠道) | -| 审批申请 | ✅ | ✅ | ❌ | ❌ | -| 管理供应商 | ✅ | ✅ | ❌ | ❌ | -| 管理管理员 | ✅ | ❌ | ❌ | ❌ | -| 申请资源 | ❌ | ✅ | ✅ | ✅ | -| 查看 Agent 计费 | ✅ | ✅ | ✅ | ✅ | - diff --git a/Docs/项目文档/超级管理员控制台-后端接口需求清单(已人工审核).md b/Docs/项目文档/超级管理员控制台-后端接口需求清单(已人工审核).md new file mode 100644 index 0000000..821d248 --- /dev/null +++ b/Docs/项目文档/超级管理员控制台-后端接口需求清单(已人工审核).md @@ -0,0 +1,1530 @@ +# 超级管理员控制台 - 后端接口清单 + +> **版本**: v1.2.0 +> **更新时间**: 2026-01-06 +> **说明**: 本文档基于前端业务逻辑分析，列出所有后端接口需求，包括已对接接口和未对接接口，按钮操作接口和数据展示接口 + +--- + +## 目录 + +1. [概览模块 (Overview)](#概览模块-overview) +2. [渠道管理模块 (Channels)](#渠道管理模块-channels) +3. [资源管理模块 (Resources)](#资源管理模块-resources) +4. [监控模块 (Monitoring)](#监控模块-monitoring) +5. [计费模块 (Billing)](#计费模块-billing) +6. [设置模块 (Settings)](#设置模块-settings) +7. [附录：接口汇总表](#附录接口汇总表) + +--- + +## 概览模块 (Overview) + +### 数据展示接口 + +#### D1. 仪表板统计接口 ✅ 已对接 + +**展示位置**: 概览页面 → 顶部统计卡片区域 + +**展示内容**: +- 总渠道数（如：5） +- 总租户数（如：7） +- 总收入（如：$0） + +**功能描述**: 获取平台整体统计数据，用于概览页面顶部的统计卡片展示 + +**接口**: +``` +GET /api/admin/dashboard/stats +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.totalChannels | int | 总渠道数 | +| data.totalTenants | int | 总租户数 | +| data.totalRevenue | float | 总收入 | +| data.totalAgents | int | 总Agent数（用于活跃指标） | + +**前端调用**: `TaijiAPIClient.getAdminDashboardStats()` + +--- + +#### D2. 系统监控指标接口 ✅ 已对接 + +**展示位置**: 概览页面 → 系统指标卡片 + +**展示内容**: +- CPU使用率（如：5.9%） +- 内存使用率（如：33.6%） +- 存储使用率（如：64.8%） +- 活跃Agent（如：0%） + +**功能描述**: 获取平台整体的系统监控指标 + +**接口**: +``` +GET /api/v1/monitoring/metrics +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.cpu_usage | float | CPU使用率百分比 | +| data.memory_usage | float | 内存使用率百分比 | +| data.disk_usage | float | 存储使用率百分比 | +| data.system.cpu_usage_percent | float | 备选：CPU使用率 | +| data.system.memory_usage_percent | float | 备选：内存使用率 | +| data.system.disk_usage_percent | float | 备选：存储使用率 | + +**前端调用**: `TaijiAPIClient.getMonitoringMetrics()` + +--- + +#### D3. 最近登录租户列表接口 ✅ 已对接 + +**展示位置**: 概览页面 → 最近登录的租户列表 + +**展示内容**: 显示最近登录的租户列表，包含租户名称、邮箱、渠道、状态等 + +**功能描述**: 获取最近登录的租户列表，用于概览页面展示 + +**接口**: +``` +GET /api/admin/dashboard/recent-logins?limit=10 +``` + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| limit | int | 否 | 返回数量，默认10，最多50 | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.recentTenants | array | 最近登录的租户列表 | +| data.recentTenants[].id | string | 租户ID | +| data.recentTenants[].name | string | 租户名称 | +| data.recentTenants[].email | string | 邮箱 | +| data.recentTenants[].channelName | string | 所属渠道 | +| data.recentTenants[].lastLoginAt | string | 最后登录时间 | +| data.recentTenants[].status | string | 状态 | + +**前端调用**: `TaijiAPIClient.getRecentLogins(10)` + +--- + +#### D4. 平台资源分配统计接口 ✅ 已对接（复用） + +**展示位置**: 概览页面 → 平台资源分配统计卡片 + +**展示内容**: +- 已分配CPU（如：0.0 核） +- 已分配内存（如：0.0 GB） +- 共 X 个 Agent +- 平均 X GB/Agent + +**功能描述**: 获取平台所有Agent的资源分配汇总统计 + +**复用接口**: +``` +GET /api/admin/platform-agents/status +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.summary.total | int | Agent总数 | +| data.summary.totalCpuAllocated | float | 已分配CPU总核数 | +| data.summary.totalMemoryAllocated | float | 已分配内存总量（GB） | +| data.summary.avgMemoryPerAgent | float | 平均每Agent内存 | + +**前端调用**: `TaijiAPIClient.getPlatformAgentStatus()` + +--- + +### 按钮操作接口 + +#### 1. 搜索租户按钮 ⚠️ 需新增 + +**按钮位置**: 概览页面 → 最近登录的租户列表 → 搜索框 + +**按钮作用**: 在最近登录的租户列表中搜索特定租户 + +**功能描述**: 用户输入关键词后，根据租户名称、邮箱等字段进行模糊搜索，筛选显示匹配的租户 + +**接口需求**: +``` +GET /api/admin/dashboard/recent-logins/search +``` + +**请求参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| keyword | string | 是 | 搜索关键词（租户名称/邮箱） | +| limit | int | 否 | 返回数量，默认10 | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.recentTenants | array | 匹配的租户列表 | + +--- + +## 渠道管理模块 (Channels) + +### 数据展示接口 + +#### D2. 渠道统计概览接口 + +**展示位置**: 渠道管理页面 → 渠道列表卡片 + +**展示内容**: 每个渠道卡片显示租户数、月收入、佣金比例等统计信息 + +**功能描述**: 获取渠道列表及其统计数据，用于渠道卡片展示 + +**接口需求**: +``` +GET /api/admin/channels/stats +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.channels | array | 渠道列表（含统计数据） | + +--- + +### 按钮操作接口 + +#### 2. 搜索渠道按钮 + +**按钮位置**: 渠道管理页面 → 搜索框 + +**按钮作用**: 在渠道列表中搜索特定渠道 + +**功能描述**: 用户输入关键词后，根据渠道名称、联系人、邮箱等字段进行模糊搜索 + +**接口需求**: +``` +GET /api/admin/channels/search +``` + +**请求参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| keyword | string | 是 | 搜索关键词 | +| status | string | 否 | 状态筛选（active/inactive） | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.channels | array | 匹配的渠道列表 | + +--- + +#### 3. 查看渠道详情按钮 + +**按钮位置**: 渠道管理页面 → 渠道卡片 → 更多操作菜单 → "查看详情" + +**按钮作用**: 查看渠道的完整详细信息 + +**功能描述**: 点击后弹出对话框，显示渠道的基本信息、资源配置、配额信息等详细数据 + +**接口需求**: +``` +GET /api/admin/channels/{channel_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 是 | 渠道ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 渠道ID | +| data.name | string | 渠道名称 | +| data.email | string | 联系邮箱 | +| data.status | string | 状态 | +| data.createdAt | string | 创建时间 | +| data.cpuCores | float | 分配的CPU核心数 | +| data.memory | string | 分配的内存大小 | +| data.tenantCount | int | 租户总数 | +| data.creditLimit | float | 授信额度 | +| data.usedCredit | float | 已用授信 | +| data.remainingCredit | float | 剩余授信 | +| data.commissionRate | float | 佣金比例 | + +--- + +#### 4. 删除渠道按钮 + +**按钮位置**: 渠道管理页面 → 渠道卡片 → 更多操作菜单 → "删除渠道" + +**按钮作用**: 删除指定渠道（软删除） + +**功能描述**: 点击后弹出确认对话框，确认后将渠道状态设为inactive，要求渠道下无活跃租户 + +**接口需求**: +``` +DELETE /api/admin/channels/{channel_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 是 | 渠道ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| message | string | 操作结果消息 | + +--- + +#### 5. 删除租户按钮 + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "删除"按钮 + +**按钮作用**: 删除指定租户（软删除） + +**功能描述**: 点击后弹出确认对话框，确认后将租户状态设为inactive + +**接口需求**: +``` +DELETE /api/channel/tenants/{tenant_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| tenant_id | string | 是 | 租户ID | + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 超级管理员必填 | 渠道ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| message | string | 操作结果消息 | + +--- + +#### 6. 禁用租户按钮 + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "禁用"按钮 + +**按钮作用**: 暂停租户账号 + +**功能描述**: 将租户状态设为suspended，租户将无法登录和使用服务 + +**接口需求**: +``` +PUT /api/channel/tenants/{tenant_id}/status +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| tenant_id | string | 是 | 租户ID | + +**请求体**: +```json +{ + "status": "suspended" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.tenantId | string | 租户ID | +| data.status | string | 新状态 | +| message | string | 操作结果消息 | + +--- + +#### 7. 修改租户密码按钮 + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "修改密码"按钮 + +**按钮作用**: 重置租户登录密码 + +**功能描述**: 点击后弹出对话框，输入新密码和确认密码，提交后更新租户密码 + +**接口需求**: +``` +PUT /api/channel/tenants/{tenant_id}/password +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| tenant_id | string | 是 | 租户ID | + +**请求体**: +```json +{ + "newPassword": "NewSecurePass123" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.tenantId | string | 租户ID | +| message | string | 操作结果消息 | + +--- + +#### 8. 管理租户权限按钮 + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "管理权限"按钮 + +**按钮作用**: 配置租户的功能访问权限 + +**功能描述**: 点击后弹出对话框，显示权限复选框列表，勾选后保存租户的权限配置 + +**接口需求**: +``` +PUT /api/channel/tenants/{tenant_id}/permissions +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| tenant_id | string | 是 | 租户ID | + +**请求体**: +```json +{ + "permissions": ["dashboard", "agents", "models", "billing", "resources", "data-tools", "api-gateway"] +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.tenantId | string | 租户ID | +| data.permissions | array | 更新后的权限列表 | +| message | string | 操作结果消息 | + +--- + +#### 9. 供应商申请审批-拒绝按钮 + +**按钮位置**: 渠道管理页面 → 渠道申请审批表格 → "审批"按钮 → 审批对话框 → "拒绝"按钮 + +**按钮作用**: 拒绝渠道的供应商申请 + +**功能描述**: 点击后将申请状态设为rejected，渠道将无法使用该供应商 + +**接口需求**: +``` +PUT /api/admin/providers/applications/{application_id}/review +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| application_id | string | 是 | 申请ID | + +**请求体**: +```json +{ + "approved": false, + "reason": "申请被拒绝" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.applicationId | string | 申请ID | +| data.status | string | 新状态（rejected） | +| message | string | 操作结果消息 | + +--- + +#### 10. 供应商申请审批-批准按钮 + +**按钮位置**: 渠道管理页面 → 渠道申请审批表格 → "审批"按钮 → 审批对话框 → "批准"按钮 + +**按钮作用**: 批准渠道的供应商申请 + +**功能描述**: 点击后将申请状态设为approved，自动创建ChannelProviderAccess记录 + +**接口需求**: +``` +PUT /api/admin/providers/applications/{application_id}/review +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| application_id | string | 是 | 申请ID | + +**请求体**: +```json +{ + "approved": true, + "reason": "申请已批准" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.applicationId | string | 申请ID | +| data.status | string | 新状态（approved） | +| message | string | 操作结果消息 | + +--- + +#### 11. 平台Agent申请审批-拒绝按钮 + +**按钮位置**: 渠道管理页面 → 平台Agent申请审批表格 → "审批"按钮 → 审批对话框 → "拒绝"按钮 + +**按钮作用**: 拒绝渠道的平台Agent申请 + +**功能描述**: 点击后将申请状态设为rejected，渠道将无法使用该平台Agent + +**接口需求**: +``` +PUT /api/admin/applications/platform-agents/{application_id}/review +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| application_id | string | 是 | 申请ID | + +**请求体**: +```json +{ + "action": "reject", + "reviewReason": "申请被拒绝" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.applicationId | string | 申请ID | +| data.status | string | 新状态（rejected） | +| message | string | 操作结果消息 | + +--- + +#### 12. 平台Agent申请审批-批准按钮 + +**按钮位置**: 渠道管理页面 → 平台Agent申请审批表格 → "审批"按钮 → 审批对话框 → "批准"按钮 + +**按钮作用**: 批准渠道的平台Agent申请 + +**功能描述**: 点击后将申请状态设为approved，为渠道分配指定数量的Pod配额 + +**接口需求**: +``` +PUT /api/admin/applications/platform-agents/{application_id}/review +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| application_id | string | 是 | 申请ID | + +**请求体**: +```json +{ + "action": "approve", + "podQuota": 5, + "reviewReason": "申请已批准" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.applicationId | string | 申请ID | +| data.status | string | 新状态（approved） | +| message | string | 操作结果消息 | + +--- + +#### 27. 保存资源配置按钮 + +**按钮位置**: 渠道管理页面 → 渠道卡片 → "资源管理"菜单项 → 资源管理对话框 → "保存配置"按钮 + +**按钮作用**: 保存渠道的资源配置（模型、Agent、自定义Agent资源、授信额度） + +**功能描述**: 为渠道配置可用的模型供应商、Agent分配及数量、自定义Agent的CPU/内存资源、授信额度 + +**接口需求**: +``` +PUT /api/admin/channels/{channel_id}/resources +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 是 | 渠道ID | + +**请求体**: +```json +{ + "models": ["model-id-1", "model-id-2"], + "agents": [ + {"agentId": "agent-id-1", "quantity": 10}, + {"agentId": "agent-id-2", "quantity": 5} + ], + "customAgentResources": {"cpu": 2.0, "memory": 4.0}, + "channelCredit": 100000.00 +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.channelId | string | 渠道ID | +| message | string | 操作结果消息 | + +--- + +#### 28. 保存渠道编辑按钮 + +**按钮位置**: 渠道管理页面 → 渠道卡片 → "编辑"菜单项 → 编辑对话框 → "保存更改"按钮 + +**按钮作用**: 保存渠道基本信息的修改 + +**功能描述**: 修改渠道名称、联系人、邮箱、电话等基本信息 + +**接口需求**: +``` +PUT /api/admin/channels/{channel_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 是 | 渠道ID | + +**请求体**: +```json +{ + "name": "更新后的渠道名", + "email": "newemail@channel.com", + "contactName": "张三", + "phone": "+86-10-12345678" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 渠道ID | +| message | string | 操作结果消息 | + +--- + +#### 29. 保存佣金修改按钮 + +**按钮位置**: 渠道管理页面 → 渠道卡片 → "修改佣金"菜单项 → 佣金对话框 → "保存"按钮 + +**按钮作用**: 更新渠道的佣金比例 + +**功能描述**: 修改渠道的佣金分成比例 + +**接口需求**: +``` +PUT /api/admin/channels/{channel_id}/commission +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 是 | 渠道ID | + +**请求体**: +```json +{ + "commissionRate": 0.18 +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.channelId | string | 渠道ID | +| data.commissionRate | float | 新的佣金比例 | +| message | string | 操作结果消息 | + +--- + +#### 30. 创建渠道按钮 + +**按钮位置**: 渠道管理页面 → "添加渠道"按钮 → 创建对话框 → "创建"按钮 + +**按钮作用**: 创建新的分销渠道 + +**功能描述**: 填写渠道名称、邮箱、密码、佣金比例，创建新渠道账户 + +**接口需求**: +``` +POST /api/admin/channels/create +``` + +**请求体**: +```json +{ + "name": "新渠道", + "email": "channel@example.com", + "password": "SecurePass123", + "commissionRate": 0.15 +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 渠道ID | +| data.name | string | 渠道名称 | +| message | string | 操作结果消息 | + +--- + +#### 31. 添加租户按钮 + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → "添加租户"按钮 → 添加租户对话框 → "创建租户"按钮 + +**按钮作用**: 为渠道创建新租户或管理员 + +**功能描述**: 填写租户名称、邮箱、密码、系统权限，创建新租户或渠道管理员 + +**接口需求（创建租户）**: +``` +POST /api/channel/tenants/create +``` + +**请求体**: +```json +{ + "name": "租户名称", + "email": "tenant@example.com", + "password": "SecurePass123", + "subscriptionTier": "free", + "channelId": "channel-uuid" +} +``` + +**接口需求（创建渠道管理员）**: +``` +POST /api/admin/admins/create +``` + +**请求体**: +```json +{ + "name": "管理员名称", + "email": "admin@example.com", + "password": "SecurePass123", + "role": "billing_admin", + "channelId": "channel-uuid" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 用户ID | +| message | string | 操作结果消息 | + +--- + +#### 32. 删除渠道管理员按钮 + +**按钮位置**: 渠道管理页面 → 编辑渠道对话框 → 管理员管理区域 → 管理员行 → 删除图标按钮 + +**按钮作用**: 从渠道移除管理员 + +**功能描述**: 点击后将管理员从该渠道移除 + +**接口需求**: +``` +DELETE /api/admin/channels/{channel_id}/admins/{admin_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 是 | 渠道ID | +| admin_id | string | 是 | 管理员ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| message | string | 操作结果消息 | + +--- + +## 资源管理模块 (Resources) + +### 数据展示接口 + +#### D3. Agent模板列表接口 + +**展示位置**: 资源管理页面 → 平台Agent模板管理区域 + +**展示内容**: 显示所有可用的Agent模板卡片，包含名称、描述、CPU/内存配置等 + +**功能描述**: 获取平台所有Agent模板的列表和配置信息 + +**接口需求**: +``` +GET /api/admin/platform-agents/templates +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.templates | array | 模板列表 | +| data.templates[].id | string | 模板ID | +| data.templates[].name | string | 模板名称 | +| data.templates[].displayName | string | 显示名称 | +| data.templates[].description | string | 模板描述 | +| data.templates[].cpuRequest | string | CPU请求量 | +| data.templates[].cpuLimit | string | CPU上限 | +| data.templates[].memoryRequest | string | 内存请求量 | +| data.templates[].memoryLimit | string | 内存上限 | +| data.templates[].maxPods | int | 最大Pod数量 | +| data.templates[].isEnabled | bool | 是否启用 | + +--- + +#### D4. 模型供应商列表接口 + +**展示位置**: 资源管理页面 → 货源供应商管理区域 + +**展示内容**: 显示所有模型供应商卡片，包含名称、状态、支持模型数、RPM/TPM等 + +**功能描述**: 获取平台所有模型供应商的列表和配置信息 + +**接口需求**: +``` +GET /api/providers/models +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.providers | array | 供应商列表 | +| data.providers[].id | string | 供应商ID | +| data.providers[].name | string | 供应商名称 | +| data.providers[].provider | string | 供应商类型 | +| data.providers[].supportedModels | array | 支持的模型列表 | +| data.providers[].rpm | int | 每分钟请求数限制 | +| data.providers[].tpm | int | 每分钟令牌数限制 | +| data.providers[].status | string | 状态 | + +--- + +### 按钮操作接口 + +#### 13. Agent模板配置-保存按钮 + +**按钮位置**: 资源管理页面 → Agent模板卡片 → "配置"按钮 → 配置对话框 → "保存配置"按钮 + +**按钮作用**: 保存Agent模板的K8s资源配置 + +**功能描述**: 配置Agent模板的CPU请求/限制、内存请求/限制、最大实例数等参数 + +**接口需求**: +``` +PUT /api/admin/platform-agents/templates/{name}/config +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| name | string | 是 | 模板名称（如 echo_agent） | + +**请求体**: +```json +{ + "cpuRequest": "100m", + "cpuLimit": "500m", + "memoryRequest": "128Mi", + "memoryLimit": "512Mi", + "maxPods": 10, + "isEnabled": true, + "displayName": "Echo 测试服务", + "description": "简单的 Echo 服务，用于测试和调试" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.templateName | string | 模板名称 | +| message | string | 操作结果消息 | + +--- + +#### 14. Agent模板删除按钮 + +**按钮位置**: 资源管理页面 → Agent模板卡片 → "删除"按钮 + +**按钮作用**: 删除Agent模板配置 + +**功能描述**: 点击后弹出确认对话框，确认后删除该Agent模板的配置 + +**接口需求**: +``` +DELETE /api/admin/platform-agents/templates/{name} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| name | string | 是 | 模板名称 | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| message | string | 操作结果消息 | + +--- + +#### 15. 添加模型供应商按钮 + +**按钮位置**: 资源管理页面 → "添加模型供应商"按钮 + +**按钮作用**: 创建新的模型供应商配置 + +**功能描述**: 点击后弹出对话框，填写供应商名称、API URL、API密钥、支持的模型列表、RPM/TPM限制等信息 + +**接口需求**: +``` +POST /api/providers/models/create +``` + +**请求体**: +```json +{ + "name": "OpenAI", + "provider": "openai", + "apiKey": "sk-...", + "apiUrl": "https://api.openai.com/v1", + "supportedModels": ["gpt-4", "gpt-3.5-turbo"], + "rpm": 1000, + "tpm": 100000 +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 供应商ID | +| message | string | 操作结果消息 | + +--- + +#### 16. 模型供应商配置按钮 + +**按钮位置**: 资源管理页面 → 模型供应商卡片 → "配置"按钮 + +**按钮作用**: 修改模型供应商配置 + +**功能描述**: 点击后弹出对话框，可修改供应商的API URL、API密钥、支持的模型列表、RPM/TPM限制等 + +**接口需求**: +``` +PUT /api/providers/models/{provider_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| provider_id | string | 是 | 供应商ID | + +**请求体**: +```json +{ + "name": "OpenAI", + "apiUrl": "https://api.openai.com/v1", + "apiKey": "sk-...", + "supportedModels": ["gpt-4", "gpt-3.5-turbo", "gpt-4-turbo"], + "rpm": 2000, + "tpm": 200000 +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 供应商ID | +| message | string | 操作结果消息 | + +--- + +#### 17. 模型供应商测试延迟按钮 + +**按钮位置**: 资源管理页面 → 模型供应商卡片 → "测试延迟"按钮 + +**按钮作用**: 测试与模型供应商的连接状态和延迟 + +**功能描述**: 点击后向供应商API发送测试请求，返回连接状态和响应延迟 + +**接口需求**: +``` +POST /api/providers/models/{provider_id}/test +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| provider_id | string | 是 | 供应商ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.status | string | 连接状态（connected/failed） | +| data.latency | int | 响应延迟（毫秒） | +| data.message | string | 测试结果消息 | + +--- + +#### 18. 模型供应商删除按钮 + +**按钮位置**: 资源管理页面 → 模型供应商卡片 → "删除"按钮 + +**按钮作用**: 删除模型供应商配置 + +**功能描述**: 点击后弹出确认对话框，确认后删除该供应商配置 + +**接口需求**: +``` +DELETE /api/providers/models/{provider_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| provider_id | string | 是 | 供应商ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| message | string | 操作结果消息 | + +--- + +## 监控模块 (Monitoring) + +### 数据展示接口 + +#### D5. Agent健康监控汇总接口 + +**展示位置**: 监控页面 → Agent健康监控区域 → 汇总统计卡片 + +**展示内容**: 显示Agent总数、健康Agent数、警告/异常Agent数等汇总统计 + +**功能描述**: 获取所有Agent的健康状态汇总统计 + +**接口需求**: +``` +GET /api/admin/platform-agents/status +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.summary.total | int | Agent总数 | +| data.summary.byHealthStatus.healthy | int | 健康Agent数 | +| data.summary.byHealthStatus.warning | int | 警告Agent数 | +| data.summary.byHealthStatus.critical | int | 异常Agent数 | +| data.agents | array | Agent详细列表 | + +--- + +#### D6. Agent详细指标接口 + +**展示位置**: 监控页面 → Agent健康监控区域 → Agent卡片 + +**展示内容**: 每个Agent卡片显示CPU使用率、内存使用率、CPU/内存上限、运行状态等 + +**功能描述**: 获取每个Agent的详细资源使用指标 + +**接口需求**: +``` +GET /api/admin/platform-agents/status +``` + +**响应字段（agents数组中每个元素）**: +| 字段 | 类型 | 说明 | +|------|------|------| +| id | string | Agent ID | +| name | string | Agent名称 | +| type | string | Agent类型（platform/custom） | +| healthStatus | string | 健康状态（healthy/warning/critical） | +| cpuUsage | string | CPU实际使用量 | +| cpuLimit | string | CPU上限 | +| cpuUtilization | float | CPU利用率百分比 | +| memoryUsage | string | 内存实际使用量 | +| memoryLimit | string | 内存上限 | +| memoryUtilization | float | 内存利用率百分比 | +| status | string | 运行状态 | +| source | string | 数据来源（k8s/database） | + +--- + +#### D7. 系统监控指标接口 + +**展示位置**: 概览页面 → 系统指标卡片 + +**展示内容**: 显示CPU使用率、内存使用率、存储使用率、活跃Agent数等系统级指标 + +**功能描述**: 获取平台整体的系统监控指标 + +**接口需求**: +``` +GET /api/v1/monitoring/metrics +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.cpu_usage | float | CPU使用率百分比 | +| data.memory_usage | float | 内存使用率百分比 | +| data.disk_usage | float | 存储使用率百分比 | +| data.active_agents | int | 活跃Agent数量 | + +--- + +## 计费模块 (Billing) + +### 数据展示接口 + +#### D8. 计费概览统计接口 + +**展示位置**: 计费管理页面 → 统计卡片区域 + +**展示内容**: 显示渠道总数、总计费额、总EU消耗等汇总统计 + +**功能描述**: 获取计费数据的汇总统计信息 + +**接口需求**: +``` +GET /api/admin/billing/overview +``` + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| startTime | string | 是 | 开始时间（ISO 8601格式） | +| endTime | string | 是 | 结束时间（ISO 8601格式） | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.summary.totalChannels | int | 渠道总数 | +| data.summary.totalBilling | float | 总计费额 | +| data.summary.totalEU | int | 总EU消耗 | + +--- + +#### D9. 渠道维度计费详情接口 + +**展示位置**: 计费管理页面 → 渠道维度 → 渠道计费详情表格 + +**展示内容**: 显示每个渠道的调用次数、总EU、渠道总价等 + +**功能描述**: 获取按渠道维度分组的计费详情 + +**接口需求**: +``` +GET /api/admin/billing/overview +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.channelStats | array | 渠道统计列表 | +| data.channelStats[].channelId | string | 渠道ID | +| data.channelStats[].channelName | string | 渠道名称 | +| data.channelStats[].calls | int | 调用次数 | +| data.channelStats[].totalEU | int | 总EU | +| data.channelStats[].totalCost | float | 渠道总价 | + +--- + +#### D10. 租户维度计费详情接口 + +**展示位置**: 计费管理页面 → 租户维度 → 租户计费详情表格 + +**展示内容**: 显示每个租户的所属渠道、调用次数、总EU、用户总价等 + +**功能描述**: 获取按租户维度分组的计费详情 + +**接口需求**: +``` +GET /api/admin/billing/overview +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.tenantStats | array | 租户统计列表 | +| data.tenantStats[].tenantId | string | 租户ID | +| data.tenantStats[].tenantName | string | 租户名称 | +| data.tenantStats[].channelName | string | 渠道名称 | +| data.tenantStats[].calls | int | 调用次数 | +| data.tenantStats[].totalEU | int | 总EU | +| data.tenantStats[].totalCost | float | 用户总价 | + +--- + +#### D11. 调用记录明细接口 + +**展示位置**: 计费管理页面 → 调用记录 → 调用记录明细表格 + +**展示内容**: 显示每次调用的ID、租户、渠道、调用时间、时长、EU、单次调用总价等 + +**功能描述**: 获取详细的调用记录列表 + +**接口需求**: +``` +GET /api/admin/billing/call-records +``` + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| startTime | string | 是 | 开始时间 | +| endTime | string | 是 | 结束时间 | +| page | int | 否 | 页码，默认1 | +| pageSize | int | 否 | 每页数量，默认20 | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.records | array | 调用记录列表 | +| data.records[].id | string | 调用ID | +| data.records[].tenantName | string | 租户名称 | +| data.records[].channelName | string | 渠道名称 | +| data.records[].callTime | string | 调用时间 | +| data.records[].duration | int | 时长（秒） | +| data.records[].eu | float | EU消耗 | +| data.records[].cost | float | 单次调用总价 | +| data.pagination.total | int | 总记录数 | +| data.pagination.page | int | 当前页 | + +--- + +### 按钮操作接口 + +#### 19. 时间查询按钮 + +**按钮位置**: 计费管理页面 → "时间查询"按钮 + +**按钮作用**: 按时间范围筛选计费数据 + +**功能描述**: 点击后弹出对话框，选择开始时间和结束时间，查询该时间段内的计费数据 + +**接口需求**: +``` +GET /api/admin/billing/overview +``` + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| startTime | string | 是 | 开始时间（ISO 8601格式） | +| endTime | string | 是 | 结束时间（ISO 8601格式） | + +--- + +#### 20. 筛选按钮 + +**按钮位置**: 计费管理页面 → "筛选"按钮 + +**按钮作用**: 按条件筛选计费数据 + +**功能描述**: 点击后弹出对话框，可按客户名称、最小/最大调用次数等条件筛选 + +**接口需求**: +``` +GET /api/admin/billing/overview +``` + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| startTime | string | 是 | 开始时间 | +| endTime | string | 是 | 结束时间 | +| channelName | string | 否 | 渠道名称筛选 | +| tenantName | string | 否 | 租户名称筛选 | +| minCalls | int | 否 | 最小调用次数 | +| maxCalls | int | 否 | 最大调用次数 | + +--- + +#### 21. 导出按钮 + +**按钮位置**: 计费管理页面 → "导出"按钮 + +**按钮作用**: 导出计费数据为文件 + +**功能描述**: 点击后将当前筛选条件下的计费数据导出为Excel/CSV/PDF格式文件 + +**接口需求**: +``` +GET /api/admin/billing/export +``` + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| startTime | string | 是 | 开始时间 | +| endTime | string | 是 | 结束时间 | +| format | string | 是 | 导出格式（excel/csv/pdf） | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.fileUrl | string | 导出文件下载URL | +| message | string | 操作结果消息 | + +--- + +## 设置模块 (Settings) + +### 数据展示接口 + +#### D12. 管理员列表接口 + +**展示位置**: 设置页面 → 当前管理员列表 + +**展示内容**: 显示所有系统管理员的姓名、邮箱、角色、状态等 + +**功能描述**: 获取系统管理员列表 + +**接口需求**: +``` +GET /api/admin/admins +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.admins | array | 管理员列表 | +| data.admins[].id | string | 管理员ID | +| data.admins[].name | string | 管理员姓名 | +| data.admins[].email | string | 邮箱 | +| data.admins[].role | string | 角色 | +| data.admins[].status | string | 状态 | + +--- + +### 按钮操作接口 + +#### 22. 添加管理员按钮 + +**按钮位置**: 设置页面 → 当前管理员列表 → "添加管理员"按钮 + +**按钮作用**: 创建新的系统管理员账户 + +**功能描述**: 点击后弹出对话框，填写管理员姓名、邮箱、密码、角色，创建新管理员 + +**接口需求**: +``` +POST /api/admin/admins/create +``` + +**请求体**: +```json +{ + "name": "管理员姓名", + "email": "admin@example.com", + "password": "SecurePass123", + "role": "billing_admin" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 管理员ID | +| message | string | 操作结果消息 | + +--- + +#### 23. 删除管理员按钮 + +**按钮位置**: 设置页面 → 当前管理员列表 → 管理员行 → 删除图标按钮 + +**按钮作用**: 删除系统管理员账户（软删除） + +**功能描述**: 点击后弹出确认对话框，确认后将管理员状态设为inactive + +**接口需求**: +``` +DELETE /api/admin/admins/{admin_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| admin_id | string | 是 | 管理员ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| message | string | 操作结果消息 | + +--- + +#### 24-26. 角色权限配置按钮 + +**按钮位置**: 设置页面 → 角色权限配置区域 → "保存权限配置"按钮 + +**按钮作用**: 保存角色的标签页访问权限配置 + +**功能描述**: 选择角色后，勾选该角色可访问的标签页，点击保存更新权限配置 + +**接口需求**: +``` +PUT /api/admin/roles/{role_id}/permissions +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| role_id | string | 是 | 角色ID（billing-admin/operations-admin/super-admin） | + +**请求体**: +```json +{ + "permissions": ["overview", "channels", "resources", "monitoring", "billing", "settings"] +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.roleId | string | 角色ID | +| data.permissions | array | 更新后的权限列表 | +| message | string | 操作结果消息 | + +--- + +## 附录：接口汇总表 + +### 数据展示接口汇总 + +| 序号 | 接口 | 方法 | 展示内容 | 模块 | +|------|------|------|----------|------| +| D1 | /api/admin/platform/resource-allocation | GET | 平台资源分配统计 | 概览 | +| D2 | /api/admin/channels/stats | GET | 渠道统计概览 | 渠道管理 | +| D3 | /api/admin/platform-agents/templates | GET | Agent模板列表 | 资源管理 | +| D4 | /api/providers/models | GET | 模型供应商列表 | 资源管理 | +| D5 | /api/admin/platform-agents/status | GET | Agent健康监控汇总 | 监控 | +| D6 | /api/admin/platform-agents/status | GET | Agent详细指标 | 监控 | +| D7 | /api/v1/monitoring/metrics | GET | 系统监控指标 | 概览 | +| D8 | /api/admin/billing/overview | GET | 计费概览统计 | 计费 | +| D9 | /api/admin/billing/overview | GET | 渠道维度计费详情 | 计费 | +| D10 | /api/admin/billing/overview | GET | 租户维度计费详情 | 计费 | +| D11 | /api/admin/billing/call-records | GET | 调用记录明细 | 计费 | +| D12 | /api/admin/admins | GET | 管理员列表 | 设置 | + +### 按钮操作接口汇总 + +| 序号 | 接口 | 方法 | 按钮/功能 | 模块 | +|------|------|------|----------|------| +| 1 | /api/admin/dashboard/recent-logins/search | GET | 搜索租户 | 概览 | +| 2 | /api/admin/channels/search | GET | 搜索渠道 | 渠道管理 | +| 3 | /api/admin/channels/{channel_id} | GET | 查看渠道详情 | 渠道管理 | +| 4 | /api/admin/channels/{channel_id} | DELETE | 删除渠道 | 渠道管理 | +| 5 | /api/channel/tenants/{tenant_id} | DELETE | 删除租户 | 渠道管理 | +| 6 | /api/channel/tenants/{tenant_id}/status | PUT | 禁用租户 | 渠道管理 | +| 7 | /api/channel/tenants/{tenant_id}/password | PUT | 修改租户密码 | 渠道管理 | +| 8 | /api/channel/tenants/{tenant_id}/permissions | PUT | 管理租户权限 | 渠道管理 | +| 9 | /api/admin/providers/applications/{id}/review | PUT | 供应商申请审批-拒绝 | 渠道管理 | +| 10 | /api/admin/providers/applications/{id}/review | PUT | 供应商申请审批-批准 | 渠道管理 | +| 11 | /api/admin/applications/platform-agents/{id}/review | PUT | 平台Agent申请审批-拒绝 | 渠道管理 | +| 12 | /api/admin/applications/platform-agents/{id}/review | PUT | 平台Agent申请审批-批准 | 渠道管理 | +| 13 | /api/admin/platform-agents/templates/{name}/config | PUT | Agent模板配置-保存 | 资源管理 | +| 14 | /api/admin/platform-agents/templates/{name} | DELETE | Agent模板删除 | 资源管理 | +| 15 | /api/providers/models/create | POST | 添加模型供应商 | 资源管理 | +| 16 | /api/providers/models/{provider_id} | PUT | 模型供应商配置 | 资源管理 | +| 17 | /api/providers/models/{provider_id}/test | POST | 模型供应商测试延迟 | 资源管理 | +| 18 | /api/providers/models/{provider_id} | DELETE | 模型供应商删除 | 资源管理 | +| 19 | /api/admin/billing/overview | GET | 时间查询 | 计费 | +| 20 | /api/admin/billing/overview | GET | 筛选 | 计费 | +| 21 | /api/admin/billing/export | GET | 导出 | 计费 | +| 22 | /api/admin/admins/create | POST | 添加管理员 | 设置 | +| 23 | /api/admin/admins/{admin_id} | DELETE | 删除管理员 | 设置 | +| 24-26 | /api/admin/roles/{role_id}/permissions | PUT | 保存权限配置 | 设置 | +| 27 | /api/admin/channels/{channel_id}/resources | PUT | 保存资源配置 | 渠道管理 | +| 28 | /api/admin/channels/{channel_id} | PUT | 保存渠道编辑 | 渠道管理 | +| 29 | /api/admin/channels/{channel_id}/commission | PUT | 保存佣金修改 | 渠道管理 | +| 30 | /api/admin/channels/create | POST | 创建渠道 | 渠道管理 | +| 31 | /api/channel/tenants/create | POST | 添加租户 | 渠道管理 | +| 32 | /api/admin/channels/{channel_id}/admins/{admin_id} | DELETE | 删除渠道管理员 | 渠道管理 | + +--- + +## 更新日志 + +### v1.1.0 (2026-01-06) + +- 新增数据展示接口（D1-D12） +- 补充监控模块的Agent详细指标接口 +- 补充计费模块的调用记录明细接口 +- 完善接口汇总表 \ No newline at end of file diff --git a/Docs/项目文档/超级管理员控制台-接口对接文档.md b/Docs/项目文档/超级管理员控制台-接口对接文档.md new file mode 100644 index 0000000..9c40a0a --- /dev/null +++ b/Docs/项目文档/超级管理员控制台-接口对接文档.md @@ -0,0 +1,1414 @@ +# 超级管理员控制台 - 接口对接文档 + +> **版本**: v1.0.1 +> **更新时间**: 2026-01-06 +> **说明**: 本文档基于前端业务需求清单与后端API接口清单核实，列出所有超级管理员端接口的对接状态 +> **最新测试**: 2026-01-06 13:37 UTC - 所有已对接接口测试通过 + +--- + +## 目录 + +1. [接口对接状态总览](#接口对接状态总览) +2. [概览模块 (Overview)](#概览模块-overview) +3. [渠道管理模块 (Channels)](#渠道管理模块-channels) +4. [资源管理模块 (Resources)](#资源管理模块-resources) +5. [监控模块 (Monitoring)](#监控模块-monitoring) +6. [计费模块 (Billing)](#计费模块-billing) +7. [设置模块 (Settings)](#设置模块-settings) +8. [接口汇总表](#接口汇总表) +9. [未对接接口清单](#未对接接口清单) + +--- + +## 接口对接状态总览 + +| 类别 | 总数 | 已对接 | 未对接 | 对接率 | +|------|------|--------|--------|--------| +| 数据展示接口 | 12 | 10 | 2 | 83.3% | +| 按钮操作接口 | 32 | 27 | 5 | 84.4% | +| **合计** | **44** | **37** | **7** | **84.1%** | + +### 状态说明 +- ✅ **已对接**: 后端接口已实现，前端可直接调用 +- ⚠️ **部分对接**: 接口存在但参数或响应格式需调整 +- ❌ **未对接**: 后端接口未实现，需要开发 + +--- + +## 概览模块 (Overview) + +### 数据展示接口 + +#### D1. 仪表板统计接口 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/dashboard/stats` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin, billing_admin, operations_admin | + +**展示位置**: 概览页面 → 顶部统计卡片区域 + +**展示内容**: +- 总渠道数 +- 总租户数 +- 总收入 +- 总Agent数 + +**响应字段**: +```json +{ + "success": true, + "data": { + "totalChannels": 5, + "totalTenants": 7, + "totalAgents": 0, + "totalCalls": 0, + "totalRevenue": 0.0, + "totalAllocatedCpu": 7.0, + "totalAllocatedMemory": 7.0, + "platformAgents": { + "count": 14, + "cpu": 7.0, + "memory": 7.0 + }, + "customAgents": { + "count": 0, + "cpu": 0, + "memory": 0 + } + }, + "message": null +} +``` + +> **实际测试结果** (2026-01-06): ✅ 接口正常，返回字段比文档更丰富，包含平台Agent和自定义Agent的详细统计 + +**前端调用**: `TaijiAPIClient.getAdminDashboardStats()` + +--- + +#### D2. 系统监控指标接口 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/v1/monitoring/metrics` | +| **后端状态** | ✅ 已实现 (monitoring.py) | +| **权限要求** | 无（公开接口） | + +**展示位置**: 概览页面 → 系统指标卡片 + +**展示内容**: +- CPU使用率 +- 内存使用率 +- 存储使用率 +- 活跃Agent + +**响应字段**: +```json +{ + "timestamp": "2026-01-06T13:33:13.415377", + "system": { + "cpu_usage_percent": 16.1, + "memory_usage_percent": 27.9, + "memory_used_mb": 8448.43, + "memory_total_mb": 32047.15, + "disk_usage_percent": 65.1, + "disk_used_gb": 80.07, + "disk_total_gb": 122.95 + }, + "services": { + "active_agents": 0, + "total_executions_24h": 0, + "success_rate_percent": 0.0, + "avg_execution_time_ms": 0.0, + "daily_active_users": 0 + }, + "billing": { + "total_eu_consumed_24h": 0.0, + "total_cost_24h": 0.0 + } +} +``` + +> **实际测试结果** (2026-01-06): ✅ 接口正常，响应格式与文档略有不同，不包含外层 `success` 字段 + +**前端调用**: `TaijiAPIClient.getMonitoringMetrics()` + +--- + +#### D3. 最近登录租户列表接口 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/dashboard/recent-logins` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin, billing_admin, operations_admin | + +**展示位置**: 概览页面 → 最近登录的租户列表 + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| limit | int | 否 | 返回数量，默认10，最多50 | + +**响应字段**: +```json +{ + "success": true, + "data": { + "recentTenants": [ + { + "id": "tenant-uuid", + "name": "租户名称", + "email": "tenant@example.com", + "channelName": "渠道A", + "lastLoginAt": "2026-01-06T10:00:00Z", + "status": "active" + } + ] + } +} +``` + +**前端调用**: `TaijiAPIClient.getRecentLogins(10)` + +--- + +#### D4. 平台资源分配统计接口 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/platform-agents/status` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin, billing_admin, operations_admin | + +**展示位置**: 概览页面 → 平台资源分配统计卡片 + +**展示内容**: +- 已分配CPU +- 已分配内存 +- Agent总数 +- 平均内存/Agent + +**响应字段**: +```json +{ + "success": true, + "data": { + "summary": { + "total": 10, + "totalCpuAllocated": 2.0, + "totalMemoryAllocated": 4.0, + "avgMemoryPerAgent": 0.4 + }, + "agents": [] + } +} +``` + +**前端调用**: `TaijiAPIClient.getPlatformAgentStatus()` + +--- + +## 渠道管理模块 (Channels) + +### 数据展示接口 + +#### D5. 渠道列表接口 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/channels` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin, billing_admin, operations_admin | + +**展示位置**: 渠道管理页面 → 渠道列表卡片 + +**响应字段**: +```json +{ + "success": true, + "data": { + "channels": [ + { + "id": "channel-uuid", + "name": "渠道名称", + "email": "channel@example.com", + "status": "active", + "tenantCount": 5, + "commissionRate": 0.15, + "createdAt": "2026-01-01T00:00:00Z" + } + ] + } +} +``` + +--- + +#### D6. 渠道统计概览接口 ❌ 未对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/channels/stats` | +| **后端状态** | ❌ 未实现 | +| **权限要求** | super_admin, billing_admin, operations_admin | + +**说明**: 前端需求中需要获取渠道的统计数据（租户数、月收入、佣金比例等），当前后端 `/api/admin/channels` 接口可能已包含部分统计数据，建议确认是否需要单独实现此接口或复用现有接口。 + +--- + +### 按钮操作接口 + +#### 1. 搜索渠道 ❌ 未对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/channels/search` | +| **后端状态** | ❌ 未实现 | +| **权限要求** | super_admin, billing_admin, operations_admin | + +**按钮位置**: 渠道管理页面 → 搜索框 + +**说明**: 建议在 `/api/admin/channels` 接口中添加搜索参数支持，或实现独立的搜索接口。 + +**建议请求参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| keyword | string | 是 | 搜索关键词 | +| status | string | 否 | 状态筛选（active/inactive） | + +--- + +#### 2. 查看渠道详情 ⚠️ 部分对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/channels/{channel_id}` | +| **后端状态** | ⚠️ 需确认（可能通过 channels 列表获取） | +| **权限要求** | super_admin, billing_admin, operations_admin | + +**按钮位置**: 渠道管理页面 → 渠道卡片 → 更多操作菜单 → "查看详情" + +**说明**: 后端 API 清单中未明确列出单个渠道详情接口，但 `PUT /api/admin/channels/{channel_id}` 存在，建议确认是否有对应的 GET 接口。 + +--- + +#### 3. 删除渠道 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `DELETE /api/admin/channels/{channel_id}` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin | + +**按钮位置**: 渠道管理页面 → 渠道卡片 → 更多操作菜单 → "删除渠道" + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 是 | 渠道ID | + +**响应字段**: +```json +{ + "success": true, + "message": "渠道删除成功" +} +``` + +--- + +#### 4. 删除租户 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `DELETE /api/channel/tenants/{tenant_id}` | +| **后端状态** | ✅ 已实现 (channel.py) | +| **权限要求** | channel_admin | + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "删除"按钮 + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| tenant_id | string | 是 | 租户ID | + +**响应字段**: +```json +{ + "success": true, + "message": "租户删除成功" +} +``` + +--- + +#### 5. 禁用租户 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `PUT /api/channel/tenants/{tenant_id}/status` | +| **后端状态** | ✅ 已实现 (channel.py) | +| **权限要求** | channel_admin | + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "禁用"按钮 + +**请求体**: +```json +{ + "status": "suspended" +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "tenantId": "tenant-uuid", + "status": "suspended" + }, + "message": "租户状态更新成功" +} +``` + +--- + +#### 6. 修改租户密码 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `PUT /api/channel/tenants/{tenant_id}/password` | +| **后端状态** | ✅ 已实现 (channel.py) | +| **权限要求** | channel_admin | + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "修改密码"按钮 + +**请求体**: +```json +{ + "newPassword": "NewSecurePass123" +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "tenantId": "tenant-uuid" + }, + "message": "密码修改成功" +} +``` + +--- + +#### 7. 管理租户权限 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `PUT /api/channel/tenants/{tenant_id}/permissions` | +| **后端状态** | ✅ 已实现 (channel.py) | +| **权限要求** | channel_admin | + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "管理权限"按钮 + +**请求体**: +```json +{ + "permissions": ["dashboard", "agents", "models", "billing", "resources", "data-tools", "api-gateway"] +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "tenantId": "tenant-uuid", + "permissions": ["dashboard", "agents", "models"] + }, + "message": "权限更新成功" +} +``` + +--- + +#### 8. 供应商申请审批 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `PUT /api/admin/providers/applications/{application_id}/review` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin, billing_admin | + +**按钮位置**: 渠道管理页面 → 渠道申请审批表格 → "审批"按钮 + +**请求体（批准）**: +```json +{ + "approved": true, + "reason": "申请已批准" +} +``` + +**请求体（拒绝）**: +```json +{ + "approved": false, + "reason": "申请被拒绝" +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "applicationId": "app-uuid", + "status": "approved" + }, + "message": "审批完成" +} +``` + +--- + +#### 9. 平台Agent申请审批 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `PUT /api/admin/applications/platform-agents/{application_id}/review` | +| **后端状态** | ✅ 已实现 (admin.py, platform_agent_quota.py) | +| **权限要求** | super_admin, billing_admin | + +**按钮位置**: 渠道管理页面 → 平台Agent申请审批表格 → "审批"按钮 + +**请求体（批准）**: +```json +{ + "action": "approve", + "podQuota": 5, + "reviewReason": "申请已批准" +} +``` + +**请求体（拒绝）**: +```json +{ + "action": "reject", + "reviewReason": "申请被拒绝" +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "applicationId": "app-uuid", + "status": "approved" + }, + "message": "审批完成" +} +``` + +--- + +#### 10. 保存资源配置 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `PUT /api/admin/channels/{channel_id}/resources` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin, billing_admin | + +**按钮位置**: 渠道管理页面 → 渠道卡片 → "资源管理"菜单项 → "保存配置"按钮 + +**请求体**: +```json +{ + "models": ["model-id-1", "model-id-2"], + "agents": [ + {"agentId": "agent-id-1", "quantity": 10}, + {"agentId": "agent-id-2", "quantity": 5} + ], + "customAgentResources": {"cpu": 2.0, "memory": 4.0}, + "channelCredit": 100000.00 +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "channelId": "channel-uuid" + }, + "message": "资源配置保存成功" +} +``` + +--- + +#### 11. 保存渠道编辑 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `PUT /api/admin/channels/{channel_id}` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin, billing_admin | + +**按钮位置**: 渠道管理页面 → 渠道卡片 → "编辑"菜单项 → "保存更改"按钮 + +**请求体**: +```json +{ + "name": "更新后的渠道名", + "email": "newemail@channel.com", + "contactName": "张三", + "phone": "+86-10-12345678" +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "id": "channel-uuid" + }, + "message": "渠道信息更新成功" +} +``` + +--- + +#### 12. 保存佣金修改 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `PUT /api/admin/channels/{channel_id}/commission` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin, billing_admin | + +**按钮位置**: 渠道管理页面 → 渠道卡片 → "修改佣金"菜单项 → "保存"按钮 + +**请求体**: +```json +{ + "commissionRate": 0.18 +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "channelId": "channel-uuid", + "commissionRate": 0.18 + }, + "message": "佣金比例更新成功" +} +``` + +--- + +#### 13. 创建渠道 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `POST /api/admin/channels/create` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin, billing_admin | + +**按钮位置**: 渠道管理页面 → "添加渠道"按钮 → "创建"按钮 + +**请求体**: +```json +{ + "name": "新渠道", + "email": "channel@example.com", + "password": "SecurePass123", + "commissionRate": 0.15 +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "id": "channel-uuid", + "name": "新渠道" + }, + "message": "渠道创建成功" +} +``` + +--- + +#### 14. 添加租户 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `POST /api/channel/tenants/create` | +| **后端状态** | ✅ 已实现 (channel.py) | +| **权限要求** | channel_admin | + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → "添加租户"按钮 + +**请求体**: +```json +{ + "name": "租户名称", + "email": "tenant@example.com", + "password": "SecurePass123", + "subscriptionTier": "free", + "channelId": "channel-uuid" +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "id": "tenant-uuid" + }, + "message": "租户创建成功" +} +``` + +--- + +#### 15. 删除渠道管理员 ⚠️ 部分对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `DELETE /api/admin/channels/{channel_id}/admins/{admin_id}` | +| **后端状态** | ⚠️ 需确认 | +| **权限要求** | super_admin | + +**按钮位置**: 渠道管理页面 → 编辑渠道对话框 → 管理员管理区域 → 删除图标按钮 + +**说明**: 后端 API 清单中有 `GET /api/admin/channels/{channel_id}/admins` 获取渠道管理员列表，但未明确列出删除接口。建议确认是否已实现。 + +--- + +## 资源管理模块 (Resources) + +### 数据展示接口 + +#### D7. Agent模板列表接口 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/platform-agents/templates` | +| **后端状态** | ✅ 已实现 (admin.py, platform_agent_quota.py) | +| **权限要求** | super_admin, billing_admin | + +**展示位置**: 资源管理页面 → 平台Agent模板管理区域 + +**响应字段**: +```json +{ + "success": true, + "data": { + "templates": [ + { + "id": "template-uuid", + "name": "echo_agent", + "displayName": "Echo 测试服务", + "description": "简单的 Echo 服务，用于测试和调试", + "cpuRequest": "100m", + "cpuLimit": "500m", + "memoryRequest": "128Mi", + "memoryLimit": "512Mi", + "maxPods": 10, + "isEnabled": true + } + ] + } +} +``` + +--- + +#### D8. 模型供应商列表接口 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/providers/models` | +| **后端状态** | ✅ 已实现 (providers.py) | +| **权限要求** | 已认证用户 | + +**展示位置**: 资源管理页面 → 货源供应商管理区域 + +**响应字段**: +```json +{ + "success": true, + "data": { + "providers": [ + { + "id": "provider-uuid", + "name": "OpenAI", + "provider": "openai", + "supportedModels": ["gpt-4", "gpt-3.5-turbo"], + "rpm": 1000, + "tpm": 100000, + "status": "active" + } + ] + } +} +``` + +--- + +### 按钮操作接口 + +#### 16. Agent模板配置-保存 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `PUT /api/admin/platform-agents/templates/{name}/config` | +| **后端状态** | ✅ 已实现 (platform_agent_quota.py) | +| **权限要求** | admin, super_admin | + +**按钮位置**: 资源管理页面 → Agent模板卡片 → "配置"按钮 → "保存配置"按钮 + +**请求体**: +```json +{ + "cpuRequest": "100m", + "cpuLimit": "500m", + "memoryRequest": "128Mi", + "memoryLimit": "512Mi", + "maxPods": 10, + "isEnabled": true, + "displayName": "Echo 测试服务", + "description": "简单的 Echo 服务，用于测试和调试" +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "templateName": "echo_agent" + }, + "message": "模板配置保存成功" +} +``` + +--- + +#### 17. Agent模板删除 ❌ 未对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `DELETE /api/admin/platform-agents/templates/{name}` | +| **后端状态** | ❌ 未实现 | +| **权限要求** | super_admin | + +**按钮位置**: 资源管理页面 → Agent模板卡片 → "删除"按钮 + +**说明**: 后端 API 清单中未列出此接口，需要开发实现。 + +--- + +#### 18. 添加模型供应商 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `POST /api/providers/models/create` | +| **后端状态** | ✅ 已实现 (providers.py) | +| **权限要求** | super_admin, billing_admin | + +**按钮位置**: 资源管理页面 → "添加模型供应商"按钮 + +**请求体**: +```json +{ + "name": "OpenAI", + "provider": "openai", + "apiKey": "sk-...", + "apiUrl": "https://api.openai.com/v1", + "supportedModels": ["gpt-4", "gpt-3.5-turbo"], + "rpm": 1000, + "tpm": 100000 +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "id": "provider-uuid" + }, + "message": "供应商创建成功" +} +``` + +--- + +#### 19. 模型供应商配置 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `PUT /api/providers/models/{provider_id}` | +| **后端状态** | ✅ 已实现 (providers.py) | +| **权限要求** | super_admin, billing_admin | + +**按钮位置**: 资源管理页面 → 模型供应商卡片 → "配置"按钮 + +**请求体**: +```json +{ + "name": "OpenAI", + "apiUrl": "https://api.openai.com/v1", + "apiKey": "sk-...", + "supportedModels": ["gpt-4", "gpt-3.5-turbo", "gpt-4-turbo"], + "rpm": 2000, + "tpm": 200000 +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "id": "provider-uuid" + }, + "message": "供应商配置更新成功" +} +``` + +--- + +#### 20. 模型供应商测试延迟 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `POST /api/providers/models/{provider_id}/test` | +| **后端状态** | ✅ 已实现 (providers.py) | +| **权限要求** | super_admin, billing_admin | + +**按钮位置**: 资源管理页面 → 模型供应商卡片 → "测试延迟"按钮 + +**响应字段**: +```json +{ + "success": true, + "data": { + "status": "connected", + "latency": 150, + "message": "连接测试成功" + } +} +``` + +--- + +#### 21. 模型供应商删除 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `DELETE /api/providers/models/{provider_id}` | +| **后端状态** | ✅ 已实现 (providers.py) | +| **权限要求** | super_admin | + +**按钮位置**: 资源管理页面 → 模型供应商卡片 → "删除"按钮 + +**响应字段**: +```json +{ + "success": true, + "message": "供应商删除成功" +} +``` + +--- + +## 监控模块 (Monitoring) + +### 数据展示接口 + +#### D9. Agent健康监控汇总接口 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/platform-agents/status` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin, billing_admin, operations_admin | + +**展示位置**: 监控页面 → Agent健康监控区域 → 汇总统计卡片 + +**响应字段**: +```json +{ + "success": true, + "data": { + "summary": { + "total": 10, + "byHealthStatus": { + "healthy": 8, + "warning": 1, + "critical": 1 + } + }, + "agents": [ + { + "id": "agent-uuid", + "name": "echo-agent-1", + "type": "platform", + "healthStatus": "healthy", + "cpuUsage": "50m", + "cpuLimit": "500m", + "cpuUtilization": 10.0, + "memoryUsage": "128Mi", + "memoryLimit": "512Mi", + "memoryUtilization": 25.0, + "status": "running", + "source": "k8s" + } + ] + } +} +``` + +--- + +#### D10. Agent监控接口 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/monitoring/agents` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin, billing_admin, operations_admin | + +**展示位置**: 监控页面 → Agent健康监控区域 + +**说明**: 此接口与 `/api/admin/platform-agents/status` 功能类似，用于监控Agent健康状态。 + +--- + +## 计费模块 (Billing) + +### 数据展示接口 + +#### D11. 计费概览统计接口 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/billing/overview` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin, billing_admin | + +**展示位置**: 计费管理页面 → 统计卡片区域 + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| startTime | string | 是 | 开始时间（ISO 8601格式） | +| endTime | string | 是 | 结束时间（ISO 8601格式） | + +**响应字段**: +```json +{ + "success": true, + "data": { + "summary": { + "totalChannels": 5, + "totalBilling": 10000.00, + "totalEU": 50000 + }, + "channelStats": [ + { + "channelId": "channel-uuid", + "channelName": "渠道A", + "calls": 1000, + "totalEU": 10000, + "totalCost": 2000.00 + } + ], + "tenantStats": [ + { + "tenantId": "tenant-uuid", + "tenantName": "租户A", + "channelName": "渠道A", + "calls": 500, + "totalEU": 5000, + "totalCost": 1000.00 + } + ] + } +} +``` + +--- + +#### D12. 调用记录明细接口 ❌ 未对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/billing/call-records` | +| **后端状态** | ❌ 未实现 | +| **权限要求** | super_admin, billing_admin | + +**展示位置**: 计费管理页面 → 调用记录 → 调用记录明细表格 + +**说明**: 后端 API 清单中未列出此接口，需要开发实现。 + +**建议查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| startTime | string | 是 | 开始时间 | +| endTime | string | 是 | 结束时间 | +| page | int | 否 | 页码，默认1 | +| pageSize | int | 否 | 每页数量，默认20 | + +--- + +### 按钮操作接口 + +#### 22. 时间查询/筛选 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/billing/overview` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin, billing_admin | + +**按钮位置**: 计费管理页面 → "时间查询"/"筛选"按钮 + +**说明**: 时间查询和筛选功能复用计费概览接口，通过查询参数实现筛选。 + +--- + +#### 23. 导出计费数据 ❌ 未对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/billing/export` | +| **后端状态** | ❌ 未实现 | +| **权限要求** | super_admin, billing_admin | + +**按钮位置**: 计费管理页面 → "导出"按钮 + +**说明**: 后端 API 清单中未列出此接口，需要开发实现。 + +**建议查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| startTime | string | 是 | 开始时间 | +| endTime | string | 是 | 结束时间 | +| format | string | 是 | 导出格式（excel/csv/pdf） | + +--- + +## 设置模块 (Settings) + +### 数据展示接口 + +#### D13. 管理员列表接口 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/admins` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin | + +**展示位置**: 设置页面 → 当前管理员列表 + +**响应字段**: +```json +{ + "success": true, + "data": { + "admins": [ + { + "id": "admin-uuid", + "name": "管理员姓名", + "email": "admin@example.com", + "role": "super_admin", + "status": "active" + } + ] + } +} +``` + +--- + +#### D14. 角色列表接口 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `GET /api/admin/roles` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin | + +**展示位置**: 设置页面 → 角色权限配置区域 + +**响应字段**: +```json +{ + "success": true, + "data": { + "roles": [ + { + "id": "super_admin", + "name": "超级管理员", + "permissions": ["overview", "channels", "resources", "monitoring", "billing", "settings"] + }, + { + "id": "billing_admin", + "name": "计费管理员", + "permissions": ["overview", "channels", "billing"] + }, + { + "id": "operations_admin", + "name": "运维管理员", + "permissions": ["overview", "monitoring"] + } + ] + } +} +``` + +--- + +### 按钮操作接口 + +#### 24. 添加管理员 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `POST /api/admin/admins/create` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin | + +**按钮位置**: 设置页面 → 当前管理员列表 → "添加管理员"按钮 + +**请求体**: +```json +{ + "name": "管理员姓名", + "email": "admin@example.com", + "password": "SecurePass123", + "role": "billing_admin" +} +``` + +**响应字段**: +```json +{ + "success": true, + "data": { + "id": "admin-uuid" + }, + "message": "管理员创建成功" +} +``` + +--- + +#### 25. 删除管理员 ✅ 已对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `DELETE /api/admin/admins/{admin_id}` | +| **后端状态** | ✅ 已实现 (admin.py) | +| **权限要求** | super_admin | + +**按钮位置**: 设置页面 → 当前管理员列表 → 管理员行 → 删除图标按钮 + +**响应字段**: +```json +{ + "success": true, + "message": "管理员删除成功" +} +``` + +--- + +#### 26. 保存角色权限配置 ❌ 未对接 + +| 属性 | 值 | +|------|-----| +| **接口路径** | `PUT /api/admin/roles/{role_id}/permissions` | +| **后端状态** | ❌ 未实现 | +| **权限要求** | super_admin | + +**按钮位置**: 设置页面 → 角色权限配置区域 → "保存权限配置"按钮 + +**说明**: 后端 API 清单中未列出此接口，需要开发实现。 + +**建议请求体**: +```json +{ + "permissions": ["overview", "channels", "resources", "monitoring", "billing", "settings"] +} +``` + +--- + +## 接口汇总表 + +### 已对接接口汇总 + +| 序号 | 接口路径 | 方法 | 功能 | 模块 | +|------|----------|------|------|------| +| 1 | /api/admin/dashboard/stats | GET | 仪表板统计 | 概览 | +| 2 | /api/v1/monitoring/metrics | GET | 系统监控指标 | 概览 | +| 3 | /api/admin/dashboard/recent-logins | GET | 最近登录租户 | 概览 | +| 4 | /api/admin/platform-agents/status | GET | 平台资源分配统计 | 概览 | +| 5 | /api/admin/channels | GET | 渠道列表 | 渠道管理 | +| 6 | /api/admin/channels/create | POST | 创建渠道 | 渠道管理 | +| 7 | /api/admin/channels/{channel_id} | PUT | 更新渠道信息 | 渠道管理 | +| 8 | /api/admin/channels/{channel_id} | DELETE | 删除渠道 | 渠道管理 | +| 9 | /api/admin/channels/{channel_id}/resources | GET | 获取渠道资源 | 渠道管理 | +| 10 | /api/admin/channels/{channel_id}/resources | PUT | 分配渠道资源 | 渠道管理 | +| 11 | /api/admin/channels/{channel_id}/commission | PUT | 更新佣金比例 | 渠道管理 | +| 12 | /api/admin/channels/{channel_id}/admins | GET | 获取渠道管理员 | 渠道管理 | +| 13 | /api/channel/tenants/create | POST | 创建租户 | 渠道管理 | +| 14 | /api/channel/tenants/{tenant_id} | DELETE | 删除租户 | 渠道管理 | +| 15 | /api/channel/tenants/{tenant_id}/status | PUT | 更新租户状态 | 渠道管理 | +| 16 | /api/channel/tenants/{tenant_id}/password | PUT | 重置租户密码 | 渠道管理 | +| 17 | /api/channel/tenants/{tenant_id}/permissions | PUT | 更新租户权限 | 渠道管理 | +| 18 | /api/admin/providers/applications | GET | 获取供应商申请 | 渠道管理 | +| 19 | /api/admin/providers/applications/{id}/review | PUT | 审批供应商申请 | 渠道管理 | +| 20 | /api/admin/applications/platform-agents | GET | 获取Agent申请 | 渠道管理 | +| 21 | /api/admin/applications/platform-agents/{id}/review | PUT | 审批Agent申请 | 渠道管理 | +| 22 | /api/admin/platform-agents/templates | GET | Agent模板列表 | 资源管理 | +| 23 | /api/admin/platform-agents/templates/{name}/config | PUT | 配置Agent模板 | 资源管理 | +| 24 | /api/providers/models | GET | 模型供应商列表 | 资源管理 | +| 25 | /api/providers/models/create | POST | 创建模型供应商 | 资源管理 | +| 26 | /api/providers/models/{provider_id} | PUT | 更新供应商配置 | 资源管理 | +| 27 | /api/providers/models/{provider_id} | DELETE | 删除供应商 | 资源管理 | +| 28 | /api/providers/models/{provider_id}/test | POST | 测试供应商连接 | 资源管理 | +| 29 | /api/admin/monitoring/agents | GET | 监控Agent健康 | 监控 | +| 30 | /api/admin/billing/overview | GET | 计费概览统计 | 计费 | +| 31 | /api/admin/admins | GET | 管理员列表 | 设置 | +| 32 | /api/admin/admins/create | POST | 创建管理员 | 设置 | +| 33 | /api/admin/admins/{admin_id} | DELETE | 删除管理员 | 设置 | +| 34 | /api/admin/roles | GET | 角色列表 | 设置 | + +--- + +## 未对接接口清单 + +以下接口在前端需求中存在，但后端尚未实现，需要开发： + +| 序号 | 接口路径 | 方法 | 功能 | 优先级 | +|------|----------|------|------|--------| +| 1 | /api/admin/channels/stats | GET | 渠道统计概览 | 中 | +| 2 | /api/admin/channels/search | GET | 搜索渠道 | 中 | +| 3 | /api/admin/platform-agents/templates/{name} | DELETE | 删除Agent模板 | 低 | +| 4 | /api/admin/billing/call-records | GET | 调用记录明细 | 高 | +| 5 | /api/admin/billing/export | GET | 导出计费数据 | 中 | +| 6 | /api/admin/roles/{role_id}/permissions | PUT | 保存角色权限 | 低 | +| 7 | /api/admin/channels/{channel_id}/admins/{admin_id} | DELETE | 删除渠道管理员 | 低 | + +### 建议优先级说明 + +- **高**: 核心业务功能，影响用户体验 +- **中**: 辅助功能，可通过其他方式临时替代 +- **低**: 增强功能，可延后实现 + +--- + +## 附录：权限矩阵 + +| 接口类别 | super_admin | billing_admin | operations_admin | +|----------|-------------|---------------|------------------| +| 仪表板统计 | ✅ | ✅ | ✅ | +| 系统监控 | ✅ | ✅ | ✅ | +| 渠道管理（读） | ✅ | ✅ | ✅ | +| 渠道管理（写） | ✅ | ✅ | ❌ | +| 渠道删除 | ✅ | ❌ | ❌ | +| 资源管理（读） | ✅ | ✅ | ✅ | +| 资源管理（写） | ✅ | ✅ | ❌ | +| 计费管理 | ✅ | ✅ | ❌ | +| 管理员管理 | ✅ | ❌ | ❌ | +| 角色权限配置 | ✅ | ❌ | ❌ | + +--- + +## 接口测试报告 + +### 测试环境 +- **测试时间**: 2026-01-06 13:37 UTC +- **服务地址**: http://localhost:8002 +- **部署方式**: docker compose build mcp-server +- **测试账号**: + - 超级管理员: superadmin@taiji-ai.com / Admin@123456 + - 渠道管理员: 66@66.com / 66 + +### 测试结果汇总 + +| 模块 | 接口数 | 通过 | 失败 | 通过率 | +|------|--------|------|------|--------| +| 概览模块 | 4 | 4 | 0 | 100% | +| 渠道管理模块 | 15 | 15 | 0 | 100% | +| 资源管理模块 | 8 | 8 | 0 | 100% | +| 监控模块 | 2 | 2 | 0 | 100% | +| 计费模块 | 2 | 2 | 0 | 100% | +| 设置模块 | 4 | 4 | 0 | 100% | +| **合计** | **35** | **35** | **0** | **100%** | + +### 已修复问题 + +1. **计费概览接口时区问题** (D11) + - **问题**: `GET /api/admin/billing/overview` 返回 Internal Server Error + - **原因**: 时间参数解析后带时区信息，但数据库字段是 naive datetime，导致 `can't subtract offset-naive and offset-aware datetimes` 错误 + - **修复**: 在 [`admin.py`](services/mcp-server/app/routes/admin.py:2015) 中移除时区信息 + - **状态**: ✅ 已修复 + +### 字段差异说明 + +以下接口的实际返回字段与文档定义有差异（均为向后兼容的扩展）： + +1. **D1. 仪表板统计接口**: 新增 `totalCalls`, `totalAllocatedCpu`, `totalAllocatedMemory`, `platformAgents`, `customAgents` 字段 +2. **D2. 系统监控指标接口**: 响应格式不同，不包含外层 `success` 字段，增加了 `services` 和 `billing` 统计 +3. **D4. 平台资源分配统计接口**: `summary` 字段结构变化，新增 `running`, `pending`, `error` 状态统计 +4. **D5. 渠道列表接口**: 新增 `channelCredit`, `customAgentCpu`, `customAgentMemory`, `totalAllocatedCpu`, `totalAllocatedMemory` 字段 +5. **D7. Agent模板列表接口**: 新增 `category`, `version`, `port`, `envInfo`, `status` 字段 + +### 登录接口说明 + +登录接口 `POST /api/auth/login` 需要 `role` 参数： +- 超级管理员登录: `role: "admin"` +- 渠道管理员登录: `role: "channel"` +- 普通用户登录: `role: "user"` + +--- + +## 更新日志 + +### v1.0.1 (2026-01-06) + +- 完成所有已对接接口的实际测试 +- 修复计费概览接口时区问题 +- 更新响应字段文档，记录实际返回值 +- 添加接口测试报告章节 + +### v1.0.0 (2026-01-06) + +- 初始版本 +- 完成前端需求与后端API的对接核实 +- 识别7个未对接接口 +- 整理34个已对接接口 +- 添加权限矩阵说明 \ No newline at end of file diff --git a/Docs/项目文档/超级管理员控制台-未对接后端接口清单.md b/Docs/项目文档/超级管理员控制台-未对接后端接口清单.md deleted file mode 100644 index 75fd9c4..0000000 --- a/Docs/项目文档/超级管理员控制台-未对接后端接口清单.md +++ /dev/null @@ -1,800 +0,0 @@ -# 超级管理员控制台 - 未对接后端接口清单 - -> **版本**: v1.1.0 -> **更新时间**: 2026-01-06 -> **说明**: 本文档基于前端业务逻辑分析，列出所有需要但尚未对接的后端接口，包括按钮操作接口和数据展示接口 - ---- - -## 目录 - -1. [概览模块 (Overview)](#概览模块-overview) -2. [渠道管理模块 (Channels)](#渠道管理模块-channels) -3. [资源管理模块 (Resources)](#资源管理模块-resources) -4. [监控模块 (Monitoring)](#监控模块-monitoring) -5. [计费模块 (Billing)](#计费模块-billing) -6. [设置模块 (Settings)](#设置模块-settings) -7. [附录：接口汇总表](#附录接口汇总表) - ---- - -## 概览模块 (Overview) - -### 数据展示接口 - -#### D1. 平台资源分配统计接口 - -**展示位置**: 概览页面 → 平台资源分配统计卡片 - -**展示内容**: 显示平台已分配的CPU核心数、内存大小、Agent数量等汇总信息 - -**功能描述**: 获取平台所有Agent的资源分配汇总统计，用于展示资源使用概况 - -**接口需求**: -``` -GET /api/admin/platform/resource-allocation -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.totalCpuAllocated | float | 已分配CPU总核数 | -| data.totalMemoryAllocated | float | 已分配内存总量（GB） | -| data.totalAgentCount | int | Agent总数 | -| data.avgCpuPerAgent | float | 平均每Agent CPU | -| data.avgMemoryPerAgent | float | 平均每Agent内存 | -| data.byChannel | array | 按渠道分组的资源统计 | - ---- - -### 按钮操作接口 - -#### 1. 搜索租户按钮 - -**按钮位置**: 概览页面 → 最近登录的租户列表 → 搜索框 - -**按钮作用**: 在最近登录的租户列表中搜索特定租户 - -**功能描述**: 用户输入关键词后，根据租户名称、邮箱等字段进行模糊搜索，筛选显示匹配的租户 - -**接口需求**: -``` -GET /api/admin/dashboard/recent-logins/search -``` - -**请求参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| keyword | string | 是 | 搜索关键词（租户名称/邮箱） | -| limit | int | 否 | 返回数量，默认10 | - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.recentTenants | array | 匹配的租户列表 | - ---- - -## 渠道管理模块 (Channels) - -### 数据展示接口 - -#### D2. 渠道统计概览接口 - -**展示位置**: 渠道管理页面 → 渠道列表卡片 - -**展示内容**: 每个渠道卡片显示租户数、月收入、佣金比例等统计信息 - -**功能描述**: 获取渠道列表及其统计数据，用于渠道卡片展示 - -**接口需求**: -``` -GET /api/admin/channels/stats -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.channels | array | 渠道列表（含统计数据） | - ---- - -### 按钮操作接口 - -#### 2. 搜索渠道按钮 - -**按钮位置**: 渠道管理页面 → 搜索框 - -**按钮作用**: 在渠道列表中搜索特定渠道 - -**功能描述**: 用户输入关键词后，根据渠道名称、联系人、邮箱等字段进行模糊搜索 - -**接口需求**: -``` -GET /api/admin/channels/search -``` - -**请求参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| keyword | string | 是 | 搜索关键词 | -| status | string | 否 | 状态筛选（active/inactive） | - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.channels | array | 匹配的渠道列表 | - ---- - -#### 3. 查看渠道详情按钮 - -**按钮位置**: 渠道管理页面 → 渠道卡片 → 更多操作菜单 → "查看详情" - -**按钮作用**: 查看渠道的完整详细信息 - -**功能描述**: 点击后弹出对话框，显示渠道的基本信息、资源配置、配额信息等详细数据 - -**接口需求**: -``` -GET /api/admin/channels/{channel_id} -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 是 | 渠道ID | - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.id | string | 渠道ID | -| data.name | string | 渠道名称 | -| data.email | string | 联系邮箱 | -| data.status | string | 状态 | -| data.createdAt | string | 创建时间 | -| data.cpuCores | float | 分配的CPU核心数 | -| data.memory | string | 分配的内存大小 | -| data.tenantCount | int | 租户总数 | -| data.creditLimit | float | 授信额度 | -| data.usedCredit | float | 已用授信 | -| data.remainingCredit | float | 剩余授信 | -| data.commissionRate | float | 佣金比例 | - ---- - -#### 4. 删除渠道按钮 - -**按钮位置**: 渠道管理页面 → 渠道卡片 → 更多操作菜单 → "删除渠道" - -**按钮作用**: 删除指定渠道（软删除） - -**功能描述**: 点击后弹出确认对话框，确认后将渠道状态设为inactive，要求渠道下无活跃租户 - -**接口需求**: -``` -DELETE /api/admin/channels/{channel_id} -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 是 | 渠道ID | - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| message | string | 操作结果消息 | - ---- - -#### 5. 删除租户按钮 - -**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "删除"按钮 - -**按钮作用**: 删除指定租户（软删除） - -**功能描述**: 点击后弹出确认对话框，确认后将租户状态设为inactive - -**接口需求**: -``` -DELETE /api/channel/tenants/{tenant_id} -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| tenant_id | string | 是 | 租户ID | - -**查询参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 超级管理员必填 | 渠道ID | - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| message | string | 操作结果消息 | - ---- - -#### 6. 禁用租户按钮 - -**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "禁用"按钮 - -**按钮作用**: 暂停租户账号 - -**功能描述**: 将租户状态设为suspended，租户将无法登录和使用服务 - -**接口需求**: -``` -PUT /api/channel/tenants/{tenant_id}/status -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| tenant_id | string | 是 | 租户ID | - -**请求体**: -```json -{ - "status": "suspended" -} -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.tenantId | string | 租户ID | -| data.status | string | 新状态 | -| message | string | 操作结果消息 | - ---- - -#### 7. 修改租户密码按钮 - -**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "修改密码"按钮 - -**按钮作用**: 重置租户登录密码 - -**功能描述**: 点击后弹出对话框，输入新密码和确认密码，提交后更新租户密码 - -**接口需求**: -``` -PUT /api/channel/tenants/{tenant_id}/password -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| tenant_id | string | 是 | 租户ID | - -**请求体**: -```json -{ - "newPassword": "NewSecurePass123" -} -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.tenantId | string | 租户ID | -| message | string | 操作结果消息 | - ---- - -#### 8. 管理租户权限按钮 - -**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "管理权限"按钮 - -**按钮作用**: 配置租户的功能访问权限 - -**功能描述**: 点击后弹出对话框，显示权限复选框列表，勾选后保存租户的权限配置 - -**接口需求**: -``` -PUT /api/channel/tenants/{tenant_id}/permissions -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| tenant_id | string | 是 | 租户ID | - -**请求体**: -```json -{ - "permissions": ["dashboard", "agents", "models", "billing", "resources", "data-tools", "api-gateway"] -} -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.tenantId | string | 租户ID | -| data.permissions | array | 更新后的权限列表 | -| message | string | 操作结果消息 | - ---- - -#### 9. 供应商申请审批-拒绝按钮 - -**按钮位置**: 渠道管理页面 → 渠道申请审批表格 → "审批"按钮 → 审批对话框 → "拒绝"按钮 - -**按钮作用**: 拒绝渠道的供应商申请 - -**功能描述**: 点击后将申请状态设为rejected，渠道将无法使用该供应商 - -**接口需求**: -``` -PUT /api/admin/providers/applications/{application_id}/review -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| application_id | string | 是 | 申请ID | - -**请求体**: -```json -{ - "approved": false, - "reason": "申请被拒绝" -} -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.applicationId | string | 申请ID | -| data.status | string | 新状态（rejected） | -| message | string | 操作结果消息 | - ---- - -#### 10. 供应商申请审批-批准按钮 - -**按钮位置**: 渠道管理页面 → 渠道申请审批表格 → "审批"按钮 → 审批对话框 → "批准"按钮 - -**按钮作用**: 批准渠道的供应商申请 - -**功能描述**: 点击后将申请状态设为approved，自动创建ChannelProviderAccess记录 - -**接口需求**: -``` -PUT /api/admin/providers/applications/{application_id}/review -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| application_id | string | 是 | 申请ID | - -**请求体**: -```json -{ - "approved": true, - "reason": "申请已批准" -} -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.applicationId | string | 申请ID | -| data.status | string | 新状态（approved） | -| message | string | 操作结果消息 | - ---- - -#### 11. 平台Agent申请审批-拒绝按钮 - -**按钮位置**: 渠道管理页面 → 平台Agent申请审批表格 → "审批"按钮 → 审批对话框 → "拒绝"按钮 - -**按钮作用**: 拒绝渠道的平台Agent申请 - -**功能描述**: 点击后将申请状态设为rejected，渠道将无法使用该平台Agent - -**接口需求**: -``` -PUT /api/admin/applications/platform-agents/{application_id}/review -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| application_id | string | 是 | 申请ID | - -**请求体**: -```json -{ - "action": "reject", - "reviewReason": "申请被拒绝" -} -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.applicationId | string | 申请ID | -| data.status | string | 新状态（rejected） | -| message | string | 操作结果消息 | - ---- - -#### 12. 平台Agent申请审批-批准按钮 - -**按钮位置**: 渠道管理页面 → 平台Agent申请审批表格 → "审批"按钮 → 审批对话框 → "批准"按钮 - -**按钮作用**: 批准渠道的平台Agent申请 - -**功能描述**: 点击后将申请状态设为approved，为渠道分配指定数量的Pod配额 - -**接口需求**: -``` -PUT /api/admin/applications/platform-agents/{application_id}/review -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| application_id | string | 是 | 申请ID | - -**请求体**: -```json -{ - "action": "approve", - "podQuota": 5, - "reviewReason": "申请已批准" -} -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.applicationId | string | 申请ID | -| data.status | string | 新状态（approved） | -| message | string | 操作结果消息 | - ---- - -#### 27. 保存资源配置按钮 - -**按钮位置**: 渠道管理页面 → 渠道卡片 → "资源管理"菜单项 → 资源管理对话框 → "保存配置"按钮 - -**按钮作用**: 保存渠道的资源配置（模型、Agent、自定义Agent资源、授信额度） - -**功能描述**: 为渠道配置可用的模型供应商、Agent分配及数量、自定义Agent的CPU/内存资源、授信额度 - -**接口需求**: -``` -PUT /api/admin/channels/{channel_id}/resources -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 是 | 渠道ID | - -**请求体**: -```json -{ - "models": ["model-id-1", "model-id-2"], - "agents": [ - {"agentId": "agent-id-1", "quantity": 10}, - {"agentId": "agent-id-2", "quantity": 5} - ], - "customAgentResources": {"cpu": 2.0, "memory": 4.0}, - "channelCredit": 100000.00 -} -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.channelId | string | 渠道ID | -| message | string | 操作结果消息 | - ---- - -#### 28. 保存渠道编辑按钮 - -**按钮位置**: 渠道管理页面 → 渠道卡片 → "编辑"菜单项 → 编辑对话框 → "保存更改"按钮 - -**按钮作用**: 保存渠道基本信息的修改 - -**功能描述**: 修改渠道名称、联系人、邮箱、电话等基本信息 - -**接口需求**: -``` -PUT /api/admin/channels/{channel_id} -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 是 | 渠道ID | - -**请求体**: -```json -{ - "name": "更新后的渠道名", - "email": "newemail@channel.com", - "contactName": "张三", - "phone": "+86-10-12345678" -} -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.id | string | 渠道ID | -| message | string | 操作结果消息 | - ---- - -#### 29. 保存佣金修改按钮 - -**按钮位置**: 渠道管理页面 → 渠道卡片 → "修改佣金"菜单项 → 佣金对话框 → "保存"按钮 - -**按钮作用**: 更新渠道的佣金比例 - -**功能描述**: 修改渠道的佣金分成比例 - -**接口需求**: -``` -PUT /api/admin/channels/{channel_id}/commission -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 是 | 渠道ID | - -**请求体**: -```json -{ - "commissionRate": 0.18 -} -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.channelId | string | 渠道ID | -| data.commissionRate | float | 新的佣金比例 | -| message | string | 操作结果消息 | - ---- - -#### 30. 创建渠道按钮 - -**按钮位置**: 渠道管理页面 → "添加渠道"按钮 → 创建对话框 → "创建"按钮 - -**按钮作用**: 创建新的分销渠道 - -**功能描述**: 填写渠道名称、邮箱、密码、佣金比例，创建新渠道账户 - -**接口需求**: -``` -POST /api/admin/channels/create -``` - -**请求体**: -```json -{ - "name": "新渠道", - "email": "channel@example.com", - "password": "SecurePass123", - "commissionRate": 0.15 -} -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.id | string | 渠道ID | -| data.name | string | 渠道名称 | -| message | string | 操作结果消息 | - ---- - -#### 31. 添加租户按钮 - -**按钮位置**: 渠道管理页面 → 查看租户对话框 → "添加租户"按钮 → 添加租户对话框 → "创建租户"按钮 - -**按钮作用**: 为渠道创建新租户或管理员 - -**功能描述**: 填写租户名称、邮箱、密码、系统权限，创建新租户或渠道管理员 - -**接口需求（创建租户）**: -``` -POST /api/channel/tenants/create -``` - -**请求体**: -```json -{ - "name": "租户名称", - "email": "tenant@example.com", - "password": "SecurePass123", - "subscriptionTier": "free", - "channelId": "channel-uuid" -} -``` - -**接口需求（创建渠道管理员）**: -``` -POST /api/admin/admins/create -``` - -**请求体**: -```json -{ - "name": "管理员名称", - "email": "admin@example.com", - "password": "SecurePass123", - "role": "billing_admin", - "channelId": "channel-uuid" -} -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.id | string | 用户ID | -| message | string | 操作结果消息 | - ---- - -#### 32. 删除渠道管理员按钮 - -**按钮位置**: 渠道管理页面 → 编辑渠道对话框 → 管理员管理区域 → 管理员行 → 删除图标按钮 - -**按钮作用**: 从渠道移除管理员 - -**功能描述**: 点击后将管理员从该渠道移除 - -**接口需求**: -``` -DELETE /api/admin/channels/{channel_id}/admins/{admin_id} -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| channel_id | string | 是 | 渠道ID | -| admin_id | string | 是 | 管理员ID | - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| message | string | 操作结果消息 | - ---- - -## 资源管理模块 (Resources) - -### 数据展示接口 - -#### D3. Agent模板列表接口 - -**展示位置**: 资源管理页面 → 平台Agent模板管理区域 - -**展示内容**: 显示所有可用的Agent模板卡片，包含名称、描述、CPU/内存配置等 - -**功能描述**: 获取平台所有Agent模板的列表和配置信息 - -**接口需求**: -``` -GET /api/admin/platform-agents/templates -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.templates | array | 模板列表 | -| data.templates[].id | string | 模板ID | -| data.templates[].name | string | 模板名称 | -| data.templates[].displayName | string | 显示名称 | -| data.templates[].description | string | 模板描述 | -| data.templates[].cpuRequest | string | CPU请求量 | -| data.templates[].cpuLimit | string | CPU上限 | -| data.templates[].memoryRequest | string | 内存请求量 | -| data.templates[].memoryLimit | string | 内存上限 | -| data.templates[].maxPods | int | 最大Pod数量 | -| data.templates[].isEnabled | bool | 是否启用 | - ---- - -#### D4. 模型供应商列表接口 - -**展示位置**: 资源管理页面 → 货源供应商管理区域 - -**展示内容**: 显示所有模型供应商卡片，包含名称、状态、支持模型数、RPM/TPM等 - -**功能描述**: 获取平台所有模型供应商的列表和配置信息 - -**接口需求**: -``` -GET /api/providers/models -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.providers | array | 供应商列表 | -| data.providers[].id | string | 供应商ID | -| data.providers[].name | string | 供应商名称 | -| data.providers[].provider | string | 供应商类型 | -| data.providers[].supportedModels | array | 支持的模型列表 | -| data.providers[].rpm | int | 每分钟请求数限制 | -| data.providers[].tpm | int | 每分钟令牌数限制 | -| data.providers[].status | string | 状态 | - ---- - -### 按钮操作接口 - -#### 13. Agent模板配置-保存按钮 - -**按钮位置**: 资源管理页面 → Agent模板卡片 → "配置"按钮 → 配置对话框 → "保存配置"按钮 - -**按钮作用**: 保存Agent模板的K8s资源配置 - -**功能描述**: 配置Agent模板的CPU请求/限制、内存请求/限制、最大实例数等参数 - -**接口需求**: -``` -PUT /api/admin/platform-agents/templates/{name}/config -``` - -**路径参数**: -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| name | string | 是 | 模板名称（如 echo_agent） | - -**请求体**: -```json -{ - "cpuRequest": "100m", - "cpuLimit": "500m", - "memoryRequest": "128Mi", - "memoryLimit": "512Mi", - "maxPods": 10, - "isEnabled": true, - "displayName": "Echo 测试服务", - "description": "简单的 Echo 服务，用于测试和调试" -} -``` - -**响应字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| success | bool | 是否成功 | -| data.templateName | string | 模板名称 | -| message | string | 操作结果 \ No newline at end of file diff --git a/plans/超级管理员控制台-后端接口需求清单(已人工审核).md b/plans/超级管理员控制台-后端接口需求清单(已人工审核).md new file mode 100644 index 0000000..eff39b7 --- /dev/null +++ b/plans/超级管理员控制台-后端接口需求清单(已人工审核).md @@ -0,0 +1,1503 @@ +# 超级管理员控制台 - 后端接口清单 + +> **版本**: v1.2.0 +> **更新时间**: 2026-01-06 +> **说明**: 本文档基于前端业务逻辑分析，列出所有后端接口需求，包括已对接接口和未对接接口，按钮操作接口和数据展示接口 + +--- + +## 目录 + +1. [概览模块 (Overview)](#概览模块-overview) +2. [渠道管理模块 (Channels)](#渠道管理模块-channels) +3. [资源管理模块 (Resources)](#资源管理模块-resources) +4. [监控模块 (Monitoring)](#监控模块-monitoring) +5. [计费模块 (Billing)](#计费模块-billing) +6. [设置模块 (Settings)](#设置模块-settings) +7. [附录：接口汇总表](#附录接口汇总表) + +--- + +## 概览模块 (Overview) + +### 数据展示接口 + +#### D1. 仪表板统计接口 ✅ 已对接 + +**展示位置**: 概览页面 → 顶部统计卡片区域 + +**展示内容**: +- 总渠道数（如：5） +- 总租户数（如：7） +- 总收入（如：$0） + +**功能描述**: 获取平台整体统计数据，用于概览页面顶部的统计卡片展示 + +**接口**: +``` +GET /api/admin/dashboard/stats +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.totalChannels | int | 总渠道数 | +| data.totalTenants | int | 总租户数 | +| data.totalRevenue | float | 总收入 | +| data.totalAgents | int | 总Agent数（用于活跃指标） | + +**前端调用**: `TaijiAPIClient.getAdminDashboardStats()` + +--- + +#### D2. 系统监控指标接口 ✅ 已对接 + +**展示位置**: 概览页面 → 系统指标卡片 + +**展示内容**: +- CPU使用率（如：5.9%） +- 内存使用率（如：33.6%） +- 存储使用率（如：64.8%） +- 活跃Agent（如：0%） + +**功能描述**: 获取平台整体的系统监控指标 + +**接口**: +``` +GET /api/v1/monitoring/metrics +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.cpu_usage | float | CPU使用率百分比 | +| data.memory_usage | float | 内存使用率百分比 | +| data.disk_usage | float | 存储使用率百分比 | +| data.system.cpu_usage_percent | float | 备选：CPU使用率 | +| data.system.memory_usage_percent | float | 备选：内存使用率 | +| data.system.disk_usage_percent | float | 备选：存储使用率 | + +**前端调用**: `TaijiAPIClient.getMonitoringMetrics()` + +--- + +#### D3. 最近登录租户列表接口 ✅ 已对接 + +**展示位置**: 概览页面 → 最近登录的租户列表 + +**展示内容**: 显示最近登录的租户列表，包含租户名称、邮箱、渠道、状态等 + +**功能描述**: 获取最近登录的租户列表，用于概览页面展示 + +**接口**: +``` +GET /api/admin/dashboard/recent-logins?limit=10 +``` + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| limit | int | 否 | 返回数量，默认10，最多50 | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.recentTenants | array | 最近登录的租户列表 | +| data.recentTenants[].id | string | 租户ID | +| data.recentTenants[].name | string | 租户名称 | +| data.recentTenants[].email | string | 邮箱 | +| data.recentTenants[].channelName | string | 所属渠道 | +| data.recentTenants[].lastLoginAt | string | 最后登录时间 | +| data.recentTenants[].status | string | 状态 | + +**前端调用**: `TaijiAPIClient.getRecentLogins(10)` + +--- + +#### D4. 平台资源分配统计接口 ✅ 已对接（复用） + +**展示位置**: 概览页面 → 平台资源分配统计卡片 + +**展示内容**: +- 已分配CPU（如：0.0 核） +- 已分配内存（如：0.0 GB） +- 共 X 个 Agent +- 平均 X GB/Agent + +**功能描述**: 获取平台所有Agent的资源分配汇总统计 + +**复用接口**: +``` +GET /api/admin/platform-agents/status +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.summary.total | int | Agent总数 | +| data.summary.totalCpuAllocated | float | 已分配CPU总核数 | +| data.summary.totalMemoryAllocated | float | 已分配内存总量（GB） | +| data.summary.avgMemoryPerAgent | float | 平均每Agent内存 | + +**前端调用**: `TaijiAPIClient.getPlatformAgentStatus()` + +--- + +### 按钮操作接口 + +## 渠道管理模块 (Channels) + +### 数据展示接口 + +#### D2. 渠道统计概览接口 + +**展示位置**: 渠道管理页面 → 渠道列表卡片 + +**展示内容**: 每个渠道卡片显示租户数、月收入、佣金比例等统计信息 + +**功能描述**: 获取渠道列表及其统计数据，用于渠道卡片展示 + +**接口需求**: +``` +GET /api/admin/channels/stats +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.channels | array | 渠道列表（含统计数据） | + +--- + +### 按钮操作接口 + +#### 2. 搜索渠道按钮 + +**按钮位置**: 渠道管理页面 → 搜索框 + +**按钮作用**: 在渠道列表中搜索特定渠道 + +**功能描述**: 用户输入关键词后，根据渠道名称、联系人、邮箱等字段进行模糊搜索 + +**接口需求**: +``` +GET /api/admin/channels/search +``` + +**请求参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| keyword | string | 是 | 搜索关键词 | +| status | string | 否 | 状态筛选（active/inactive） | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.channels | array | 匹配的渠道列表 | + +--- + +#### 3. 查看渠道详情按钮 + +**按钮位置**: 渠道管理页面 → 渠道卡片 → 更多操作菜单 → "查看详情" + +**按钮作用**: 查看渠道的完整详细信息 + +**功能描述**: 点击后弹出对话框，显示渠道的基本信息、资源配置、配额信息等详细数据 + +**接口需求**: +``` +GET /api/admin/channels/{channel_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 是 | 渠道ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 渠道ID | +| data.name | string | 渠道名称 | +| data.email | string | 联系邮箱 | +| data.status | string | 状态 | +| data.createdAt | string | 创建时间 | +| data.cpuCores | float | 分配的CPU核心数 | +| data.memory | string | 分配的内存大小 | +| data.tenantCount | int | 租户总数 | +| data.creditLimit | float | 授信额度 | +| data.usedCredit | float | 已用授信 | +| data.remainingCredit | float | 剩余授信 | +| data.commissionRate | float | 佣金比例 | + +--- + +#### 4. 删除渠道按钮 + +**按钮位置**: 渠道管理页面 → 渠道卡片 → 更多操作菜单 → "删除渠道" + +**按钮作用**: 删除指定渠道（软删除） + +**功能描述**: 点击后弹出确认对话框，确认后将渠道状态设为inactive，要求渠道下无活跃租户 + +**接口需求**: +``` +DELETE /api/admin/channels/{channel_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 是 | 渠道ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| message | string | 操作结果消息 | + +--- + +#### 5. 删除租户按钮 + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "删除"按钮 + +**按钮作用**: 删除指定租户（软删除） + +**功能描述**: 点击后弹出确认对话框，确认后将租户状态设为inactive + +**接口需求**: +``` +DELETE /api/channel/tenants/{tenant_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| tenant_id | string | 是 | 租户ID | + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 超级管理员必填 | 渠道ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| message | string | 操作结果消息 | + +--- + +#### 6. 禁用租户按钮 + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "禁用"按钮 + +**按钮作用**: 暂停租户账号 + +**功能描述**: 将租户状态设为suspended，租户将无法登录和使用服务 + +**接口需求**: +``` +PUT /api/channel/tenants/{tenant_id}/status +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| tenant_id | string | 是 | 租户ID | + +**请求体**: +```json +{ + "status": "suspended" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.tenantId | string | 租户ID | +| data.status | string | 新状态 | +| message | string | 操作结果消息 | + +--- + +#### 7. 修改租户密码按钮 + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "修改密码"按钮 + +**按钮作用**: 重置租户登录密码 + +**功能描述**: 点击后弹出对话框，输入新密码和确认密码，提交后更新租户密码 + +**接口需求**: +``` +PUT /api/channel/tenants/{tenant_id}/password +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| tenant_id | string | 是 | 租户ID | + +**请求体**: +```json +{ + "newPassword": "NewSecurePass123" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.tenantId | string | 租户ID | +| message | string | 操作结果消息 | + +--- + +#### 8. 管理租户权限按钮 + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → 租户列表 → "管理权限"按钮 + +**按钮作用**: 配置租户的功能访问权限 + +**功能描述**: 点击后弹出对话框，显示权限复选框列表，勾选后保存租户的权限配置 + +**接口需求**: +``` +PUT /api/channel/tenants/{tenant_id}/permissions +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| tenant_id | string | 是 | 租户ID | + +**请求体**: +```json +{ + "permissions": ["dashboard", "agents", "models", "billing", "resources", "data-tools", "api-gateway"] +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.tenantId | string | 租户ID | +| data.permissions | array | 更新后的权限列表 | +| message | string | 操作结果消息 | + +--- + +#### 9. 供应商申请审批-拒绝按钮 + +**按钮位置**: 渠道管理页面 → 渠道申请审批表格 → "审批"按钮 → 审批对话框 → "拒绝"按钮 + +**按钮作用**: 拒绝渠道的供应商申请 + +**功能描述**: 点击后将申请状态设为rejected，渠道将无法使用该供应商 + +**接口需求**: +``` +PUT /api/admin/providers/applications/{application_id}/review +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| application_id | string | 是 | 申请ID | + +**请求体**: +```json +{ + "approved": false, + "reason": "申请被拒绝" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.applicationId | string | 申请ID | +| data.status | string | 新状态（rejected） | +| message | string | 操作结果消息 | + +--- + +#### 10. 供应商申请审批-批准按钮 + +**按钮位置**: 渠道管理页面 → 渠道申请审批表格 → "审批"按钮 → 审批对话框 → "批准"按钮 + +**按钮作用**: 批准渠道的供应商申请 + +**功能描述**: 点击后将申请状态设为approved，自动创建ChannelProviderAccess记录 + +**接口需求**: +``` +PUT /api/admin/providers/applications/{application_id}/review +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| application_id | string | 是 | 申请ID | + +**请求体**: +```json +{ + "approved": true, + "reason": "申请已批准" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.applicationId | string | 申请ID | +| data.status | string | 新状态（approved） | +| message | string | 操作结果消息 | + +--- + +#### 11. 平台Agent申请审批-拒绝按钮 + +**按钮位置**: 渠道管理页面 → 平台Agent申请审批表格 → "审批"按钮 → 审批对话框 → "拒绝"按钮 + +**按钮作用**: 拒绝渠道的平台Agent申请 + +**功能描述**: 点击后将申请状态设为rejected，渠道将无法使用该平台Agent + +**接口需求**: +``` +PUT /api/admin/applications/platform-agents/{application_id}/review +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| application_id | string | 是 | 申请ID | + +**请求体**: +```json +{ + "action": "reject", + "reviewReason": "申请被拒绝" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.applicationId | string | 申请ID | +| data.status | string | 新状态（rejected） | +| message | string | 操作结果消息 | + +--- + +#### 12. 平台Agent申请审批-批准按钮 + +**按钮位置**: 渠道管理页面 → 平台Agent申请审批表格 → "审批"按钮 → 审批对话框 → "批准"按钮 + +**按钮作用**: 批准渠道的平台Agent申请 + +**功能描述**: 点击后将申请状态设为approved，为渠道分配指定数量的Pod配额 + +**接口需求**: +``` +PUT /api/admin/applications/platform-agents/{application_id}/review +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| application_id | string | 是 | 申请ID | + +**请求体**: +```json +{ + "action": "approve", + "podQuota": 5, + "reviewReason": "申请已批准" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.applicationId | string | 申请ID | +| data.status | string | 新状态（approved） | +| message | string | 操作结果消息 | + +--- + +#### 27. 保存资源配置按钮 + +**按钮位置**: 渠道管理页面 → 渠道卡片 → "资源管理"菜单项 → 资源管理对话框 → "保存配置"按钮 + +**按钮作用**: 保存渠道的资源配置（模型、Agent、自定义Agent资源、授信额度） + +**功能描述**: 为渠道配置可用的模型供应商、Agent分配及数量、自定义Agent的CPU/内存资源、授信额度 + +**接口需求**: +``` +PUT /api/admin/channels/{channel_id}/resources +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 是 | 渠道ID | + +**请求体**: +```json +{ + "models": ["model-id-1", "model-id-2"], + "agents": [ + {"agentId": "agent-id-1", "quantity": 10}, + {"agentId": "agent-id-2", "quantity": 5} + ], + "customAgentResources": {"cpu": 2.0, "memory": 4.0}, + "channelCredit": 100000.00 +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.channelId | string | 渠道ID | +| message | string | 操作结果消息 | + +--- + +#### 28. 保存渠道编辑按钮 + +**按钮位置**: 渠道管理页面 → 渠道卡片 → "编辑"菜单项 → 编辑对话框 → "保存更改"按钮 + +**按钮作用**: 保存渠道基本信息的修改 + +**功能描述**: 修改渠道名称、联系人、邮箱、电话等基本信息 + +**接口需求**: +``` +PUT /api/admin/channels/{channel_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 是 | 渠道ID | + +**请求体**: +```json +{ + "name": "更新后的渠道名", + "email": "newemail@channel.com", + "contactName": "张三", + "phone": "+86-10-12345678" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 渠道ID | +| message | string | 操作结果消息 | + +--- + +#### 29. 保存佣金修改按钮 + +**按钮位置**: 渠道管理页面 → 渠道卡片 → "修改佣金"菜单项 → 佣金对话框 → "保存"按钮 + +**按钮作用**: 更新渠道的佣金比例 + +**功能描述**: 修改渠道的佣金分成比例 + +**接口需求**: +``` +PUT /api/admin/channels/{channel_id}/commission +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 是 | 渠道ID | + +**请求体**: +```json +{ + "commissionRate": 0.18 +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.channelId | string | 渠道ID | +| data.commissionRate | float | 新的佣金比例 | +| message | string | 操作结果消息 | + +--- + +#### 30. 创建渠道按钮 + +**按钮位置**: 渠道管理页面 → "添加渠道"按钮 → 创建对话框 → "创建"按钮 + +**按钮作用**: 创建新的分销渠道 + +**功能描述**: 填写渠道名称、邮箱、密码、佣金比例，创建新渠道账户 + +**接口需求**: +``` +POST /api/admin/channels/create +``` + +**请求体**: +```json +{ + "name": "新渠道", + "email": "channel@example.com", + "password": "SecurePass123", + "commissionRate": 0.15 +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 渠道ID | +| data.name | string | 渠道名称 | +| message | string | 操作结果消息 | + +--- + +#### 31. 添加租户按钮 + +**按钮位置**: 渠道管理页面 → 查看租户对话框 → "添加租户"按钮 → 添加租户对话框 → "创建租户"按钮 + +**按钮作用**: 为渠道创建新租户或管理员 + +**功能描述**: 填写租户名称、邮箱、密码、系统权限，创建新租户或渠道管理员 + +**接口需求（创建租户）**: +``` +POST /api/channel/tenants/create +``` + +**请求体**: +```json +{ + "name": "租户名称", + "email": "tenant@example.com", + "password": "SecurePass123", + "subscriptionTier": "free", + "channelId": "channel-uuid" +} +``` + +**接口需求（创建渠道管理员）**: +``` +POST /api/admin/admins/create +``` + +**请求体**: +```json +{ + "name": "管理员名称", + "email": "admin@example.com", + "password": "SecurePass123", + "role": "billing_admin", + "channelId": "channel-uuid" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 用户ID | +| message | string | 操作结果消息 | + +--- + +#### 32. 删除渠道管理员按钮 + +**按钮位置**: 渠道管理页面 → 编辑渠道对话框 → 管理员管理区域 → 管理员行 → 删除图标按钮 + +**按钮作用**: 从渠道移除管理员 + +**功能描述**: 点击后将管理员从该渠道移除 + +**接口需求**: +``` +DELETE /api/admin/channels/{channel_id}/admins/{admin_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel_id | string | 是 | 渠道ID | +| admin_id | string | 是 | 管理员ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| message | string | 操作结果消息 | + +--- + +## 资源管理模块 (Resources) + +### 数据展示接口 + +#### D3. Agent模板列表接口 + +**展示位置**: 资源管理页面 → 平台Agent模板管理区域 + +**展示内容**: 显示所有可用的Agent模板卡片，包含名称、描述、CPU/内存配置等 + +**功能描述**: 获取平台所有Agent模板的列表和配置信息 + +**接口需求**: +``` +GET /api/admin/platform-agents/templates +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.templates | array | 模板列表 | +| data.templates[].id | string | 模板ID | +| data.templates[].name | string | 模板名称 | +| data.templates[].displayName | string | 显示名称 | +| data.templates[].description | string | 模板描述 | +| data.templates[].cpuRequest | string | CPU请求量 | +| data.templates[].cpuLimit | string | CPU上限 | +| data.templates[].memoryRequest | string | 内存请求量 | +| data.templates[].memoryLimit | string | 内存上限 | +| data.templates[].maxPods | int | 最大Pod数量 | +| data.templates[].isEnabled | bool | 是否启用 | + +--- + +#### D4. 模型供应商列表接口 + +**展示位置**: 资源管理页面 → 货源供应商管理区域 + +**展示内容**: 显示所有模型供应商卡片，包含名称、状态、支持模型数、RPM/TPM等 + +**功能描述**: 获取平台所有模型供应商的列表和配置信息 + +**接口需求**: +``` +GET /api/providers/models +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.providers | array | 供应商列表 | +| data.providers[].id | string | 供应商ID | +| data.providers[].name | string | 供应商名称 | +| data.providers[].provider | string | 供应商类型 | +| data.providers[].supportedModels | array | 支持的模型列表 | +| data.providers[].rpm | int | 每分钟请求数限制 | +| data.providers[].tpm | int | 每分钟令牌数限制 | +| data.providers[].status | string | 状态 | + +--- + +### 按钮操作接口 + +#### 13. Agent模板配置-保存按钮 + +**按钮位置**: 资源管理页面 → Agent模板卡片 → "配置"按钮 → 配置对话框 → "保存配置"按钮 + +**按钮作用**: 保存Agent模板的K8s资源配置 + +**功能描述**: 配置Agent模板的CPU请求/限制、内存请求/限制、最大实例数等参数 + +**接口需求**: +``` +PUT /api/admin/platform-agents/templates/{name}/config +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| name | string | 是 | 模板名称（如 echo_agent） | + +**请求体**: +```json +{ + "cpuRequest": "100m", + "cpuLimit": "500m", + "memoryRequest": "128Mi", + "memoryLimit": "512Mi", + "maxPods": 10, + "isEnabled": true, + "displayName": "Echo 测试服务", + "description": "简单的 Echo 服务，用于测试和调试" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.templateName | string | 模板名称 | +| message | string | 操作结果消息 | + +--- + +#### 14. Agent模板删除按钮 + +**按钮位置**: 资源管理页面 → Agent模板卡片 → "删除"按钮 + +**按钮作用**: 删除Agent模板配置 + +**功能描述**: 点击后弹出确认对话框，确认后删除该Agent模板的配置 + +**接口需求**: +``` +DELETE /api/admin/platform-agents/templates/{name} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| name | string | 是 | 模板名称 | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| message | string | 操作结果消息 | + +--- + +#### 15. 添加模型供应商按钮 + +**按钮位置**: 资源管理页面 → "添加模型供应商"按钮 + +**按钮作用**: 创建新的模型供应商配置 + +**功能描述**: 点击后弹出对话框，填写供应商名称、API URL、API密钥、支持的模型列表、RPM/TPM限制等信息 + +**接口需求**: +``` +POST /api/providers/models/create +``` + +**请求体**: +```json +{ + "name": "OpenAI", + "provider": "openai", + "apiKey": "sk-...", + "apiUrl": "https://api.openai.com/v1", + "supportedModels": ["gpt-4", "gpt-3.5-turbo"], + "rpm": 1000, + "tpm": 100000 +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 供应商ID | +| message | string | 操作结果消息 | + +--- + +#### 16. 模型供应商配置按钮 + +**按钮位置**: 资源管理页面 → 模型供应商卡片 → "配置"按钮 + +**按钮作用**: 修改模型供应商配置 + +**功能描述**: 点击后弹出对话框，可修改供应商的API URL、API密钥、支持的模型列表、RPM/TPM限制等 + +**接口需求**: +``` +PUT /api/providers/models/{provider_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| provider_id | string | 是 | 供应商ID | + +**请求体**: +```json +{ + "name": "OpenAI", + "apiUrl": "https://api.openai.com/v1", + "apiKey": "sk-...", + "supportedModels": ["gpt-4", "gpt-3.5-turbo", "gpt-4-turbo"], + "rpm": 2000, + "tpm": 200000 +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 供应商ID | +| message | string | 操作结果消息 | + +--- + +#### 17. 模型供应商测试延迟按钮 + +**按钮位置**: 资源管理页面 → 模型供应商卡片 → "测试延迟"按钮 + +**按钮作用**: 测试与模型供应商的连接状态和延迟 + +**功能描述**: 点击后向供应商API发送测试请求，返回连接状态和响应延迟 + +**接口需求**: +``` +POST /api/providers/models/{provider_id}/test +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| provider_id | string | 是 | 供应商ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.status | string | 连接状态（connected/failed） | +| data.latency | int | 响应延迟（毫秒） | +| data.message | string | 测试结果消息 | + +--- + +#### 18. 模型供应商删除按钮 + +**按钮位置**: 资源管理页面 → 模型供应商卡片 → "删除"按钮 + +**按钮作用**: 删除模型供应商配置 + +**功能描述**: 点击后弹出确认对话框，确认后删除该供应商配置 + +**接口需求**: +``` +DELETE /api/providers/models/{provider_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| provider_id | string | 是 | 供应商ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| message | string | 操作结果消息 | + +--- + +## 监控模块 (Monitoring) + +### 数据展示接口 + +#### D5. Agent健康监控汇总接口 + +**展示位置**: 监控页面 → Agent健康监控区域 → 汇总统计卡片 + +**展示内容**: 显示Agent总数、健康Agent数、警告/异常Agent数等汇总统计 + +**功能描述**: 获取所有Agent的健康状态汇总统计 + +**接口需求**: +``` +GET /api/admin/platform-agents/status +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.summary.total | int | Agent总数 | +| data.summary.byHealthStatus.healthy | int | 健康Agent数 | +| data.summary.byHealthStatus.warning | int | 警告Agent数 | +| data.summary.byHealthStatus.critical | int | 异常Agent数 | +| data.agents | array | Agent详细列表 | + +--- + +#### D6. Agent详细指标接口 + +**展示位置**: 监控页面 → Agent健康监控区域 → Agent卡片 + +**展示内容**: 每个Agent卡片显示CPU使用率、内存使用率、CPU/内存上限、运行状态等 + +**功能描述**: 获取每个Agent的详细资源使用指标 + +**接口需求**: +``` +GET /api/admin/platform-agents/status +``` + +**响应字段（agents数组中每个元素）**: +| 字段 | 类型 | 说明 | +|------|------|------| +| id | string | Agent ID | +| name | string | Agent名称 | +| type | string | Agent类型（platform/custom） | +| healthStatus | string | 健康状态（healthy/warning/critical） | +| cpuUsage | string | CPU实际使用量 | +| cpuLimit | string | CPU上限 | +| cpuUtilization | float | CPU利用率百分比 | +| memoryUsage | string | 内存实际使用量 | +| memoryLimit | string | 内存上限 | +| memoryUtilization | float | 内存利用率百分比 | +| status | string | 运行状态 | +| source | string | 数据来源（k8s/database） | + +--- + +#### D7. 系统监控指标接口 + +**展示位置**: 概览页面 → 系统指标卡片 + +**展示内容**: 显示CPU使用率、内存使用率、存储使用率、活跃Agent数等系统级指标 + +**功能描述**: 获取平台整体的系统监控指标 + +**接口需求**: +``` +GET /api/v1/monitoring/metrics +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.cpu_usage | float | CPU使用率百分比 | +| data.memory_usage | float | 内存使用率百分比 | +| data.disk_usage | float | 存储使用率百分比 | +| data.active_agents | int | 活跃Agent数量 | + +--- + +## 计费模块 (Billing) + +### 数据展示接口 + +#### D8. 计费概览统计接口 + +**展示位置**: 计费管理页面 → 统计卡片区域 + +**展示内容**: 显示渠道总数、总计费额、总EU消耗等汇总统计 + +**功能描述**: 获取计费数据的汇总统计信息 + +**接口需求**: +``` +GET /api/admin/billing/overview +``` + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| startTime | string | 是 | 开始时间（ISO 8601格式） | +| endTime | string | 是 | 结束时间（ISO 8601格式） | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.summary.totalChannels | int | 渠道总数 | +| data.summary.totalBilling | float | 总计费额 | +| data.summary.totalEU | int | 总EU消耗 | + +--- + +#### D9. 渠道维度计费详情接口 + +**展示位置**: 计费管理页面 → 渠道维度 → 渠道计费详情表格 + +**展示内容**: 显示每个渠道的调用次数、总EU、渠道总价等 + +**功能描述**: 获取按渠道维度分组的计费详情 + +**接口需求**: +``` +GET /api/admin/billing/overview +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.channelStats | array | 渠道统计列表 | +| data.channelStats[].channelId | string | 渠道ID | +| data.channelStats[].channelName | string | 渠道名称 | +| data.channelStats[].calls | int | 调用次数 | +| data.channelStats[].totalEU | int | 总EU | +| data.channelStats[].totalCost | float | 渠道总价 | + +--- + +#### D10. 租户维度计费详情接口 + +**展示位置**: 计费管理页面 → 租户维度 → 租户计费详情表格 + +**展示内容**: 显示每个租户的所属渠道、调用次数、总EU、用户总价等 + +**功能描述**: 获取按租户维度分组的计费详情 + +**接口需求**: +``` +GET /api/admin/billing/overview +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.tenantStats | array | 租户统计列表 | +| data.tenantStats[].tenantId | string | 租户ID | +| data.tenantStats[].tenantName | string | 租户名称 | +| data.tenantStats[].channelName | string | 渠道名称 | +| data.tenantStats[].calls | int | 调用次数 | +| data.tenantStats[].totalEU | int | 总EU | +| data.tenantStats[].totalCost | float | 用户总价 | + +--- + +#### D11. 调用记录明细接口 + +**展示位置**: 计费管理页面 → 调用记录 → 调用记录明细表格 + +**展示内容**: 显示每次调用的ID、租户、渠道、调用时间、时长、EU、单次调用总价等 + +**功能描述**: 获取详细的调用记录列表 + +**接口需求**: +``` +GET /api/admin/billing/call-records +``` + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| startTime | string | 是 | 开始时间 | +| endTime | string | 是 | 结束时间 | +| page | int | 否 | 页码，默认1 | +| pageSize | int | 否 | 每页数量，默认20 | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.records | array | 调用记录列表 | +| data.records[].id | string | 调用ID | +| data.records[].tenantName | string | 租户名称 | +| data.records[].channelName | string | 渠道名称 | +| data.records[].callTime | string | 调用时间 | +| data.records[].duration | int | 时长（秒） | +| data.records[].eu | float | EU消耗 | +| data.records[].cost | float | 单次调用总价 | +| data.pagination.total | int | 总记录数 | +| data.pagination.page | int | 当前页 | + +--- + +### 按钮操作接口 + +#### 19. 时间查询按钮 + +**按钮位置**: 计费管理页面 → "时间查询"按钮 + +**按钮作用**: 按时间范围筛选计费数据 + +**功能描述**: 点击后弹出对话框，选择开始时间和结束时间，查询该时间段内的计费数据 + +**接口需求**: +``` +GET /api/admin/billing/overview +``` + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| startTime | string | 是 | 开始时间（ISO 8601格式） | +| endTime | string | 是 | 结束时间（ISO 8601格式） | + +--- + +#### 20. 筛选按钮 + +**按钮位置**: 计费管理页面 → "筛选"按钮 + +**按钮作用**: 按条件筛选计费数据 + +**功能描述**: 点击后弹出对话框，可按客户名称、最小/最大调用次数等条件筛选 + +**接口需求**: +``` +GET /api/admin/billing/overview +``` + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| startTime | string | 是 | 开始时间 | +| endTime | string | 是 | 结束时间 | +| channelName | string | 否 | 渠道名称筛选 | +| tenantName | string | 否 | 租户名称筛选 | +| minCalls | int | 否 | 最小调用次数 | +| maxCalls | int | 否 | 最大调用次数 | + +--- + +#### 21. 导出按钮 + +**按钮位置**: 计费管理页面 → "导出"按钮 + +**按钮作用**: 导出计费数据为文件 + +**功能描述**: 点击后将当前筛选条件下的计费数据导出为Excel/CSV/PDF格式文件 + +**接口需求**: +``` +GET /api/admin/billing/export +``` + +**查询参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| startTime | string | 是 | 开始时间 | +| endTime | string | 是 | 结束时间 | +| format | string | 是 | 导出格式（excel/csv/pdf） | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.fileUrl | string | 导出文件下载URL | +| message | string | 操作结果消息 | + +--- + +## 设置模块 (Settings) + +### 数据展示接口 + +#### D12. 管理员列表接口 + +**展示位置**: 设置页面 → 当前管理员列表 + +**展示内容**: 显示所有系统管理员的姓名、邮箱、角色、状态等 + +**功能描述**: 获取系统管理员列表 + +**接口需求**: +``` +GET /api/admin/admins +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.admins | array | 管理员列表 | +| data.admins[].id | string | 管理员ID | +| data.admins[].name | string | 管理员姓名 | +| data.admins[].email | string | 邮箱 | +| data.admins[].role | string | 角色 | +| data.admins[].status | string | 状态 | + +--- + +### 按钮操作接口 + +#### 22. 添加管理员按钮 + +**按钮位置**: 设置页面 → 当前管理员列表 → "添加管理员"按钮 + +**按钮作用**: 创建新的系统管理员账户 + +**功能描述**: 点击后弹出对话框，填写管理员姓名、邮箱、密码、角色，创建新管理员 + +**接口需求**: +``` +POST /api/admin/admins/create +``` + +**请求体**: +```json +{ + "name": "管理员姓名", + "email": "admin@example.com", + "password": "SecurePass123", + "role": "billing_admin" +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.id | string | 管理员ID | +| message | string | 操作结果消息 | + +--- + +#### 23. 删除管理员按钮 + +**按钮位置**: 设置页面 → 当前管理员列表 → 管理员行 → 删除图标按钮 + +**按钮作用**: 删除系统管理员账户（软删除） + +**功能描述**: 点击后弹出确认对话框，确认后将管理员状态设为inactive + +**接口需求**: +``` +DELETE /api/admin/admins/{admin_id} +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| admin_id | string | 是 | 管理员ID | + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| message | string | 操作结果消息 | + +--- + +#### 24-26. 角色权限配置按钮 + +**按钮位置**: 设置页面 → 角色权限配置区域 → "保存权限配置"按钮 + +**按钮作用**: 保存角色的标签页访问权限配置 + +**功能描述**: 选择角色后，勾选该角色可访问的标签页，点击保存更新权限配置 + +**接口需求**: +``` +PUT /api/admin/roles/{role_id}/permissions +``` + +**路径参数**: +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| role_id | string | 是 | 角色ID（billing-admin/operations-admin/super-admin） | + +**请求体**: +```json +{ + "permissions": ["overview", "channels", "resources", "monitoring", "billing", "settings"] +} +``` + +**响应字段**: +| 字段 | 类型 | 说明 | +|------|------|------| +| success | bool | 是否成功 | +| data.roleId | string | 角色ID | +| data.permissions | array | 更新后的权限列表 | +| message | string | 操作结果消息 | + +--- + +## 附录：接口汇总表 + +### 数据展示接口汇总 + +| 序号 | 接口 | 方法 | 展示内容 | 模块 | +|------|------|------|----------|------| +| D1 | /api/admin/platform/resource-allocation | GET | 平台资源分配统计 | 概览 | +| D2 | /api/admin/channels/stats | GET | 渠道统计概览 | 渠道管理 | +| D3 | /api/admin/platform-agents/templates | GET | Agent模板列表 | 资源管理 | +| D4 | /api/providers/models | GET | 模型供应商列表 | 资源管理 | +| D5 | /api/admin/platform-agents/status | GET | Agent健康监控汇总 | 监控 | +| D6 | /api/admin/platform-agents/status | GET | Agent详细指标 | 监控 | +| D7 | /api/v1/monitoring/metrics | GET | 系统监控指标 | 概览 | +| D8 | /api/admin/billing/overview | GET | 计费概览统计 | 计费 | +| D9 | /api/admin/billing/overview | GET | 渠道维度计费详情 | 计费 | +| D10 | /api/admin/billing/overview | GET | 租户维度计费详情 | 计费 | +| D11 | /api/admin/billing/call-records | GET | 调用记录明细 | 计费 | +| D12 | /api/admin/admins | GET | 管理员列表 | 设置 | + +### 按钮操作接口汇总 + +| 序号 | 接口 | 方法 | 按钮/功能 | 模块 | +|------|------|------|----------|------| +| 1 | /api/admin/dashboard/recent-logins/search | GET | 搜索租户 | 概览 | +| 2 | /api/admin/channels/search | GET | 搜索渠道 | 渠道管理 | +| 3 | /api/admin/channels/{channel_id} | GET | 查看渠道详情 | 渠道管理 | +| 4 | /api/admin/channels/{channel_id} | DELETE | 删除渠道 | 渠道管理 | +| 5 | /api/channel/tenants/{tenant_id} | DELETE | 删除租户 | 渠道管理 | +| 6 | /api/channel/tenants/{tenant_id}/status | PUT | 禁用租户 | 渠道管理 | +| 7 | /api/channel/tenants/{tenant_id}/password | PUT | 修改租户密码 | 渠道管理 | +| 8 | /api/channel/tenants/{tenant_id}/permissions | PUT | 管理租户权限 | 渠道管理 | +| 9 | /api/admin/providers/applications/{id}/review | PUT | 供应商申请审批-拒绝 | 渠道管理 | +| 10 | /api/admin/providers/applications/{id}/review | PUT | 供应商申请审批-批准 | 渠道管理 | +| 11 | /api/admin/applications/platform-agents/{id}/review | PUT | 平台Agent申请审批-拒绝 | 渠道管理 | +| 12 | /api/admin/applications/platform-agents/{id}/review | PUT | 平台Agent申请审批-批准 | 渠道管理 | +| 13 | /api/admin/platform-agents/templates/{name}/config | PUT | Agent模板配置-保存 | 资源管理 | +| 14 | /api/admin/platform-agents/templates/{name} | DELETE | Agent模板删除 | 资源管理 | +| 15 | /api/providers/models/create | POST | 添加模型供应商 | 资源管理 | +| 16 | /api/providers/models/{provider_id} | PUT | 模型供应商配置 | 资源管理 | +| 17 | /api/providers/models/{provider_id}/test | POST | 模型供应商测试延迟 | 资源管理 | +| 18 | /api/providers/models/{provider_id} | DELETE | 模型供应商删除 | 资源管理 | +| 19 | /api/admin/billing/overview | GET | 时间查询 | 计费 | +| 20 | /api/admin/billing/overview | GET | 筛选 | 计费 | +| 21 | /api/admin/billing/export | GET | 导出 | 计费 | +| 22 | /api/admin/admins/create | POST | 添加管理员 | 设置 | +| 23 | /api/admin/admins/{admin_id} | DELETE | 删除管理员 | 设置 | +| 24-26 | /api/admin/roles/{role_id}/permissions | PUT | 保存权限配置 | 设置 | +| 27 | /api/admin/channels/{channel_id}/resources | PUT | 保存资源配置 | 渠道管理 | +| 28 | /api/admin/channels/{channel_id} | PUT | 保存渠道编辑 | 渠道管理 | +| 29 | /api/admin/channels/{channel_id}/commission | PUT | 保存佣金修改 | 渠道管理 | +| 30 | /api/admin/channels/create | POST | 创建渠道 | 渠道管理 | +| 31 | /api/channel/tenants/create | POST | 添加租户 | 渠道管理 | +| 32 | /api/admin/channels/{channel_id}/admins/{admin_id} | DELETE | 删除渠道管理员 | 渠道管理 | + +--- + +## 更新日志 + +### v1.1.0 (2026-01-06) + +- 新增数据展示接口（D1-D12） +- 补充监控模块的Agent详细指标接口 +- 补充计费模块的调用记录明细接口 +- 完善接口汇总表 \ No newline at end of file diff --git a/services/mcp-server/app/routes/admin.py b/services/mcp-server/app/routes/admin.py index d8fec2e..902e51f 100644 --- a/services/mcp-server/app/routes/admin.py +++ b/services/mcp-server/app/routes/admin.py @@ -2008,10 +2008,16 @@ async def get_billing_overview( """ _verify_read_permission(principal) - # 解析时间 + # 解析时间，移除时区信息以匹配数据库中的 naive datetime start_dt = datetime.fromisoformat(startTime.replace("Z", "+00:00")) end_dt = datetime.fromisoformat(endTime.replace("Z", "+00:00")) + # 转换为 naive datetime（移除时区信息） + if start_dt.tzinfo is not None: + start_dt = start_dt.replace(tzinfo=None) + if end_dt.tzinfo is not None: + end_dt = end_dt.replace(tzinfo=None) + # 渠道统计 channel_stats_result = await db.execute( select( @@ -3100,13 +3106,32 @@ async def get_platform_agents_status( k8s_status = agent.get("status", "unknown") # 获取资源使用情况 - cpu_usage = "0" - memory_usage = "0" + # 实时使用量（从 metrics-server 获取） + cpu_usage_current = "0" + memory_usage_current = "0" + # 资源限制（从 Pod spec 获取） + cpu_limit = "0" + memory_limit = "0" + # 是否有实时 metrics 数据 + has_realtime_metrics = False + metrics_timestamp = None + try: metrics = await client.get_agent_metrics(agent_name) - # 使用新的属性访问器 - cpu_usage = metrics.cpu_usage - memory_usage = metrics.memory_usage + # 资源限制 + cpu_limit = metrics.cpu_limit + memory_limit = metrics.memory_limit + + # 实时使用量（需要 metrics-server） + if metrics.has_realtime_metrics: + has_realtime_metrics = True + cpu_usage_current = metrics.cpu_usage_current + memory_usage_current = metrics.memory_usage_current + metrics_timestamp = metrics.timestamp + else: + # 没有实时数据时，显示 N/A + cpu_usage_current = "N/A" + memory_usage_current = "N/A" except Exception as e: logger.debug(f"获取 Agent {agent_name} 资源指标失败: {e}") @@ -3117,8 +3142,15 @@ async def get_platform_agents_status( "podName": agent.get("pod_name", ""), "podIp": agent.get("pod_ip", ""), "namespace": agent.get("namespace", "ai-agents"), - "cpuUsage": _format_cpu_usage(cpu_usage), - "memoryUsage": _format_memory_usage(memory_usage), + # 实时 CPU/内存使用量（从 metrics-server 获取） + "cpuUsage": _format_cpu_usage(cpu_usage_current) if cpu_usage_current != "N/A" else "N/A", + "memoryUsage": _format_memory_usage(memory_usage_current) if memory_usage_current != "N/A" else "N/A", + # 资源限制（从 Pod spec 获取） + "cpuLimit": cpu_limit, + "memoryLimit": memory_limit, + # 是否有实时 metrics 数据 + "hasRealtimeMetrics": has_realtime_metrics, + "metricsTimestamp": metrics_timestamp, "createdAt": agent.get("created_at"), })