Files
taiji-AI-PAD/Docs/项目文档/渠道合作伙伴平台-后端接口需求清单.md
T
2026-01-06 16:00:33 +00:00

27 KiB
Raw Blame History

渠道合作伙伴平台 - 后端接口需求清单

版本: v1.2.0 更新时间: 2026-01-06 说明: 本文档基于前端业务逻辑分析,列出所有后端接口需求,包括已对接接口和未对接接口,按钮操作接口和数据展示接口


目录

  1. 认证模块 (Authentication)
  2. 仪表板模块 (Dashboard/Overview)
  3. 租户管理模块 (My Tenants)
  4. 资源管理模块 (Resource Management)
  5. 计费模块 (Billing)
  6. 设置模块 (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文件 中
文件下载 需要返回文件下载链接或直接返回文件流 中

数据模型参考

租户数据结构

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资源数据结构

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
}

模型供应商数据结构

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

计费统计数据结构

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
  }>
}

管理员数据结构

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 基于前端代码版本分析