forked from xiaohei/taiji-AI-PAD
1010 lines
27 KiB
Markdown
1010 lines
27 KiB
Markdown
# 渠道合作伙伴平台 - 后端接口需求清单
|
||
|
||
> **版本**: v1.2.0
|
||
> **更新时间**: 2026-01-06
|
||
> **说明**: 本文档基于前端业务逻辑分析，列出所有后端接口需求，包括已对接接口和未对接接口，按钮操作接口和数据展示接口
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [认证模块 (Authentication)](#认证模块-authentication)
|
||
2. [仪表板模块 (Dashboard/Overview)](#仪表板模块-dashboardoverview)
|
||
3. [租户管理模块 (My Tenants)](#租户管理模块-my-tenants)
|
||
4. [资源管理模块 (Resource Management)](#资源管理模块-resource-management)
|
||
5. [计费模块 (Billing)](#计费模块-billing)
|
||
6. [设置模块 (Settings)](#设置模块-settings)
|
||
7. [附录：接口汇总表](#附录接口汇总表)
|
||
|
||
---
|
||
|
||
## 认证模块 (Authentication)
|
||
|
||
### 按钮操作接口
|
||
|
||
#### B1. 渠道用户登录 ✅ 已对接
|
||
|
||
**触发位置**: 登录页面 → "登录"按钮
|
||
|
||
**功能描述**: 渠道合作伙伴通过邮箱和密码登录系统
|
||
|
||
**接口**:
|
||
```
|
||
POST /api/auth/login
|
||
```
|
||
|
||
**请求参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| email | string | 是 | 邮箱地址 |
|
||
| password | string | 是 | 密码 |
|
||
| role | string | 是 | 固定值 "channel" |
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| data.token | string | 认证令牌 |
|
||
| data.refreshToken | string | 刷新令牌 |
|
||
| data.user | object | 用户信息 |
|
||
|
||
**前端调用**: `TaijiAPIClient.login(email, password, "channel")`
|
||
|
||
**Token存储**: `channel_token` (localStorage + Cookie)
|
||
|
||
---
|
||
|
||
#### B2. 退出登录 ✅ 已对接
|
||
|
||
**触发位置**: 页面头部 → "退出"按钮
|
||
|
||
**功能描述**: 清除认证状态，退出系统
|
||
|
||
**接口**:
|
||
```
|
||
POST /api/auth/logout
|
||
```
|
||
|
||
**前端调用**: `TaijiAPIClient.logout()`
|
||
|
||
**前端行为**: 清除所有本地存储的token，跳转到登录页
|
||
|
||
---
|
||
|
||
## 仪表板模块 (Dashboard/Overview)
|
||
|
||
### 数据展示接口
|
||
|
||
#### D1. 渠道统计概览 ⚠️ 部分对接
|
||
|
||
**展示位置**: 仪表板页面 → 顶部统计卡片区域
|
||
|
||
**展示内容**:
|
||
- 总租户数（如：5）
|
||
- 活跃租户（如：3）
|
||
- 月度收入（如：$12,500）
|
||
- 已获佣金（如：$1,250）
|
||
|
||
**功能描述**: 获取渠道的核心业务指标统计
|
||
|
||
**当前实现**: 从租户列表接口计算总租户数和活跃租户数
|
||
|
||
**接口**:
|
||
```
|
||
GET /api/channel/tenants
|
||
```
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| data.tenants | array | 租户列表 |
|
||
| data.tenants[].status | string | 租户状态（用于计算活跃数） |
|
||
|
||
**前端调用**: `TaijiAPIClient.getChannelTenants()`
|
||
|
||
**待完善**:
|
||
- ❌ 月度收入统计（monthlyRevenue）- 需要后端提供专门接口
|
||
- ❌ 佣金统计（commission）- 需要后端提供专门接口
|
||
|
||
**建议新增接口**:
|
||
```
|
||
GET /api/channel/dashboard/stats
|
||
```
|
||
|
||
**建议响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| data.totalTenants | int | 总租户数 |
|
||
| data.activeTenants | int | 活跃租户数 |
|
||
| data.monthlyRevenue | float | 月度收入 |
|
||
| data.commission | float | 累计佣金 |
|
||
|
||
---
|
||
|
||
#### D2. 平台Agent概览 ✅ 已对接
|
||
|
||
**展示位置**: 仪表板页面 → "平台Agent概览"区域
|
||
|
||
**展示内容**:
|
||
- Agent名称（如：gpt-assistant）
|
||
- Agent描述
|
||
- 可用配额（如：10）
|
||
- 授权状态（已授权/未授权）
|
||
|
||
**功能描述**: 展示渠道可分配给租户的Agent资源列表
|
||
|
||
**接口**:
|
||
```
|
||
GET /api/channel/available-platform-agents
|
||
```
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| data.templates | array | Agent模板列表 |
|
||
| data.templates[].name | string | 模板名称 |
|
||
| data.templates[].displayName | string | 显示名称 |
|
||
| data.templates[].description | string | 描述 |
|
||
| data.templates[].podQuota | int | Pod配额 |
|
||
| data.templates[].podRemaining | int | 剩余配额 |
|
||
| data.templates[].hasAccess | bool | 是否已授权 |
|
||
|
||
**前端调用**: `TaijiAPIClient.getAvailablePlatformAgents()`
|
||
|
||
---
|
||
|
||
## 租户管理模块 (My Tenants)
|
||
|
||
### 数据展示接口
|
||
|
||
#### D3. 租户列表 ✅ 已对接
|
||
|
||
**展示位置**: "我的租户"标签页 → 租户列表
|
||
|
||
**展示内容**:
|
||
- 租户名称
|
||
- 状态（活跃/已暂停）
|
||
- 方案（企业版/专业版/入门版）
|
||
- 用户数
|
||
- 月收入
|
||
|
||
**功能描述**: 展示该渠道下所有租户的基本信息
|
||
|
||
**接口**:
|
||
```
|
||
GET /api/channel/tenants
|
||
```
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| data.tenants | array | 租户列表 |
|
||
| data.tenants[].id | string | 租户ID |
|
||
| data.tenants[].name | string | 租户名称 |
|
||
| data.tenants[].status | string | 状态：active/suspended |
|
||
| data.tenants[].plan | string | 方案：enterprise/professional/starter |
|
||
| data.tenants[].users | int | 用户数 |
|
||
| data.tenants[].revenue | string | 月收入（如 "$3,200"） |
|
||
| data.tenants[].balance | string | 余额 |
|
||
| data.tenants[].creditLimit | string | 授信额度 |
|
||
|
||
**前端调用**: `TaijiAPIClient.getChannelTenants()`
|
||
|
||
---
|
||
|
||
### 按钮操作接口
|
||
|
||
#### B3. 创建租户 ✅ 已对接
|
||
|
||
**触发位置**: "我的租户"标签页 → "添加租户"按钮
|
||
|
||
**功能描述**: 渠道为其客户创建新的租户账号
|
||
|
||
**接口**:
|
||
```
|
||
POST /api/channel/tenants/create
|
||
```
|
||
|
||
**请求参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| name | string | 是 | 公司名称 |
|
||
| email | string | 是 | 联系邮箱（用于登录） |
|
||
| password | string | 是 | 登录密码 |
|
||
| subscriptionTier | string | 否 | 订阅等级：free/pro/enterprise |
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| data.tenant | object | 创建的租户信息 |
|
||
| data.tenant.id | string | 租户ID |
|
||
|
||
**前端调用**: `TaijiAPIClient.createChannelTenant(data)`
|
||
|
||
**备注**: 前端锁定为"租户"角色，避免渠道自行调整权限
|
||
|
||
---
|
||
|
||
#### B4. 查看租户详情 ✅ 已对接（前端展示）
|
||
|
||
**触发位置**: 租户列表 → 操作菜单 → "查看详情"
|
||
|
||
**功能描述**: 查看租户的详细信息
|
||
|
||
**当前实现**: 使用租户列表中的数据展示，无需额外接口
|
||
|
||
**展示字段**:
|
||
- 租户名称
|
||
- 状态
|
||
- 方案
|
||
- 用户数
|
||
- 月度收入
|
||
- 创建时间
|
||
|
||
---
|
||
|
||
#### B5. 删除租户 ✅ 已对接
|
||
|
||
**触发位置**: 租户列表 → 操作菜单 → "删除租户"
|
||
|
||
**功能描述**: 删除指定租户及其所有数据（软删除）
|
||
|
||
**接口**:
|
||
```
|
||
DELETE /api/channel/tenants/{tenantId}
|
||
```
|
||
|
||
**路径参数**:
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| tenantId | string | 租户ID |
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| message | string | 操作结果消息 |
|
||
|
||
**前端调用**: `TaijiAPIClient.deleteTenant(tenantId)`
|
||
|
||
**确认机制**: 二次确认弹窗，显示租户信息和警告提示
|
||
|
||
---
|
||
|
||
#### B6. 分配资源 ✅ 已对接
|
||
|
||
**触发位置**: 租户列表 → 操作菜单 → "分配资源"
|
||
|
||
**功能描述**: 为租户分配Agent配额和模型配额
|
||
|
||
**接口**:
|
||
```
|
||
PUT /api/channel/tenants/{tenantId}/resources
|
||
```
|
||
|
||
**路径参数**:
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| 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） |
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| message | string | 操作结果消息 |
|
||
|
||
**前端调用**: `TaijiAPIClient.allocateTenantResources(tenantId, data)`
|
||
|
||
---
|
||
|
||
#### B7. 租户充值 ✅ 已对接
|
||
|
||
**触发位置**: 租户列表 → 操作菜单 → "充值"
|
||
|
||
**功能描述**: 为租户账户充值余额
|
||
|
||
**接口**:
|
||
```
|
||
POST /api/channel/tenants/{tenantId}/recharge
|
||
```
|
||
|
||
**路径参数**:
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| tenantId | string | 租户ID |
|
||
|
||
**请求参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| amount | float | 是 | 充值金额（USD） |
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| data.newBalance | float | 充值后余额 |
|
||
|
||
**前端调用**: `TaijiAPIClient.rechargeTenant(tenantId, amount)`
|
||
|
||
**快捷金额**: $50, $100, $500, $1000
|
||
|
||
---
|
||
|
||
#### B8. 设置授信额度 ✅ 已对接
|
||
|
||
**触发位置**: 租户列表 → 操作菜单 → "授信额度"
|
||
|
||
**功能描述**: 允许租户在余额不足时继续使用服务
|
||
|
||
**接口**:
|
||
```
|
||
PUT /api/channel/tenants/{tenantId}/credit
|
||
```
|
||
|
||
**路径参数**:
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| tenantId | string | 租户ID |
|
||
|
||
**请求参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| creditLimit | float | 是 | 授信额度（USD） |
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| message | string | 操作结果消息 |
|
||
|
||
**前端调用**: `TaijiAPIClient.setTenantCreditLimit(tenantId, creditLimit)`
|
||
|
||
**快捷金额**: $500, $1000, $5000, $10000
|
||
|
||
---
|
||
|
||
#### B9. 管理计费 ✅ 已对接
|
||
|
||
**触发位置**: 租户列表 → 操作菜单 → "管理计费"
|
||
|
||
**功能描述**: 设置租户的订阅层级和折扣比例
|
||
|
||
**接口**:
|
||
```
|
||
PUT /api/channel/tenants/{tenantId}/billing
|
||
```
|
||
|
||
**路径参数**:
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| tenantId | string | 租户ID |
|
||
|
||
**请求参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| subscriptionTier | string | 否 | 订阅层级：free/professional/enterprise |
|
||
| discount | int | 否 | 折扣比例（0-100的百分比） |
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| message | string | 操作结果消息 |
|
||
|
||
**前端调用**: `TaijiAPIClient.updateTenantBilling(tenantId, data)`
|
||
|
||
**订阅层级说明**:
|
||
| 层级 | 价格 | 说明 |
|
||
|------|------|------|
|
||
| 免费版 (free) | $0/mo | 基础功能 |
|
||
| 专业版 (professional) | $1,800/mo | 适合中小企业 |
|
||
| 企业版 (enterprise) | $3,200/mo | 无限制 |
|
||
|
||
---
|
||
|
||
## 资源管理模块 (Resource Management)
|
||
|
||
### 数据展示接口
|
||
|
||
#### D4. 平台Agent模板列表 ✅ 已对接
|
||
|
||
**展示位置**: "资源管理"标签页 → "平台Agent模板"区域
|
||
|
||
**展示内容**:
|
||
- Agent名称和显示名称
|
||
- 描述
|
||
- 状态（可用/不可用）
|
||
- 授权状态（已授权/未授权）
|
||
- CPU配置（cpuRequest / cpuLimit）
|
||
- 内存配置（memoryRequest / memoryLimit）
|
||
- Pod配额信息（配额/已使用/剩余）
|
||
|
||
**功能描述**: 展示渠道可用的平台Agent模板及其资源配置
|
||
|
||
**接口**:
|
||
```
|
||
GET /api/channel/available-platform-agents
|
||
```
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| data.templates | array | Agent模板列表 |
|
||
| data.templates[].name | string | 模板名称 |
|
||
| data.templates[].displayName | string | 显示名称 |
|
||
| data.templates[].description | string | 描述 |
|
||
| data.templates[].status | string | 状态：available/unavailable |
|
||
| data.templates[].hasAccess | bool | 是否已授权 |
|
||
| data.templates[].pendingApplication | bool | 是否有待审批的申请 |
|
||
| data.templates[].cpuRequest | string | CPU请求量（如 "100m"） |
|
||
| data.templates[].cpuLimit | string | CPU上限（如 "500m"） |
|
||
| data.templates[].memoryRequest | string | 内存请求量（如 "128Mi"） |
|
||
| data.templates[].memoryLimit | string | 内存上限（如 "512Mi"） |
|
||
| data.templates[].podQuota | int | Pod配额 |
|
||
| data.templates[].podUsed | int | 已使用Pod数 |
|
||
| data.templates[].podRemaining | int | 剩余Pod数 |
|
||
|
||
**前端调用**: `TaijiAPIClient.getAvailablePlatformAgents()`
|
||
|
||
---
|
||
|
||
#### D5. 模型供应商列表 ✅ 已对接
|
||
|
||
**展示位置**: "资源管理"标签页 → "模型管理"区域
|
||
|
||
**展示内容**:
|
||
- 供应商名称
|
||
- 供应商类型（openai, anthropic等）
|
||
- 授权状态（已授权/未授权）
|
||
- 支持模型数
|
||
- 授权RPM
|
||
- 授权TPM
|
||
|
||
**功能描述**: 展示渠道可用的模型供应商及授权状态
|
||
|
||
**接口**:
|
||
```
|
||
GET /api/channel/providers
|
||
```
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| data.providers | array | 供应商列表 |
|
||
| data.providers[].id | string | 供应商ID |
|
||
| data.providers[].name | string | 供应商名称 |
|
||
| data.providers[].provider | string | 供应商类型 |
|
||
| data.providers[].hasAccess | bool | 是否已授权 |
|
||
| data.providers[].pendingApplication | bool | 是否有待审批的申请 |
|
||
| data.providers[].supportedModels | array | 支持的模型列表 |
|
||
| data.providers[].rpm | int | 授权RPM |
|
||
| data.providers[].tpm | int | 授权TPM |
|
||
|
||
**前端调用**: `TaijiAPIClient.getChannelProviders()`
|
||
|
||
---
|
||
|
||
### 按钮操作接口
|
||
|
||
#### B10. 申请平台Agent配额 ✅ 已对接
|
||
|
||
**触发位置**: Agent模板卡片 → "申请使用"/"申请更多配额"按钮
|
||
|
||
**功能描述**: 向超级管理员申请使用平台Agent资源
|
||
|
||
**接口**:
|
||
```
|
||
POST /api/channel/applications/platform-agents
|
||
```
|
||
|
||
**请求参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| templateName | string | 是 | Agent模板名称 |
|
||
| requestedPodQuota | int | 是 | 申请的Pod配额数量 |
|
||
| reason | string | 是 | 申请理由 |
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| data.applicationId | string | 申请ID |
|
||
| message | string | 操作结果消息 |
|
||
|
||
**前端调用**: `TaijiAPIClient.applyForPlatformAgent(data)`
|
||
|
||
---
|
||
|
||
#### B11. 申请模型供应商使用权限 ✅ 已对接
|
||
|
||
**触发位置**: 模型供应商卡片 → "申请使用"按钮
|
||
|
||
**功能描述**: 向超级管理员申请使用模型供应商资源
|
||
|
||
**接口**:
|
||
```
|
||
POST /api/channel/providers/apply
|
||
```
|
||
|
||
**请求参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| providerId | string | 是 | 供应商ID |
|
||
| requestedRpm | int | 否 | 申请的RPM配额 |
|
||
| requestedTpm | int | 否 | 申请的TPM配额 |
|
||
| reason | string | 是 | 申请理由 |
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| data.applicationId | string | 申请ID |
|
||
| message | string | 操作结果消息 |
|
||
|
||
**前端调用**: `TaijiAPIClient.applyForProvider(data)`
|
||
|
||
---
|
||
|
||
## 计费模块 (Billing)
|
||
|
||
### 数据展示接口
|
||
|
||
#### D6. 租户计费统计 ✅ 已对接
|
||
|
||
**展示位置**: "计费"标签页 → "租户计费统计"区域
|
||
|
||
**展示内容**:
|
||
- 租户名称和ID
|
||
- 调用次数
|
||
- 总EU消耗
|
||
- 租户总价（¥）
|
||
|
||
**功能描述**: 按租户维度展示计费统计数据
|
||
|
||
**接口**:
|
||
```
|
||
GET /api/channel/billing/stats
|
||
```
|
||
|
||
**查询参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| startTime | string | 是 | 开始时间（ISO 8601格式） |
|
||
| endTime | string | 是 | 结束时间（ISO 8601格式） |
|
||
| tenantName | string | 否 | 租户名称筛选 |
|
||
| minCalls | int | 否 | 最小调用次数 |
|
||
| maxCalls | int | 否 | 最大调用次数 |
|
||
| export | string | 否 | 导出格式：excel/csv/pdf |
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| data.tenantStats | array | 租户统计列表 |
|
||
| data.tenantStats[].tenantId | string | 租户ID |
|
||
| data.tenantStats[].tenantName | string | 租户名称 |
|
||
| data.tenantStats[].calls | int | 调用次数 |
|
||
| data.tenantStats[].totalEU | float | 总EU消耗 |
|
||
| data.tenantStats[].totalCost | float | 租户总价（¥） |
|
||
|
||
**前端调用**: `TaijiAPIClient.getChannelBillingStats(params)`
|
||
|
||
**默认范围**: 最近30天
|
||
|
||
---
|
||
|
||
#### D7. 调用记录明细 ✅ 已对接
|
||
|
||
**展示位置**: "计费"标签页 → "调用记录明细"表格
|
||
|
||
**展示内容**:
|
||
- 时间戳
|
||
- 租户名称
|
||
- Agent类型
|
||
- 调用时长（秒）
|
||
- EU消耗
|
||
- 单次调用总价（¥）
|
||
|
||
**功能描述**: 展示详细的调用记录
|
||
|
||
**接口**: 同 D6，使用 `data.callRecords` 字段
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| data.callRecords | array | 调用记录列表 |
|
||
| data.callRecords[].timestamp | string | 调用时间戳 |
|
||
| data.callRecords[].tenantName | string | 租户名称 |
|
||
| data.callRecords[].agentType | string | Agent类型 |
|
||
| data.callRecords[].duration | int | 调用时长（秒） |
|
||
| data.callRecords[].eu | float | EU消耗 |
|
||
| data.callRecords[].price | float | 单次调用价格（¥） |
|
||
|
||
**计费规则**: 1 EU = 10秒调用时长
|
||
|
||
---
|
||
|
||
### 按钮操作接口
|
||
|
||
#### B12. 时间范围查询 ✅ 已对接
|
||
|
||
**触发位置**: "计费"标签页 → "时间查询"按钮
|
||
|
||
**功能描述**: 按时间范围查询计费数据
|
||
|
||
**接口**: 同 D6，通过 `startTime` 和 `endTime` 参数实现
|
||
|
||
---
|
||
|
||
#### B13. 筛选功能 ✅ 已对接
|
||
|
||
**触发位置**: "计费"标签页 → "筛选"按钮
|
||
|
||
**功能描述**: 按条件筛选计费数据
|
||
|
||
**筛选条件**:
|
||
- 客户名称（tenantName）
|
||
- 最小调用次数（minCalls）
|
||
- 最大调用次数（maxCalls）
|
||
|
||
**接口**: 同 D6，通过查询参数实现
|
||
|
||
---
|
||
|
||
#### B14. 数据导出 ⚠️ 待完善
|
||
|
||
**触发位置**: "计费"标签页 → "导出"按钮
|
||
|
||
**功能描述**: 导出计费数据
|
||
|
||
**支持格式**:
|
||
- Excel (.xlsx)
|
||
- CSV (.csv)
|
||
- PDF (.pdf)
|
||
|
||
**接口**: 同 D6，通过 `export` 参数实现
|
||
|
||
**待完善**: 后端需要支持生成并返回文件下载链接
|
||
|
||
---
|
||
|
||
## 设置模块 (Settings)
|
||
|
||
### 数据展示接口
|
||
|
||
#### D8. 管理员列表 ✅ 已对接
|
||
|
||
**展示位置**: "设置"标签页 → "当前管理员列表"区域
|
||
|
||
**展示内容**:
|
||
- 管理员名称
|
||
- 邮箱
|
||
- 角色（渠道管理员/计费管理员/运营管理员）
|
||
- 状态（活跃/已停用）
|
||
|
||
**功能描述**: 展示该渠道下的所有管理员
|
||
|
||
**接口**:
|
||
```
|
||
GET /api/channel/admins
|
||
```
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| data.admins | array | 管理员列表 |
|
||
| data.admins[].id | string | 管理员ID |
|
||
| data.admins[].name | string | 管理员名称 |
|
||
| data.admins[].email | string | 邮箱 |
|
||
| data.admins[].role | string | 角色：channel_admin/billing_admin/operations_admin |
|
||
| data.admins[].status | string | 状态：active/inactive |
|
||
|
||
**前端调用**: `TaijiAPIClient.getChannelAdmins()`
|
||
|
||
---
|
||
|
||
### 按钮操作接口
|
||
|
||
#### B15. 创建管理员 ✅ 已对接
|
||
|
||
**触发位置**: "设置"标签页 → "添加管理员"按钮
|
||
|
||
**功能描述**: 创建计费管理员或运营管理员
|
||
|
||
**接口**:
|
||
```
|
||
POST /api/channel/admins/create
|
||
```
|
||
|
||
**请求参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| name | string | 是 | 管理员姓名 |
|
||
| email | string | 是 | 登录邮箱 |
|
||
| password | string | 是 | 登录密码 |
|
||
| role | string | 是 | 角色：billing_admin/operations_admin |
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| data.admin | object | 创建的管理员信息 |
|
||
| data.admin.id | string | 管理员ID |
|
||
|
||
**前端调用**: `TaijiAPIClient.createChannelAdmin(data)`
|
||
|
||
---
|
||
|
||
#### B16. 删除管理员 ✅ 已对接
|
||
|
||
**触发位置**: 管理员列表 → 删除按钮
|
||
|
||
**功能描述**: 删除指定的管理员账号
|
||
|
||
**接口**:
|
||
```
|
||
DELETE /api/admin/admins/{adminId}
|
||
```
|
||
|
||
**路径参数**:
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| adminId | string | 管理员ID |
|
||
|
||
**响应字段**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | bool | 是否成功 |
|
||
| message | string | 操作结果消息 |
|
||
|
||
**前端调用**: `TaijiAPIClient.deleteAdmin(adminId)`
|
||
|
||
**确认机制**: 二次确认弹窗
|
||
|
||
---
|
||
|
||
#### B17. 配置角色权限 ⚠️ 待完善
|
||
|
||
**触发位置**: "设置"标签页 → 角色卡片 → "配置权限"按钮
|
||
|
||
**功能描述**: 设置不同角色可访问的功能模块
|
||
|
||
**可配置模块**:
|
||
- 概览（overview）
|
||
- 租户管理（tenants）
|
||
- 资源管理（resources）
|
||
- 计费（billing）
|
||
- 设置（settings）
|
||
|
||
**默认角色权限**:
|
||
| 角色 | 默认权限 |
|
||
|------|----------|
|
||
| 计费管理员 | overview, tenants, billing |
|
||
| 运营管理员 | overview, tenants, resources |
|
||
|
||
**当前实现**: 权限配置仅在前端状态管理
|
||
|
||
**待完善**: 需要后端接口持久化权限配置
|
||
|
||
**建议新增接口**:
|
||
```
|
||
PUT /api/channel/roles/{roleId}/permissions
|
||
```
|
||
|
||
**建议请求参数**:
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| permissions | array | 权限列表（如 ["overview", "tenants", "billing"]） |
|
||
|
||
---
|
||
|
||
## 附录：接口汇总表
|
||
|
||
### 认证相关接口
|
||
|
||
| 接口 | 方法 | 路径 | 状态 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 登录 | POST | `/api/auth/login` | ✅ 已对接 | 用户登录 |
|
||
| 登出 | POST | `/api/auth/logout` | ✅ 已对接 | 用户登出 |
|
||
|
||
### 仪表板相关接口
|
||
|
||
| 接口 | 方法 | 路径 | 状态 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 渠道统计 | GET | `/api/channel/dashboard/stats` | ❌ 待开发 | 月度收入、佣金统计 |
|
||
| 平台Agent概览 | GET | `/api/channel/available-platform-agents` | ✅ 已对接 | 可用Agent模板 |
|
||
|
||
### 租户管理相关接口
|
||
|
||
| 接口 | 方法 | 路径 | 状态 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 获取租户列表 | GET | `/api/channel/tenants` | ✅ 已对接 | 获取渠道下所有租户 |
|
||
| 创建租户 | POST | `/api/channel/tenants/create` | ✅ 已对接 | 创建新租户 |
|
||
| 删除租户 | DELETE | `/api/channel/tenants/{tenantId}` | ✅ 已对接 | 删除租户 |
|
||
| 分配资源 | PUT | `/api/channel/tenants/{tenantId}/resources` | ✅ 已对接 | 分配Agent和模型资源 |
|
||
| 充值 | POST | `/api/channel/tenants/{tenantId}/recharge` | ✅ 已对接 | 为租户充值 |
|
||
| 设置授信 | PUT | `/api/channel/tenants/{tenantId}/credit` | ✅ 已对接 | 设置授信额度 |
|
||
| 更新计费 | PUT | `/api/channel/tenants/{tenantId}/billing` | ✅ 已对接 | 更新计费设置 |
|
||
| 更新状态 | PUT | `/api/channel/tenants/{tenantId}/status` | ✅ 已对接 | 更新租户状态 |
|
||
| 更新权限 | PUT | `/api/channel/tenants/{tenantId}/permissions` | ✅ 已对接 | 更新租户权限 |
|
||
|
||
### 资源管理相关接口
|
||
|
||
| 接口 | 方法 | 路径 | 状态 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 获取供应商列表 | GET | `/api/channel/providers` | ✅ 已对接 | 获取可用模型供应商 |
|
||
| 申请供应商 | POST | `/api/channel/providers/apply` | ✅ 已对接 | 申请使用供应商 |
|
||
| 获取申请列表 | GET | `/api/channel/providers/applications` | ✅ 已对接 | 获取申请记录 |
|
||
| 获取平台Agent | GET | `/api/channel/available-platform-agents` | ✅ 已对接 | 获取可用Agent模板 |
|
||
| 申请Agent配额 | POST | `/api/channel/applications/platform-agents` | ✅ 已对接 | 申请Agent配额 |
|
||
| 获取Agent申请 | GET | `/api/channel/applications/platform-agents` | ✅ 已对接 | 获取Agent申请记录 |
|
||
|
||
### 计费统计相关接口
|
||
|
||
| 接口 | 方法 | 路径 | 状态 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 获取计费统计 | GET | `/api/channel/billing/stats` | ✅ 已对接 | 获取租户计费统计 |
|
||
|
||
### 管理员管理相关接口
|
||
|
||
| 接口 | 方法 | 路径 | 状态 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 获取管理员列表 | GET | `/api/channel/admins` | ✅ 已对接 | 获取渠道管理员 |
|
||
| 创建管理员 | POST | `/api/channel/admins/create` | ✅ 已对接 | 创建管理员 |
|
||
| 删除管理员 | DELETE | `/api/admin/admins/{adminId}` | ✅ 已对接 | 删除管理员 |
|
||
| 配置角色权限 | PUT | `/api/channel/roles/{roleId}/permissions` | ❌ 待开发 | 配置角色权限 |
|
||
|
||
---
|
||
|
||
## 待后端完善的功能点
|
||
|
||
### 1. 统计数据接口
|
||
|
||
| 需求 | 说明 | 优先级 |
|
||
|------|------|--------|
|
||
| 月度收入统计 | 需要专门的接口返回渠道月度收入 | 高 |
|
||
| 佣金统计 | 需要接口返回渠道累计佣金 | 高 |
|
||
| 渠道仪表板统计 | 建议提供 `/api/channel/dashboard/stats` 聚合接口 | 高 |
|
||
|
||
### 2. 权限配置持久化
|
||
|
||
| 需求 | 说明 | 优先级 |
|
||
|------|------|--------|
|
||
| 角色权限保存 | 当前权限配置仅在前端状态管理，需要后端接口持久化 | 中 |
|
||
| 权限验证 | 后端需要根据角色权限控制API访问 | 中 |
|
||
|
||
### 3. 数据导出功能
|
||
|
||
| 需求 | 说明 | 优先级 |
|
||
|------|------|--------|
|
||
| 导出接口 | 计费数据导出需要后端支持生成Excel/CSV/PDF文件 | 中 |
|
||
| 文件下载 | 需要返回文件下载链接或直接返回文件流 | 中 |
|
||
|
||
---
|
||
|
||
## 数据模型参考
|
||
|
||
### 租户数据结构
|
||
|
||
```typescript
|
||
interface Tenant {
|
||
id: string
|
||
name: string
|
||
email: string
|
||
status: "active" | "suspended" | "inactive"
|
||
plan: "enterprise" | "professional" | "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"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 前端源文件参考
|
||
|
||
| 文件路径 | 说明 |
|
||
|----------|------|
|
||
| `app/channel/dashboard/page.tsx` | 渠道仪表板主页面（约3000行） |
|
||
| `app/channel/login/page.tsx` | 渠道登录页面 |
|
||
| `app/channel/layout.tsx` | 渠道布局组件 |
|
||
| `lib/api-client.ts` | API客户端封装 |
|
||
|
||
---
|
||
|
||
*文档生成时间: 2026-01-06*
|
||
*基于前端代码版本分析* |