# Taiji AI Platform - 后端开发对接清单

## 系统架构概述

Taiji AI Platform 是一个多租户AI Agent管理平台，包含以下四个主要系统：

1. **用户侧平台** (User Dashboard) - `/`
2. **渠道合作伙伴平台** (Channel Partner Platform) - `/channel`
3. **超级管理员控制台** (Super Admin Console) - `/admin`
4. **平台供应商管理中心** (Provider Management Center) - `/admin/providers`

---

## 一、核心业务模块

### 1. 用户侧平台 (User Dashboard)

#### 1.1 概览 (Overview) - `/`
**功能**：系统状态、Agent活动、资源消耗监控
**需要的API**：
- `GET /api/user/dashboard/stats` - 获取统计数据
  ```json
  {
    "activeAgents": number,
    "totalRequests": number,
    "euBalance": number,
    "systemHealth": number
  }
  ```
- `GET /api/user/agents/activity` - Agent活动数据
- `GET /api/user/resources/usage` - 资源使用情况

#### 1.2 服务网关 (Service Gateway) - `/model-gateway`
**功能**：选择服务网关类型（MCP/A2A/API），创建API接口
**需要的API**：
- `POST /api/gateway/select` - 选择网关类型
  ```json
  {
    "gatewayType": "MCP" | "A2A" | "API"
  }
  ```
- `POST /api/gateway/api/create` - 创建API（支持JSON文档或URL）
  ```json
  {
    "name": string,
    "method": "json" | "url",
    "content": string | File
  }
  ```
- `GET /api/gateway/apis` - 获取API列表
- `GET /api/gateway/monitoring` - 监控数据

#### 1.3 数据与工具 (Data & Tools) - `/data-tools`
**功能**：数据模板管理、工具生成、Pod部署
**需要的API**：
- `POST /api/tools/generate` - 生成新工具
  ```json
  {
    "name": string,
    "description": string,
    "frameworkTemplate": "MCP" | "A2A" | "API",
    "gateway": string,
    "agentCount": number,
    "cpu": number,
    "memory": number,
    "maxScale": number,
    "model": string
  }
  ```
- `GET /api/tools/list` - 工具列表
- `POST /api/data-templates/create` - 创建数据模板
  ```json
  {
    "name": string,
    "type": "json_api" | "cloud_storage",
    "config": {
      "apiUrl"?: string,
      "queryParams"?: Record<string, string>,
      "cloudProvider"?: "azure" | "gcp" | "aws",
      "connectionString"?: string
    }
  }
  ```

#### 1.4 代理工厂 (Agent Factory) - `/agent-factory`
**功能**：展示和部署平台原生Agent
**需要的API**：
- `GET /api/agents/platform` - 获取平台原生Agent列表
- `POST /api/agents/deploy` - 部署Agent
  ```json
  {
    "agentId": string,
    "instances": number,
    "model": string,
    "gateway": "MCP" | "A2A" | "API"
  }
  ```
- `GET /api/agents/deployed` - 获取已部署Agent

#### 1.5 编排中心 (Orchestration Hub) - `/orchestration`
**功能**：创建工作流，最多3个Agent节点
**需要的API**：
- `POST /api/workflows/create` - 创建工作流
  ```json
  {
    "name": string,
    "description": string,
    "gateway": "MCP" | "A2A" | "API",
    "nodes": Array<{
      "agentId": string,
      "agentType": "platform" | "custom",
      "agentName": string
    }> // 最多3个
  }
  ```
- `GET /api/workflows/list` - 工作流列表
- `PUT /api/workflows/{id}` - 更新工作流
- `DELETE /api/workflows/{id}` - 删除工作流

#### 1.6 计费与资源 (Billing & Resources) - `/billing`
**功能**：EU余额、使用记录、充值
**需要的API**：
- `GET /api/billing/balance` - 获取EU余额
- `GET /api/billing/history` - 使用历史
  ```json
  {
    "records": Array<{
      "timestamp": string,
      "agentName": string,
      "duration": number,
      "eu": number, // 1 EU = 10秒
      "cost": number
    }>
  }
  ```
- `POST /api/billing/recharge` - 充值

---

### 2. 渠道合作伙伴平台 (Channel Partner)

#### 2.1 登录 - `/channel/login`
**需要的API**：
- `POST /api/channel/auth/login`
  ```json
  {
    "email": string,
    "password": string
  }
  ```

#### 2.2 概览 - `/channel/dashboard`
**需要的API**：
- `GET /api/channel/dashboard/stats` - 渠道统计数据
- `GET /api/channel/agents/available` - 可分配Agent列表及数量

#### 2.3 租户管理 - `/channel/dashboard` (Tenants Tab)
**需要的API**：
- `GET /api/channel/tenants` - 租户列表
- `POST /api/channel/tenants/create` - 创建租户
- `PUT /api/channel/tenants/{id}/resources` - 分配资源
  ```json
  {
    "agents": Array<{
      "agentId": string,
      "quantity": number
    }>,
    "models": Array<{
      "modelId": string,
      "rpm": number,
      "tpm": number
    }>,
    "customAgentResources": {
      "cpu": number,
      "memory": number
    }
  }
  ```
- `PUT /api/channel/tenants/{id}/billing` - 管理计费
  ```json
  {
    "subscriptionTier": "free" | "pro" | "enterprise",
    "discount": number // 0-100
  }
  ```

#### 2.4 资源管理 - `/channel/dashboard` (Resources Tab)
**需要的API**：
- `GET /api/channel/resources/agents` - Agent配额
- `GET /api/channel/resources/models` - 已分配模型
- `POST /api/channel/resources/apply` - 提交申请
  ```json
  {
    "type": "model" | "agent",
    "modelName"?: string,
    "rpm"?: number,
    "tpm"?: number,
    "agentType"?: string,
    "quantity"?: number,
    "reason": string
  }
  ```

#### 2.5 计费 - `/channel/dashboard` (Billing Tab)
**需要的API**：
- `GET /api/channel/billing/stats` - 计费统计（租户维度 + 调用记录）

#### 2.6 设置 - `/channel/dashboard` (Settings Tab)
**需要的API**：
- `GET /api/channel/admins` - 管理员列表
- `POST /api/channel/admins/create` - 创建管理员
  ```json
  {
    "name": string,
    "email": string,
    "password": string,
    "role": "billing_admin" | "operations_admin",
    "permissions": string[]
  }
  ```
- `PUT /api/channel/admins/{id}/permissions` - 更新权限

---

### 3. 超级管理员控制台 (Super Admin)

#### 3.1 登录 - `/admin/login`
**需要的API**：
- `POST /api/admin/auth/login`

#### 3.2 概览 - `/admin/dashboard`
**需要的API**：
- `GET /api/admin/dashboard/stats` - 平台全局统计

#### 3.3 渠道管理 - `/admin/dashboard` (Channels Tab)
**需要的API**：
- `GET /api/admin/channels` - 渠道列表
- `POST /api/admin/channels/create` - 创建渠道
  ```json
  {
    "name": string,
    "email": string,
    "commissionRate": number // 0-100
  }
  ```
- `PUT /api/admin/channels/{id}/commission` - 修改佣金
- `PUT /api/admin/channels/{id}/resources` - 资源管理（模型+数据源+Agent+配额）
  ```json
  {
    "models": string[],
    "dataSources": string[],
    "agents": Array<{
      "agentId": string,
      "quantity": number
    }>,
    "customAgentResources": {
      "cpu": number,
      "memory": number
    },
    "monthlyQuota": number,
    "monthlyBudget": number
  }
  ```
- `GET /api/admin/channels/applications` - 渠道申请列表
- `PUT /api/admin/channels/applications/{id}/approve` - 审批申请
  ```json
  {
    "approved": boolean,
    "reason"?: string
  }
  ```

#### 3.4 资源管理 - `/admin/dashboard` (Resources Tab)
**需要的API**：
- `GET /api/admin/resources/models` - 模型供应商列表
- `POST /api/admin/resources/models/add` - 添加模型供应商
  ```json
  {
    "name": string,
    "apiUrl": string,
    "apiKey": string,
    "supportedModels": string[],
    "rpm": number,
    "tpm": number
  }
  ```
- `GET /api/admin/resources/agents` - Agent资源列表
- `PUT /api/admin/resources/agents/{id}` - 配置Agent资源
  ```json
  {
    "cpu": number,
    "memory": number,
    "maxInstances": number
  }
  ```

#### 3.5 监控 - `/admin/dashboard` (Monitoring Tab)
**需要的API**：
- `GET /api/admin/monitoring/agents` - Agent健康状态

#### 3.6 计费 - `/admin/dashboard` (Billing Tab)
**需要的API**：
- `GET /api/admin/billing/overview` - 计费概览（渠道+租户+调用明细）
  ```json
  {
    "channels": Array<{
      "channelName": string,
      "calls": number,
      "totalEU": number,
      "totalCost": number
    }>,
    "tenants": Array<{
      "tenantName": string,
      "channelName": string,
      "calls": number,
      "totalEU": number,
      "totalCost": number
    }>,
    "callRecords": Array<{
      "timestamp": string, // 精确到时分秒
      "channelName": string,
      "tenantName": string,
      "agentName": string,
      "duration": number, // 秒
      "eu": number, // 1 EU = 10秒
      "cost": number
    }>
  }
  ```

#### 3.7 设置 - `/admin/dashboard` (Settings Tab)
**需要的API**：
- `GET /api/admin/roles` - 角色列表
- `POST /api/admin/admins/create` - 创建管理员
  ```json
  {
    "name": string,
    "email": string,
    "password": string,
    "role": "billing_admin" | "operations_admin" | "super_admin",
    "permissions": string[]
  }
  ```

#### 3.8 供应商管理中心后台 - `/admin/dashboard` (Provider Backend Tab)
**需要的API**：
- `GET /api/admin/providers/stats` - 供应商运营数据

#### 3.9 渠道管理中心后台 - `/admin/dashboard` (Channel Backend Tab)
**需要的API**：
- `GET /api/admin/channels/backend/stats` - 渠道后台数据

---

### 4. 平台供应商管理中心

#### 4.1 登录 - `/admin/providers/login`
**需要的API**：
- `POST /api/providers/auth/login`

#### 4.2 管理中心 - `/admin/providers`
**需要的API**：
- `GET /api/providers/models` - 模型供应商列表
- `POST /api/providers/models/add` - 添加模型供应商（支持多云平台）
- `GET /api/providers/data` - 数据供应商（RapidAPI）

---

## 二、数据模型设计建议

### 1. 用户/租户表 (Users/Tenants)
```typescript
{
  id: string
  name: string
  email: string
  role: "user" | "channel_admin" | "super_admin" | "provider_admin"
  channelId?: string // 所属渠道
  subscriptionTier: "free" | "pro" | "enterprise"
  discount: number
  createdAt: Date
  updatedAt: Date
}
```

### 2. 渠道表 (Channels)
```typescript
{
  id: string
  name: string
  email: string
  commissionRate: number
  monthlyQuota: number
  monthlyBudget: number
  createdAt: Date
  updatedAt: Date
}
```

### 3. Agent表 (Agents)
```typescript
{
  id: string
  name: string
  type: "platform" | "custom"
  description: string
  cpu: number
  memory: number
  maxInstances: number
  status: "active" | "inactive" | "deploying"
  createdAt: Date
  updatedAt: Date
}
```

### 4. 模型供应商表 (Model Providers)
```typescript
{
  id: string
  name: string
  source: "openai" | "anthropic" | "google" | "azure" | "aws" | "openroute"
  apiUrl: string
  apiKey: string
  supportedModels: string[]
  rpm: number
  tpm: number
  status: "active" | "inactive"
  createdAt: Date
  updatedAt: Date
}
```

### 5. 资源分配表 (Resource Allocations)
```typescript
{
  id: string
  targetId: string // channelId 或 tenantId
  targetType: "channel" | "tenant"
  resourceType: "agent" | "model"
  resourceId: string
  quantity?: number // Agent数量
  rpm?: number // 模型RPM
  tpm?: number // 模型TPM
  customAgentCpu?: number
  customAgentMemory?: number
  createdAt: Date
  updatedAt: Date
}
```

### 6. 计费记录表 (Billing Records)
```typescript
{
  id: string
  timestamp: Date // 精确到秒
  channelId: string
  tenantId: string
  agentId: string
  agentName: string
  duration: number // 秒
  eu: number // 1 EU = 10秒
  cost: number
  createdAt: Date
}
```

### 7. 申请审批表 (Applications)
```typescript
{
  id: string
  channelId: string
  type: "model" | "agent"
  // 模型申请
  modelName?: string
  rpm?: number
  tpm?: number
  // Agent申请
  agentType?: string
  quantity?: number
  // 通用
  reason: string
  status: "pending" | "approved" | "rejected"
  reviewedBy?: string
  reviewedAt?: Date
  createdAt: Date
  updatedAt: Date
}
```

### 8. 工作流表 (Workflows)
```typescript
{
  id: string
  userId: string
  name: string
  description: string
  gateway: "MCP" | "A2A" | "API"
  nodes: Array<{
    agentId: string
    agentType: "platform" | "custom"
    agentName: string
    order: number
  }>
  status: "active" | "inactive"
  createdAt: Date
  updatedAt: Date
}
```

---

## 三、认证与权限

### 1. JWT Token 结构
```typescript
{
  userId: string
  role: "user" | "channel_admin" | "super_admin" | "provider_admin"
  channelId?: string
  permissions: string[]
  exp: number
}
```

### 2. 权限列表
- `view:overview` - 查看概览
- `manage:tenants` - 管理租户
- `manage:resources` - 管理资源
- `view:billing` - 查看计费
- `manage:billing` - 管理计费
- `view:settings` - 查看设置
- `manage:settings` - 管理设置
- `approve:applications` - 审批申请

---

## 四、环境变量配置

前端已配置的环境变量：
```bash
NEXT_PUBLIC_DATA_INGESTION_URL=http://localhost:8001
NEXT_PUBLIC_MCP_SERVER_URL=http://localhost:8000
NEXT_PUBLIC_API_GATEWAY_URL=http://localhost:80
```

建议后端环境变量：
```bash
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
JWT_SECRET=...
ENCRYPTION_KEY=...
```

---

## 五、关键业务逻辑

### 1. EU计算规则
- **1 EU = 10秒调用时间**
- 计费公式：`EU = Math.ceil(duration / 10)`
- 不足10秒按10秒计算

### 2. 资源分配层级
```
超级管理员
  ↓ 分配资源到渠道
渠道管理员
  ↓ 分配资源到租户
租户
  ↓ 使用资源
```

### 3. 服务网关选择
- 用户在创建Agent、工具、工作流时必须选择服务网关类型
- 支持三种类型：MCP、A2A、API

### 4. Agent部署
- 平台Agent：固定CPU（2核）、内存（4GB）
- 自定义Agent：由渠道/超级管理员分配资源

### 5. 工作流限制
- 最多3个Agent节点
- 支持平台Agent + 自定义Agent混合

---

## 六、国际化支持

前端已实现完整的中英文切换，后端返回数据建议：
1. 错误消息使用错误码，由前端翻译
2. 动态数据（如Agent名称）保持原样
3. 系统消息可以包含国际化字段

---

## 七、前端已完成功能检查

✅ **用户侧平台**
- ✅ 概览
- ✅ 服务网关（MCP/A2A/API选择、API创建）
- ✅ 数据与工具（数据模板、工具生成、Pod部署）
- ✅ 代理工厂（平台Agent展示、部署配置）
- ✅ 编排中心（工作流创建、最多3节点）
- ✅ 计费与资源
- ✅ 完整国际化

✅ **渠道合作伙伴平台**
- ✅ 登录
- ✅ 概览（可分配Agent展示）
- ✅ 租户管理（资源分配、计费管理）
- ✅ 资源管理（模型申请、Agent申请）
- ✅ 计费（租户+调用记录）
- ✅ 设置（角色权限）
- ✅ 完整国际化
- ✅ 修改密码功能

✅ **超级管理员控制台**
- ✅ 登录
- ✅ 概览
- ✅ 渠道管理（创建、佣金、资源管理、申请审批）
- ✅ 资源管理（模型供应商、Agent配置）
- ✅ 监控（Agent健康）
- ✅ 计费（三维度：渠道+租户+调用）
- ✅ 设置（角色管理）
- ✅ 供应商/渠道管理后台
- ✅ 完整国际化

✅ **平台供应商管理中心**
- ✅ 登录
- ✅ 模型管理（多云平台支持）
- ✅ 完整国际化

---

## 八、待后端实现的核心功能

### 高优先级
1. ✅ 认证系统（JWT）
2. ✅ 用户/渠道/租户CRUD
3. ✅ 资源分配逻辑
4. ✅ 计费系统（EU计算）
5. ✅ 申请审批流程

### 中优先级
6. ✅ Agent部署管理
7. ✅ 工作流执行引擎
8. ✅ 服务网关路由
9. ✅ 监控数据采集

### 低优先级
10. ✅ WebSocket实时通信
11. ✅ 数据模板处理
12. ✅ 工具自动生成

---

## 九、API响应格式建议

### 成功响应
```json
{
  "success": true,
  "data": { ... },
  "message": "操作成功"
}
```

### 错误响应
```json
{
  "success": false,
  "error": {
    "code": "AUTH_FAILED",
    "message": "认证失败"
  }
}
```

---

## 十、下一步行动

1. **后端团队**：
   - 根据此文档设计数据库Schema
   - 实现认证系统
   - 实现核心API端点（建议按优先级）
   - 编写API文档（Swagger/OpenAPI）

2. **前端团队**：
   - 等待后端API文档
   - 对接API（替换Mock数据）
   - 联调测试
   - 性能优化

3. **测试团队**：
   - 准备测试用例
   - 集成测试
   - 压力测试

---

**文档版本**: v1.0  
**最后更新**: 2025-01-08  
**维护者**: Taiji AI Platform Team