forked from xiaohei/taiji-AI-PAD
1417 lines
34 KiB
Markdown
1417 lines
34 KiB
Markdown
# 超级管理员控制台 - 接口对接文档
|
||
|
||
> **版本**: v1.0.3
|
||
> **更新时间**: 2026-01-06
|
||
> **说明**: 本文档基于前端业务需求清单与后端API接口清单核实，列出所有超级管理员端接口的对接状态
|
||
> **最新测试**: 2026-01-06 14:54 UTC - 所有已对接接口测试通过
|
||
> **前端代码核对**: 2026-01-06 14:54 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) |
|
||
| **前端状态** | ✅ 已实现 (2026-01-06 修复) |
|
||
| **权限要求** | super_admin |
|
||
|
||
**按钮位置**: 渠道管理页面 → 渠道卡片 → 更多操作菜单 → "删除渠道"
|
||
|
||
**前端调用**: 直接fetch调用 `DELETE ${API_BASE_URLS.mcpServer}/api/admin/channels/${channel.id}`
|
||
|
||
**路径参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| 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健康监控区域 → 汇总统计卡片
|
||
|
||
**实际响应字段** (2026-01-06 14:54 UTC 测试确认):
|
||
```json
|
||
{
|
||
"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格式） |
|
||
|
||
**响应字段**:
|
||
```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个已对接接口
|
||
- 添加权限矩阵说明 |