taijibaga/taiji-AI-PAD

Fork 0

forked from xiaohei/taiji-AI-PAD

Files

T

zhanggangyong 1154b4e7ae 更新租户配额

2026-01-12 16:47:41 +00:00

42 KiB

Raw Blame History

超级管理员控制台 - 接口对接文档

版本: v1.0.4 更新时间: 2026-01-13 说明: 本文档基于前端业务需求清单与后端API接口清单核实，列出所有超级管理员端接口的对接状态 最新测试: 2026-01-06 14:54 UTC - 所有已对接接口测试通过 前端代码核对: 2026-01-06 14:54 UTC - 已完成前端代码与接口文档的一致性核对，修复健康状态判断问题

接口对接状态总览

类别	总数	已对接	未对接	对接率
数据展示接口	14	12	2	85.7%
按钮操作接口	34	29	5	85.3%
合计	48	41	7	85.4%

状态说明

✅ 已对接: 后端接口已实现，前端可直接调用
⚠️ 部分对接: 接口存在但参数或响应格式需调整
❌ 未对接: 后端接口未实现，需要开发

概览模块 (Overview)

数据展示接口

D1. 仪表板统计接口 ✅ 已对接

属性	值
接口路径	`GET /api/admin/dashboard/stats`
后端状态	✅ 已实现 (admin.py)
权限要求	super_admin, billing_admin, operations_admin

展示位置: 概览页面 → 顶部统计卡片区域

展示内容:

总渠道数
总租户数
总收入
总Agent数

响应字段:

{
  "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

响应字段:

{
  "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

响应字段:

{
  "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

响应字段:

{
  "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

展示位置: 渠道管理页面 → 渠道列表卡片

响应字段:

{
  "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)
前端状态	✅ 已实现 (2026-01-06 修复)
权限要求	super_admin

按钮位置: 渠道管理页面 → 渠道卡片 → 更多操作菜单 → "删除渠道"

前端调用: 直接fetch调用 DELETE ${API_BASE_URLS.mcpServer}/api/admin/channels/${channel.id}

路径参数:

参数	类型	必填	说明
channel_id	string	是	渠道ID

响应字段:

{
  "success": true,
  "message": "渠道删除成功"
}

4. 删除租户 ✅ 已对接

属性	值
接口路径	`DELETE /api/channel/tenants/{tenant_id}`
后端状态	✅ 已实现 (channel.py)
权限要求	channel_admin

按钮位置: 渠道管理页面 → 查看租户对话框 → 租户列表 → "删除"按钮

路径参数:

参数	类型	必填	说明
tenant_id	string	是	租户ID
curl -i -X DELETE "http://localhost:8002/api/channel/tenants/2c45b96d-c158-466f-b5fc-3eccdc24a8bb?channel_id=6e6fc470-76f8-4bb1-8ea4-625dc5b12bc6" \
-H "Authorization: Bearer $SUPER_ADMIN_TOKEN"
响应字段:

{
  "success": true,
  "message": "租户删除成功"
}

5. 禁用租户 ✅ 已对接

属性	值
接口路径	`PUT /api/channel/tenants/{tenant_id}/status`
后端状态	✅ 已实现 (channel.py)
权限要求	channel_admin

按钮位置: 渠道管理页面 → 查看租户对话框 → 租户列表 → "禁用"按钮

请求体:

{
  "status": "suspended"
}

响应字段:

{
  "success": true,
  "data": {
    "tenantId": "tenant-uuid",
    "status": "suspended"
  },
  "message": "租户状态更新成功"
}

6. 修改租户密码 ✅ 已对接

属性	值
接口路径	`PUT /api/channel/tenants/{tenant_id}/password`
后端状态	✅ 已实现 (channel.py)
权限要求	channel_admin

按钮位置: 渠道管理页面 → 查看租户对话框 → 租户列表 → "修改密码"按钮

请求体:

{
  "newPassword": "NewSecurePass123"
}

响应字段:

{
  "success": true,
  "data": {
    "tenantId": "tenant-uuid"
  },
  "message": "密码修改成功"
}

7. 管理租户权限 ✅ 已对接

属性	值
接口路径	`PUT /api/channel/tenants/{tenant_id}/permissions`
后端状态	✅ 已实现 (channel.py)
权限要求	channel_admin

按钮位置: 渠道管理页面 → 查看租户对话框 → 租户列表 → "管理权限"按钮

请求体:

{
  "permissions": ["dashboard", "agents", "models", "billing", "resources", "data-tools", "api-gateway"]
}

响应字段:

{
  "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

按钮位置: 渠道管理页面 → 渠道申请审批表格 → "审批"按钮

请求体（批准）:

{
  "approved": true,
  "reason": "申请已批准"
}

请求体（拒绝）:

{
  "approved": false,
  "reason": "申请被拒绝"
}

响应字段:

{
  "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申请审批表格 → "审批"按钮

请求体（批准）:

{
  "action": "approve",
  "podQuota": 5,
  "reviewReason": "申请已批准"
}

请求体（拒绝）:

{
  "action": "reject",
  "reviewReason": "申请被拒绝"
}

响应字段:

{
  "success": true,
  "data": {
    "applicationId": "app-uuid",
    "status": "approved"
  },
  "message": "审批完成"
}

10. 保存资源配置 ✅ 已对接

属性	值
接口路径	`PUT /api/admin/channels/{channel_id}/resources`
后端状态	✅ 已实现 (admin.py)
权限要求	super_admin, billing_admin

按钮位置: 渠道管理页面 → 渠道卡片 → "资源管理"菜单项 → "保存配置"按钮

请求体:

{
  "models": ["provider-uuid-1", "gpt-4", "provider-uuid-2", "claude-3-opus"],
  "agents": [
    {"agentId": "agent-id-1", "quantity": 10},
    {"agentId": "agent-id-2", "quantity": 5}
  ],
  "customAgentResources": {"cpu": 2.0, "memory": 4.0},
  "channelCredit": 100000.00
}

参数说明:

models: 模型列表，支持以下三种格式（可混合使用）：
1. 供应商ID（UUID格式）：系统会自动展开为该供应商的所有支持模型
2. 模型名称（字符串）：直接使用该模型名称
3. 混合使用：可在同一数组中同时传入供应商ID和模型名称
示例：
```
{
  "models": [
    "550e8400-e29b-41d4-a716-446655440000",  // 供应商UUID，会展开为所有模型
    "gpt-4",                                   // 直接指定模型名称
    "claude-3-opus"                            // 直接指定模型名称
  ]
}
```
系统会自动去重，最终存储的是模型名称列表。
agents: 平台Agent配额列表
- agentId: Agent模板ID
- quantity: 分配的Pod数量
customAgentResources: 自定义Agent资源配额
- cpu: CPU核心数（浮点数）
- memory: 内存大小（GB，浮点数）
channelCredit: 渠道信用额度（浮点数）

重要说明:

平台Agent在渠道分配给租户时不会立即启动Pod，仅创建配额记录
Pod实际启动时机：租户调用 POST /api/tenant/platform-agents/use 时
自定义Agent在租户创建时立即启动Pod

响应字段:

{
  "success": true,
  "data": {
    "channelId": "channel-uuid",
    "allocatedModels": ["gpt-4", "claude-3-opus", "gpt-3.5-turbo"],
    "allocatedAgents": [
      {"agentId": "agent-id-1", "quantity": 10},
      {"agentId": "agent-id-2", "quantity": 5}
    ],
    "customAgentResources": {"cpu": 2.0, "memory": 4.0},
    "channelCredit": 100000.00
  },
  "message": "资源配置保存成功"
}

11. 保存渠道编辑 ✅ 已对接

属性	值
接口路径	`PUT /api/admin/channels/{channel_id}`
后端状态	✅ 已实现 (admin.py)
权限要求	super_admin, billing_admin

按钮位置: 渠道管理页面 → 渠道卡片 → "编辑"菜单项 → "保存更改"按钮

请求体:

{
  "name": "更新后的渠道名",
  "email": "newemail@channel.com",
  "contactName": "张三",
  "phone": "+86-10-12345678"
}

响应字段:

{
  "success": true,
  "data": {
    "id": "channel-uuid"
  },
  "message": "渠道信息更新成功"
}

12. 保存佣金修改 ✅ 已对接

属性	值
接口路径	`PUT /api/admin/channels/{channel_id}/commission`
后端状态	✅ 已实现 (admin.py)
权限要求	super_admin, billing_admin

按钮位置: 渠道管理页面 → 渠道卡片 → "修改佣金"菜单项 → "保存"按钮

请求体:

{
  "commissionRate": 0.18
}

响应字段:

{
  "success": true,
  "data": {
    "channelId": "channel-uuid",
    "commissionRate": 0.18
  },
  "message": "佣金比例更新成功"
}

13. 创建渠道 ✅ 已对接

属性	值
接口路径	`POST /api/admin/channels/create`
后端状态	✅ 已实现 (admin.py)
权限要求	super_admin, billing_admin

按钮位置: 渠道管理页面 → "添加渠道"按钮 → "创建"按钮

请求体:

{
  "name": "新渠道",
  "email": "channel@example.com",
  "password": "SecurePass123",
  "commissionRate": 0.15
}

响应字段:

{
  "success": true,
  "data": {
    "id": "channel-uuid",
    "name": "新渠道"
  },
  "message": "渠道创建成功"
}

14. 添加租户 ✅ 已对接

属性	值
接口路径	`POST /api/channel/tenants/create`
后端状态	✅ 已实现 (channel.py)
权限要求	channel_admin

按钮位置: 渠道管理页面 → 查看租户对话框 → "添加租户"按钮

请求体:

{
  "name": "租户名称",
  "email": "tenant@example.com",
  "password": "SecurePass123",
  "subscriptionTier": "free",
  "channelId": "channel-uuid"
}

响应字段:

{
  "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 获取渠道管理员列表，但未明确列出删除接口。建议确认是否已实现。

16. 查看渠道租户资源分配 ✅ 已对接

属性	值
接口路径	`GET /api/admin/channels/{channel_id}/tenants/resources`
后端状态	✅ 已实现 (admin.py)
权限要求	super_admin, billing_admin, operations_admin, channel_admin

按钮位置: 渠道管理页面 → 渠道卡片 → "查看租户资源分配"菜单项

说明: 查看渠道下所有租户被分配的资源（自定义Agent、平台Agent、模型）

路径参数:

参数	类型	必填	说明
channel_id	string	是	渠道ID

响应字段:

{
  "success": true,
  "data": {
    "channelId": "channel-uuid",
    "channelName": "渠道名称",
    "tenants": [
      {
        "tenantId": "tenant-uuid",
        "tenantName": "租户名称",
        "tenantEmail": "tenant@example.com",
        "status": "active",
        "createdAt": "2026-01-01T00:00:00Z",
        "customAgentQuota": {
          "cpuQuota": 2.0,
          "memoryQuota": 4.0,
          "cpuUsed": 1.0,
          "memoryUsed": 2.0,
          "agentCount": 2
        },
        "platformAgents": [
          {
            "templateName": "echo_agent",
            "podQuota": 5,
            "podUsed": 2,
            "cpuPerPod": "100m",
            "memoryPerPod": "256Mi"
          }
        ],
        "models": [
          {
            "modelName": "gpt-4o",
            "rpmLimit": 1000,
            "tpmLimit": 100000,
            "maxBudget": 500.0,
            "budgetDuration": "monthly"
          }
        ]
      }
    ],
    "summary": {
      "totalTenants": 5,
      "tenantsWithCustomAgents": 3,
      "tenantsWithPlatformAgents": 4,
      "tenantsWithModels": 5,
      "totalCustomAgentCpuQuota": 10.0,
      "totalCustomAgentMemoryQuota": 20.0,
      "totalCustomAgentCpuUsed": 5.0,
      "totalCustomAgentMemoryUsed": 10.0,
      "totalPlatformAgentPodQuota": 25,
      "totalPlatformAgentPodUsed": 10
    }
  },
  "message": "获取渠道租户资源分配成功"
}

权限说明: 渠道管理员只能查看自己所属渠道的租户资源分配

前端调用: TaijiAPIClient.getChannelTenantsResources(channelId)

17. 渠道管理员查看租户资源分配汇总 ✅ 已对接

属性	值
接口路径	`GET /api/channel/tenants/resources/summary`
后端状态	✅ 已实现 (channel.py)
权限要求	channel_admin, billing_admin, operations_admin, super_admin

按钮位置: 渠道管理控制台 → 租户管理 → "资源分配汇总"

说明: 渠道管理员查看自己渠道下所有租户的资源分配汇总，包括渠道配额和租户分配情况对比

查询参数:

参数	类型	必填	说明
channel_id	string	否	渠道ID（超级管理员必填，其他管理员自动使用所属渠道）

响应字段:

{
  "success": true,
  "data": {
    "channelId": "channel-uuid",
    "channelName": "渠道名称",
    "channelQuota": {
      "customAgentQuota": {
        "cpuQuota": 20.0,
        "memoryQuota": 40.0,
        "cpuAllocated": 10.0,
        "memoryAllocated": 20.0
      },
      "platformAgents": [
        {
          "templateName": "echo_agent",
          "podQuota": 50,
          "podUsed": 10,
          "cpuPerPod": "100m",
          "memoryPerPod": "256Mi"
        }
      ],
      "models": ["gpt-4o", "claude-3-opus"]
    },
    "tenants": [
      {
        "tenantId": "tenant-uuid",
        "tenantName": "租户名称",
        "tenantEmail": "tenant@example.com",
        "status": "active",
        "subscriptionTier": "pro",
        "balance": 1000.0,
        "createdAt": "2026-01-01T00:00:00Z",
        "customAgentQuota": {
          "cpuQuota": 2.0,
          "memoryQuota": 4.0,
          "cpuUsed": 1.0,
          "memoryUsed": 2.0,
          "agentCount": 2
        },
        "platformAgents": [...],
        "models": [...]
      }
    ],
    "summary": {
      "totalTenants": 5,
      "tenantsWithCustomAgents": 3,
      "tenantsWithPlatformAgents": 4,
      "tenantsWithModels": 5,
      "totalCustomAgentCpuQuota": 10.0,
      "totalCustomAgentMemoryQuota": 20.0,
      "totalCustomAgentCpuUsed": 5.0,
      "totalCustomAgentMemoryUsed": 10.0,
      "totalPlatformAgentPodQuota": 25,
      "totalPlatformAgentPodUsed": 10,
      "totalModelsAllocated": 10
    }
  },
  "message": "获取渠道租户资源分配成功"
}

使用场景: 渠道管理员可以查看渠道的总配额与已分配给租户的配额对比，方便进行资源管理

前端调用: TaijiAPIClient.getChannelTenantsResourcesSummary(channelId)

资源管理模块 (Resources)

数据展示接口

D7. Agent模板列表接口 ✅ 已对接

属性	值
接口路径	`GET /api/admin/platform-agents/templates`
后端状态	✅ 已实现 (admin.py, platform_agent_quota.py)
权限要求	super_admin, billing_admin

展示位置: 资源管理页面 → 平台Agent模板管理区域

响应字段:

{
  "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)
权限要求	已认证用户

展示位置: 资源管理页面 → 货源供应商管理区域

响应字段:

{
  "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模板卡片 → "配置"按钮 → "保存配置"按钮

请求体:

{
  "cpuRequest": "100m",
  "cpuLimit": "500m",
  "memoryRequest": "128Mi",
  "memoryLimit": "512Mi",
  "maxPods": 10,
  "isEnabled": true,
  "displayName": "Echo 测试服务",
  "description": "简单的 Echo 服务，用于测试和调试"
}

响应字段:

{
  "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

按钮位置: 资源管理页面 → "添加模型供应商"按钮

请求体:

{
  "name": "OpenAI",
  "provider": "openai",
  "apiKey": "sk-...",
  "apiUrl": "https://api.openai.com/v1",
  "supportedModels": ["gpt-4", "gpt-3.5-turbo"],
  "rpm": 1000,
  "tpm": 100000
}

响应字段:

{
  "success": true,
  "data": {
    "id": "provider-uuid"
  },
  "message": "供应商创建成功"
}

19. 模型供应商配置 ✅ 已对接

属性	值
接口路径	`PUT /api/providers/models/{provider_id}`
后端状态	✅ 已实现 (providers.py)
权限要求	super_admin, billing_admin

按钮位置: 资源管理页面 → 模型供应商卡片 → "配置"按钮

请求体:

{
  "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": true,
  "data": {
    "id": "provider-uuid"
  },
  "message": "供应商配置更新成功"
}

20. 模型供应商测试延迟 ✅ 已对接

属性	值
接口路径	`POST /api/providers/models/{provider_id}/test`
后端状态	✅ 已实现 (providers.py)
权限要求	super_admin, billing_admin

按钮位置: 资源管理页面 → 模型供应商卡片 → "测试延迟"按钮

响应字段:

{
  "success": true,
  "data": {
    "status": "connected",
    "latency": 150,
    "message": "连接测试成功"
  }
}

21. 模型供应商删除 ✅ 已对接

属性	值
接口路径	`DELETE /api/providers/models/{provider_id}`
后端状态	✅ 已实现 (providers.py)
权限要求	super_admin

按钮位置: 资源管理页面 → 模型供应商卡片 → "删除"按钮

响应字段:

{
  "success": true,
  "message": "供应商删除成功"
}

监控模块 (Monitoring)

数据展示接口

D9. Agent健康监控汇总接口 ✅ 已对接

属性	值
接口路径	`GET /api/admin/platform-agents/status`
后端状态	✅ 已实现 (admin.py)
权限要求	super_admin, billing_admin, operations_admin

展示位置: 监控页面 → Agent健康监控区域 → 汇总统计卡片

实际响应字段 (2026-01-06 14:54 UTC 测试确认):

{
  "success": true,
  "data": {
    "agents": [
      {
        "name": "alice-echo",
        "template": "echo_agent",
        "status": "Running",
        "podName": "",
        "podIp": "10.244.1.143",
        "namespace": "ai-agents",
        "cpuUsage": "0.01m",
        "memoryUsage": "8.5Mi",
        "cpuLimit": "500m",
        "memoryLimit": "512Mi",
        "hasRealtimeMetrics": true,
        "metricsTimestamp": "2026-01-06T14:44:572",
        "createdAt": "2026-01-05T07:36:09+00:00"
      }
    ]
  }
}

重要说明:

status 字段值为 "Running"（首字母大写），不是 "running"

没有 healthStatus 字段，健康状态通过 status 字段判断

没有 byHealthStatus 汇总统计，前端需要自行计算

前端判断健康状态时应使用: status === "Running" 或 status === "available"

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格式）

响应字段:

{
  "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

展示位置: 设置页面 → 当前管理员列表

响应字段:

{
  "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

展示位置: 设置页面 → 角色权限配置区域

响应字段:

{
  "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

按钮位置: 设置页面 → 当前管理员列表 → "添加管理员"按钮

请求体:

{
  "name": "管理员姓名",
  "email": "admin@example.com",
  "password": "SecurePass123",
  "role": "billing_admin"
}

响应字段:

{
  "success": true,
  "data": {
    "id": "admin-uuid"
  },
  "message": "管理员创建成功"
}

25. 删除管理员 ✅ 已对接

属性	值
接口路径	`DELETE /api/admin/admins/{admin_id}`
后端状态	✅ 已实现 (admin.py)
权限要求	super_admin

按钮位置: 设置页面 → 当前管理员列表 → 管理员行 → 删除图标按钮

响应字段:

{
  "success": true,
  "message": "管理员删除成功"
}

26. 保存角色权限配置 ❌ 未对接

属性	值
接口路径	`PUT /api/admin/roles/{role_id}/permissions`
后端状态	❌ 未实现
权限要求	super_admin

按钮位置: 设置页面 → 角色权限配置区域 → "保存权限配置"按钮

说明: 后端 API 清单中未列出此接口，需要开发实现。

建议请求体:

{
  "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	角色列表	设置
35	/api/admin/channels/{channel_id}/tenants/resources	GET	查看渠道租户资源分配	渠道管理
36	/api/channel/tenants/resources/summary	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	100%
渠道管理模块	15	15	100%
资源管理模块	8	8	100%
监控模块	2	2	100%
计费模块	2	2	100%
设置模块	4	4	100%
合计	35	35	100%

已修复问题

计费概览接口时区问题 (D11)
- 问题: GET /api/admin/billing/overview 返回 Internal Server Error
- 原因: 时间参数解析后带时区信息，但数据库字段是 naive datetime，导致 can't subtract offset-naive and offset-aware datetimes 错误
- 修复: 在 admin.py 中移除时区信息
- 状态: ✅ 已修复

字段差异说明

以下接口的实际返回字段与文档定义有差异（均为向后兼容的扩展）：

D1. 仪表板统计接口: 新增 totalCalls, totalAllocatedCpu, totalAllocatedMemory, platformAgents, customAgents 字段
D2. 系统监控指标接口: 响应格式不同，不包含外层 success 字段，增加了 services 和 billing 统计
D4. 平台资源分配统计接口: summary 字段结构变化，新增 running, pending, error 状态统计
D5. 渠道列表接口: 新增 channelCredit, customAgentCpu, customAgentMemory, totalAllocatedCpu, totalAllocatedMemory 字段
D7. Agent模板列表接口: 新增 category, version, port, envInfo, status 字段

登录接口说明

登录接口 POST /api/auth/login 需要 role 参数：

超级管理员登录: role: "admin"
渠道管理员登录: role: "channel"
普通用户登录: role: "user"

更新日志

v1.0.4 (2026-01-13)

新增 GET /api/admin/channels/{channel_id}/tenants/resources 接口：查看渠道下所有租户的资源分配（自定义Agent、平台Agent、模型）
新增 GET /api/channel/tenants/resources/summary 接口：渠道管理员查看租户资源分配汇总，包含渠道配额对比
支持超级管理员和渠道管理员查看租户资源分配情况

v1.0.1 (2026-01-06)

完成所有已对接接口的实际测试
修复计费概览接口时区问题
更新响应字段文档，记录实际返回值
添加接口测试报告章节

v1.0.0 (2026-01-06)

初始版本
完成前端需求与后端API的对接核实
识别7个未对接接口
整理34个已对接接口
添加权限矩阵说明

42 KiB Raw Blame History Unescape Escape

超级管理员控制台 - 接口对接文档

目录

接口对接状态总览

状态说明

概览模块 (Overview)

数据展示接口

D1. 仪表板统计接口 ✅ 已对接

D2. 系统监控指标接口 ✅ 已对接

D3. 最近登录租户列表接口 ✅ 已对接

D4. 平台资源分配统计接口 ✅ 已对接

渠道管理模块 (Channels)

数据展示接口

D5. 渠道列表接口 ✅ 已对接

D6. 渠道统计概览接口 ❌ 未对接

按钮操作接口

1. 搜索渠道 ❌ 未对接

2. 查看渠道详情 ⚠️ 部分对接

3. 删除渠道 ✅ 已对接

4. 删除租户 ✅ 已对接

5. 禁用租户 ✅ 已对接

6. 修改租户密码 ✅ 已对接

7. 管理租户权限 ✅ 已对接

8. 供应商申请审批 ✅ 已对接

9. 平台Agent申请审批 ✅ 已对接

10. 保存资源配置 ✅ 已对接

11. 保存渠道编辑 ✅ 已对接

12. 保存佣金修改 ✅ 已对接

13. 创建渠道 ✅ 已对接

14. 添加租户 ✅ 已对接

15. 删除渠道管理员 ⚠️ 部分对接

16. 查看渠道租户资源分配 ✅ 已对接

17. 渠道管理员查看租户资源分配汇总 ✅ 已对接

资源管理模块 (Resources)

数据展示接口

D7. Agent模板列表接口 ✅ 已对接

D8. 模型供应商列表接口 ✅ 已对接

按钮操作接口

16. Agent模板配置-保存 ✅ 已对接

17. Agent模板删除 ❌ 未对接

18. 添加模型供应商 ✅ 已对接

19. 模型供应商配置 ✅ 已对接

20. 模型供应商测试延迟 ✅ 已对接

21. 模型供应商删除 ✅ 已对接

监控模块 (Monitoring)

数据展示接口

D9. Agent健康监控汇总接口 ✅ 已对接

D10. Agent监控接口 ✅ 已对接

计费模块 (Billing)

数据展示接口

D11. 计费概览统计接口 ✅ 已对接

D12. 调用记录明细接口 ❌ 未对接

按钮操作接口

22. 时间查询/筛选 ✅ 已对接

23. 导出计费数据 ❌ 未对接

设置模块 (Settings)

数据展示接口

D13. 管理员列表接口 ✅ 已对接

D14. 角色列表接口 ✅ 已对接

按钮操作接口

24. 添加管理员 ✅ 已对接

25. 删除管理员 ✅ 已对接

26. 保存角色权限配置 ❌ 未对接

接口汇总表

已对接接口汇总

未对接接口清单

建议优先级说明

附录：权限矩阵

接口测试报告

测试环境

测试结果汇总

已修复问题

字段差异说明

登录接口说明

更新日志

v1.0.4 (2026-01-13)

v1.0.1 (2026-01-06)

v1.0.0 (2026-01-06)

42 KiB

Raw Blame History