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

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

---

## 目录

1. [接口核实总结](#接口核实总结)
2. [认证模块 (Authentication)](#认证模块-authentication)
3. [概览模块 (Dashboard Overview)](#概览模块-dashboard-overview)
4. [服务网关模块 (Service Gateway)](#服务网关模块-service-gateway)
5. [数据与工具模块 (Data & Tools)](#数据与工具模块-data--tools)
6. [代理工厂模块 (Agent Factory)](#代理工厂模块-agent-factory)
7. [编排中心模块 (Orchestration Hub)](#编排中心模块-orchestration-hub)
8. [计费与资源模块 (Billing & Resources)](#计费与资源模块-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`](../services/mcp-server/app/routes/auth.py:42) |

**请求参数**:
```json
{
  "email": "string",      // 用户邮箱
  "password": "string",   // 用户密码
  "role": "user"          // 角色类型，固定为 "user"
}
```

**响应示例**:
```json
{
  "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`](../services/mcp-server/app/routes/auth.py:173) |

**请求头**:
```
Authorization: Bearer <token>
```

**响应示例**:
```json
{
  "success": true,
  "message": "登出成功"
}
```

---

### B3. 刷新Token接口 ✅ 已对接

| 项目 | 说明 |
|------|------|
| **前端需求路径** | `POST /api/auth/refresh` |
| **后端实际路径** | `POST /api/auth/refresh` |
| **状态** | ✅ 完全匹配 |
| **后端文件** | [`services/mcp-server/app/routes/auth.py`](../services/mcp-server/app/routes/auth.py:212) |

**响应示例**:
```json
{
  "success": true,
  "data": {
    "token": "新的JWT访问令牌",
    "refreshToken": "新的刷新令牌"
  }
}
```

---

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

| 项目 | 说明 |
|------|------|
| **前端需求路径** | `PUT /api/auth/password` |
| **后端实际路径** | `PUT /api/auth/password` |
| **状态** | ✅ 完全匹配 |
| **后端文件** | [`services/mcp-server/app/routes/auth.py`](../services/mcp-server/app/routes/auth.py:250) |

**请求参数**:
```json
{
  "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`](../services/mcp-server/app/routes/auth.py:344) |

**响应示例**:
```json
{
  "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`](../services/mcp-server/app/routes/auth.py:289) |

**响应示例**:
```json
{
  "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`](../services/mcp-server/app/routes/user.py:105) |

**响应示例**:
```json
{
  "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`](../services/mcp-server/app/routes/monitoring.py:63) |

**响应示例**:
```json
{
  "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`](../services/mcp-server/app/routes/user.py:658) |

**响应示例**:
```json
{
  "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`](../services/mcp-server/app/routes/monitoring.py:36) |

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| 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`](../services/mcp-server/app/routes/user.py:208) |

**请求参数**:
```json
{
  "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`](../services/mcp-server/app/routes/user.py:192) |

**请求参数**:
```json
{
  "gatewayType": "MCP"  // 网关类型：MCP, A2A, API
}
```

---

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

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

**响应示例**:
```json
{
  "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`](../services/mcp-server/app/routes/user.py:264) |

**响应示例**:
```json
{
  "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`](../services/mcp-server/app/routes/providers.py:62) |

**注意**: 此接口需要 `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`](../services/mcp-server/app/routes/user.py:348) |

**请求参数**:
```json
{
  "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`](../services/mcp-server/app/routes/user.py:436) |

**请求参数**:
```json
{
  "name": "string",    // 模板名称
  "type": "string",    // 模板类型：json_api, cloud_storage
  "config": {}         // 配置信息
}
```

---

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

| 项目 | 说明 |
|------|------|
| **前端需求路径** | `GET /tools` |
| **后端实际路径** | `GET /tools` |
| **状态** | ✅ 完全匹配 |
| **后端文件** | [`services/mcp-server/app/routes/tools.py`](../services/mcp-server/app/routes/tools.py:22) |

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

**响应示例**:
```json
{
  "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`](../services/data-ingestion/app/routes/stats.py:14) |

**响应示例**:
```json
{
  "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`](../services/mcp-server/app/routes/user.py:497) |

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

**响应示例**:
```json
{
  "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`](../services/mcp-server/app/routes/user.py:1114) |

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

**请求参数**:
```json
{
  "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`](../services/mcp-server/app/routes/user.py:466) |

**响应示例**:
```json
{
  "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`](../services/mcp-server/app/routes/agents.py:389) |

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| 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`](../services/mcp-server/app/routes/user.py:1457) |

**前端需要调整**: 将 `/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`](../services/mcp-server/app/routes/user.py:616) |

**请求参数**:
```json
{
  "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` 中未找到工作流运行接口的实现。需要后端补充实现。

**建议实现**:
```python
@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` 中未找到工作流列表接口的实现。需要后端补充实现。

**建议实现**:
```python
@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`](../services/mcp-server/app/routes/user.py:697) |

**请求参数**:
```json
{
  "amount": 100.00,           // 充值金额
  "paymentMethod": "alipay"   // 支付方式：alipay, wechat, card（可选）
}
```

**响应示例**:
```json
{
  "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`](../services/mcp-server/app/routes/user.py:736) |

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

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| startTime | string | 是 | 开始时间（ISO格式） |
| endTime | string | 是 | 结束时间（ISO格式） |
| export | string | 是 | 导出格式：excel, csv, pdf |

**响应示例**:
```json
{
  "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. 计费余额接口](#d4-计费余额接口--已对接)

---

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

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

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

**响应示例**:
```json
{
  "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 | 初始版本，完成前后端接口核实 |