taijibaga/taiji-AI-PAD

Fork 0

forked from xiaohei/taiji-AI-PAD

Files

T

Ubuntu c735d60140 更新接口

2025-12-25 07:25:32 +00:00

21 KiB

Raw Blame History

Taiji AI Platform - 后端开发需求与接口文档

版本: v3.0
更新日期: 2025-01-08
状态: 前端设计完成，待后端开发

系统概述

平台架构

┌─────────────────────────────────────────────────────────────────┐
│                      Taiji AI Platform                          │
├─────────────────┬─────────────────┬─────────────────┬───────────┤
│   用户侧平台    │  渠道合作伙伴   │  超级管理员     │  供应商   │
│   (租户使用)    │   平台          │   控制台        │  管理中心 │
├─────────────────┴─────────────────┴─────────────────┴───────────┤
│                        API Gateway                               │
├──────────────────────────────────────────────────────────────────┤
│  服务网关 (MCP/A2A/API)  │  计费引擎  │  资源调度  │  监控系统  │
├──────────────────────────────────────────────────────────────────┤
│                      数据库 & 缓存                               │
│            PostgreSQL    │    Redis    │    S3                   │
└──────────────────────────────────────────────────────────────────┘

核心服务端口

服务	端口	说明
Next.js 前端	3000	主应用
API网关	80/443	外部访问
MCP服务	8000	MCP协议服务
数据摄取	8001	数据处理服务

四大子系统功能清单

1. 用户侧平台 (/)

页面	功能模块	核心功能
概览	仪表板	统计数据、Agent活动图表、资源使用情况
服务网关	网关管理	选择网关类型(MCP/A2A/API)、创建API(JSON/URL)、监控
数据与工具	工具管理	数据模板、工具生成、Pod部署配置
代理工厂	Agent管理	平台Agent展示、部署配置
编排中心	工作流	创建工作流(最多3节点)、运行管理
计费与资源	计费	余额显示、充值、使用记录、筛选、导出
密钥管理	安全	服务终结点、API密钥查看与更新

2. 渠道合作伙伴平台 (/channel)

页面	功能模块	核心功能
概览	仪表板	渠道统计、可分配Agent概览
租户管理	租户	创建租户、分配资源、管理计费、充值、授信额度
资源管理	资源	Agent配额监控、模型管理、提交申请(模型/Agent)
计费	计费	租户计费统计、调用记录、筛选、导出
设置	权限	管理员角色(计费/运营)、权限配置

3. 超级管理员控制台 (/admin)

页面	功能模块	核心功能
概览	仪表板	平台全局统计
渠道管理	渠道	创建渠道、佣金设置、统一资源管理、申请审批
资源管理	资源	模型供应商、Agent计算资源配置
监控	监控	Agent健康状态、性能指标
计费	计费	三维度计费(渠道/租户/调用)、筛选、导出
设置	权限	管理员角色(计费/运营/超级)、权限配置

4. 供应商管理中心 (/admin/providers)

页面	功能模块	核心功能
模型管理	供应商	多云模型供应商配置

完整API接口规范

通用响应格式

// 成功响应
{
  "success": true,
  "data": { ... },
  "message"?: string
}

// 错误响应
{
  "success": false,
  "error": {
    "code": string,
    "message": string
  }
}

一、认证模块

POST /api/auth/login

Request:
{
  "email": string,
  "password": string,
  "role": "user" | "channel" | "admin" | "provider"
}

Response:
{
  "success": true,
  "data": {
    "token": string,
    "refreshToken": string,
    "user": {
      "id": string,
      "name": string,
      "email": string,
      "role": string,
      "channelId"?: string
    }
  }
}

POST /api/auth/logout

POST /api/auth/refresh

PUT /api/auth/password

二、密钥管理模块

GET /api/keys/info

获取服务终结点和API密钥

Response:
{
  "success": true,
  "data": {
    "endpoint": "https://api.taiji-ai.com/v1",
    "apiKey": "sk-xxxx...xxxx", // 部分隐藏
    "createdAt": string,
    "lastUsed": string
  }
}

POST /api/keys/regenerate

重新生成API密钥

Response:
{
  "success": true,
  "data": {
    "apiKey": "sk-新密钥完整显示",
    "message": "旧密钥已失效"
  }
}

三、用户侧API

3.1 概览

GET /api/user/dashboard/stats

Response:
{
  "activeAgents": number,
  "totalRequests": number,
  "euBalance": number,
  "systemHealth": number
}

GET /api/user/agents/activity

Query: { period: "7d" | "30d" | "90d" }
Response:
{
  "data": Array<{
    "date": string,
    "agentName": string,
    "requests": number
  }>
}

3.2 服务网关

POST /api/gateway/select

Request:
{
  "gatewayType": "MCP" | "A2A" | "API"
}

POST /api/gateway/api/create

Request:
{
  "name": string,
  "method": "json" | "url",
  "content": string // JSON文档或URL
}

GET /api/gateway/apis

GET /api/gateway/monitoring

3.3 数据与工具

POST /api/tools/generate

Request:
{
  "name": string,
  "description": string,
  "frameworkTemplate": "MCP" | "A2A" | "API",
  "gateway": string, // 网关ID
  "agentCount": number,
  "cpu": number,
  "memory": number,
  "maxScale": number,
  "model": string
}

POST /api/data-templates/create

Request (JSON API):
{
  "name": string,
  "type": "json_api",
  "config": {
    "apiUrl": string,
    "queryParams": Record<string, string>
  }
}

Request (云存储):
{
  "name": string,
  "type": "cloud_storage",
  "config": {
    "provider": "azure" | "gcp" | "aws",
    "service": "blob" | "s3" | "gcs",
    "connectionString": string
  }
}

Request (数据库):
{
  "name": string,
  "type": "database",
  "config": {
    "type": "postgresql" | "mysql" | "mongodb" | "snowflake" | "databricks",
    "connectionString": string
  }
}

3.4 代理工厂

GET /api/agents/platform

Response:
{
  "data": Array<{
    "id": string,
    "name": string,
    "description": string,
    "category": string,
    "cpu": number, // 固定2核
    "memory": number, // 固定4GB
    "status": "available" | "unavailable"
  }>
}

POST /api/agents/deploy

Request:
{
  "agentId": string,
  "instances": number,
  "model": string,
  "gateway": "MCP" | "A2A" | "API"
}

3.5 编排中心

POST /api/workflows/create

Request:
{
  "name": string,
  "description": string,
  "gateway": "MCP" | "A2A" | "API",
  "nodes": Array<{
    "agentId": string,
    "agentType": "platform" | "custom",
    "agentName": string,
    "order": number
  }> // 最多3个节点
}

Error (超过3节点):
{
  "success": false,
  "error": {
    "code": "WORKFLOW_NODE_LIMIT",
    "message": "工作流最多支持3个Agent节点"
  }
}

3.6 计费与资源（新增余额充值）

GET /api/billing/balance

Response:
{
  "balance": number, // 当前余额
  "monthlySpent": number, // 本月消费
  "currency": "CNY"
}

POST /api/billing/recharge

Request:
{
  "amount": number, // 充值金额
  "paymentMethod": "alipay" | "wechat" | "card"
}

Response:
{
  "orderId": string,
  "amount": number,
  "paymentUrl": string, // 支付跳转URL
  "status": "pending"
}

GET /api/billing/history

Query:
{
  "startTime": string, // ISO 8601 精确到分钟
  "endTime": string,
  "customerName"?: string,
  "minCalls"?: number,
  "maxCalls"?: number,
  "export"?: "excel" | "csv" | "pdf",
  "page": number,
  "pageSize": number
}

Response (查询):
{
  "total": number,
  "records": Array<{
    "id": string,
    "timestamp": string, // 精确到秒
    "agentName": string,
    "duration": number, // 秒
    "eu": number, // 1 EU = 10秒
    "cost": number
  }>
}

Response (导出):
{
  "fileUrl": string,
  "format": string,
  "expiresAt": string
}

四、渠道合作伙伴API

4.1 租户管理

GET /api/channel/tenants

POST /api/channel/tenants/create

PUT /api/channel/tenants/{id}/resources

分配资源（包含自定义Agent资源）

Request:
{
  "agents": Array<{
    "agentId": string,
    "quantity": number
  }>,
  "models": Array<{
    "modelName": string,
    "rpm": number,
    "tpm": number
  }>,
  "customAgentResources": {
    "cpu": number,
    "memory": number
  }
}

PUT /api/channel/tenants/{id}/billing

管理租户计费

Request:
{
  "subscriptionTier": "free" | "pro" | "enterprise",
  "discount": number // 0-100
}

POST /api/channel/tenants/{id}/recharge（新增）

为租户充值

Request:
{
  "amount": number
}

Response:
{
  "success": true,
  "data": {
    "tenantId": string,
    "newBalance": number,
    "rechargeAmount": number
  }
}

PUT /api/channel/tenants/{id}/credit（新增）

设置租户授信额度

Request:
{
  "creditLimit": number
}

Response:
{
  "success": true,
  "data": {
    "tenantId": string,
    "creditLimit": number
  }
}

4.2 资源申请

POST /api/channel/resources/apply

Request (模型申请):
{
  "type": "model",
  "modelName": string,
  "rpm": number,
  "tpm": number,
  "reason": string
}

Request (Agent申请):
{
  "type": "agent",
  "agentType": string,
  "quantity": number,
  "reason": string
}

4.3 计费

GET /api/channel/billing/stats

Query:
{
  "startTime": string,
  "endTime": string,
  "tenantName"?: string,
  "minCalls"?: number,
  "maxCalls"?: number,
  "export"?: "excel" | "csv" | "pdf"
}

Response:
{
  "tenantStats": Array<{
    "tenantId": string,
    "tenantName": string,
    "calls": number,
    "totalEU": number,
    "totalCost": number
  }>,
  "callRecords": Array<{
    "id": string,
    "timestamp": string,
    "tenantName": string,
    "agentName": string,
    "duration": number,
    "eu": number,
    "cost": number
  }>
}

五、超级管理员API

5.1 渠道管理

PUT /api/admin/channels/{id}/resources（统一资源管理）

Request:
{
  "models": Array<string>, // 模型供应商ID
  "agents": Array<{
    "agentId": string,
    "quantity": number
  }>,
  "customAgentResources": {
    "cpu": number,
    "memory": number
  },
  "channelCredit": number // 渠道授信额度
}

GET /api/admin/channels/applications

获取渠道申请（模型+Agent）

Response:
{
  "data": Array<{
    "id": string,
    "channelId": string,
    "channelName": string,
    "type": "model" | "agent",
    "details": {
      "modelName"?: string,
      "rpm"?: number,
      "tpm"?: number,
      "agentType"?: string,
      "quantity"?: number
    },
    "reason": string,
    "status": "pending" | "approved" | "rejected",
    "createdAt": string
  }>
}

PUT /api/admin/channels/applications/{id}/review

Request:
{
  "approved": boolean,
  "reason"?: string
}

5.2 计费（三维度）

GET /api/admin/billing/overview

Query:
{
  "startTime": string,
  "endTime": string,
  "channelName"?: string,
  "tenantName"?: string,
  "minCalls"?: number,
  "maxCalls"?: number,
  "export"?: "excel" | "csv" | "pdf"
}

Response:
{
  "channelStats": Array<{
    "channelId": string,
    "channelName": string,
    "calls": number,
    "totalEU": number,
    "totalCost": number
  }>,
  "tenantStats": Array<{
    "tenantId": string,
    "tenantName": string,
    "channelName": string,
    "calls": number,
    "totalEU": number,
    "totalCost": number
  }>,
  "callRecords": Array<{
    "id": string,
    "timestamp": string,
    "channelName": string,
    "tenantName": string,
    "agentName": string,
    "duration": number,
    "eu": number,
    "cost": number
  }>
}

数据库设计

核心表结构

-- 用户表
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(100) NOT NULL,
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  role VARCHAR(50) NOT NULL, -- user, channel_admin, super_admin, provider_admin
  channel_id UUID REFERENCES channels(id),
  subscription_tier VARCHAR(20) DEFAULT 'free',
  discount DECIMAL(5,2) DEFAULT 0,
  balance DECIMAL(12,2) DEFAULT 0, -- 账户余额
  credit_limit DECIMAL(12,2) DEFAULT 0, -- 授信额度
  status VARCHAR(20) DEFAULT 'active',
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- 渠道表
CREATE TABLE channels (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(100) NOT NULL,
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  commission_rate DECIMAL(5,2) DEFAULT 0,
  channel_credit DECIMAL(12,2) DEFAULT 0, -- 渠道授信额度
  custom_agent_cpu DECIMAL(5,2) DEFAULT 2, -- 自定义Agent CPU
  custom_agent_memory DECIMAL(5,2) DEFAULT 4, -- 自定义Agent 内存
  status VARCHAR(20) DEFAULT 'active',
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- Agent表
CREATE TABLE agents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(100) NOT NULL,
  type VARCHAR(20) NOT NULL, -- platform, custom
  description TEXT,
  category VARCHAR(50),
  cpu DECIMAL(5,2) NOT NULL,
  memory DECIMAL(5,2) NOT NULL,
  max_instances INT DEFAULT 100,
  status VARCHAR(20) DEFAULT 'active',
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- 模型供应商表
CREATE TABLE model_providers (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(100) NOT NULL,
  provider VARCHAR(50) NOT NULL, -- openai, anthropic, azure, google, aws
  api_url VARCHAR(500) NOT NULL,
  api_key_encrypted TEXT NOT NULL,
  supported_models JSONB NOT NULL,
  rpm INT NOT NULL,
  tpm INT NOT NULL,
  status VARCHAR(20) DEFAULT 'active',
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- 资源分配表
CREATE TABLE resource_allocations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  target_id UUID NOT NULL,
  target_type VARCHAR(20) NOT NULL, -- channel, tenant
  resource_type VARCHAR(20) NOT NULL, -- agent, model
  resource_id UUID NOT NULL,
  quantity INT, -- Agent数量
  rpm INT, -- 模型RPM
  tpm INT, -- 模型TPM
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- 计费记录表
CREATE TABLE billing_records (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  timestamp TIMESTAMP NOT NULL,
  channel_id UUID REFERENCES channels(id),
  tenant_id UUID REFERENCES users(id),
  agent_id UUID REFERENCES agents(id),
  agent_name VARCHAR(100) NOT NULL,
  duration INT NOT NULL, -- 秒
  eu INT NOT NULL, -- 1 EU = 10秒
  cost DECIMAL(12,4) NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

-- 充值记录表
CREATE TABLE recharge_records (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id),
  channel_id UUID REFERENCES channels(id),
  amount DECIMAL(12,2) NOT NULL,
  payment_method VARCHAR(50),
  status VARCHAR(20) DEFAULT 'pending', -- pending, success, failed
  order_id VARCHAR(100),
  created_at TIMESTAMP DEFAULT NOW(),
  completed_at TIMESTAMP
);

-- 申请审批表
CREATE TABLE applications (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  channel_id UUID REFERENCES channels(id),
  type VARCHAR(20) NOT NULL, -- model, agent
  model_name VARCHAR(100),
  rpm INT,
  tpm INT,
  agent_type VARCHAR(100),
  quantity INT,
  reason TEXT,
  status VARCHAR(20) DEFAULT 'pending', -- pending, approved, rejected
  reviewed_by UUID,
  review_reason TEXT,
  created_at TIMESTAMP DEFAULT NOW(),
  reviewed_at TIMESTAMP
);

-- 工作流表
CREATE TABLE workflows (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id),
  name VARCHAR(100) NOT NULL,
  description TEXT,
  gateway VARCHAR(20) NOT NULL, -- MCP, A2A, API
  nodes JSONB NOT NULL, -- 最多3个节点
  status VARCHAR(20) DEFAULT 'active',
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- API密钥表
CREATE TABLE api_keys (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id),
  api_key_hash VARCHAR(255) NOT NULL,
  api_key_prefix VARCHAR(10) NOT NULL, -- sk-xxxx
  last_used TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW()
);

-- 索引
CREATE INDEX idx_billing_timestamp ON billing_records(timestamp);
CREATE INDEX idx_billing_channel ON billing_records(channel_id);
CREATE INDEX idx_billing_tenant ON billing_records(tenant_id);
CREATE INDEX idx_applications_status ON applications(status);
CREATE INDEX idx_users_channel ON users(channel_id);

业务规则

1. EU计算规则

1 EU = 10秒调用时间
EU = CEILING(duration_seconds / 10)
不足10秒按1 EU计算

2. 计费价格（建议）

1 EU = ¥0.01 (可配置)

3. 余额与授信

可用额度 = 账户余额 + 授信额度
消费优先扣除余额，余额不足时使用授信额度
授信额度用完后服务暂停

4. 资源分配层级

超级管理员 → 渠道 → 租户
每层只能分配不超过上级分配的资源

5. 工作流限制

最多3个Agent节点
支持平台Agent + 自定义Agent混合

6. 平台Agent资源（固定）

CPU: 2核/实例
内存: 4GB/实例

7. 自定义Agent资源（由上级分配）

CPU: 由渠道/管理员配置
内存: 由渠道/管理员配置

认证与权限

JWT Token结构

{
  "userId": string,
  "role": "user" | "channel_admin" | "billing_admin" | "operations_admin" | "admin" | "super_admin" | "provider_admin",
  "channelId"?: string,
  "permissions": string[],
  "iat": number,
  "exp": number
}

权限列表

权限	说明
view:overview	查看概览
manage:tenants	管理租户
manage:resources	管理资源
view:billing	查看计费
manage:billing	管理计费（含充值）
manage:settings	管理设置
approve:applications	审批申请
manage:channels	管理渠道
manage:providers	管理供应商
view:monitoring	查看监控

角色权限映射

角色	说明	权限
计费管理员 (billing_admin)	负责计费、充值等财务操作	view:overview, view:billing, manage:billing
运营管理员 (operations_admin)	负责租户和资源的日常运营管理	view:overview, manage:tenants, manage:resources, view:billing
管理员 (admin)	平台管理员，拥有除超级管理员外的大部分权限	view:overview, manage:tenants, manage:resources, view:billing, manage:billing, manage:settings, view:monitoring
超级管理员 (super_admin)	拥有全部权限，可进行所有管理操作	全部权限

部署要求

环境变量

# 数据库
DATABASE_URL=postgresql://taiji:By%40123456.@taijipda.postgres.database.azure.com:5432/postgres?sslmode=require

# Redis
REDIS_URL=rediss://:nkJgt1ERFpdeYrEFNyFtsc5K4ycvx2jIeAzCaGGf1OQ%3D@taiji.southeastasia.redis.azure.net:10000/0?ssl_cert_reqs=none

# JWT
JWT_SECRET=zsbgnw
JWT_EXPIRES_IN=24h

# 加密
ENCRYPTION_KEY=zsbgnw

# 支付（可选）
ALIPAY_APP_ID=xxx
WECHAT_PAY_APP_ID=xxx

# 云存储
AWS_ACCESS_KEY_ID=xxx
AWS_SECRET_ACCESS_KEY=xxx
S3_BUCKET=taiji-ai-exports

服务依赖

PostgreSQL 14+
Redis 6+
Node.js 18+ (或 Python 3.10+)
S3兼容存储（导出文件）

开发优先级建议

P0 - 核心功能

认证系统（登录、JWT、权限）
用户/渠道/租户CRUD
余额与授信管理
计费记录与查询

P1 - 资源管理

资源分配逻辑
申请审批流程
Agent部署管理

P2 - 高级功能

服务网关集成（MCP/A2A/API）
工作流引擎
监控与告警

P3 - 运营支持

导出功能（Excel/CSV/PDF）
API密钥管理
数据模板处理

文档版本: v3.0
最后更新: 2025-01-08
前端状态: 设计完成，支持中英文
后端状态: 待开发

21 KiB Raw Blame History Unescape Escape