taiji-AI-PAD/Docs/项目文档/渠道合作伙伴平台-接口对接文档.md

# 渠道合作伙伴平台 - 接口对接文档

> **版本**: v1.0.0
> **更新时间**: 2026-01-06
> **说明**: 本文档基于前端业务需求清单与后端API接口清单核实，列出渠道平台所有接口的对接状态

---

## 目录

1. [接口对接核实总结](#接口对接核实总结)
2. [认证模块](#认证模块)
3. [仪表板模块](#仪表板模块)
4. [租户管理模块](#租户管理模块)
5. [资源管理模块](#资源管理模块)
6. [计费模块](#计费模块)
7. [设置模块](#设置模块)
8. [接口汇总表](#接口汇总表)
9. [待完善功能清单](#待完善功能清单)

---

## 接口对接核实总结

### 核实结果概览

| 分类 | 已对接 | 部分对接 | 待开发 | 总计 |
|------|--------|----------|--------|------|
| 认证模块 | 2 | 0 | 0 | 2 |
| 仪表板模块 | 1 | 1 | 0 | 2 |
| 租户管理模块 | 9 | 0 | 0 | 9 |
| 资源管理模块 | 4 | 0 | 0 | 4 |
| 计费模块 | 3 | 1 | 0 | 4 |
| 设置模块 | 2 | 0 | 1 | 3 |
| **总计** | **21** | **2** | **1** | **24** |

### 核实说明

- ✅ **已对接**: 后端接口已存在且与前端需求匹配
- ⚠️ **部分对接**: 后端接口存在但功能不完整
- ❌ **待开发**: 后端接口不存在，需要新增

---

## 认证模块

### 1. 渠道用户登录 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | 登录页面 → "登录"按钮 |
| **接口路径** | `POST /api/auth/login` |
| **后端文件** | `services/mcp-server/app/routes/auth.py` |
| **权限要求** | 无 |

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| email | string | 是 | 邮箱地址 |
| password | string | 是 | 密码 |
| role | string | 是 | 固定值 `"channel"` |

**响应示例**:

```json
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "channel_001",
      "email": "channel@example.com",
      "role": "channel_admin",
      "name": "渠道管理员"
    }
  }
}
```

**前端调用**: `TaijiAPIClient.login(email, password, "channel")`

**Token存储**: `channel_token` (localStorage + Cookie)

---

### 2. 退出登录 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | 页面头部 → "退出"按钮 |
| **接口路径** | `POST /api/auth/logout` |
| **后端文件** | `services/mcp-server/app/routes/auth.py` |
| **权限要求** | 已认证用户 |

**请求头**:

```
Authorization: Bearer <token>
```

**响应示例**:

```json
{
  "success": true,
  "message": "登出成功"
}
```

**前端调用**: `TaijiAPIClient.logout()`

**前端行为**: 清除所有本地存储的token，跳转到登录页

---

## 仪表板模块

### 3. 渠道统计概览 ⚠️ 部分对接

| 属性 | 值 |
|------|-----|
| **展示位置** | 仪表板页面 → 顶部统计卡片区域 |
| **当前接口** | `GET /api/channel/tenants` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**展示内容**:
- 总租户数（从租户列表计算）✅
- 活跃租户（从租户列表计算）✅
- 月度收入 ❌ 需要专门接口
- 已获佣金 ❌ 需要专门接口

**当前实现**: 从租户列表接口计算总租户数和活跃租户数

**响应示例**:

```json
{
  "success": true,
  "data": {
    "tenants": [
      {
        "id": "tenant_001",
        "name": "租户A",
        "status": "active"
      }
    ]
  }
}
```

**待完善**: 建议后端新增聚合统计接口

```
GET /api/channel/dashboard/stats
```

**建议响应**:

```json
{
  "success": true,
  "data": {
    "totalTenants": 5,
    "activeTenants": 3,
    "monthlyRevenue": 12500.00,
    "commission": 1250.00
  }
}
```

---

### 4. 平台Agent概览 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **展示位置** | 仪表板页面 → "平台Agent概览"区域 |
| **接口路径** | `GET /api/channel/available-platform-agents` |
| **后端文件** | `services/mcp-server/app/routes/platform_agent_quota.py` |
| **权限要求** | channel_admin |

**响应示例**:

```json
{
  "success": true,
  "data": {
    "templates": [
      {
        "name": "gpt-assistant",
        "displayName": "GPT助手",
        "description": "基于GPT的智能助手",
        "podQuota": 10,
        "podRemaining": 8,
        "hasAccess": true
      }
    ]
  }
}
```

**前端调用**: `TaijiAPIClient.getAvailablePlatformAgents()`

---

## 租户管理模块

### 5. 租户列表 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **展示位置** | "我的租户"标签页 → 租户列表 |
| **接口路径** | `GET /api/channel/tenants` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**响应示例**:

```json
{
  "success": true,
  "data": {
    "tenants": [
      {
        "id": "tenant_001",
        "name": "企业A",
        "status": "active",
        "plan": "enterprise",
        "users": 50,
        "revenue": "$3,200",
        "balance": "$1,500",
        "creditLimit": "$5,000"
      }
    ]
  }
}
```

**前端调用**: `TaijiAPIClient.getChannelTenants()`

---

### 6. 创建租户 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | "我的租户"标签页 → "添加租户"按钮 |
| **接口路径** | `POST /api/channel/tenants/create` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 公司名称 |
| email | string | 是 | 联系邮箱（用于登录） |
| password | string | 是 | 登录密码 |
| subscriptionTier | string | 否 | 订阅等级：free/pro/enterprise |

**请求示例**:

```json
{
  "name": "新企业",
  "email": "admin@newcompany.com",
  "password": "SecurePass123",
  "subscriptionTier": "pro"
}
```

**响应示例**:

```json
{
  "success": true,
  "data": {
    "tenant": {
      "id": "tenant_002",
      "name": "新企业",
      "email": "admin@newcompany.com"
    }
  }
}
```

**前端调用**: `TaijiAPIClient.createChannelTenant(data)`

---

### 7. 删除租户 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | 租户列表 → 操作菜单 → "删除租户" |
| **接口路径** | `DELETE /api/channel/tenants/{tenantId}` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| tenantId | string | 租户ID |

**响应示例**:

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

**前端调用**: `TaijiAPIClient.deleteTenant(tenantId)`

---

### 8. 分配资源 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | 租户列表 → 操作菜单 → "分配资源" |
| **接口路径** | `PUT /api/channel/tenants/{tenantId}/resources` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| tenantId | string | 租户ID |

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| agents | array | 否 | Agent配额列表 |
| agents[].agentId | string | 是 | Agent模板名称 |
| agents[].quantity | int | 是 | 分配数量 |
| models | array | 否 | 模型配额列表 |
| models[].modelName | string | 是 | 模型名称（如gpt-4） |
| models[].rpm | int | 是 | 每分钟请求数限制 |
| models[].tpm | int | 是 | 每分钟令牌数限制 |
| customAgentQuota | object | 否 | 自定义Agent资源配额 |
| customAgentQuota.cpuQuota | float | 否 | CPU配额（核数/Agent） |
| customAgentQuota.memoryQuota | float | 否 | 内存配额（GB/Agent） |

**请求示例**:

```json
{
  "agents": [
    {
      "agentId": "gpt-assistant",
      "quantity": 5
    }
  ],
  "models": [
    {
      "modelName": "gpt-4",
      "rpm": 100,
      "tpm": 50000
    }
  ],
  "customAgentQuota": {
    "cpuQuota": 0.5,
    "memoryQuota": 1.0
  }
}
```

**响应示例**:

```json
{
  "success": true,
  "message": "资源分配成功"
}
```

**前端调用**: `TaijiAPIClient.allocateTenantResources(tenantId, data)`

---

### 9. 租户充值 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | 租户列表 → 操作菜单 → "充值" |
| **接口路径** | `POST /api/channel/tenants/{tenantId}/recharge` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| tenantId | string | 租户ID |

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| amount | float | 是 | 充值金额（USD） |

**请求示例**:

```json
{
  "amount": 500.00
}
```

**响应示例**:

```json
{
  "success": true,
  "data": {
    "newBalance": 2000.00
  }
}
```

**前端调用**: `TaijiAPIClient.rechargeTenant(tenantId, amount)`

**快捷金额**: $50, $100, $500, $1000

---

### 10. 设置授信额度 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | 租户列表 → 操作菜单 → "授信额度" |
| **接口路径** | `PUT /api/channel/tenants/{tenantId}/credit` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| tenantId | string | 租户ID |

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| creditLimit | float | 是 | 授信额度（USD） |

**请求示例**:

```json
{
  "creditLimit": 5000.00
}
```

**响应示例**:

```json
{
  "success": true,
  "message": "授信额度设置成功"
}
```

**前端调用**: `TaijiAPIClient.setTenantCreditLimit(tenantId, creditLimit)`

**快捷金额**: $500, $1000, $5000, $10000

---

### 11. 管理计费 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | 租户列表 → 操作菜单 → "管理计费" |
| **接口路径** | `PUT /api/channel/tenants/{tenantId}/billing` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| tenantId | string | 租户ID |

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| subscriptionTier | string | 否 | 订阅层级：free/pro/enterprise |
| discount | int | 否 | 折扣比例（0-100的百分比） |

**请求示例**:

```json
{
  "subscriptionTier": "pro",
  "discount": 10
}
```

**响应示例**:

```json
{
  "success": true,
  "message": "计费设置更新成功"
}
```

**前端调用**: `TaijiAPIClient.updateTenantBilling(tenantId, data)`

**订阅层级说明**:

| 层级 | 价格 | 说明 |
|------|------|------|
| 免费版 (free) | $0/mo | 基础功能 |
| 专业版 (pro) | $1,800/mo | 适合中小企业 |
| 企业版 (enterprise) | $3,200/mo | 无限制 |

---

### 12. 更新租户状态 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | 租户列表 → 操作菜单 → "暂停/启用" |
| **接口路径** | `PUT /api/channel/tenants/{tenantId}/status` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| tenantId | string | 租户ID |

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | string | 是 | 状态：active/suspended |

**请求示例**:

```json
{
  "status": "suspended"
}
```

**响应示例**:

```json
{
  "success": true,
  "message": "租户状态更新成功"
}
```

**前端调用**: `TaijiAPIClient.updateTenantStatus(tenantId, status)`

---

### 13. 更新租户权限 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | 租户详情 → 权限设置 |
| **接口路径** | `PUT /api/channel/tenants/{tenantId}/permissions` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| tenantId | 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", "create:agents", "read:billing", "export:data"]
}
```

**响应示例**:

```json
{
  "success": true,
  "message": "租户权限更新成功"
}
```

**前端调用**: `TaijiAPIClient.updateTenantPermissions(tenantId, permissions)`

---

## 资源管理模块

### 14. 平台Agent模板列表 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **展示位置** | "资源管理"标签页 → "平台Agent模板"区域 |
| **接口路径** | `GET /api/channel/available-platform-agents` |
| **后端文件** | `services/mcp-server/app/routes/platform_agent_quota.py` |
| **权限要求** | channel_admin |

**响应示例**:

```json
{
  "success": true,
  "data": {
    "templates": [
      {
        "name": "gpt-assistant",
        "displayName": "GPT助手",
        "description": "基于GPT的智能助手",
        "status": "available",
        "hasAccess": true,
        "pendingApplication": false,
        "cpuRequest": "100m",
        "cpuLimit": "500m",
        "memoryRequest": "128Mi",
        "memoryLimit": "512Mi",
        "podQuota": 10,
        "podUsed": 2,
        "podRemaining": 8
      }
    ]
  }
}
```

**前端调用**: `TaijiAPIClient.getAvailablePlatformAgents()`

---

### 15. 模型供应商列表 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **展示位置** | "资源管理"标签页 → "模型管理"区域 |
| **接口路径** | `GET /api/channel/providers` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**响应示例**:

```json
{
  "success": true,
  "data": {
    "providers": [
      {
        "id": "provider_001",
        "name": "OpenAI",
        "provider": "openai",
        "hasAccess": true,
        "pendingApplication": false,
        "supportedModels": ["gpt-4", "gpt-3.5-turbo"],
        "rpm": 1000,
        "tpm": 100000
      }
    ]
  }
}
```

**前端调用**: `TaijiAPIClient.getChannelProviders()`

---

### 16. 申请平台Agent配额 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | Agent模板卡片 → "申请使用"/"申请更多配额"按钮 |
| **接口路径** | `POST /api/channel/applications/platform-agents` |
| **后端文件** | `services/mcp-server/app/routes/platform_agent_quota.py` |
| **权限要求** | channel_admin |

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| templateName | string | 是 | Agent模板名称 |
| requestedPodQuota | int | 是 | 申请的Pod配额数量 |
| reason | string | 是 | 申请理由 |

**请求示例**:

```json
{
  "templateName": "gpt-assistant",
  "requestedPodQuota": 10,
  "reason": "业务扩展需要更多Agent实例"
}
```

**响应示例**:

```json
{
  "success": true,
  "data": {
    "applicationId": "app_001"
  },
  "message": "申请已提交，等待审批"
}
```

**前端调用**: `TaijiAPIClient.applyForPlatformAgent(data)`

---

### 17. 申请模型供应商使用权限 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | 模型供应商卡片 → "申请使用"按钮 |
| **接口路径** | `POST /api/channel/providers/apply` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| providerId | string | 是 | 供应商ID |
| requestedRpm | int | 否 | 申请的RPM配额 |
| requestedTpm | int | 否 | 申请的TPM配额 |
| reason | string | 是 | 申请理由 |

**请求示例**:

```json
{
  "providerId": "provider_001",
  "requestedRpm": 500,
  "requestedTpm": 50000,
  "reason": "需要使用OpenAI模型服务"
}
```

**响应示例**:

```json
{
  "success": true,
  "data": {
    "applicationId": "app_002"
  },
  "message": "申请已提交，等待审批"
}
```

**前端调用**: `TaijiAPIClient.applyForProvider(data)`

---

## 计费模块

### 18. 租户计费统计 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **展示位置** | "计费"标签页 → "租户计费统计"区域 |
| **接口路径** | `GET /api/channel/billing/stats` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**查询参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| startTime | string | 是 | 开始时间（ISO 8601格式） |
| endTime | string | 是 | 结束时间（ISO 8601格式） |
| tenantName | string | 否 | 租户名称筛选 |
| minCalls | int | 否 | 最小调用次数 |
| maxCalls | int | 否 | 最大调用次数 |
| export | string | 否 | 导出格式：excel/csv/pdf |

**请求示例**:

```
GET /api/channel/billing/stats?startTime=2026-01-01T00:00:00Z&endTime=2026-01-31T23:59:59Z
```

**响应示例**:

```json
{
  "success": true,
  "data": {
    "tenantStats": [
      {
        "tenantId": "tenant_001",
        "tenantName": "企业A",
        "calls": 1500,
        "totalEU": 150.5,
        "totalCost": 450.00
      }
    ],
    "callRecords": [
      {
        "timestamp": "2026-01-15T10:30:00Z",
        "tenantName": "企业A",
        "agentType": "gpt-assistant",
        "duration": 120,
        "eu": 12.0,
        "price": 36.00
      }
    ]
  }
}
```

**前端调用**: `TaijiAPIClient.getChannelBillingStats(params)`

**默认范围**: 最近30天

---

### 19. 时间范围查询 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | "计费"标签页 → "时间查询"按钮 |
| **接口路径** | `GET /api/channel/billing/stats` |
| **说明** | 通过 `startTime` 和 `endTime` 参数实现 |

---

### 20. 筛选功能 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | "计费"标签页 → "筛选"按钮 |
| **接口路径** | `GET /api/channel/billing/stats` |
| **说明** | 通过查询参数实现筛选 |

**筛选条件**:
- 客户名称（tenantName）
- 最小调用次数（minCalls）
- 最大调用次数（maxCalls）

---

### 21. 数据导出 ⚠️ 部分对接

| 属性 | 值 |
|------|-----|
| **触发位置** | "计费"标签页 → "导出"按钮 |
| **接口路径** | `GET /api/channel/billing/stats` |
| **说明** | 通过 `export` 参数实现 |

**支持格式**:
- Excel (.xlsx)
- CSV (.csv)
- PDF (.pdf)

**待完善**: 后端需要支持生成并返回文件下载链接或文件流

---

## 设置模块

### 22. 管理员列表 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **展示位置** | "设置"标签页 → "当前管理员列表"区域 |
| **接口路径** | `GET /api/channel/admins` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**响应示例**:

```json
{
  "success": true,
  "data": {
    "admins": [
      {
        "id": "admin_001",
        "name": "张三",
        "email": "zhangsan@example.com",
        "role": "channel_admin",
        "status": "active"
      },
      {
        "id": "admin_002",
        "name": "李四",
        "email": "lisi@example.com",
        "role": "billing_admin",
        "status": "active"
      }
    ]
  }
}
```

**前端调用**: `TaijiAPIClient.getChannelAdmins()`

---

### 23. 创建管理员 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | "设置"标签页 → "添加管理员"按钮 |
| **接口路径** | `POST /api/channel/admins/create` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin |

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 管理员姓名 |
| email | string | 是 | 登录邮箱 |
| password | string | 是 | 登录密码 |
| role | string | 是 | 角色：billing_admin/operations_admin |

**请求示例**:

```json
{
  "name": "王五",
  "email": "wangwu@example.com",
  "password": "SecurePass123",
  "role": "billing_admin"
}
```

**响应示例**:

```json
{
  "success": true,
  "data": {
    "admin": {
      "id": "admin_003",
      "name": "王五",
      "email": "wangwu@example.com",
      "role": "billing_admin"
    }
  }
}
```

**前端调用**: `TaijiAPIClient.createChannelAdmin(data)`

---

### 24. 删除管理员 ✅ 已对接

| 属性 | 值 |
|------|-----|
| **触发位置** | 管理员列表 → 删除按钮 |
| **接口路径** | `DELETE /api/admin/admins/{adminId}` |
| **后端文件** | `services/mcp-server/app/routes/admin.py` |
| **权限要求** | super_admin |

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| adminId | string | 管理员ID |

**响应示例**:

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

**前端调用**: `TaijiAPIClient.deleteAdmin(adminId)`

**注意**: 此接口使用的是 `/api/admin/admins/{adminId}` 路径，需要 super_admin 权限。前端需求文档中标注为已对接，但实际上渠道管理员可能无法直接调用此接口，需要确认权限配置。

---

### 25. 配置角色权限 ❌ 待开发

| 属性 | 值 |
|------|-----|
| **触发位置** | "设置"标签页 → 角色卡片 → "配置权限"按钮 |
| **建议接口** | `PUT /api/channel/roles/{roleId}/permissions` |
| **状态** | 后端接口不存在 |

**功能描述**: 设置不同角色可访问的功能模块

**可配置模块**:
- 概览（overview）
- 租户管理（tenants）
- 资源管理（resources）
- 计费（billing）
- 设置（settings）

**默认角色权限**:

| 角色 | 默认权限 |
|------|----------|
| 计费管理员 | overview, tenants, billing |
| 运营管理员 | overview, tenants, resources |

**当前实现**: 权限配置仅在前端状态管理

**建议请求参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| permissions | array | 权限列表（如 ["overview", "tenants", "billing"]） |

**建议请求示例**:

```json
{
  "permissions": ["overview", "tenants", "billing"]
}
```

---

## 接口汇总表

### 认证相关接口

| 序号 | 接口 | 方法 | 路径 | 状态 | 说明 |
|------|------|------|------|------|------|
| 1 | 登录 | POST | `/api/auth/login` | ✅ 已对接 | 用户登录 |
| 2 | 登出 | POST | `/api/auth/logout` | ✅ 已对接 | 用户登出 |

### 仪表板相关接口

| 序号 | 接口 | 方法 | 路径 | 状态 | 说明 |
|------|------|------|------|------|------|
| 3 | 渠道统计 | GET | `/api/channel/tenants` | ⚠️ 部分对接 | 当前从租户列表计算，建议新增聚合接口 |
| 4 | 平台Agent概览 | GET | `/api/channel/available-platform-agents` | ✅ 已对接 | 可用Agent模板 |

### 租户管理相关接口

| 序号 | 接口 | 方法 | 路径 | 状态 | 说明 |
|------|------|------|------|------|------|
| 5 | 获取租户列表 | GET | `/api/channel/tenants` | ✅ 已对接 | 获取渠道下所有租户 |
| 6 | 创建租户 | POST | `/api/channel/tenants/create` | ✅ 已对接 | 创建新租户 |
| 7 | 删除租户 | DELETE | `/api/channel/tenants/{tenantId}` | ✅ 已对接 | 删除租户 |
| 8 | 分配资源 | PUT | `/api/channel/tenants/{tenantId}/resources` | ✅ 已对接 | 分配Agent和模型资源 |
| 9 | 充值 | POST | `/api/channel/tenants/{tenantId}/recharge` | ✅ 已对接 | 为租户充值 |
| 10 | 设置授信 | PUT | `/api/channel/tenants/{tenantId}/credit` | ✅ 已对接 | 设置授信额度 |
| 11 | 更新计费 | PUT | `/api/channel/tenants/{tenantId}/billing` | ✅ 已对接 | 更新计费设置 |
| 12 | 更新状态 | PUT | `/api/channel/tenants/{tenantId}/status` | ✅ 已对接 | 更新租户状态 |
| 13 | 更新权限 | PUT | `/api/channel/tenants/{tenantId}/permissions` | ✅ 已对接 | 更新租户权限 |

### 资源管理相关接口

| 序号 | 接口 | 方法 | 路径 | 状态 | 说明 |
|------|------|------|------|------|------|
| 14 | 获取平台Agent | GET | `/api/channel/available-platform-agents` | ✅ 已对接 | 获取可用Agent模板 |
| 15 | 获取供应商列表 | GET | `/api/channel/providers` | ✅ 已对接 | 获取可用模型供应商 |
| 16 | 申请Agent配额 | POST | `/api/channel/applications/platform-agents` | ✅ 已对接 | 申请Agent配额 |
| 17 | 申请供应商 | POST | `/api/channel/providers/apply` | ✅ 已对接 | 申请使用供应商 |

### 计费统计相关接口

| 序号 | 接口 | 方法 | 路径 | 状态 | 说明 |
|------|------|------|------|------|------|
| 18 | 获取计费统计 | GET | `/api/channel/billing/stats` | ✅ 已对接 | 获取租户计费统计 |
| 19 | 时间范围查询 | GET | `/api/channel/billing/stats` | ✅ 已对接 | 通过参数实现 |
| 20 | 筛选功能 | GET | `/api/channel/billing/stats` | ✅ 已对接 | 通过参数实现 |
| 21 | 数据导出 | GET | `/api/channel/billing/stats` | ⚠️ 部分对接 | 需要后端支持文件生成 |

### 管理员管理相关接口

| 序号 | 接口 | 方法 | 路径 | 状态 | 说明 |
|------|------|------|------|------|------|
| 22 | 获取管理员列表 | GET | `/api/channel/admins` | ✅ 已对接 | 获取渠道管理员 |
| 23 | 创建管理员 | POST | `/api/channel/admins/create` | ✅ 已对接 | 创建管理员 |
| 24 | 删除管理员 | DELETE | `/api/admin/admins/{adminId}` | ✅ 已对接 | 删除管理员（需super_admin权限） |
| 25 | 配置角色权限 | PUT | `/api/channel/roles/{roleId}/permissions` | ❌ 待开发 | 配置角色权限 |

---

## 待完善功能清单

### 高优先级

| 序号 | 需求 | 说明 | 建议接口 |
|------|------|------|----------|
| 1 | 渠道仪表板统计 | 需要专门的聚合接口返回月度收入、佣金等统计数据 | `GET /api/channel/dashboard/stats` |
| 2 | 数据导出功能 | 计费数据导出需要后端支持生成Excel/CSV/PDF文件 | 修改 `/api/channel/billing/stats` 支持文件流返回 |

### 中优先级

| 序号 | 需求 | 说明 | 建议接口 |
|------|------|------|----------|
| 3 | 角色权限配置 | 当前权限配置仅在前端状态管理，需要后端接口持久化 | `PUT /api/channel/roles/{roleId}/permissions` |
| 4 | 权限验证 | 后端需要根据角色权限控制API访问 | 中间件实现 |

### 低优先级

| 序号 | 需求 | 说明 | 建议接口 |
|------|------|------|----------|
| 5 | 删除管理员权限调整 | 当前使用admin接口，建议增加channel专用接口 | `DELETE /api/channel/admins/{adminId}` |

---

## 后端接口与前端需求对照表

以下是后端 [`channel.py`](services/mcp-server/app/routes/channel.py) 中已实现的所有接口与前端需求的对照：

| 后端接口 | 前端是否使用 | 说明 |
|----------|--------------|------|
| `GET /api/channel/tenants` | ✅ 使用 | 租户列表 |
| `POST /api/channel/tenants/create` | ✅ 使用 | 创建租户 |
| `PUT /api/channel/tenants/{tenant_id}/resources` | ✅ 使用 | 分配资源 |
| `PUT /api/channel/tenants/{tenant_id}/billing` | ✅ 使用 | 管理计费 |
| `POST /api/channel/tenants/{tenant_id}/recharge` | ✅ 使用 | 租户充值 |
| `PUT /api/channel/tenants/{tenant_id}/credit` | ✅ 使用 | 设置授信 |
| `DELETE /api/channel/tenants/{tenant_id}` | ✅ 使用 | 删除租户 |
| `PUT /api/channel/tenants/{tenant_id}/status` | ✅ 使用 | 更新状态 |
| `PUT /api/channel/tenants/{tenant_id}/permissions` | ✅ 使用 | 更新权限 |
| `PUT /api/channel/tenants/{tenant_id}/password` | ❓ 未明确 | 重置密码（前端需求未提及） |
| `GET /api/channel/tenants/{tenant_id}/custom-agent-quota` | ❓ 未明确 | 获取自定义Agent配额 |
| `POST /api/channel/admins/create` | ✅ 使用 | 创建管理员 |
| `GET /api/channel/admins` | ✅ 使用 | 管理员列表 |
| `POST /api/channel/resources/apply` | ❓ 未明确 | 申请资源（前端可能使用其他接口） |
| `GET /api/channel/billing/stats` | ✅ 使用 | 计费统计 |
| `GET /api/channel/providers` | ✅ 使用 | 供应商列表 |
| `POST /api/channel/providers/apply` | ✅ 使用 | 申请供应商 |
| `GET /api/channel/providers/applications` | ✅ 使用 | 供应商申请列表 |
| `GET /api/channel/providers/access` | ❓ 未明确 | 已授权供应商列表 |
| `GET /api/channel/available-platform-agents` | ✅ 使用 | 平台Agent模板 |
| `POST /api/channel/applications/platform-agents` | ✅ 使用 | 申请Agent配额 |
| `GET /api/channel/applications/platform-agents` | ✅ 使用 | Agent申请列表 |
| `GET /api/channel/platform-agents` | ❓ 未明确 | 渠道Agent配额 |
| `POST /api/channel/tenants/{tenant_id}/platform-agents` | ❓ 未明确 | 分配Agent给租户 |
| `GET /api/channel/tenants/{tenant_id}/platform-agents/usage` | ❓ 未明确 | 租户Agent使用情况 |
| `GET /api/channel/agent-billing/stats` | ❓ 未明确 | Agent计费统计 |
| `GET /api/channel/agent-billing/history` | ❓ 未明确 | Agent计费历史 |
| `GET /api/channel/agent-billing/tenant-summary` | ❓ 未明确 | 租户Agent计费汇总 |

---

## 数据模型参考

### 租户数据结构

```typescript
interface Tenant {
  id: string
  name: string
  email: string
  status: "active" | "suspended" | "inactive"
  plan: "enterprise" | "pro" | "starter" | "free"
  users: number
  revenue: string  // 如 "$3,200"
  balance?: string
  creditLimit?: string
  createdAt?: string
}
```

### Agent资源数据结构

```typescript
interface AgentResource {
  id: string
  name: string
  displayName?: string
  description?: string
  status: "available" | "unavailable" | "Running" | "Pending"
  hasAccess: boolean
  pendingApplication?: boolean
  cpuRequest?: string   // K8s格式，如 "100m"
  cpuLimit?: string     // K8s格式，如 "500m"
  memoryRequest?: string // K8s格式，如 "128Mi"
  memoryLimit?: string   // K8s格式，如 "512Mi"
  podQuota?: number
  podUsed?: number
  podRemaining?: number
}
```

### 模型供应商数据结构

```typescript
interface ModelProvider {
  id: string
  name: string
  provider?: string  // openai, anthropic等
  type?: string
  hasAccess: boolean
  pendingApplication?: boolean
  supportedModels?: string[]
  rpm: number
  tpm: number
}
```

### 计费统计数据结构

```typescript
interface BillingStats {
  tenantStats: Array<{
    tenantId: string
    tenantName: string
    calls: number
    totalEU: number
    totalCost: number
  }>
  callRecords: Array<{
    timestamp: string
    tenantName: string
    agentType: string
    duration: number  // 秒
    eu: number
    price: number
  }>
}
```

### 管理员数据结构

```typescript
interface ChannelAdmin {
  id: string
  name: string
  email: string
  role: "channel_admin" | "billing_admin" | "operations_admin"
  status?: "active" | "inactive"
}
```

---

## 错误码说明

| 错误码 | HTTP状态码 | 说明 |
|--------|------------|------|
| AUTH_FAILED | 401 | 认证失败 |
| TOKEN_EXPIRED | 401 | Token已过期 |
| PERMISSION_DENIED | 403 | 权限不足 |
| NOT_FOUND | 404 | 资源不存在 |
| VALIDATION_ERROR | 400 | 参数验证失败 |
| QUOTA_EXCEEDED | 400 | 配额超限 |
| DUPLICATE_ENTRY | 409 | 重复数据 |
| INTERNAL_ERROR | 500 | 服务器内部错误 |

---

## 前端源文件参考

| 文件路径 | 说明 |
|----------|------|
| `app/channel/dashboard/page.tsx` | 渠道仪表板主页面 |
| `app/channel/login/page.tsx` | 渠道登录页面 |
| `app/channel/layout.tsx` | 渠道布局组件 |
| `lib/api-client.ts` | API客户端封装 |

---

## 后端源文件参考

| 文件路径 | 说明 |
|----------|------|
| [`services/mcp-server/app/routes/auth.py`](services/mcp-server/app/routes/auth.py) | 认证模块 |
| [`services/mcp-server/app/routes/channel.py`](services/mcp-server/app/routes/channel.py) | 渠道合作伙伴API |
| [`services/mcp-server/app/routes/platform_agent_quota.py`](services/mcp-server/app/routes/platform_agent_quota.py) | 平台Agent配额管理 |
| [`services/mcp-server/app/routes/admin.py`](services/mcp-server/app/routes/admin.py) | 超级管理员API |

---

*文档生成时间: 2026-01-06*
*基于前端需求清单 v1.2.0 与后端API清单核实*