Files
taiji-AI-PAD/Docs/租户用户端-接口对接文档.md
T
2026-01-06 16:00:33 +00:00

27 KiB

租户用户端 - 接口对接文档

版本: v1.0.0 更新时间: 2026-01-06 说明: 本文档基于前端业务需求清单与后端实际接口实现的核实结果,提供完整的接口对接说明


目录

  1. 接口核实总结
  2. 认证模块 (Authentication)
  3. 概览模块 (Dashboard Overview)
  4. 服务网关模块 (Service Gateway)
  5. 数据与工具模块 (Data & Tools)
  6. 代理工厂模块 (Agent Factory)
  7. 编排中心模块 (Orchestration Hub)
  8. 计费与资源模块 (Billing & Resources)
  9. 接口差异说明
  10. 附录:完整接口清单

接口核实总结

核实结果统计

状态 数量 说明
✅ 完全匹配 26 前端需求与后端实现完全一致
⚠️ 路径差异 3 接口存在但路径略有不同
❌ 后端缺失 3 前端需要但后端未实现
总计 32 -

关键发现

  1. 路径差异:部分接口在 user.py 中的路径与前端需求清单略有不同
  2. 缺失接口:工作流运行、工作流删除、账单导出功能后端尚未完整实现
  3. 额外接口:后端提供了更多前端未列出的接口(如自定义Agent管理、Agent计费统计等)

认证模块 (Authentication)

B1. 用户登录接口 ✅ 已对接

项目 说明
前端需求路径 POST /api/auth/login
后端实际路径 POST /api/auth/login
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/auth.py

请求参数:

{
  "email": "string",      // 用户邮箱
  "password": "string",   // 用户密码
  "role": "user"          // 角色类型,固定为 "user"
}

响应示例:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "uuid",
      "name": "用户名",
      "email": "user@example.com",
      "role": "user",
      "channelId": "uuid"
    }
  }
}

B2. 用户登出接口 ✅ 已对接

项目 说明
前端需求路径 POST /api/auth/logout
后端实际路径 POST /api/auth/logout
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/auth.py

请求头:

Authorization: Bearer <token>

响应示例:

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

B3. 刷新Token接口 ✅ 已对接

项目 说明
前端需求路径 POST /api/auth/refresh
后端实际路径 POST /api/auth/refresh
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/auth.py

响应示例:

{
  "success": true,
  "data": {
    "token": "新的JWT访问令牌",
    "refreshToken": "新的刷新令牌"
  }
}

B4. 修改密码接口 ✅ 已对接

项目 说明
前端需求路径 PUT /api/auth/password
后端实际路径 PUT /api/auth/password
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/auth.py

请求参数:

{
  "old_password": "string",  // 旧密码
  "new_password": "string"   // 新密码
}

B5. 重新生成API密钥接口 ✅ 已对接

项目 说明
前端需求路径 POST /api/auth/keys/regenerate
后端实际路径 POST /api/auth/keys/regenerate
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/auth.py

响应示例:

{
  "success": true,
  "data": {
    "apiKey": "sk-xxxxxxxxxxxxx",
    "message": "旧密钥已失效"
  }
}

D1. 获取API密钥信息接口 ✅ 已对接

项目 说明
前端需求路径 GET /api/auth/keys/info
后端实际路径 GET /api/auth/keys/info
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/auth.py

响应示例:

{
  "success": true,
  "data": {
    "endpoint": "https://api.taiji-ai.com/v1",
    "apiKey": "sk-xxxx...xxxx",
    "createdAt": "2026-01-01T00:00:00Z",
    "lastUsed": "2026-01-06T10:00:00Z"
  }
}

概览模块 (Dashboard Overview)

D2. 用户仪表板统计接口 ✅ 已对接

项目 说明
前端需求路径 GET /api/user/dashboard/stats
后端实际路径 GET /api/user/dashboard/stats
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/user.py

响应示例:

{
  "success": true,
  "data": {
    "activeAgents": 5,
    "totalRequests": 12500,
    "euBalance": 1000.50,
    "systemHealth": 98.5
  }
}

D3. 监控仪表盘接口 ✅ 已对接

项目 说明
前端需求路径 GET /api/v1/monitoring/dashboard
后端实际路径 GET /api/v1/monitoring/dashboard
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/monitoring.py

响应示例:

{
  "timestamp": "2026-01-06T14:00:00Z",
  "health": {
    "services": {
      "mcp_server": "healthy",
      "data_ingestion": "healthy",
      "api_gateway": "healthy"
    }
  },
  "metrics": {
    "cpu_usage": 45.2,
    "memory_usage": 62.8
  },
  "stats": {},
  "alerts": {
    "items": [],
    "count": 0,
    "critical_count": 0,
    "warning_count": 0
  }
}

D4. 计费余额接口 ✅ 已对接

项目 说明
前端需求路径 GET /api/user/billing/balance
后端实际路径 GET /api/user/billing/balance
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/user.py

响应示例:

{
  "success": true,
  "data": {
    "balance": 5000.00,
    "monthlySpent": 1200.50,
    "currency": "CNY"
  }
}

注意: 前端需求中有 euBalance 字段,后端返回的是 balance。如需 EU 余额,可从 dashboard/stats 接口获取。


D5. 监控趋势数据接口 ✅ 已对接

项目 说明
前端需求路径 GET /api/v1/monitoring/trends
后端实际路径 GET /api/v1/monitoring/trends
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/monitoring.py

请求参数:

参数 类型 必填 说明
metric string 否 指标类型:executions, eu_consumption
period string 否 时间周期:24h, 7d, 30d
interval string 否 时间间隔:1h, 6h, 1d

服务网关模块 (Service Gateway)

B6. 创建API接口 ✅ 已对接

项目 说明
前端需求路径 POST /api/user/gateway/api/create
后端实际路径 POST /api/user/gateway/api/create
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/user.py

请求参数:

{
  "name": "string",     // API名称
  "method": "string",   // 上传方式:json 或 url
  "content": "string"   // JSON内容或URL地址
}

B7. 选择网关类型接口 ✅ 已对接

项目 说明
前端需求路径 POST /api/user/gateway/select
后端实际路径 POST /api/user/gateway/select
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/user.py

请求参数:

{
  "gatewayType": "MCP"  // 网关类型:MCP, A2A, API
}

D6. 网关API列表接口 ✅ 已对接

项目 说明
前端需求路径 GET /api/user/gateway/apis
后端实际路径 GET /api/user/gateway/apis
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/user.py

响应示例:

{
  "success": true,
  "data": {
    "apis": [
      {
        "id": "uuid",
        "name": "API名称",
        "method": "json",
        "createdAt": "2026-01-01T00:00:00Z"
      }
    ]
  }
}

D7. 网关监控数据接口 ✅ 已对接

项目 说明
前端需求路径 GET /api/user/gateway/monitoring
后端实际路径 GET /api/user/gateway/monitoring
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/user.py

响应示例:

{
  "success": true,
  "data": {
    "uptime": 99.9,
    "requestsPerMinute": 1250,
    "averageLatency": 45,
    "errorRate": 0.1
  }
}

D8. 模型提供商列表接口 ✅ 已对接

项目 说明
前端需求路径 GET /api/providers/models
后端实际路径 GET /api/providers/models
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/providers.py

注意: 此接口需要 manage:providers 权限(super_admin 或 provider_admin)。普通用户可能无法访问。


数据与工具模块 (Data & Tools)

B8. 生成工具接口 ✅ 已对接

项目 说明
前端需求路径 POST /api/user/tools/generate
后端实际路径 POST /api/user/tools/generate
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/user.py

请求参数:

{
  "name": "string",              // 工具名称
  "description": "string",       // 工具描述(可选)
  "frameworkTemplate": "string", // 框架模板:langchain, a2a, api
  "gateway": "string",           // 服务网关:mcp-gateway, a2a-gateway, api-gateway
  "agentCount": 1,               // Agent个数
  "cpu": 1,                      // CPU核数
  "memory": 2,                   // 内存大小(GB)
  "maxScale": 3,                 // 可扩展Agent数量
  "model": "string"              // 使用的模型
}

配额检查: 后端会检查用户的自定义 Agent 配额(CPU/内存),配额不足时返回 400 错误。


B9. 创建数据模板接口 ✅ 已对接

项目 说明
前端需求路径 POST /api/user/data-templates/create
后端实际路径 POST /api/user/data-templates/create
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/user.py

请求参数:

{
  "name": "string",    // 模板名称
  "type": "string",    // 模板类型:json_api, cloud_storage
  "config": {}         // 配置信息
}

D9. 工具列表接口 ✅ 已对接

项目 说明
前端需求路径 GET /tools
后端实际路径 GET /tools
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/tools.py

请求参数:

参数 类型 必填 说明
category string 否 工具类别
search string 否 搜索关键词
is_active bool 否 是否激活
is_public bool 否 是否公开
page int 否 页码,默认1
page_size int 否 每页数量,默认20

响应示例:

{
  "items": [
    {
      "id": "uuid",
      "name": "工具名称",
      "description": "工具描述",
      "category": "类别",
      "is_active": true,
      "is_public": true
    }
  ],
  "total": 100,
  "page": 1,
  "page_size": 20,
  "pages": 5
}

D10. 统计信息接口 ✅ 已对接

项目 说明
前端需求路径 GET /stats
后端实际路径 GET /stats
状态 ✅ 完全匹配
后端服务 Data-Ingestion 服务
后端文件 services/data-ingestion/app/routes/stats.py

响应示例:

{
  "total_apis": 150,
  "processed_apis": 145,
  "generated_tools": 120,
  "failed_processes": 5,
  "cache_size": 1024,
  "last_sync": "2026-01-06T10:00:00Z",
  "categories": {
    "data": 50,
    "ai": 30,
    "utility": 40
  }
}

注意: 此接口由 Data-Ingestion 服务提供,前端需要调用正确的服务地址。


代理工厂模块 (Agent Factory)

B10. 部署Agent接口 ✅ 已对接

项目 说明
前端需求路径 POST /api/user/agents/deploy
后端实际路径 POST /api/user/agents/deploy
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/user.py

请求参数:

{
  "agentId": "string",   // Agent ID
  "instances": 1,        // 实例数量
  "model": "string",     // 使用的模型
  "gateway": "MCP"       // 服务网关:MCP, A2A, API
}

响应示例:

{
  "success": true,
  "data": {
    "agentId": "uuid",
    "podName": "agent-name-xxxxxxxx",
    "namespace": "taiji-agents",
    "status": "Running",
    "servicePort": 8080,
    "instances": 1,
    "model": "gpt-4",
    "gateway": "MCP"
  },
  "message": "Agent xxx 部署成功"
}

B11. 创建自定义Agent接口 ✅ 已对接

项目 说明
前端需求路径 POST /api/user/agents/custom/create
后端实际路径 POST /api/user/custom-agents
状态 ⚠️ 路径差异
后端文件 services/mcp-server/app/routes/user.py

前端需要调整: 将 /api/user/agents/custom/create 改为 /api/user/custom-agents

请求参数:

{
  "name": "string",           // Agent名称
  "template": "string",       // 模板名称
  "endpoint": "string",       // 终结点URL(可选)
  "apiKey": "string",         // API密钥(可选)
  "cpuRequest": "100m",       // CPU请求
  "cpuLimit": "500m",         // CPU限制(可选)
  "memoryRequest": "128Mi",   // 内存请求
  "memoryLimit": "512Mi",     // 内存限制(可选)
  "envConfig": {}             // 环境变量配置(可选)
}

D11. 平台Agent列表接口 ✅ 已对接

项目 说明
前端需求路径 GET /api/user/agents/platform
后端实际路径 GET /api/user/agents/platform
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/user.py

响应示例:

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "uuid",
        "name": "Agent名称",
        "description": "Agent描述",
        "category": "通用",
        "cpu": 1.0,
        "memory": 2.0,
        "status": "available"
      }
    ]
  }
}

D12. 已部署Agent列表接口 ✅ 已对接

项目 说明
前端需求路径 GET /agents
后端实际路径 GET /agents
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/agents.py

请求参数:

参数 类型 必填 说明
skip int 否 跳过数量,默认0
limit int 否 返回数量限制,默认100
template string 否 按模板类型过滤

D13. 自定义Agent列表接口 ✅ 已对接

项目 说明
前端需求路径 GET /api/user/agents/custom
后端实际路径 GET /api/user/custom-agents
状态 ⚠️ 路径差异
后端文件 services/mcp-server/app/routes/user.py

前端需要调整: 将 /api/user/agents/custom 改为 /api/user/custom-agents


编排中心模块 (Orchestration Hub)

B12. 创建工作流接口 ✅ 已对接

项目 说明
前端需求路径 POST /api/user/workflows/create
后端实际路径 POST /api/user/workflows/create
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/user.py

请求参数:

{
  "name": "string",           // 工作流名称
  "description": "string",    // 工作流描述(可选)
  "gateway": "MCP",           // 服务网关:MCP, A2A, API
  "nodes": [                  // 节点列表(最多3个)
    {
      "agentId": "string",
      "agentType": "platform", // platform 或 custom
      "agentName": "string",
      "order": 1
    }
  ]
}

B13. 运行工作流接口 ❌ 后端缺失

项目 说明
前端需求路径 POST /api/user/workflows/{workflow_id}/run
后端实际路径 未实现
状态 ❌ 后端缺失

说明: 后端 user.py 中未找到工作流运行接口的实现。需要后端补充实现。

建议实现:

@router.post("/workflows/{workflow_id}/run", response_model=SuccessResponse)
async def run_workflow(
    workflow_id: str,
    input: Optional[dict] = None,
    principal: dict = Depends(require_auth),
    db: AsyncSession = Depends(get_db)
):
    """运行指定的工作流"""
    pass

B14. 删除工作流接口 ❌ 后端缺失

项目 说明
前端需求路径 DELETE /api/user/workflows/{workflow_id}
后端实际路径 未实现
状态 ❌ 后端缺失

说明: 后端 user.py 中未找到工作流删除接口的实现。需要后端补充实现。


D14. 工作流列表接口 ❌ 后端缺失

项目 说明
前端需求路径 GET /api/user/workflows
后端实际路径 未实现
状态 ❌ 后端缺失

说明: 后端 user.py 中未找到工作流列表接口的实现。需要后端补充实现。

建议实现:

@router.get("/workflows", response_model=SuccessResponse)
async def list_workflows(
    principal: dict = Depends(require_auth),
    db: AsyncSession = Depends(get_db)
):
    """获取用户的工作流列表"""
    pass

计费与资源模块 (Billing & Resources)

B15. 充值接口 ✅ 已对接

项目 说明
前端需求路径 POST /api/user/billing/recharge
后端实际路径 POST /api/user/billing/recharge
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/user.py

请求参数:

{
  "amount": 100.00,           // 充值金额
  "paymentMethod": "alipay"   // 支付方式:alipay, wechat, card(可选)
}

响应示例:

{
  "success": true,
  "data": {
    "orderId": "ORD20260106140000xxxxxxxx",
    "amount": 100.00,
    "paymentUrl": "https://pay.taiji-ai.com/checkout?order_id=xxx",
    "status": "pending"
  }
}

B16. 导出账单接口 ⚠️ 部分实现

项目 说明
前端需求路径 GET /api/user/billing/history?export={format}
后端实际路径 GET /api/user/billing/history (支持 export 参数)
状态 ⚠️ 部分实现
后端文件 services/mcp-server/app/routes/user.py

说明: 后端接口支持 export 参数(excel, csv, pdf),但实际返回的是模拟的文件URL,未真正生成文件。

请求参数:

参数 类型 必填 说明
startTime string 是 开始时间(ISO格式)
endTime string 是 结束时间(ISO格式)
export string 是 导出格式:excel, csv, pdf

响应示例:

{
  "success": true,
  "data": {
    "fileUrl": "https://exports.taiji-ai.com/xxx/excel/billing_xxx.excel",
    "format": "excel",
    "expiresAt": "2026-01-07T14:00:00Z"
  }
}

D15. 计费余额接口 ✅ 已对接

与 D4 相同,参见 D4. 计费余额接口


D16. 计费历史接口 ✅ 已对接

项目 说明
前端需求路径 GET /api/user/billing/history
后端实际路径 GET /api/user/billing/history
状态 ✅ 完全匹配
后端文件 services/mcp-server/app/routes/user.py

请求参数:

参数 类型 必填 说明
startTime string 是 开始时间(ISO格式)
endTime string 是 结束时间(ISO格式)
customerName string 否 客户名称筛选
minCalls int 否 最小调用次数
maxCalls int 否 最大调用次数
page int 否 页码,默认1
pageSize int 否 每页数量,默认20

响应示例:

{
  "success": true,
  "data": {
    "total": 150,
    "records": [
      {
        "id": "uuid",
        "timestamp": "2026-01-06T10:00:00Z",
        "agentName": "Agent名称",
        "duration": 120,
        "eu": 12,
        "cost": 1.20
      }
    ]
  }
}

接口差异说明

1. 路径差异汇总

前端需求路径 后端实际路径 建议
POST /api/user/agents/custom/create POST /api/user/custom-agents 前端调整路径
GET /api/user/agents/custom GET /api/user/custom-agents 前端调整路径

2. 后端缺失接口

接口 说明 优先级
GET /api/user/workflows 工作流列表 高
POST /api/user/workflows/{id}/run 运行工作流 高
DELETE /api/user/workflows/{id} 删除工作流 中

3. 后端额外提供的接口

以下接口后端已实现,但前端需求清单中未列出:

接口 说明
GET /api/user/custom-agent-quota 获取自定义Agent配额
GET /api/user/platform-agents/available 获取可用平台Agent
POST /api/user/platform-agents/use 使用平台Agent
DELETE /api/user/platform-agents/{instance_name} 停止平台Agent
GET /api/user/platform-agents/instances 获取平台Agent实例列表
GET /api/user/custom-agents/templates 获取自定义Agent模板
DELETE /api/user/custom-agents/{name} 删除自定义Agent
PUT /api/user/custom-agents/{name}/scale 扩缩容自定义Agent
GET /api/user/custom-agents/{name}/logs 获取Agent日志
POST /api/user/custom-agents/{name}/restart 重启Agent
GET /api/user/agent-billing/stats Agent计费统计
GET /api/user/agent-billing/history Agent计费历史
GET /api/user/agents/activity Agent活动数据

附录:完整接口清单

按钮操作接口

序号 接口名称 方法 路径 状态 所属模块
B1 用户登录 POST /api/auth/login ✅ 已对接 认证
B2 用户登出 POST /api/auth/logout ✅ 已对接 认证
B3 刷新Token POST /api/auth/refresh ✅ 已对接 认证
B4 修改密码 PUT /api/auth/password ✅ 已对接 认证
B5 重新生成API密钥 POST /api/auth/keys/regenerate ✅ 已对接 认证
B6 创建API POST /api/user/gateway/api/create ✅ 已对接 服务网关
B7 选择网关类型 POST /api/user/gateway/select ✅ 已对接 服务网关
B8 生成工具 POST /api/user/tools/generate ✅ 已对接 数据与工具
B9 创建数据模板 POST /api/user/data-templates/create ✅ 已对接 数据与工具
B10 部署Agent POST /api/user/agents/deploy ✅ 已对接 代理工厂
B11 创建自定义Agent POST /api/user/custom-agents ⚠️ 路径差异 代理工厂
B12 创建工作流 POST /api/user/workflows/create ✅ 已对接 编排中心
B13 运行工作流 POST /api/user/workflows/{id}/run ❌ 后端缺失 编排中心
B14 删除工作流 DELETE /api/user/workflows/{id} ❌ 后端缺失 编排中心
B15 充值 POST /api/user/billing/recharge ✅ 已对接 计费与资源
B16 导出账单 GET /api/user/billing/history?export= ⚠️ 部分实现 计费与资源

数据展示接口

序号 接口名称 方法 路径 状态 所属模块
D1 获取API密钥信息 GET /api/auth/keys/info ✅ 已对接 认证
D2 用户仪表板统计 GET /api/user/dashboard/stats ✅ 已对接 概览
D3 监控仪表盘 GET /api/v1/monitoring/dashboard ✅ 已对接 概览
D4 计费余额 GET /api/user/billing/balance ✅ 已对接 概览
D5 监控趋势数据 GET /api/v1/monitoring/trends ✅ 已对接 概览
D6 网关API列表 GET /api/user/gateway/apis ✅ 已对接 服务网关
D7 网关监控数据 GET /api/user/gateway/monitoring ✅ 已对接 服务网关
D8 模型提供商列表 GET /api/providers/models ✅ 已对接 服务网关
D9 工具列表 GET /tools ✅ 已对接 数据与工具
D10 统计信息 GET /stats ✅ 已对接 数据与工具
D11 平台Agent列表 GET /api/user/agents/platform ✅ 已对接 代理工厂
D12 已部署Agent列表 GET /agents ✅ 已对接 代理工厂
D13 自定义Agent列表 GET /api/user/custom-agents ⚠️ 路径差异 代理工厂
D14 工作流列表 GET /api/user/workflows ❌ 后端缺失 编排中心
D15 计费余额 GET /api/user/billing/balance ✅ 已对接 计费与资源
D16 计费历史 GET /api/user/billing/history ✅ 已对接 计费与资源

接口统计

状态 数量 占比
✅ 完全匹配 26 81.3%
⚠️ 路径差异/部分实现 3 9.4%
❌ 后端缺失 3 9.4%
总计 32 100%

版本历史

版本 日期 更新内容
v1.0.0 2026-01-06 初始版本,完成前后端接口核实