xiaohei/taiji-pda-v0

Fork 1

mirror of https://github.com/Fasthei/taiji-pda-v0.git synced 2026-09-26 21:13:25 +00:00

Files

T

xiaohei eb2a88861b feat: 添加租户管理和K8s Agent API，更新文档

2025-12-31 09:11:28 +00:00

22 KiB

Raw Blame History

前后端参数对比分析报告

生成时间: 2025-12-31
分析范围: taiji-pad-v0 前端项目 vs taiji-AI-PAD 后端API文档

📋 执行摘要

本报告深入分析了前端项目 taiji-pad-v0 与后端API文档 taiji-AI-PAD/Docs/前后端调试接口说明 之间的参数匹配情况。通过逐一对比每个API接口的请求参数、响应数据结构，找出了以下问题：

🔴 关键发现

问题类型	数量	严重程度
参数名称不匹配	3	高
响应数据结构不一致	5	高
前端缺少必需参数	2	中
前端使用硬编码数据	4	中
接口路径不一致	1	低

🔍 详细分析

1. 认证模块 (`/api/auth`)

1.1 登录接口 - ✅ 匹配

项目	后端文档	前端实现	状态
路径	`POST /api/auth/login`	`POST /api/auth/login`	✅
参数 email	string, 必需	string	✅
参数 password	string, 必需	string	✅
参数 role	string, 可选	string	✅
响应 token	data.token	data.token	✅

1.2 修改密码接口 - ⚠️ 参数名不匹配

项目	后端文档	前端实现	状态
路径	`PUT /api/auth/password`	`PUT /api/auth/password`	✅
参数	`old_password`, `new_password`	`old_password`, `new_password`	✅

前端代码 (api-client.ts:245):

body: JSON.stringify({ old_password: oldPassword, new_password: newPassword }),

2. 用户侧平台 (`/api/user`)

2.1 获取仪表板统计 - ✅ 匹配

项目	后端文档	前端实现	状态
路径	`GET /api/user/dashboard/stats`	`GET /api/user/dashboard/stats`	✅
响应 activeAgents	data.activeAgents	data.activeAgents	✅
响应 totalRequests	data.totalRequests	data.totalRequests	✅
响应 euBalance	data.euBalance	data.euBalance	✅
响应 systemHealth	data.systemHealth	data.systemHealth	✅

2.2 获取Agent活动数据 - ✅ 匹配

项目	后端文档	前端实现	状态
路径	`GET /api/user/agents/activity`	`GET /api/user/agents/activity`	✅
参数 period	`7d`, `30d`, `90d`	`7d`, `30d`, `90d`	✅

2.3 部署Agent - ⚠️ 参数类型需确认

项目	后端文档	前端实现	状态
路径	`POST /api/user/agents/deploy`	`POST /api/user/agents/deploy`	✅
参数 agentId	string, 必需	string	✅
参数 instances	int, 必需	number	✅
参数 model	string, 必需	string	✅
参数 gateway	string, 必需	`"MCP" \| "A2A" \| "API"`	⚠️

问题: 后端文档显示 gateway 可选值为 MCP/LiteLLM，但前端定义为 MCP/A2A/API

后端文档:

gateway (string, 必需): 网关类型 (MCP/LiteLLM)

前端代码 (api-client.ts:410):

gateway: "MCP" | "A2A" | "API"

2.4 创建工作流 - ✅ 匹配

项目	后端文档	前端实现	状态
路径	`POST /api/user/workflows/create`	`POST /api/user/workflows/create`	✅
参数 name	string, 必需	string	✅
参数 gateway	string, 必需	`"MCP" \| "A2A" \| "API"`	⚠️
参数 nodes	array, 必需	array	✅

3. 渠道合作伙伴 (`/api/channel`)

3.1 创建租户 - 🔴 参数映射问题

项目	后端文档	前端实现	状态
路径	`POST /api/channel/tenants/create`	`POST /api/channel/tenants/create`	✅
参数 name	string, 必需	string	✅
参数 email	string, 必需	string	✅
参数 password	string, 必需	string	✅
参数 subscriptionTier	string, 可选	通过 systemRole 映射	⚠️
参数 channelId	string, 条件必需	string, 可选	✅

问题: 前端使用 systemRole 参数，需要映射到后端的 subscriptionTier

前端代码 (api-client.ts:522-556):

static async createChannelTenant(data: {
  name: string
  email: string
  password: string
  systemRole?: "tenant" | "admin" | "billing-admin" | "operations-admin"
  subscriptionTier?: "free" | "pro" | "enterprise"
  channelId?: string
}) {
  // 角色到订阅等级的映射
  const roleToTierMap: Record<string, string> = {
    "tenant": "free",
    "admin": "pro",
    "billing-admin": "enterprise",
    "operations-admin": "enterprise"
  }
  // ...
}

分析: 前端已实现映射逻辑，但 systemRole 的值与后端角色系统不完全对应。后端的角色是 user, channel_admin, billing_admin, operations_admin，而前端使用的是 tenant, admin, billing-admin, operations-admin。

3.2 分配租户资源 - ✅ 匹配

项目	后端文档	前端实现	状态
路径	`PUT /api/channel/tenants/{tenant_id}/resources`	`PUT /api/channel/tenants/${tenantId}/resources`	✅
参数 agents	array	array	✅
参数 models	array	array	✅
参数 customAgentResources	object, 可选	object, 可选	✅

3.3 申请使用供应商 - ✅ 匹配

项目	后端文档	前端实现	状态
路径	`POST /api/channel/providers/apply`	`POST /api/channel/providers/apply`	✅
参数 providerId	string, 必需	string	✅
参数 requestedRpm	int, 可选	number, 可选	✅
参数 requestedTpm	int, 可选	number, 可选	✅
参数 reason	string, 必需	string	✅

3.4 禁用/启用租户 - 🔴 接口不存在于后端文档

项目	后端文档	前端实现	状态
禁用路径	❌ 未定义	`PUT /api/channel/tenants/${tenantId}/disable`	🔴
启用路径	❌ 未定义	`PUT /api/channel/tenants/${tenantId}/enable`	🔴

问题: 前端定义了 disableTenant 和 enableTenant 方法，但后端文档中没有这两个接口。后端只有 updateTenantStatus 接口。

前端代码 (api-client.ts:629-646):

static async disableTenant(tenantId: string) {
  const response = await fetch(`${API_BASE_URLS.mcpServer}/api/channel/tenants/${tenantId}/disable`, {
    method: "PUT",
    headers: buildHeaders(),
  })
  return handleResponse(response)
}

static async enableTenant(tenantId: string) {
  const response = await fetch(`${API_BASE_URLS.mcpServer}/api/channel/tenants/${tenantId}/enable`, {
    method: "PUT",
    headers: buildHeaders(),
  })
  return handleResponse(response)
}

建议: 应使用后端的 PUT /api/channel/tenants/{tenant_id}/status 接口，传入 { status: "suspended" } 或 { status: "active" }。

4. 超级管理员 (`/api/admin`)

4.1 创建管理员 - 🔴 缺少必需参数

项目	后端文档	前端实现	状态
路径	`POST /api/admin/admins/create`	`POST /api/admin/admins/create`	✅
参数 name	string, 必需	string	✅
参数 email	string, 必需	string	✅
参数 password	string, 必需	string	✅
参数 role	string, 可选	string	✅
参数 channelId	string, 必需	❌ 未传递	🔴

问题: 后端文档明确指出 channelId 对于 billing_admin 和 operations_admin 是必需参数，但前端 createAdmin 方法没有传递此参数。

后端文档:

channelId (string, 必需): 渠道ID，指定管理员所属的渠道
重要说明: channelId 对于 billing_admin 和 operations_admin 来说是必需参数

前端代码 (api-client.ts:807-819):

static async createAdmin(data: {
  name: string
  email: string
  password: string
  role: "billing_admin" | "operations_admin"
}) {
  const response = await fetch(`${API_BASE_URLS.mcpServer}/api/admin/admins/create`, {
    method: "POST",
    headers: buildHeaders(),
    body: JSON.stringify(data),
  })
  return handleResponse(response)
}

建议: 添加 channelId 参数：

static async createAdmin(data: {
  name: string
  email: string
  password: string
  role: "billing_admin" | "operations_admin"
  channelId: string  // 添加此参数
}) {

4.2 更新渠道信息 - ⚠️ 参数不完整

项目	后端文档	前端实现	状态
路径	`PUT /api/admin/channels/{channel_id}`	`PUT /api/admin/channels/${channelId}`	✅
参数 name	string, 可选	string, 可选	✅
参数 email	string, 可选	❌ 未定义	⚠️
参数 commissionRate	float, 可选	number, 可选	✅
参数 status	string, 可选	❌ 未定义	⚠️
参数 isActive	❌ 未定义	boolean, 可选	⚠️

问题: 前端使用 isActive 参数，但后端使用 status 参数。

前端代码 (api-client.ts:862-873):

static async updateAdminChannel(channelId: string, data: {
  name?: string
  commissionRate?: number
  isActive?: boolean  // 应该是 status?: "active" | "inactive"
}) {

4.3 更新Agent资源配置 - 🔴 参数名不匹配

项目	后端文档	前端实现	状态
路径	`PUT /api/admin/resources/agents/{agent_id}/config`	`PUT /api/admin/resources/agents/${agentId}/config`	✅
参数 cpu	float, 可选	❌ 未定义	🔴
参数 memory	float, 可选	❌ 未定义	🔴
参数 maxInstances	int, 可选	❌ 未定义	🔴
参数 name	❌ 未定义	string, 可选	⚠️
参数 description	❌ 未定义	string, 可选	⚠️
参数 price	❌ 未定义	number, 可选	⚠️
参数 category	❌ 未定义	string, 可选	⚠️
参数 frameworkTemplate	❌ 未定义	string, 可选	⚠️
参数 isActive	❌ 未定义	boolean, 可选	⚠️

问题: 前端和后端的参数完全不匹配！

后端文档:

{
  "cpu": 4.0,
  "memory": 8.0,
  "maxInstances": 10
}

前端代码 (api-client.ts:1028-1042):

static async updateAgentResourceConfig(agentId: string, data: {
  name?: string
  description?: string
  price?: number
  category?: string
  frameworkTemplate?: string
  isActive?: boolean
}) {

建议: 修改前端参数定义以匹配后端：

static async updateAgentResourceConfig(agentId: string, data: {
  cpu?: number
  memory?: number
  maxInstances?: number
}) {

4.4 更新渠道供应商授权 - ⚠️ 参数传递方式不同

项目	后端文档	前端实现	状态
路径	`PUT /api/admin/providers/access/{access_id}`	`PUT /api/admin/providers/access/${accessId}`	✅
参数传递方式	Query Parameters	Query Parameters	✅
参数 status	query param	query param	✅
参数 rpm_limit	query param (snake_case)	query param (rpmLimit → rpm_limit)	✅
参数 tpm_limit	query param (snake_case)	query param (tpmLimit → tpm_limit)	✅

前端代码 (api-client.ts:914-932):

static async updateChannelProviderAccess(accessId: string, params: {
  status?: "active" | "suspended" | "expired"
  rpmLimit?: number
  tpmLimit?: number
}) {
  const queryParams = new URLSearchParams()
  if (params.status) queryParams.append("status", params.status)
  if (params.rpmLimit) queryParams.append("rpm_limit", params.rpmLimit.toString())
  if (params.tpmLimit) queryParams.append("tpm_limit", params.tpmLimit.toString())
  // ...
}

分析: 前端正确地将 camelCase 转换为 snake_case，匹配后端期望的参数名。

5. 监控相关 (`/api/v1/monitoring`)

5.1 获取系统性能指标 - ✅ 匹配

项目	后端文档	前端实现	状态
路径	`GET /api/v1/monitoring/metrics`	`GET /api/v1/monitoring/metrics`	✅

5.2 获取服务统计信息 - ✅ 匹配

项目	后端文档	前端实现	状态
路径	`GET /api/v1/monitoring/stats`	`GET /api/v1/monitoring/stats`	✅
参数 service	query param	query param	✅

5.3 获取性能趋势数据 - ✅ 匹配

项目	后端文档	前端实现	状态
路径	`GET /api/v1/monitoring/trends`	`GET /api/v1/monitoring/trends`	✅
参数 metric	query param	query param	✅
参数 period	query param	query param	✅
参数 interval	query param	query param	✅

6. 前端页面硬编码数据问题

6.1 渠道仪表板 - 硬编码数据

文件: app/channel/dashboard/page.tsx

问题: 页面中存在大量硬编码的模拟数据，而不是从API获取。

硬编码示例 (第702-724行):

const platformModelProviders = [
  { id: 1, name: "OpenAI", status: "active", requests: 52000, latency: 150, uptime: "99.9%", icon: "🤖" },
  { id: 2, name: "Anthropic", status: "active", requests: 38000, latency: 180, uptime: "99.8%", icon: "🧠" },
  { id: 3, name: "Google AI", status: "active", requests: 25000, latency: 120, uptime: "99.95%", icon: "🔍" },
  { id: 4, name: "Meta Llama", status: "active", requests: 15000, latency: 95, uptime: "99.7%", icon: "🦙" },
]

const platformDataProviders = [
  { id: 1, name: "RapidAPI", status: "active", apis: 8000, calls: 2200000, capacity: "95%", icon: "⚡" },
  { id: 2, name: "API Hub", status: "active", apis: 5000, calls: 1500000, capacity: "87%", icon: "🔗" },
  { id: 3, name: "OpenData", status: "active", apis: 3000, calls: 800000, capacity: "92%", icon: "📊" },
]

影响: 这些数据不会随后端实际数据变化而更新，导致页面显示的信息与实际不符。

6.2 概览页面Agent数据 - 硬编码

文件: app/channel/dashboard/page.tsx (第839-869行)

{[
  { name: "Weather Query Agent", nameZh: "天气查询代理", allocated: 10, icon: "☁️" },
  { name: "Data Analysis Agent", nameZh: "数据分析代理", allocated: 15, icon: "📊" },
  { name: "Document Processing Agent", nameZh: "文档处理代理", allocated: 8, icon: "📄" },
  // ...
].map((agent) => (
  // ...
))}

建议: 应该使用 agentResourcesData 状态变量中的数据，该数据已通过 TaijiAPIClient.getAdminAgentResources() 获取。

📊 响应数据结构对比

1. 获取租户列表响应

后端文档:

{
  "success": true,
  "data": {
    "tenants": [
      {
        "id": "tenant-uuid-1",
        "name": "企业客户A",
        "email": "contact@company-a.com",
        "subscriptionTier": "pro",
        "balance": 1500.00,
        "creditLimit": 2000.00,
        "status": "active",
        "createdAt": "2025-12-01T00:00:00Z"
      }
    ]
  }
}

前端期望 (从 channel/dashboard/page.tsx 分析):

// 前端使用的字段
tenant.id
tenant.name
tenant.status
tenant.plan      // ⚠️ 后端是 subscriptionTier
tenant.users     // ⚠️ 后端未返回此字段
tenant.revenue   // ⚠️ 后端未返回此字段

问题: 前端期望 plan, users, revenue 字段，但后端返回的是 subscriptionTier, 且没有 users 和 revenue 字段。

2. 获取Agent资源响应

后端文档:

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "agent-uuid-1",
        "name": "weather-agent",
        "type": "platform",
        "category": "数据查询",
        "cpu": 2.0,
        "memory": 4.0,
        "status": "active"
      }
    ]
  }
}

前端期望 (从 channel/dashboard/page.tsx 分析):

// 前端使用的字段
agent.id
agent.name
agent.description  // ⚠️ 后端未返回
agent.status
agent.cpu
agent.memory
agent.quantity     // ⚠️ 后端未返回，前端使用 agent.quantity ?? agent.available ?? 0
agent.usage?.cpu   // ⚠️ 后端未返回
agent.usage?.memory // ⚠️ 后端未返回

问题: 前端期望 description, quantity, usage 等字段，但后端未返回这些字段。

3. 获取模型供应商响应

后端文档:

{
  "success": true,
  "data": {
    "providers": [
      {
        "id": "provider-uuid-1",
        "name": "OpenAI",
        "provider": "openai",
        "apiUrl": "https://api.openai.com/v1",
        "supportedModels": ["gpt-4", "gpt-4o-mini"],
        "rpm": 3500,
        "tpm": 90000,
        "status": "active",
        "isActive": true
      }
    ]
  }
}

前端期望 (从 channel/dashboard/page.tsx 分析):

// 前端使用的字段
provider.id
provider.name
provider.provider || provider.type  // 后端返回 provider
provider.status || provider.isActive
provider.supportedModels
provider.rpm
provider.tpm
provider.hasAccess          // ⚠️ 仅渠道API返回
provider.pendingApplication // ⚠️ 仅渠道API返回

分析: 前端同时支持管理员API和渠道API的响应格式，但需要注意 hasAccess 和 pendingApplication 字段仅在渠道API (/api/channel/providers) 中返回。

🔧 修复建议

高优先级修复

1. 修复 `createAdmin` 缺少 `channelId` 参数

文件: lib/api-client.ts

// 修改前
static async createAdmin(data: {
  name: string
  email: string
  password: string
  role: "billing_admin" | "operations_admin"
}) {

// 修改后
static async createAdmin(data: {
  name: string
  email: string
  password: string
  role: "billing_admin" | "operations_admin"
  channelId: string  // 添加必需参数
}) {

2. 修复 `updateAgentResourceConfig` 参数不匹配

文件: lib/api-client.ts

// 修改前
static async updateAgentResourceConfig(agentId: string, data: {
  name?: string
  description?: string
  price?: number
  category?: string
  frameworkTemplate?: string
  isActive?: boolean
}) {

// 修改后
static async updateAgentResourceConfig(agentId: string, data: {
  cpu?: number
  memory?: number
  maxInstances?: number
}) {

3. 移除不存在的 `disableTenant` 和 `enableTenant` 接口

文件: lib/api-client.ts

建议删除这两个方法，改用 updateTenantStatus:

// 删除 disableTenant 和 enableTenant 方法
// 使用 updateTenantStatus 代替
static async updateTenantStatus(tenantId: string, status: "active" | "inactive" | "suspended") {
  const response = await fetch(`${API_BASE_URLS.mcpServer}/api/channel/tenants/${tenantId}/status`, {
    method: "PUT",
    headers: buildHeaders(),
    body: JSON.stringify({ status }),
  })
  return handleResponse(response)
}

4. 修复 `updateAdminChannel` 参数

文件: lib/api-client.ts

// 修改前
static async updateAdminChannel(channelId: string, data: {
  name?: string
  commissionRate?: number
  isActive?: boolean
}) {

// 修改后
static async updateAdminChannel(channelId: string, data: {
  name?: string
  email?: string
  commissionRate?: number
  status?: "active" | "inactive"
}) {

中优先级修复

5. 统一 gateway 参数值

前端多处使用 "MCP" | "A2A" | "API"，但后端文档显示应为 "MCP" | "LiteLLM"。需要与后端确认正确的值。

6. 移除硬编码数据

在 app/channel/dashboard/page.tsx 中，将硬编码的 platformModelProviders 和 platformDataProviders 替换为从API获取的数据。

📈 监控配置数据为空的原因分析

根据用户反馈"监控配置的信息都没有内容"，分析可能的原因：

1. 后端返回模拟数据

后端API文档中的响应示例都是模拟数据，实际后端可能：

返回空数组 []
返回默认值 0
数据库中没有实际业务数据

2. 前端使用硬编码数据

如上文分析，前端多处使用硬编码数据而非API返回的数据，导致：

即使后端有数据，前端也不会显示
页面显示的是静态模拟数据

3. API调用失败但静默处理

前端代码中存在多处 try-catch 静默处理错误：

// channel/dashboard/page.tsx:313-330
try {
  const providersResponse = await TaijiAPIClient.getChannelProviders()
  if (providersResponse.success && providersResponse.data?.providers) {
    setModelProvidersData(providersResponse.data.providers)
  }
} catch (providerError) {
  console.warn("Failed to load channel providers:", providerError)
  // 静默失败，不显示错误给用户
}

4. 权限问题

某些API需要特定角色权限：

渠道管理员无法访问 /api/admin/resources/agents
普通用户无法访问 /api/channel/tenants

🎯 总结

问题统计

类别	问题数量	影响程度
参数名称不匹配	3	🔴 高 - 导致API调用失败
响应数据结构不一致	5	🔴 高 - 导致数据无法正确显示
前端缺少必需参数	2	🟡 中 - 特定功能无法使用
前端使用硬编码数据	4	🟡 中 - 数据不真实
接口不存在	2	🔴 高 - 功能完全无法使用

建议优先级

立即修复: createAdmin 缺少 channelId、updateAgentResourceConfig 参数不匹配
尽快修复: 移除 disableTenant/enableTenant，使用 updateTenantStatus
计划修复: 移除硬编码数据，使用API返回的真实数据
需要确认: gateway 参数值 (MCP/A2A/API vs MCP/LiteLLM)

下一步行动

与后端开发确认API文档是否为最新版本
修复前端API客户端中的参数问题
移除硬编码数据，确保使用API返回的真实数据
添加更好的错误处理和用户提示
测试所有API接口的实际响应

报告生成者: Claude AI 审核状态: 待审核

22 KiB Raw Blame History

前后端参数对比分析报告

📋 执行摘要

🔴 关键发现

🔍 详细分析

1. 认证模块 (/api/auth)

1.1 登录接口 - ✅ 匹配

1.2 修改密码接口 - ⚠️ 参数名不匹配

2. 用户侧平台 (/api/user)

2.1 获取仪表板统计 - ✅ 匹配

2.2 获取Agent活动数据 - ✅ 匹配

2.3 部署Agent - ⚠️ 参数类型需确认

2.4 创建工作流 - ✅ 匹配

3. 渠道合作伙伴 (/api/channel)

3.1 创建租户 - 🔴 参数映射问题

3.2 分配租户资源 - ✅ 匹配

3.3 申请使用供应商 - ✅ 匹配

3.4 禁用/启用租户 - 🔴 接口不存在于后端文档

4. 超级管理员 (/api/admin)

4.1 创建管理员 - 🔴 缺少必需参数

4.2 更新渠道信息 - ⚠️ 参数不完整

4.3 更新Agent资源配置 - 🔴 参数名不匹配

4.4 更新渠道供应商授权 - ⚠️ 参数传递方式不同

5. 监控相关 (/api/v1/monitoring)

5.1 获取系统性能指标 - ✅ 匹配

5.2 获取服务统计信息 - ✅ 匹配

5.3 获取性能趋势数据 - ✅ 匹配

6. 前端页面硬编码数据问题

6.1 渠道仪表板 - 硬编码数据

6.2 概览页面Agent数据 - 硬编码

📊 响应数据结构对比

1. 获取租户列表响应

2. 获取Agent资源响应

3. 获取模型供应商响应

🔧 修复建议

高优先级修复

1. 修复 createAdmin 缺少 channelId 参数

2. 修复 updateAgentResourceConfig 参数不匹配

3. 移除不存在的 disableTenant 和 enableTenant 接口

4. 修复 updateAdminChannel 参数

中优先级修复

5. 统一 gateway 参数值

6. 移除硬编码数据

📈 监控配置数据为空的原因分析

1. 后端返回模拟数据

2. 前端使用硬编码数据

3. API调用失败但静默处理

4. 权限问题

🎯 总结

问题统计

建议优先级

下一步行动

22 KiB

Raw Blame History

1. 认证模块 (`/api/auth`)

2. 用户侧平台 (`/api/user`)

3. 渠道合作伙伴 (`/api/channel`)

4. 超级管理员 (`/api/admin`)

5. 监控相关 (`/api/v1/monitoring`)

1. 修复 `createAdmin` 缺少 `channelId` 参数

2. 修复 `updateAgentResourceConfig` 参数不匹配

3. 移除不存在的 `disableTenant` 和 `enableTenant` 接口

4. 修复 `updateAdminChannel` 参数