diff --git a/Docs/前后端调试说明/API文档/01-认证与授权.md b/Docs/前后端调试说明/API文档/01-认证与授权.md new file mode 100644 index 0000000..b0a35ca --- /dev/null +++ b/Docs/前后端调试说明/API文档/01-认证与授权.md @@ -0,0 +1,306 @@ +# 认证与授权 API + +**基础URL**: `http://localhost:8002/api/auth` + +--- + +## 目录 + +1. [认证方式](#认证方式) +2. [权限角色](#权限角色) +3. [权限矩阵](#权限矩阵) +4. [认证模块 API](#认证模块-api) +5. [豁免路径](#豁免路径) + +--- + +## 认证方式 + +系统支持两种认证方式： + +### 1. JWT Bearer Token认证 + +- 通过 `/api/auth/login` 登录获取token +- 在请求头中携带: `Authorization: Bearer ` +- Token有效期: 24小时 + +### 2. API Key认证 + +- 通过 `/api/auth/keys/info` 获取API密钥 +- 在请求头中携带: `X-API-Key: ` +- API Key格式: `sk-xxxx...` + +--- + +## 权限角色 + +系统支持以下角色： + +| 角色 | 说明 | 登录role参数 | +|------|------|-------------| +| super_admin | 超级管理员 | super_admin | +| billing_admin | 计费管理员 | billing_admin | +| operations_admin | 运维管理员 | operations_admin | +| channel_admin | 渠道管理员 | channel | +| provider_admin | 供应商管理员 | provider | +| user | 租户用户 | user | + +--- + +## 权限矩阵 + +| 操作 | super_admin | billing_admin | operations_admin | channel_admin | +|------|:-----------:|:-------------:|:----------------:|:-------------:| +| **管理员管理** | +| 查看管理员列表 | ✅ | ❌ | ❌ | ❌ | +| 创建管理员 | ✅ | ❌ | ❌ | ❌ | +| 删除管理员 | ✅ | ❌ | ❌ | ❌ | +| **渠道管理** | +| 查看渠道列表 | ✅ | ✅ | ✅ | ❌ | +| 创建渠道 | ✅ | ✅ | ❌ | ❌ | +| 编辑渠道 | ✅ | ✅ | ❌ | ❌ | +| 删除渠道 | ✅ | ✅ | ❌ | ❌ | +| **资源管理** | +| 查看资源 | ✅ | ✅ | ✅ | ✅ | +| 分配资源 | ✅ | ✅ | ❌ | ✅ | +| 配置Agent | ✅ | ✅ | ❌ | ❌ | +| **计费管理** | +| 查看计费记录 | ✅ | ✅ | ✅ | ✅ | +| 执行充值 | ✅ | ✅ | ❌ | ✅ | +| **监控** | +| 查看系统监控 | ✅ | ✅ | ✅ | ❌ | +| 查看Agent状态 | ✅ | ✅ | ✅ | ❌ | +| **申请审批** | +| 查看申请 | ✅ | ✅ | ✅ | ❌ | +| 审批申请 | ✅ | ✅ | ❌ | ❌ | + +> **权限层级**: super_admin > billing_admin > operations_admin > channel_admin > user + +--- + +## 认证模块 API + +### 1. 用户登录 + +**POST** `/api/auth/login` + +支持七种角色登录： + +| 角色参数 | 说明 | 登录实体 | +|---------|------|---------| +| `user` | 租户用户 | users表中role=user的用户 | +| `channel` | 渠道管理员 | channels表中的渠道账号 | +| `billing_admin` | 计费管理员 | users表中role=billing_admin的用户 | +| `operations_admin` | 运营管理员 | users表中role=operations_admin的用户 | +| `admin` | 管理员 | users表中role=admin的用户 | +| `super_admin` | 超级管理员 | users表中role=super_admin的用户 | +| `provider` | 供应商管理员 | users表中role=provider_admin的用户 | + +**请求体**: +```json +{ + "email": "superadmin@taiji-ai.com", + "password": "Admin@123456", + "role": "super_admin" +} +``` + +**curl示例**: +```bash +# 超级管理员登录 +curl -s -X POST "http://localhost:8002/api/auth/login" \ + -H "Content-Type: application/json" \ + -d '{"email":"superadmin@taiji-ai.com","password":"Admin@123456","role":"super_admin"}' + +# 渠道管理员登录 +curl -s -X POST "http://localhost:8002/api/auth/login" \ + -H "Content-Type: application/json" \ + -d '{"email":"channel-alpha@test.com","password":"Channel@123456","role":"channel"}' + +# 租户用户登录 +curl -s -X POST "http://localhost:8002/api/auth/login" \ + -H "Content-Type: application/json" \ + -d '{"email":"zhangsan@company.com","password":"User@123456","role":"user"}' +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "user": { + "id": "d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b", + "name": "超级管理员", + "email": "superadmin@taiji-ai.com", + "role": "super_admin", + "channelId": null + } + } +} +``` + +**渠道登录响应示例**: +```json +{ + "success": true, + "data": { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "user": { + "id": "2c1a76d5-9f22-48bc-a5db-8b18b04c5c0b", + "name": "测试渠道Alpha", + "email": "channel-alpha@test.com", + "role": "channel_admin", + "channelId": "2c1a76d5-9f22-48bc-a5db-8b18b04c5c0b" + } + } +} +``` + +--- + +### 2. 用户登出 + +**POST** `/api/auth/logout` + +**请求头**: +- `Authorization: Bearer ` + +**响应示例**: +```json +{ + "success": true, + "message": "登出成功" +} +``` + +--- + +### 3. 刷新Token + +**POST** `/api/auth/refresh` + +**请求头**: +- `Authorization: Bearer ` + +**响应示例**: +```json +{ + "success": true, + "data": { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." + } +} +``` + +--- + +### 4. 修改密码 + +**PUT** `/api/auth/password` + +**请求头**: +- `Authorization: Bearer ` + +**请求体**: +```json +{ + "old_password": "admin123", + "new_password": "newpassword456" +} +``` + +**响应示例**: +```json +{ + "success": true, + "message": "密码修改成功" +} +``` + +--- + +### 5. 获取API密钥信息 + +**GET** `/api/auth/keys/info` + +获取当前用户的API密钥信息（部分隐藏） + +**请求头**: +- `Authorization: Bearer ` + +**响应示例**: +```json +{ + "success": true, + "data": { + "endpoint": "https://api.taiji-ai.com/v1", + "apiKey": "sk-xxxx...xxxx", + "createdAt": "2025-12-25T05:00:00Z", + "lastUsed": "2025-12-25T10:30:00Z" + } +} +``` + +--- + +### 6. 重新生成API密钥 + +**POST** `/api/auth/keys/regenerate` + +重新生成API密钥，旧密钥将立即失效 + +**请求头**: +- `Authorization: Bearer ` + +**响应示例**: +```json +{ + "success": true, + "data": { + "apiKey": "sk-aBcD1234EfGh5678IjKl9012MnOp3456", + "message": "旧密钥已失效" + } +} +``` + +--- + +## 豁免路径 + +以下路径无需认证即可访问： +- `/health` - 健康检查 +- `/metrics` - Prometheus指标 +- `/docs` - Swagger文档 +- `/redoc` - ReDoc文档 +- `/openapi.json` - OpenAPI规范 +- `/api/auth/login` - 登录接口 + +--- + +## 使用示例 + +### 使用JWT Token + +```bash +# 1. 登录获取token +TOKEN=$(curl -s -X POST "http://localhost:8002/api/auth/login" \ + -H "Content-Type: application/json" \ + -d '{"email":"admin@taiji-ai.com","password":"admin123","role":"user"}' \ + | jq -r '.data.token') + +# 2. 使用token访问API +curl -X GET "http://localhost:8002/api/user/dashboard/stats" \ + -H "Authorization: Bearer $TOKEN" +``` + +### 使用API Key + +```bash +curl -X GET "http://localhost:8002/api/user/dashboard/stats" \ + -H "X-API-Key: sk-aBcD1234EfGh5678IjKl9012MnOp3456" +``` + diff --git a/Docs/前后端调试说明/API文档/02-Data-Ingestion服务.md b/Docs/前后端调试说明/API文档/02-Data-Ingestion服务.md new file mode 100644 index 0000000..afcef44 --- /dev/null +++ b/Docs/前后端调试说明/API文档/02-Data-Ingestion服务.md @@ -0,0 +1,401 @@ +# Data Ingestion 服务 API + +**基础URL**: `http://localhost:8001` + +--- + +## 目录 + +1. [健康检查](#1-健康检查) +2. [RapidAPI 同步](#2-同步-rapidapi-端点) +3. [RapidAPI 测试](#3-测试-rapidapi-端点) +4. [OpenAPI 解析](#4-解析-openapi-规范) +5. [APILLAMA 处理](#5-apillama-处理-api-文档) +6. [工具生成](#6-生成工具定义) +7. [工具管理](#7-获取工具列表) +8. [统计信息](#10-获取统计信息) +9. [缓存管理](#11-清除缓存) +10. [Prometheus Metrics](#12-prometheus-metrics) + +--- + +## 1. 健康检查 + +**GET** `/health` + +检查服务健康状态。 + +**请求示例**: +```bash +curl -X GET "http://localhost:8001/health" +``` + +**响应示例**: +```json +{ + "status": "healthy", + "timestamp": "2025-12-25T05:04:23.211960", + "services": { + "data_ingestion": "healthy", + "redis": "healthy", + "nats": "healthy", + "rapidapi": "healthy", + "apillama": "healthy" + }, + "stats": { + "total_apis": 0, + "processed_apis": 0, + "generated_tools": 20, + "cache_size": 44 + } +} +``` + +--- + +## 2. 同步 RapidAPI 端点 + +**POST** `/rapidapi/sync` + +同步 RapidAPI 端点列表（后台任务）。 + +**查询参数**: +- `category` (string, 可选): API 分类 +- `limit` (int, 可选, 默认: 100): 同步数量限制 + +**请求示例**: +```bash +curl -X POST "http://localhost:8001/rapidapi/sync?category=weather&limit=50" +``` + +**响应示例**: +```json +{ + "message": "RapidAPI端点同步已启动", + "category": "weather", + "limit": 50 +} +``` + +--- + +## 3. 测试 RapidAPI 端点 + +**POST** `/rapidapi/test` + +测试 RapidAPI 端点调用。 + +**请求体**: +```json +{ + "endpoint": "https://rapidapi.com/api/weather/v1/current", + "method": "GET", + "params": { + "location": "Beijing" + }, + "headers": { + "X-Custom-Header": "value" + } +} +``` + +**响应示例**: +```json +{ + "success": true, + "status_code": 200, + "data": { + "temperature": 25, + "condition": "sunny" + }, + "response_time": 123.45, + "headers": { + "content-type": "application/json" + } +} +``` + +--- + +## 4. 解析 OpenAPI 规范 + +**POST** `/openapi/parse` + +解析 OpenAPI/Swagger 规范文档，并后台生成工具。 + +**查询参数**: +- `url` (string, 必需): OpenAPI 文档 URL + +**请求示例**: +```bash +curl -X POST "http://localhost:8001/openapi/parse?url=https://api.example.com/openapi.json" +``` + +**响应示例**: +```json +{ + "url": "https://api.example.com/openapi.json", + "title": "Example API", + "version": "1.0.0", + "endpoints_count": 15, + "schemas_count": 8, + "parsed_data": { + "version": "3.0.0", + "info": { + "title": "Example API", + "version": "1.0.0" + }, + "paths": {}, + "parsed": true + }, + "parsing_time": 0.234 +} +``` + +--- + +## 5. APILLAMA 处理 API 文档 + +**POST** `/apillama/process` + +使用 APILLAMA 处理 API 文档，生成结构化 Schema。 + +**请求体**: +```json +{ + "api_doc": { + "title": "Weather API", + "description": "Get weather information", + "parameters": [ + { + "name": "location", + "type": "string", + "description": "City name", + "required": true + } + ] + }, + "context": { + "service": "Weather service" + }, + "output_format": "json_schema", + "include_examples": true, + "enhance_descriptions": true, + "validate_schema": true +} +``` + +**请求参数说明**: +- `api_doc` (string | object, 必需): API 文档 +- `context` (object, 可选): 上下文信息 +- `output_format` (string, 可选): 输出格式 (`pydantic`, `json_schema`, `openapi`) +- `include_examples` (bool, 可选): 是否生成示例 +- `enhance_descriptions` (bool, 可选): 是否增强描述 +- `validate_schema` (bool, 可选): 是否校验 Schema + +**响应示例**: +```json +{ + "processed": true, + "output_format": "json_schema", + "schema": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "City name" + } + }, + "required": ["location"] + }, + "description": "Weather API for getting current weather information", + "parameters": [], + "examples": [], + "processing_time": 1.234, + "confidence_score": 0.95, + "completeness_score": 0.88 +} +``` + +--- + +## 6. 生成工具定义 + +**POST** `/tools/generate` + +从 API 端点生成工具定义（后台任务）。 + +**请求体**: +```json +{ + "url": "https://api.example.com/users", + "method": "GET", + "name": "get_users", + "description": "Get list of users", + "parameters": [ + { + "name": "page", + "type": "integer", + "location": "query", + "required": false + } + ], + "responses": {}, + "security": [], + "tags": ["users"] +} +``` + +**响应示例**: +```json +{ + "message": "工具生成任务已启动", + "endpoint": "https://api.example.com/users", + "method": "GET" +} +``` + +--- + +## 7. 获取工具列表 + +**GET** `/tools` + +获取已生成的工具列表。 + +**查询参数**: +- `category` (string, 可选): 工具分类 +- `limit` (int, 可选, 默认: 100): 返回数量限制 +- `offset` (int, 可选, 默认: 0): 偏移量 + +**请求示例**: +```bash +curl -X GET "http://localhost:8001/tools?category=weather&limit=20&offset=0" +``` + +**响应示例**: +```json +[ + { + "name": "get_weather", + "description": "Get weather information", + "category": "weather", + "url": "https://api.example.com/weather", + "method": "GET", + "parameters": [], + "created_at": "2025-12-25T05:00:00Z" + } +] +``` + +--- + +## 8. 获取特定工具定义 + +**GET** `/tools/{tool_name}` + +获取特定工具的定义。 + +**请求示例**: +```bash +curl -X GET "http://localhost:8001/tools/get_weather" +``` + +**响应示例**: +```json +{ + "name": "get_weather", + "description": "Get weather information", + "category": "weather", + "url": "https://api.example.com/weather", + "method": "GET", + "parameters": [], + "created_at": "2025-12-25T05:00:00Z" +} +``` + +--- + +## 9. 删除工具 + +**DELETE** `/tools/{tool_name}` + +删除指定的工具定义。 + +**请求示例**: +```bash +curl -X DELETE "http://localhost:8001/tools/get_weather" +``` + +**响应示例**: +```json +{ + "message": "工具 get_weather 已删除" +} +``` + +--- + +## 10. 获取统计信息 + +**GET** `/stats` + +获取服务统计信息。 + +**请求示例**: +```bash +curl -X GET "http://localhost:8001/stats" +``` + +**响应示例**: +```json +{ + "total_apis": 100, + "processed_apis": 85, + "generated_tools": 20, + "failed_processes": 2, + "cache_size": 44, + "last_sync": "2025-12-25T05:00:00Z", + "categories": { + "weather": 15, + "finance": 10, + "general": 5 + } +} +``` + +--- + +## 11. 清除缓存 + +**POST** `/cache/clear` + +清除处理缓存（保留工具注册表）。 + +**请求示例**: +```bash +curl -X POST "http://localhost:8001/cache/clear" +``` + +**响应示例**: +```json +{ + "message": "缓存已清理" +} +``` + +> **说明**: 该端点仅清除处理缓存和失败记录，不会删除已生成的工具定义。 + +--- + +## 12. Prometheus Metrics + +**GET** `/metrics` + +获取 Prometheus 格式的监控指标。 + +**请求示例**: +```bash +curl -X GET "http://localhost:8001/metrics" +``` + diff --git a/Docs/前后端调试说明/API文档/03-MCP-Server服务.md b/Docs/前后端调试说明/API文档/03-MCP-Server服务.md new file mode 100644 index 0000000..19e53b5 --- /dev/null +++ b/Docs/前后端调试说明/API文档/03-MCP-Server服务.md @@ -0,0 +1,487 @@ +# MCP Server 服务 API + +**基础URL**: `http://localhost:8002` + +> **说明**: MCP Server在容器内运行在端口8000，通过Docker映射到主机端口8002。 + +--- + +## 目录 + +1. [健康检查](#1-健康检查) +2. [Agent 管理](#agent-管理) +3. [工具执行](#5-执行-agent-工具) +4. [MCP 监控 API](#mcp-监控-api) +5. [WebSocket API](#websocket-api) + +--- + +## 1. 健康检查 + +**GET** `/health` + +检查 MCP Server 健康状态。 + +**请求示例**: +```bash +curl -X GET "http://localhost:8002/health" +``` + +**响应示例**: +```json +{ + "status": "healthy", + "timestamp": "2025-12-25T05:04:23.211960", + "version": "1.0.0", + "services": { + "database": "healthy", + "redis": "healthy", + "nats": "healthy" + } +} +``` + +--- + +## Agent 管理 + +### 2. 注册 Agent + +**POST** `/agents` + +注册新的 Agent。 + +**请求体**: +```json +{ + "name": "weather-agent", + "description": "Weather information agent", + "role": "assistant", + "goal": "Provide real-time weather summaries", + "tools": ["get_weather"], + "config": { + "default_model": "gpt-4o-mini" + }, + "capabilities": ["weather_query", "location_search"] +} +``` + +**响应示例**: +```json +{ + "id": "d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b", + "name": "weather-agent", + "description": "Weather information agent", + "role": "assistant", + "goal": "Provide real-time weather summaries", + "tools": ["get_weather"], + "capabilities": ["weather_query", "location_search"], + "endpoints": { + "mcp": "mcp://localhost:8002/agents/d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b", + "http": "http://localhost:8002/agents/d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b", + "websocket": "ws://localhost:8002/agents/d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b/ws" + }, + "status": "active", + "version": "1.0.0", + "total_executions": 0, + "success_rate": 0.0, + "avg_execution_time": 0.0, + "created_at": "2025-12-25T05:00:00Z", + "updated_at": "2025-12-25T05:00:00Z" +} +``` + +> **说明**: Agent创建后会自动绑定到测试用户(test_user)，并在Redis中缓存1小时。 + +--- + +### 3. 获取 Agent 列表 + +**GET** `/agents` + +获取所有注册的 Agent 列表。 + +**查询参数**: +- `skip` (int, 可选, 默认: 0): 起始偏移 +- `limit` (int, 可选, 默认: 100): 返回数量限制 + +**请求示例**: +```bash +curl -X GET "http://localhost:8002/agents?skip=0&limit=20" +``` + +**响应示例**: +```json +[ + { + "id": "d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b", + "name": "weather-agent", + "description": "Weather information agent", + "role": "assistant", + "goal": "Provide real-time weather summaries", + "tools": ["get_weather"], + "capabilities": ["weather_query", "location_search"], + "endpoints": {}, + "status": "active", + "version": "1.0.0", + "total_executions": 12, + "success_rate": 96.5, + "avg_execution_time": 0.18, + "created_at": "2025-12-25T05:00:00Z", + "updated_at": "2025-12-25T05:05:00Z" + } +] +``` + +--- + +### 4. 获取特定 Agent + +**GET** `/agents/{agent_id}` + +获取特定 Agent 的详细信息。 + +**请求示例**: +```bash +curl -X GET "http://localhost:8002/agents/d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b" +``` + +**响应示例**: +```json +{ + "id": "d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b", + "name": "weather-agent", + "description": "Weather information agent", + "role": "assistant", + "goal": "Provide real-time weather summaries", + "tools": ["get_weather"], + "capabilities": ["weather_query", "location_search"], + "endpoints": {}, + "status": "active", + "version": "1.0.0", + "total_executions": 12, + "success_rate": 96.5, + "avg_execution_time": 0.18, + "created_at": "2025-12-25T05:00:00Z", + "updated_at": "2025-12-25T05:05:00Z" +} +``` + +--- + +## 5. 执行 Agent 工具 + +**POST** `/agents/{agent_id}/execute` + +执行 Agent 的工具调用。支持API工具、函数工具和LLM工具。 + +**请求体**: +```json +{ + "jsonrpc": "2.0", + "id": "req-001", + "method": "tools/call", + "params": { + "tool": { + "name": "math_add", + "function_name": "math_add" + }, + "arguments": { + "a": 10, + "b": 20 + }, + "context": { + "session_id": "session_123" + } + } +} +``` + +**响应示例**: +```json +{ + "execution_id": "exec-4f1b9c8d", + "success": true, + "result": 30.0, + "error": null, + "execution_time": 0.001, + "cpu_usage": 12.5, + "memory_usage": 64.0, + "network_io": 0.5, + "eu_consumed": 0.01, + "cost": 0.0002, + "started_at": "2025-12-25T05:00:00Z", + "completed_at": "2025-12-25T05:00:00Z" +} +``` + +**可用的函数工具**: + +| 类别 | 工具名称 | +|------|---------| +| 数学函数 | `math_add`, `math_subtract`, `math_multiply`, `math_divide`, `math_power` | +| 字符串函数 | `string_upper`, `string_lower`, `string_length`, `string_replace` | +| 日期时间 | `datetime_now` | +| JSON | `json_parse`, `json_stringify` | +| 哈希 | `hash_md5`, `hash_sha256` | +| Base64 | `base64_encode`, `base64_decode` | + +> **说明**: 执行会自动记录到数据库，并进行EU计费（1 EU = 10秒）。 + +--- + +## 6. 获取工具列表 + +**GET** `/tools` + +当前端点返回空数组（工具清单由 Data Ingestion 服务维护）。 + +**响应示例**: +```json +[] +``` + +--- + +## 7. Prometheus Metrics + +**GET** `/metrics` + +获取 Prometheus 格式的监控指标。 + +**请求示例**: +```bash +curl -X GET "http://localhost:8002/metrics" +``` + +--- + +## MCP 监控 API + +**基础URL**: `http://localhost:8002/api/v1/monitoring` + +### 1. 获取系统性能指标 + +**GET** `/api/v1/monitoring/metrics` + +提供 CPU、内存、磁盘以及核心业务指标。 + +**请求示例**: +```bash +curl -X GET "http://localhost:8002/api/v1/monitoring/metrics" +``` + +**响应示例**: +```json +{ + "timestamp": "2025-12-25T05:10:00Z", + "system": { + "cpu_usage_percent": 42.5, + "memory_usage_percent": 61.2, + "memory_used_mb": 8243.5, + "memory_total_mb": 16384.0, + "disk_usage_percent": 70.1, + "disk_used_gb": 512.3, + "disk_total_gb": 1024.0 + }, + "services": { + "active_agents": 12, + "total_executions_24h": 268, + "success_rate_percent": 97.4, + "avg_execution_time_ms": 143.22, + "daily_active_users": 18 + }, + "billing": { + "total_eu_consumed_24h": 12.42, + "total_cost_24h": 3.87 + } +} +``` + +--- + +### 2. 获取服务统计信息 + +**GET** `/api/v1/monitoring/stats` + +按服务类型返回聚合统计。 + +**查询参数**: +- `service` (string, 可选, 默认: `all`): 可选值 `all`, `agents`, `executions`, `tools`, `users` + +**请求示例**: +```bash +curl -X GET "http://localhost:8002/api/v1/monitoring/stats?service=all" +``` + +**响应示例**: +```json +{ + "timestamp": "2025-12-25T05:10:00Z", + "stats": { + "agents": { + "total": 20, + "active": 18, + "inactive": 2, + "avg_executions": 35.4, + "avg_success_rate": 92.1 + }, + "executions": { + "total_7d": 1260, + "completed": 1210, + "failed": 32, + "running": 18 + } + } +} +``` + +--- + +### 3. 获取性能趋势数据 + +**GET** `/api/v1/monitoring/trends` + +按时间区间返回执行或消耗趋势。 + +**查询参数**: +- `metric` (string, 可选, 默认: `executions`): 可选值 `executions`, `eu_consumption` +- `period` (string, 可选, 默认: `24h`): 可选值 `24h`, `7d`, `30d` +- `interval` (string, 可选, 默认: `1h`): 可选值 `1h`, `6h`, `1d` + +**请求示例**: +```bash +curl -X GET "http://localhost:8002/api/v1/monitoring/trends?metric=executions&period=24h&interval=1h" +``` + +**响应示例**: +```json +{ + "metric": "executions", + "period": "24h", + "interval": "1h", + "data": [ + { + "timestamp": "2025-12-25T00:00:00Z", + "count": 12, + "avg_time_ms": 142.8, + "success_rate": 95.0 + } + ] +} +``` + +--- + +### 4. 获取系统告警 + +**GET** `/api/v1/monitoring/alerts` + +返回当前系统告警列表。 + +**查询参数**: +- `severity` (string, 可选): 过滤严重程度，可选 `info`, `warning`, `critical` + +**请求示例**: +```bash +curl -X GET "http://localhost:8002/api/v1/monitoring/alerts?severity=warning" +``` + +**响应示例**: +```json +{ + "timestamp": "2025-12-25T05:10:00Z", + "alerts": [ + { + "severity": "warning", + "type": "high_cpu", + "message": "CPU使用率过高: 83.2%", + "timestamp": "2025-12-25T05:09:58Z" + } + ], + "count": 1 +} +``` + +--- + +### 5. 获取监控仪表盘聚合 + +**GET** `/api/v1/monitoring/dashboard` + +聚合健康、指标、统计和告警信息。 + +**请求示例**: +```bash +curl -X GET "http://localhost:8002/api/v1/monitoring/dashboard" +``` + +**响应示例**: +```json +{ + "timestamp": "2025-12-25T05:10:00Z", + "health": { + "status": "healthy" + }, + "metrics": { + "system": {} + }, + "stats": {}, + "alerts": { + "items": [], + "count": 0, + "critical_count": 0, + "warning_count": 0 + } +} +``` + +--- + +## WebSocket API + +### MCP Protocol WebSocket + +**WebSocket URL**: `ws://localhost:8002/ws/{agent_name_or_id}` + +**连接示例**: +```javascript +const ws = new WebSocket('ws://localhost:8002/ws/agent_123456'); + +ws.onopen = () => { + ws.send(JSON.stringify({ + "type": "mcp_request", + "payload": { + "method": "tools/list", + "params": {} + } + })); +}; + +ws.onmessage = (event) => { + const data = JSON.parse(event.data); + console.log('Received:', data); +}; +``` + +**消息格式**: +```json +{ + "type": "mcp_request", + "payload": { + "method": "tools/list", + "params": {} + } +} +``` + +**响应格式**: +```json +{ + "type": "mcp_response", + "payload": { + "result": [] + } +} +``` + diff --git a/Docs/前后端调试说明/API文档/04-用户侧平台.md b/Docs/前后端调试说明/API文档/04-用户侧平台.md new file mode 100644 index 0000000..a5e1e98 --- /dev/null +++ b/Docs/前后端调试说明/API文档/04-用户侧平台.md @@ -0,0 +1,427 @@ +# 用户侧平台 API + +**基础URL**: `http://localhost:8002/api/user` + +> **权限说明**: 需要租户用户(user)或更高权限登录 + +--- + +## 目录 + +1. [概览相关](#概览相关) +2. [服务网关相关](#服务网关相关) +3. [数据与工具相关](#数据与工具相关) +4. [代理工厂相关](#代理工厂相关) +5. [编排中心相关](#编排中心相关) +6. [计费与资源相关](#计费与资源相关) + +--- + +## 概览相关 + +### 1. 获取仪表板统计 + +**GET** `/api/user/dashboard/stats` + +**请求头**: +- `Authorization: Bearer ` + +**响应示例**: +```json +{ + "success": true, + "data": { + "activeAgents": 12, + "totalRequests": 1580, + "euBalance": 2450.50, + "systemHealth": 98.5 + } +} +``` + +--- + +### 2. 获取Agent活动数据 + +**GET** `/api/user/agents/activity` + +**查询参数**: +- `period` (string): 时间范围，可选值: `7d`, `30d`, `90d` (默认: `7d`) + +**响应示例**: +```json +{ + "success": true, + "data": { + "data": [ + { + "date": "2025-12-20", + "agentName": "weather-agent", + "requests": 45 + } + ] + } +} +``` + +--- + +## 服务网关相关 + +### 3. 选择网关类型 + +**POST** `/api/user/gateway/select` + +**请求体**: +```json +{ + "gatewayType": "MCP" +} +``` + +**gatewayType可选值**: `MCP`, `A2A`, `API` + +**响应示例**: +```json +{ + "success": true, + "data": { + "gatewayType": "MCP" + }, + "message": "已选择 MCP 网关" +} +``` + +--- + +### 4. 创建网关API + +**POST** `/api/user/gateway/api/create` + +**请求体**: +```json +{ + "name": "weather-api", + "method": "json", + "content": "{\"endpoint\": \"/weather\", \"params\": {\"city\": \"string\"}}" +} +``` + +**method可选值**: `json`, `url` + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "api-uuid-1234", + "name": "weather-api" + }, + "message": "API创建成功" +} +``` + +--- + +### 5. 获取网关API列表 + +**GET** `/api/user/gateway/apis` + +**响应示例**: +```json +{ + "success": true, + "data": { + "apis": [ + { + "id": "api-uuid-1234", + "name": "weather-api", + "method": "json", + "createdAt": "2025-12-25T10:00:00Z" + } + ] + } +} +``` + +--- + +### 6. 获取网关监控数据 + +**GET** `/api/user/gateway/monitoring` + +**响应示例**: +```json +{ + "success": true, + "data": { + "uptime": 99.9, + "requestsPerMinute": 1250, + "averageLatency": 45, + "errorRate": 0.1 + } +} +``` + +--- + +## 数据与工具相关 + +### 7. 生成工具 + +**POST** `/api/user/tools/generate` + +**请求体**: +```json +{ + "name": "calculate-tool", + "description": "数学计算工具", + "frameworkTemplate": "API", + "gateway": "gateway-uuid", + "agentCount": 3, + "cpu": 2.0, + "memory": 4.0, + "maxScale": 10, + "model": "gpt-4o-mini" +} +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "tool-uuid-5678", + "name": "calculate-tool" + }, + "message": "工具生成成功" +} +``` + +--- + +### 8. 创建数据模板 + +**POST** `/api/user/data-templates/create` + +**请求体示例 (JSON API)**: +```json +{ + "name": "orders-api", + "type": "json_api", + "config": { + "apiUrl": "https://api.example.com/orders", + "queryParams": { + "limit": "100" + } + } +} +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "template-uuid-9012", + "name": "orders-api" + }, + "message": "数据模板创建成功" +} +``` + +--- + +## 代理工厂相关 + +### 9. 获取平台Agent列表 + +**GET** `/api/user/agents/platform` + +**响应示例**: +```json +{ + "success": true, + "data": { + "data": [ + { + "id": "agent-uuid-1", + "name": "weather-agent", + "description": "天气查询Agent", + "category": "数据查询", + "cpu": 2.0, + "memory": 4.0, + "status": "available" + } + ] + } +} +``` + +--- + +### 10. 部署Agent + +**POST** `/api/user/agents/deploy` + +**请求体**: +```json +{ + "agentId": "agent-uuid-1", + "instances": 3, + "model": "gpt-4o-mini", + "gateway": "MCP" +} +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "agentId": "agent-uuid-1", + "instances": 3, + "model": "gpt-4o-mini", + "gateway": "MCP", + "userId": "user-uuid" + }, + "message": "Agent weather-agent 部署成功" +} +``` + +--- + +## 编排中心相关 + +### 11. 创建工作流 + +**POST** `/api/user/workflows/create` + +**请求体**: +```json +{ + "name": "订单处理流程", + "description": "自动化订单处理工作流", + "gateway": "MCP", + "nodes": [ + { + "agentId": "agent-uuid-1", + "agentType": "platform", + "agentName": "订单验证Agent", + "order": 1 + } + ] +} +``` + +> **注意**: 工作流最多支持3个节点。 + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "workflow-uuid-3456", + "name": "订单处理流程" + }, + "message": "工作流创建成功" +} +``` + +--- + +## 计费与资源相关 + +### 12. 获取余额信息 + +**GET** `/api/user/billing/balance` + +**响应示例**: +```json +{ + "success": true, + "data": { + "balance": 2450.50, + "monthlySpent": 189.75, + "currency": "CNY" + } +} +``` + +--- + +### 13. 充值余额 + +**POST** `/api/user/billing/recharge` + +**请求体**: +```json +{ + "amount": 500.00, + "paymentMethod": "alipay" +} +``` + +**paymentMethod可选值**: `alipay`, `wechat`, `card` + +**响应示例**: +```json +{ + "success": true, + "data": { + "orderId": "ORD20251225120000abc123", + "amount": 500.00, + "paymentUrl": "https://pay.taiji-ai.com/checkout?order_id=ORD20251225120000abc123", + "status": "pending" + } +} +``` + +--- + +### 14. 获取计费历史 + +**GET** `/api/user/billing/history` + +**查询参数**: +- `startTime` (string, 必需): 开始时间 (ISO 8601) +- `endTime` (string, 必需): 结束时间 (ISO 8601) +- `customerName` (string, 可选): 客户名称筛选 +- `minCalls` (int, 可选): 最小调用次数筛选 +- `maxCalls` (int, 可选): 最大调用次数筛选 +- `export` (string, 可选): 导出格式 (`excel`, `csv`, `pdf`) +- `page` (int, 可选): 页码 (默认: 1) +- `pageSize` (int, 可选): 每页数量 (默认: 20) + +**响应示例（查询）**: +```json +{ + "success": true, + "data": { + "total": 150, + "records": [ + { + "id": "billing-uuid-1", + "timestamp": "2025-12-25T10:30:15Z", + "agentName": "weather-agent", + "duration": 45, + "eu": 5, + "cost": 0.05 + } + ] + } +} +``` + +**响应示例（导出）**: +```json +{ + "success": true, + "data": { + "fileUrl": "https://exports.taiji-ai.com/user-uuid/excel/billing_20251225123000.xlsx", + "format": "excel", + "expiresAt": "2025-12-26T12:30:00Z" + } +} +``` + diff --git a/Docs/前后端调试说明/API文档/05-渠道合作伙伴.md b/Docs/前后端调试说明/API文档/05-渠道合作伙伴.md new file mode 100644 index 0000000..25f5aa4 --- /dev/null +++ b/Docs/前后端调试说明/API文档/05-渠道合作伙伴.md @@ -0,0 +1,337 @@ +# 渠道合作伙伴 API + +**基础URL**: `http://localhost:8002/api/channel` + +> **权限说明**: 需要渠道管理员(channel_admin)或更高权限登录 + +--- + +## 目录 + +1. [租户管理相关](#租户管理相关) +2. [资源申请相关](#资源申请相关) +3. [计费统计相关](#计费统计相关) + +--- + +## 租户管理相关 + +### 1. 获取租户列表 + +**GET** `/api/channel/tenants` + +**响应示例**: +```json +{ + "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" + } + ] + } +} +``` + +--- + +### 2. 创建租户 + +**POST** `/api/channel/tenants/create` + +**请求体**: +```json +{ + "name": "企业客户B", + "email": "contact@company-b.com", + "password": "securepass123", + "subscriptionTier": "enterprise" +} +``` + +**请求参数说明**: +- `name` (string, 必需): 租户名称 +- `email` (string, 必需): 租户邮箱，用于登录 +- `password` (string, 必需): 租户密码 +- `subscriptionTier` (string, 可选): 订阅等级，默认为 `free` + +**subscriptionTier可选值**: `free`, `pro`, `enterprise` + +**curl示例**: +```bash +# 使用渠道管理员token创建租户 +curl -s -X POST "http://localhost:8002/api/channel/tenants/create" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $CHANNEL_TOKEN" \ + -d '{ + "name": "张三", + "email": "zhangsan@company.com", + "password": "User@123456", + "subscriptionTier": "pro" + }' +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "张三", + "email": "zhangsan@company.com" + }, + "message": "租户创建成功" +} +``` + +> **注意**: 创建成功后，租户可使用 `role=user` 登录系统。 + +--- + +### 3. 分配租户资源 + +**PUT** `/api/channel/tenants/{tenant_id}/resources` + +**请求体**: +```json +{ + "agents": [ + { + "agentId": "agent-uuid-1", + "quantity": 10 + } + ], + "models": [ + { + "modelName": "gpt-4o-mini", + "rpm": 60, + "tpm": 60000 + } + ], + "customAgentResources": { + "cpu": 4.0, + "memory": 8.0 + } +} +``` + +**请求参数说明**: +- `agents` (array, 必需): Agent资源分配列表 + - `agentId` (string): Agent的UUID或名称 + - `quantity` (int): 分配数量 +- `models` (array, 必需): 模型资源分配列表 + - `modelName` (string): 模型供应商名称 + - `rpm` (int): 每分钟请求数限制 + - `tpm` (int): 每分钟Token数限制 +- `customAgentResources` (object, 可选): 自定义Agent资源 + - `cpu` (float): CPU核心数 + - `memory` (float): 内存大小(GB) + +**curl示例**: +```bash +# 为租户分配资源 +curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/resources" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $CHANNEL_TOKEN" \ + -d '{ + "agents": [ + {"agentId": "通用助手", "quantity": 5}, + {"agentId": "代码助手", "quantity": 3}, + {"agentId": "数据分析师", "quantity": 2} + ], + "models": [ + {"modelName": "OpenAI", "rpm": 100, "tpm": 100000} + ] + }' +``` + +**响应示例**: +```json +{ + "success": true, + "message": "资源分配成功" +} +``` + +--- + +### 4. 更新租户计费设置 + +**PUT** `/api/channel/tenants/{tenant_id}/billing` + +**请求体**: +```json +{ + "subscriptionTier": "enterprise", + "discount": 15.0 +} +``` + +**请求参数说明**: +- `subscriptionTier` (string, 必需): 订阅等级，可选值：`free`, `pro`, `enterprise` +- `discount` (float, 必需): 折扣比例，0-100之间 + +**curl示例**: +```bash +# 更新租户计费设置 +curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/billing" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $CHANNEL_TOKEN" \ + -d '{"subscriptionTier": "pro", "discount": 10.0}' +``` + +**响应示例**: +```json +{ + "success": true, + "message": "计费设置更新成功" +} +``` + +--- + +### 5. 为租户充值 + +**POST** `/api/channel/tenants/{tenant_id}/recharge` + +**请求体**: +```json +{ + "amount": 1000.00 +} +``` + +**请求参数说明**: +- `amount` (float, 必需): 充值金额，必须大于0 + +**curl示例**: +```bash +# 为租户充值 +curl -s -X POST "http://localhost:8002/api/channel/tenants/${TENANT_ID}/recharge" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $CHANNEL_TOKEN" \ + -d '{"amount": 5000.0}' +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "tenantId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "newBalance": 5000.0, + "rechargeAmount": 5000.0 + } +} +``` + +--- + +### 6. 设置租户授信额度 + +**PUT** `/api/channel/tenants/{tenant_id}/credit` + +**请求体**: +```json +{ + "creditLimit": 5000.00 +} +``` + +**请求参数说明**: +- `creditLimit` (float, 必需): 授信额度，必须大于等于0 + +**curl示例**: +```bash +# 设置租户授信额度 +curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/credit" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $CHANNEL_TOKEN" \ + -d '{"creditLimit": 10000.0}' +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "tenantId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "creditLimit": 10000.0 + } +} +``` + +--- + +## 资源申请相关 + +### 7. 申请资源 + +**POST** `/api/channel/resources/apply` + +**请求体示例（申请模型）**: +```json +{ + "type": "model", + "modelName": "gpt-4", + "rpm": 100, + "tpm": 100000, + "reason": "客户需求增长" +} +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "application-uuid-1", + "status": "pending" + }, + "message": "申请已提交，等待审批" +} +``` + +--- + +## 计费统计相关 + +### 8. 获取渠道计费统计 + +**GET** `/api/channel/billing/stats` + +**查询参数**: +- `startTime` (string, 必需): 开始时间 +- `endTime` (string, 必需): 结束时间 +- `tenantName` (string, 可选): 租户名称筛选 +- `minCalls` (int, 可选): 最小调用次数 +- `maxCalls` (int, 可选): 最大调用次数 +- `export` (string, 可选): 导出格式 + +**响应示例**: +```json +{ + "success": true, + "data": { + "tenantStats": [ + { + "tenantId": "tenant-uuid-1", + "tenantName": "企业客户A", + "calls": 1580, + "totalEU": 158.0, + "totalCost": 158.00 + } + ], + "callRecords": [] + } +} +``` + diff --git a/Docs/前后端调试说明/API文档/06-超级管理员.md b/Docs/前后端调试说明/API文档/06-超级管理员.md new file mode 100644 index 0000000..3a9ce75 --- /dev/null +++ b/Docs/前后端调试说明/API文档/06-超级管理员.md @@ -0,0 +1,661 @@ +# 超级管理员 API + +**基础URL**: `http://localhost:8002/api/admin` + +> **权限说明**: 需要超级管理员(super_admin)、计费管理员(billing_admin)或运维管理员(operations_admin)登录 + +--- + +## 目录 + +1. [概览相关](#概览相关) +2. [管理员管理相关](#管理员管理相关) +3. [渠道管理相关](#渠道管理相关) +4. [申请审批相关](#申请审批相关) +5. [资源管理相关](#资源管理相关) +6. [监控相关](#监控相关) +7. [计费相关（三维度）](#计费相关三维度) +8. [前端集成补充接口](#前端集成补充接口) + +--- + +## 概览相关 + +### 1. 获取平台统计 + +**GET** `/api/admin/dashboard/stats` + +**响应示例**: +```json +{ + "success": true, + "data": { + "totalChannels": 15, + "totalTenants": 85, + "totalAgents": 125, + "totalCalls": 45680, + "totalRevenue": 4568.00 + } +} +``` + +--- + +## 管理员管理相关 + +> **权限说明**: 以下接口仅超级管理员(super_admin)可用 + +### 2. 获取管理员列表 + +**GET** `/api/admin/admins` + +**响应示例**: +```json +{ + "success": true, + "data": { + "admins": [ + { + "id": "admin-uuid-1", + "name": "计费管理员", + "email": "billing@taiji-ai.com", + "role": "billing_admin", + "status": "active", + "createdAt": "2025-12-01T00:00:00Z" + }, + { + "id": "admin-uuid-2", + "name": "运维管理员", + "email": "ops@taiji-ai.com", + "role": "operations_admin", + "status": "active", + "createdAt": "2025-12-01T00:00:00Z" + } + ] + } +} +``` + +--- + +### 3. 创建管理员 + +**POST** `/api/admin/admins/create` + +**请求体**: +```json +{ + "name": "新计费管理员", + "email": "newadmin@taiji-ai.com", + "password": "Admin@123456", + "role": "billing_admin" +} +``` + +**请求参数说明**: +- `name` (string, 必需): 管理员名称 +- `email` (string, 必需): 管理员邮箱，用于登录 +- `password` (string, 必需): 管理员密码 +- `role` (string, 可选): 角色类型，默认为 `billing_admin` + +**role可选值**: + +| 角色 | 说明 | 权限范围 | +|------|------|----------| +| `billing_admin` | 计费管理员 | **完整写入权限**：创建渠道、管理租户、资源分配、计费操作、审批申请 | +| `operations_admin` | 运维管理员 | **只读权限**：查看概览、渠道、租户、资源、计费、监控等 | + +**curl示例**: +```bash +# 使用超级管理员token创建计费管理员 +curl -s -X POST "http://localhost:8002/api/admin/admins/create" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $SUPER_ADMIN_TOKEN" \ + -d '{ + "name": "新计费管理员", + "email": "newadmin@taiji-ai.com", + "password": "Admin@123456", + "role": "billing_admin" + }' +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "新计费管理员", + "email": "newadmin@taiji-ai.com", + "role": "billing_admin" + }, + "message": "管理员创建成功" +} +``` + +> **注意**: +> - 计费管理员(billing_admin)可使用 `role=billing_admin` 登录，拥有完整写入权限 +> - 运维管理员(operations_admin)可使用 `role=operations_admin` 登录，只有只读权限 + +--- + +### 4. 删除管理员 + +**DELETE** `/api/admin/admins/{admin_id}` + +删除管理员（软删除，仅标记为不活跃）。 + +**curl示例**: +```bash +curl -X DELETE "http://localhost:8002/api/admin/admins/admin-uuid-1" \ + -H "Authorization: Bearer $SUPER_ADMIN_TOKEN" +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "admin-uuid-1" + }, + "message": "管理员已删除" +} +``` + +--- + +## 渠道管理相关 + +> **权限说明**: +> - **查看接口 (GET)**: super_admin、billing_admin、operations_admin 都可使用 +> - **写入接口 (POST/PUT/DELETE)**: 仅 super_admin 和 billing_admin 可使用 + +### 5. 获取渠道列表 + +**GET** `/api/admin/channels` + +**响应示例**: +```json +{ + "success": true, + "data": { + "channels": [ + { + "id": "channel-uuid-1", + "name": "合作渠道A", + "email": "partner@channel-a.com", + "commissionRate": 10.0, + "channelCredit": 50000.00, + "customAgentCpu": 2.0, + "customAgentMemory": 4.0, + "status": "active", + "createdAt": "2025-11-01T00:00:00Z" + } + ] + } +} +``` + +--- + +### 6. 创建渠道 + +**POST** `/api/admin/channels/create` + +**请求体**: +```json +{ + "name": "合作渠道B", + "email": "partner@channel-b.com", + "password": "channelpass123", + "commissionRate": 8.0 +} +``` + +**请求参数说明**: +- `name` (string, 必需): 渠道名称 +- `email` (string, 必需): 渠道管理员邮箱，用于登录 +- `password` (string, 必需): 渠道管理员密码 +- `commissionRate` (float, 可选): 佣金比例，0-100之间，默认0 + +**curl示例**: +```bash +# 使用超级管理员token创建渠道 +curl -s -X POST "http://localhost:8002/api/admin/channels/create" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $ADMIN_TOKEN" \ + -d '{ + "name": "测试渠道Alpha", + "email": "channel-alpha@test.com", + "password": "Channel@123456", + "commissionRate": 10.0 + }' +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "2c1a76d5-9f22-48bc-a5db-8b18b04c5c0b", + "name": "测试渠道Alpha", + "email": "channel-alpha@test.com" + }, + "message": "渠道创建成功" +} +``` + +> **注意**: 创建成功后，渠道管理员可使用 `role=channel` 登录系统。 + +--- + +### 7. 更新渠道信息 + +**PUT** `/api/admin/channels/{channel_id}` + +更新渠道的基本信息。 + +**请求体**: +```json +{ + "name": "合作渠道A（更新）", + "email": "new-email@channel-a.com", + "commissionRate": 12.0, + "status": "active" +} +``` + +**请求参数说明**: +- `name` (string, 可选): 渠道名称 +- `email` (string, 可选): 渠道管理员邮箱 +- `commissionRate` (float, 可选): 佣金比例，0-100之间 +- `status` (string, 可选): 状态，`active` 或 `inactive` + +**curl示例**: +```bash +curl -X PUT "http://localhost:8002/api/admin/channels/channel-uuid-1" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $ADMIN_TOKEN" \ + -d '{ + "name": "合作渠道A（更新）", + "commissionRate": 12.0 + }' +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "channel-uuid-1", + "name": "合作渠道A（更新）", + "email": "partner@channel-a.com", + "commissionRate": 12.0, + "status": "active" + }, + "message": "渠道信息更新成功" +} +``` + +--- + +### 8. 删除渠道 + +**DELETE** `/api/admin/channels/{channel_id}` + +删除渠道（软删除，仅标记为不活跃）。如果渠道下有活跃租户，将拒绝删除。 + +**curl示例**: +```bash +curl -X DELETE "http://localhost:8002/api/admin/channels/channel-uuid-1" \ + -H "Authorization: Bearer $ADMIN_TOKEN" +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "channel-uuid-1" + }, + "message": "渠道已删除" +} +``` + +**错误响应（有关联租户）**: +```json +{ + "detail": "渠道下有 5 个活跃租户，无法删除。请先移除或停用所有租户。" +} +``` + +--- + +### 9. 统一管理渠道资源 + +**PUT** `/api/admin/channels/{channel_id}/resources` + +**请求体**: +```json +{ + "models": ["model-provider-uuid-1", "model-provider-uuid-2"], + "agents": [ + { + "agentId": "agent-uuid-1", + "quantity": 50 + } + ], + "customAgentResources": { + "cpu": 4.0, + "memory": 8.0 + }, + "channelCredit": 100000.00 +} +``` + +**响应示例**: +```json +{ + "success": true, + "message": "渠道资源分配成功" +} +``` + +--- + +## 申请审批相关 + +### 10. 获取所有申请 + +**GET** `/api/admin/channels/applications` + +**响应示例**: +```json +{ + "success": true, + "data": { + "data": [ + { + "id": "application-uuid-1", + "channelId": "channel-uuid-1", + "channelName": "合作渠道A", + "type": "model", + "details": { + "modelName": "gpt-4", + "rpm": 100, + "tpm": 100000 + }, + "reason": "客户需求增长", + "status": "pending", + "createdAt": "2025-12-25T09:00:00Z" + } + ] + } +} +``` + +--- + +### 11. 审批申请 + +**PUT** `/api/admin/channels/applications/{application_id}/review` + +**请求体**: +```json +{ + "approved": true, + "reason": "审批通过，已分配资源" +} +``` + +**响应示例**: +```json +{ + "success": true, + "message": "申请已批准" +} +``` + +--- + +## 资源管理相关 + +### 12. 获取所有模型供应商 + +**GET** `/api/admin/resources/models` + +**响应示例**: +```json +{ + "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 + } + ] + } +} +``` + +--- + +### 13. 获取所有Agent资源 + +**GET** `/api/admin/resources/agents` + +**响应示例**: +```json +{ + "success": true, + "data": { + "agents": [ + { + "id": "agent-uuid-1", + "name": "weather-agent", + "type": "platform", + "category": "数据查询", + "cpu": 2.0, + "memory": 4.0, + "status": "active" + } + ] + } +} +``` + +--- + +### 14. 删除Agent资源 + +**DELETE** `/api/admin/resources/agents/{agent_id}` + +删除Agent资源（软删除，仅标记为不活跃）。 + +**curl示例**: +```bash +curl -X DELETE "http://localhost:8002/api/admin/resources/agents/agent-uuid-1" \ + -H "Authorization: Bearer $ADMIN_TOKEN" +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "agent-uuid-1", + "name": "weather-agent" + }, + "message": "Agent资源已删除" +} +``` + +--- + +### 15. 更新Agent资源配置 + +**PUT** `/api/admin/resources/agents/{agent_id}/config` + +更新Agent的资源配置（CPU、内存、最大实例数）。 + +**请求体**: +```json +{ + "cpu": 4.0, + "memory": 8.0, + "maxInstances": 10 +} +``` + +**请求参数说明**: +- `cpu` (float, 可选): CPU核心数，0.1-64之间 +- `memory` (float, 可选): 内存大小(GB)，0.5-256之间 +- `maxInstances` (int, 可选): 最大实例数，1-1000之间 + +**curl示例**: +```bash +curl -X PUT "http://localhost:8002/api/admin/resources/agents/agent-uuid-1/config" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $ADMIN_TOKEN" \ + -d '{ + "cpu": 4.0, + "memory": 8.0, + "maxInstances": 10 + }' +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "agent-uuid-1", + "name": "weather-agent", + "cpu": 4.0, + "memory": 8.0, + "maxInstances": 10 + }, + "message": "Agent资源配置更新成功" +} +``` + +--- + +## 监控相关 + +### 16. 监控Agent健康状态 + +**GET** `/api/admin/monitoring/agents` + +**响应示例**: +```json +{ + "success": true, + "data": { + "agents": [ + { + "id": "agent-uuid-1", + "name": "weather-agent", + "status": "active", + "totalExecutions": 1580, + "successRate": 98.5, + "avgExecutionTime": 145.2, + "cpu": 2.0, + "memory": 4.0 + } + ] + } +} +``` + +--- + +## 计费相关（三维度） + +### 17. 获取三维度计费统计 + +**GET** `/api/admin/billing/overview` + +**查询参数**: +- `startTime` (string, 必需) +- `endTime` (string, 必需) +- `channelName` (string, 可选) +- `tenantName` (string, 可选) +- `minCalls` (int, 可选) +- `maxCalls` (int, 可选) +- `export` (string, 可选) + +**响应示例**: +```json +{ + "success": true, + "data": { + "channelStats": [], + "tenantStats": [], + "callRecords": [] + } +} +``` + +--- + +## 前端集成补充接口 + +为了保证前端在轻量集成场景下可以持续迭代，`services/mcp-server/app/routes/frontend_integration.py` 还暴露了一组直接以 `/api` 前缀对外的超级管理员辅助接口，数据保存在内存 store 中，适合 UI 预览与模拟，调用仍需超级管理员身份。 + +### 18. 获取可用角色列表 + +**GET** `/api/admin/roles` + +返回当前前端可选择的管理员角色列表： + +**响应示例**: +```json +{ + "items": ["billing_admin", "operations_admin", "super_admin"] +} +``` + +### 19. 供应商统计（展示用） + +**GET** `/api/admin/providers/stats` + +读取当前 `ProviderModel` 表，返回供应商数量与模型信息，便于管理台展示： + +**响应示例**（实际数据会根据数据库变动）: +```json +{ + "providers": 2, + "models": [ + { + "id": "provider-uuid-1", + "name": "OpenAI", + "apiUrl": "https://api.openai.com/v1", + "supportedModels": ["gpt-4", "gpt-4o-mini"] + } + ] +} +``` + +### 20. 后台简易渠道统计 + +**GET** `/api/admin/channels/backend/stats` + +从内存 store 中读取渠道数量与资源申请数，用于管理台快速绘图： + +**响应示例**: +```json +{ + "channels": 3, + "applications": 1 +} +``` + diff --git a/Docs/前后端调试说明/API文档/07-计费与资源管理.md b/Docs/前后端调试说明/API文档/07-计费与资源管理.md new file mode 100644 index 0000000..a159524 --- /dev/null +++ b/Docs/前后端调试说明/API文档/07-计费与资源管理.md @@ -0,0 +1,788 @@ +# 计费与资源管理 API + +**基础URL**: `http://localhost:8002/api/billing-admin` + +> **权限说明**: 以下接口需要管理员权限（super_admin、billing_admin、operations_admin） + +--- + +## 目录 + +1. [配额管理](#配额管理) +2. [资源监控](#资源监控) +3. [事件管理](#事件管理) +4. [追踪管理](#追踪管理) +5. [审计日志](#审计日志) +6. [供应商健康检查](#供应商健康检查) +7. [模型定价管理](#模型定价管理) + +--- + +## 配额管理 + +### 1. 获取用户配额信息 + +**GET** `/api/billing-admin/quota/user/{user_id}` + +获取指定用户的配额汇总信息，包括余额、速率限制、活跃预警等。 + +**响应示例**: +```json +{ + "success": true, + "data": { + "hasQuota": true, + "alertType": null, + "balance": { + "balance": 2450.50, + "creditLimit": 5000.00, + "available": 7450.50, + "dailyAvgCost": 85.30, + "estimatedDays": 87.3 + }, + "rateLimit": { + "currentRpm": 12, + "rpmLimit": 60, + "allowed": true + }, + "activeAlerts": 0, + "alerts": [] + } +} +``` + +--- + +### 2. 获取渠道配额信息 + +**GET** `/api/billing-admin/quota/channel/{channel_id}` + +**响应示例**: +```json +{ + "success": true, + "data": { + "hasQuota": true, + "alertType": null, + "channelCredit": 100000.00, + "monthlyUsage": 15680.50, + "usagePercent": 15.68 + } +} +``` + +--- + +### 3. 获取配额预警列表 + +**GET** `/api/billing-admin/quota/alerts` + +**查询参数**: +- `user_id` (string, 可选): 用户ID筛选 +- `channel_id` (string, 可选): 渠道ID筛选 + +**响应示例**: +```json +{ + "success": true, + "data": { + "alerts": [ + { + "id": "alert-uuid-1", + "alertType": "balance_warning", + "thresholdPercent": 20, + "currentValue": 150.00, + "thresholdValue": 200.00, + "status": "active", + "createdAt": "2025-12-26T10:00:00Z" + } + ], + "count": 1 + } +} +``` + +--- + +### 4. 确认配额预警 + +**PUT** `/api/billing-admin/quota/alerts/{alert_id}/acknowledge` + +**响应示例**: +```json +{ + "success": true, + "message": "预警已确认" +} +``` + +--- + +### 5. 解决配额预警 + +**PUT** `/api/billing-admin/quota/alerts/{alert_id}/resolve` + +**响应示例**: +```json +{ + "success": true, + "message": "预警已解决" +} +``` + +--- + +## 资源监控 + +### 6. 获取平台资源概览 + +**GET** `/api/billing-admin/resources/overview` + +获取平台整体资源使用概览（管理员视图）。 + +**响应示例**: +```json +{ + "success": true, + "data": { + "todayCalls": 1580, + "monthCalls": 45680, + "activeUsersToday": 85, + "activeAgents": 125, + "monthTotalEu": 4568, + "timestamp": "2025-12-26T12:00:00Z" + } +} +``` + +--- + +### 7. 获取用户资源使用汇总 + +**GET** `/api/billing-admin/resources/user/{user_id}` + +**查询参数**: +- `start_date` (string, 必需): 开始日期 (ISO 8601) +- `end_date` (string, 必需): 结束日期 (ISO 8601) + +**响应示例**: +```json +{ + "success": true, + "data": { + "totalCpuSeconds": 12580.5, + "totalMemoryMbSeconds": 458720.0, + "totalNetworkBytes": 156800000, + "totalStorageBytes": 52428800, + "totalApiCalls": 1580, + "startDate": "2025-12-01T00:00:00Z", + "endDate": "2025-12-26T23:59:59Z" + } +} +``` + +--- + +### 8. 获取资源使用趋势 + +**GET** `/api/billing-admin/resources/trends` + +**查询参数**: +- `user_id` (string, 必需): 用户ID +- `period` (string, 可选): 时间范围，可选值: `7d`, `30d`, `90d` (默认: `7d`) +- `granularity` (string, 可选): 粒度，可选值: `hourly`, `daily` (默认: `daily`) + +**响应示例**: +```json +{ + "success": true, + "data": { + "trends": [ + { + "periodStart": "2025-12-25T00:00:00Z", + "periodEnd": "2025-12-25T23:59:59Z", + "cpuSeconds": 458.5, + "memoryMbSeconds": 16720.0, + "networkBytes": 5680000, + "apiCalls": 58 + } + ] + } +} +``` + +--- + +### 9. 获取Agent资源统计 + +**GET** `/api/billing-admin/resources/agent/{agent_id}` + +**查询参数**: +- `start_date` (string, 必需): 开始日期 +- `end_date` (string, 必需): 结束日期 + +**响应示例**: +```json +{ + "success": true, + "data": { + "agentId": "agent-uuid-1", + "totalExecutions": 1580, + "avgExecutionTime": 145.2, + "totalEuConsumed": 158.0, + "successRate": 98.5, + "startDate": "2025-12-01T00:00:00Z", + "endDate": "2025-12-26T23:59:59Z" + } +} +``` + +--- + +## 事件管理 + +### 10. 获取待处理事件 + +**GET** `/api/billing-admin/events/pending` + +获取待处理的计费事件列表。 + +**查询参数**: +- `limit` (int, 可选): 返回数量限制 (默认: 100, 最大: 1000) + +**响应示例**: +```json +{ + "success": true, + "data": { + "events": [ + { + "id": "event-uuid-1", + "eventId": "evt_abc123", + "eventType": "execution.end", + "userId": "user-uuid-1", + "agentId": "agent-uuid-1", + "payload": { + "success": true, + "duration_ms": 1250, + "eu_consumed": 0.13 + }, + "status": "pending", + "createdAt": "2025-12-26T12:00:00Z" + } + ], + "count": 1 + } +} +``` + +--- + +### 11. 重试失败事件 + +**POST** `/api/billing-admin/events/retry-failed` + +**查询参数**: +- `max_retries` (int, 可选): 最大重试次数 (默认: 3, 最大: 10) + +**响应示例**: +```json +{ + "success": true, + "data": { + "retriedCount": 5 + }, + "message": "已重试 5 个事件" +} +``` + +--- + +### 12. 获取事件统计 + +**GET** `/api/billing-admin/events/stats` + +**查询参数**: +- `start_date` (string, 必需): 开始日期 +- `end_date` (string, 必需): 结束日期 + +**响应示例**: +```json +{ + "success": true, + "data": { + "startDate": "2025-12-01T00:00:00Z", + "endDate": "2025-12-26T23:59:59Z", + "byStatus": { + "completed": 4520, + "pending": 15, + "failed": 3 + }, + "byType": { + "execution.end": 4200, + "execution.start": 4200, + "balance.deduct": 138 + }, + "total": 4538 + } +} +``` + +--- + +## 追踪管理 + +### 13. 获取执行追踪详情 + +**GET** `/api/billing-admin/traces/execution/{execution_id}` + +获取单个执行的完整追踪信息。 + +**响应示例**: +```json +{ + "success": true, + "data": { + "executionId": "exec-uuid-1", + "traceId": "trace-abc123", + "spans": [ + { + "spanId": "span-1", + "parentSpanId": null, + "operationName": "agent_execute", + "operationType": "agent_call", + "startedAt": "2025-12-26T12:00:00Z", + "endedAt": "2025-12-26T12:00:01.250Z", + "durationMs": 1250, + "status": "success", + "inputData": {"prompt": "***REDACTED***"}, + "outputData": {"result": "..."}, + "tokensUsed": 450, + "euConsumed": 0.13 + } + ], + "totalDurationMs": 1250, + "totalEuConsumed": 0.13, + "spanCount": 1 + } +} +``` + +--- + +### 14. 查询追踪记录 + +**GET** `/api/billing-admin/traces` + +**查询参数**: +- `user_id` (string, 可选): 用户ID筛选 +- `agent_id` (string, 可选): Agent ID筛选 +- `status` (string, 可选): 状态筛选 (`running`, `success`, `error`) +- `start_date` (string, 可选): 开始日期 +- `end_date` (string, 可选): 结束日期 +- `page` (int, 可选): 页码 (默认: 1) +- `page_size` (int, 可选): 每页数量 (默认: 20, 最大: 100) + +**响应示例**: +```json +{ + "success": true, + "data": { + "total": 150, + "page": 1, + "pageSize": 20, + "totalPages": 8, + "traces": [ + { + "traceId": "trace-abc123", + "executionId": "exec-uuid-1", + "agentId": "agent-uuid-1", + "agentName": "weather-agent", + "userId": "user-uuid-1", + "startedAt": "2025-12-26T12:00:00Z", + "endedAt": "2025-12-26T12:00:01.250Z", + "durationMs": 1250, + "spanCount": 3, + "totalTokens": 450, + "totalEu": 0.13 + } + ] + } +} +``` + +--- + +### 15. 获取追踪统计 + +**GET** `/api/billing-admin/traces/stats` + +**查询参数**: +- `user_id` (string, 可选): 用户ID筛选 +- `start_date` (string, 必需): 开始日期 +- `end_date` (string, 必需): 结束日期 + +**响应示例**: +```json +{ + "success": true, + "data": { + "startDate": "2025-12-01T00:00:00Z", + "endDate": "2025-12-26T23:59:59Z", + "totalTraces": 4200, + "totalSpans": 12600, + "totalDurationMs": 5250000, + "avgDurationMs": 1250.0, + "totalTokens": 1890000, + "totalEu": 546.0, + "byStatus": { + "success": 4150, + "error": 50 + }, + "byOperationType": [ + {"operationType": "agent_call", "count": 4200, "avgDurationMs": 850.0}, + {"operationType": "tool_call", "count": 6300, "avgDurationMs": 120.5}, + {"operationType": "llm_call", "count": 2100, "avgDurationMs": 980.0} + ] + } +} +``` + +--- + +## 审计日志 + +### 16. 查询审计日志 + +**GET** `/api/billing-admin/audit/logs` + +**查询参数**: +- `user_id` (string, 可选): 用户ID筛选 +- `action` (string, 可选): 操作类型筛选 +- `resource_type` (string, 可选): 资源类型筛选 +- `success` (bool, 可选): 成功/失败筛选 +- `start_date` (string, 可选): 开始日期 +- `end_date` (string, 可选): 结束日期 +- `page` (int, 可选): 页码 (默认: 1) +- `page_size` (int, 可选): 每页数量 (默认: 20, 最大: 100) + +**可用的action类型**: + +| 操作类型 | 说明 | +|---------|------| +| `auth.login` | 用户登录 | +| `auth.logout` | 用户登出 | +| `auth.password_change` | 密码修改 | +| `user.create` | 创建用户 | +| `user.update` | 更新用户 | +| `user.delete` | 删除用户 | +| `channel.create` | 创建渠道 | +| `channel.update` | 更新渠道 | +| `channel.delete` | 删除渠道 | +| `agent.create` | 创建Agent | +| `agent.delete` | 删除Agent | +| `application.approve` | 审批通过 | +| `application.reject` | 审批拒绝 | +| `billing.charge` | 计费扣款 | +| `provider.pricing_update` | 更新模型定价 | + +**响应示例**: +```json +{ + "success": true, + "data": { + "total": 500, + "page": 1, + "pageSize": 20, + "totalPages": 25, + "logs": [ + { + "id": "log-uuid-1", + "action": "channel.create", + "actionName": "创建渠道", + "resourceType": "channel", + "resourceId": "channel-uuid-1", + "userId": "admin-uuid-1", + "userName": "超级管理员", + "success": true, + "details": {"channelName": "合作渠道A"}, + "errorMessage": null, + "ipAddress": "192.168.1.100", + "createdAt": "2025-12-26T10:00:00Z" + } + ] + } +} +``` + +--- + +### 17. 获取审计日志汇总 + +**GET** `/api/billing-admin/audit/summary` + +**查询参数**: +- `start_date` (string, 必需): 开始日期 +- `end_date` (string, 必需): 结束日期 + +**响应示例**: +```json +{ + "success": true, + "data": { + "startDate": "2025-12-01T00:00:00Z", + "endDate": "2025-12-26T23:59:59Z", + "total": 1580, + "successTotal": 1550, + "failTotal": 30, + "byAction": [ + {"action": "auth.login", "actionName": "用户登录", "count": 850, "successCount": 820, "failCount": 30}, + {"action": "agent.create", "actionName": "创建Agent", "count": 45, "successCount": 45, "failCount": 0} + ], + "byResourceType": [ + {"resourceType": "user", "count": 520}, + {"resourceType": "agent", "count": 380}, + {"resourceType": "channel", "count": 150} + ] + } +} +``` + +--- + +### 18. 获取用户活动历史 + +**GET** `/api/billing-admin/audit/user/{user_id}/activity` + +**查询参数**: +- `days` (int, 可选): 天数 (默认: 30, 最大: 90) + +**响应示例**: +```json +{ + "success": true, + "data": { + "activity": [ + { + "action": "auth.login", + "actionName": "用户登录", + "resourceType": "user", + "resourceId": "user-uuid-1", + "success": true, + "ipAddress": "192.168.1.100", + "createdAt": "2025-12-26T08:00:00Z" + } + ] + } +} +``` + +--- + +## 供应商健康检查 + +### 19. 获取所有供应商健康状态 + +**GET** `/api/billing-admin/providers/health` + +**响应示例**: +```json +{ + "success": true, + "data": { + "providers": [ + { + "providerId": "provider-uuid-1", + "providerName": "OpenAI", + "provider": "openai", + "status": "active", + "isHealthy": true, + "lastResponseTimeMs": 45, + "lastCheckAt": "2025-12-26T12:00:00Z", + "uptime24h": 99.9 + } + ] + } +} +``` + +--- + +### 20. 获取供应商健康详情 + +**GET** `/api/billing-admin/providers/{provider_id}/health` + +**查询参数**: +- `hours` (int, 可选): 统计时间范围 (默认: 24, 最大: 168) + +**响应示例**: +```json +{ + "success": true, + "data": { + "providerId": "provider-uuid-1", + "providerName": "OpenAI", + "currentStatus": "active", + "period": "24h", + "totalChecks": 1440, + "healthyCount": 1438, + "unhealthyCount": 2, + "uptimePercent": 99.86, + "avgResponseTimeMs": 42.5, + "maxResponseTimeMs": 180, + "minResponseTimeMs": 25, + "recentChecks": [ + { + "isHealthy": true, + "responseTimeMs": 45, + "statusCode": 200, + "errorMessage": null, + "createdAt": "2025-12-26T12:00:00Z" + } + ] + } +} +``` + +--- + +### 21. 执行供应商健康检查 + +**POST** `/api/billing-admin/providers/health-check` + +立即执行所有供应商的健康检查。 + +**响应示例**: +```json +{ + "success": true, + "data": { + "timestamp": "2025-12-26T12:00:00Z", + "totalProviders": 3, + "healthyCount": 3, + "unhealthyCount": 0, + "checks": [ + { + "providerId": "provider-uuid-1", + "providerName": "OpenAI", + "isHealthy": true, + "responseTimeMs": 45, + "statusCode": 200, + "errorMessage": null + } + ] + } +} +``` + +--- + +## 模型定价管理 + +### 22. 获取模型定价列表 + +**GET** `/api/billing-admin/pricing/models` + +**查询参数**: +- `provider_id` (string, 可选): 供应商ID筛选 +- `model_name` (string, 可选): 模型名称模糊搜索 + +**响应示例**: +```json +{ + "success": true, + "data": { + "pricing": [ + { + "id": "pricing-uuid-1", + "providerId": "provider-uuid-1", + "providerName": "OpenAI", + "modelName": "gpt-4o", + "inputPricePer1k": 0.005, + "outputPricePer1k": 0.015, + "euPer1kTokens": 0.1, + "maxContextLength": 128000, + "maxOutputTokens": 4096, + "isActive": true, + "effectiveFrom": "2025-12-01T00:00:00Z" + } + ] + } +} +``` + +--- + +### 23. 创建/更新模型定价 + +**POST** `/api/billing-admin/pricing/models` + +**请求体**: +```json +{ + "providerId": "provider-uuid-1", + "modelName": "gpt-4o-mini", + "inputPricePer1k": 0.00015, + "outputPricePer1k": 0.0006, + "euPer1kTokens": 0.05, + "maxContextLength": 128000, + "maxOutputTokens": 16384 +} +``` + +**请求参数说明**: +- `providerId` (string, 必需): 供应商ID +- `modelName` (string, 必需): 模型名称 +- `inputPricePer1k` (float, 必需): 输入价格（每1K tokens），单位USD +- `outputPricePer1k` (float, 必需): 输出价格（每1K tokens），单位USD +- `euPer1kTokens` (float, 可选): EU转换率（默认: 0.1） +- `maxContextLength` (int, 可选): 最大上下文长度（默认: 4096） +- `maxOutputTokens` (int, 可选): 最大输出tokens（默认: 2048） + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "pricing-uuid-2", + "modelName": "gpt-4o-mini" + }, + "message": "模型定价已更新" +} +``` + +--- + +### 24. 计算模型调用成本 + +**POST** `/api/billing-admin/pricing/calculate` + +计算指定模型调用的成本预估。 + +**查询参数**: +- `model_name` (string, 必需): 模型名称 +- `input_tokens` (int, 必需): 输入tokens数量 +- `output_tokens` (int, 必需): 输出tokens数量 + +**请求示例**: +```bash +curl -X POST "http://localhost:8002/api/billing-admin/pricing/calculate?model_name=gpt-4o&input_tokens=1000&output_tokens=500" \ + -H "Authorization: Bearer $TOKEN" +``` + +**响应示例**: +```json +{ + "success": true, + "data": { + "modelName": "gpt-4o", + "inputTokens": 1000, + "outputTokens": 500, + "inputCost": 0.005, + "outputCost": 0.0075, + "totalCost": 0.0125, + "euConsumed": 0.15 + } +} +``` + diff --git a/Docs/前后端调试说明/API文档/08-供应商管理.md b/Docs/前后端调试说明/API文档/08-供应商管理.md new file mode 100644 index 0000000..81f8228 --- /dev/null +++ b/Docs/前后端调试说明/API文档/08-供应商管理.md @@ -0,0 +1,239 @@ +# 供应商管理 API + +**基础URL**: `http://localhost:8002/api/providers` + +> **权限说明**: 需要管理员权限 + +--- + +## 目录 + +1. [获取模型供应商列表](#1-获取模型供应商列表) +2. [创建模型供应商](#2-创建模型供应商) +3. [获取供应商详情](#3-获取供应商详情) +4. [更新供应商配置](#4-更新供应商配置) +5. [删除供应商](#5-删除供应商) +6. [测试供应商连接](#6-测试供应商连接) + +--- + +## 1. 获取模型供应商列表 + +**GET** `/api/providers/models` + +**响应示例**: +```json +{ + "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, + "createdAt": "2025-12-01T00:00:00Z" + } + ] + } +} +``` + +--- + +## 2. 创建模型供应商 + +**POST** `/api/providers/models/create` + +**请求体**: +```json +{ + "name": "Anthropic", + "provider": "anthropic", + "apiUrl": "https://api.anthropic.com/v1", + "apiKey": "sk-ant-xxxxx", + "supportedModels": ["claude-3-opus", "claude-3-sonnet"], + "rpm": 2000, + "tpm": 80000 +} +``` + +**provider可选值**: `openai`, `anthropic`, `azure`, `google`, `aws` + +**请求参数说明**: +- `name` (string, 必需): 供应商显示名称 +- `provider` (string, 必需): 供应商类型标识 +- `apiUrl` (string, 必需): API基础URL +- `apiKey` (string, 必需): API密钥 +- `supportedModels` (array, 必需): 支持的模型列表 +- `rpm` (int, 可选): 每分钟请求数限制 +- `tpm` (int, 可选): 每分钟Token数限制 + +**响应示例**: +```json +{ + "success": true, + "data": { + "id": "provider-uuid-2", + "name": "Anthropic", + "provider": "anthropic" + }, + "message": "模型供应商创建成功" +} +``` + +--- + +## 3. 获取供应商详情 + +**GET** `/api/providers/models/{provider_id}` + +**响应示例**: +```json +{ + "success": true, + "data": { + "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, + "createdAt": "2025-12-01T00:00:00Z", + "updatedAt": "2025-12-20T15:30:00Z" + } +} +``` + +--- + +## 4. 更新供应商配置 + +**PUT** `/api/providers/models/{provider_id}` + +**请求体**: +```json +{ + "name": "OpenAI", + "provider": "openai", + "apiUrl": "https://api.openai.com/v1", + "apiKey": "sk-new-key", + "supportedModels": ["gpt-4", "gpt-4o", "gpt-4o-mini"], + "rpm": 4000, + "tpm": 100000 +} +``` + +**请求参数说明**: +- `name` (string, 可选): 供应商显示名称 +- `provider` (string, 可选): 供应商类型标识 +- `apiUrl` (string, 可选): API基础URL +- `apiKey` (string, 可选): 新的API密钥 +- `supportedModels` (array, 可选): 支持的模型列表 +- `rpm` (int, 可选): 每分钟请求数限制 +- `tpm` (int, 可选): 每分钟Token数限制 + +**响应示例**: +```json +{ + "success": true, + "message": "模型供应商更新成功" +} +``` + +--- + +## 5. 删除供应商 + +**DELETE** `/api/providers/models/{provider_id}` + +**响应示例**: +```json +{ + "success": true, + "message": "模型供应商已删除" +} +``` + +> **说明**: 删除是软删除，仅标记为不活跃。 + +--- + +## 6. 测试供应商连接 + +**POST** `/api/providers/models/{provider_id}/test` + +测试供应商API连接是否正常。 + +**响应示例**: +```json +{ + "success": true, + "data": { + "status": "connected", + "latency": 45, + "message": "连接成功" + } +} +``` + +**失败响应示例**: +```json +{ + "success": false, + "data": { + "status": "failed", + "latency": null, + "message": "连接超时: API响应超过5秒" + } +} +``` + +--- + +## 供应商类型说明 + +| 供应商 | provider值 | 说明 | +|--------|-----------|------| +| OpenAI | `openai` | GPT系列模型 | +| Anthropic | `anthropic` | Claude系列模型 | +| Azure OpenAI | `azure` | Azure托管的OpenAI模型 | +| Google | `google` | Gemini系列模型 | +| AWS Bedrock | `aws` | AWS托管的各类模型 | + +--- + +## 使用示例 + +### 添加新供应商 + +```bash +curl -X POST "http://localhost:8002/api/providers/models/create" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -d '{ + "name": "OpenAI", + "provider": "openai", + "apiUrl": "https://api.openai.com/v1", + "apiKey": "sk-xxxxx", + "supportedModels": ["gpt-4o", "gpt-4o-mini"], + "rpm": 3500, + "tpm": 90000 + }' +``` + +### 测试连接 + +```bash +curl -X POST "http://localhost:8002/api/providers/models/provider-uuid-1/test" \ + -H "Authorization: Bearer $TOKEN" +``` + diff --git a/Docs/前后端调试说明/API文档/09-通用规范.md b/Docs/前后端调试说明/API文档/09-通用规范.md new file mode 100644 index 0000000..0019c3a --- /dev/null +++ b/Docs/前后端调试说明/API文档/09-通用规范.md @@ -0,0 +1,240 @@ +# 通用规范 + +本文档定义了API的通用响应格式、错误码和业务规则。 + +--- + +## 目录 + +1. [通用响应格式](#通用响应格式) +2. [错误码说明](#错误码说明) +3. [业务规则](#业务规则) + +--- + +## 通用响应格式 + +所有API端点（除非另有说明）返回以下格式： + +### 成功响应 + +**基础格式**: +```json +{ + "success": true, + "data": {}, + "message": "操作成功" +} +``` + +### 错误响应（FastAPI默认） + +```json +{ + "detail": "错误描述" +} +``` + +### 标准包装响应（SuccessResponse） + +```json +{ + "success": true, + "message": "操作成功", + "data": {}, + "timestamp": "2025-12-25T05:10:00Z" +} +``` + +### 分页响应格式 + +```json +{ + "success": true, + "data": { + "total": 150, + "page": 1, + "pageSize": 20, + "totalPages": 8, + "items": [] + } +} +``` + +--- + +## 错误码说明 + +### HTTP 状态码 + +| HTTP 状态码 | 错误码 | 说明 | +|------------|--------|------| +| 400 | `BAD_REQUEST` | 请求参数错误 | +| 401 | `UNAUTHORIZED` | 未授权 | +| 403 | `FORBIDDEN` | 禁止访问 | +| 404 | `NOT_FOUND` | 资源不存在 | +| 409 | `CONFLICT` | 资源冲突 | +| 422 | `VALIDATION_ERROR` | 数据验证失败 | +| 429 | `TOO_MANY_REQUESTS` | 请求过于频繁 | +| 500 | `INTERNAL_ERROR` | 服务器内部错误 | +| 503 | `SERVICE_UNAVAILABLE` | 服务不可用 | + +### 业务错误码 + +| 错误码 | 说明 | +|--------|------| +| `INVALID_CREDENTIALS` | 用户名或密码错误 | +| `TOKEN_EXPIRED` | Token已过期 | +| `INSUFFICIENT_BALANCE` | 余额不足 | +| `QUOTA_EXCEEDED` | 配额超限 | +| `RATE_LIMIT_EXCEEDED` | 速率限制超限 | +| `RESOURCE_NOT_FOUND` | 资源未找到 | +| `PERMISSION_DENIED` | 权限不足 | + +### 错误响应示例 + +```json +{ + "detail": { + "code": "INSUFFICIENT_BALANCE", + "message": "账户余额不足，当前余额: 10.00，需要: 25.00", + "data": { + "balance": 10.00, + "required": 25.00 + } + } +} +``` + +--- + +## 业务规则 + +### EU计算规则 + +**EU (Execution Unit)** 是系统的基本计费单位： + +- **1 EU = 10秒调用时间** +- **不足10秒按1 EU计算** +- **计算公式**: `EU = CEILING(duration_seconds / 10)` + +**示例**: +``` +5秒 -> 1 EU +10秒 -> 1 EU +15秒 -> 2 EU +60秒 -> 6 EU +125秒 -> 13 EU +``` + +### 计费价格 + +EU单价根据用户订阅等级自动确定： + +| 档位 | 订阅等级 | EU 单价 | 核心定位 | +|------|---------|---------|----------| +| **入门级（Starter）** | `free` / `starter` | **$0.015 / EU** | 拉新、试用、轻 Agent | +| **专业级（Pro）** | `pro` | **$0.02 / EU** | 主力商业用户 | +| **企业级（Enterprise）** | `enterprise` | **$0.03 / EU** | 高复杂度 / 高 SLA | + +**价格计算示例**： +``` +用户订阅等级: pro +调用时长: 45秒 +EU数量: CEILING(45 / 10) = 5 EU +费用: 5 EU × $0.02 = $0.10 +``` + +### 余额与授信 + +**可用额度计算**: +``` +可用额度 = 账户余额 + 授信额度 +``` + +**消费规则**: +1. 优先扣除账户余额 +2. 余额不足时使用授信额度 +3. 授信额度用完后服务暂停 + +### 速率限制 + +| 等级 | RPM (每分钟请求数) | TPM (每分钟Token数) | +|------|-------------------|---------------------| +| free | 20 | 20,000 | +| pro | 60 | 60,000 | +| enterprise | 200 | 200,000 | + +### 资源配额默认值 + +| 资源类型 | 默认值 | 最大值 | +|---------|--------|--------| +| CPU (核心) | 2.0 | 64 | +| 内存 (GB) | 4.0 | 256 | +| 最大实例数 | 5 | 1000 | + +--- + +## 时间格式 + +所有时间字段使用 **ISO 8601** 格式： + +``` +2025-12-25T05:10:00Z +2025-12-25T05:10:00+08:00 +``` + +### 时间查询参数 + +- `startTime` / `start_date`: 查询起始时间 +- `endTime` / `end_date`: 查询结束时间 + +**示例**: +```bash +curl "http://localhost:8002/api/user/billing/history?startTime=2025-12-01T00:00:00Z&endTime=2025-12-31T23:59:59Z" +``` + +--- + +## 分页参数 + +| 参数 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `page` | int | 1 | 页码，从1开始 | +| `pageSize` / `page_size` | int | 20 | 每页数量 | +| `skip` | int | 0 | 跳过的记录数 | +| `limit` | int | 100 | 返回的最大记录数 | + +--- + +## 排序参数 + +| 参数 | 说明 | +|------|------| +| `sort_by` | 排序字段 | +| `sort_order` | 排序方向：`asc` / `desc` | + +--- + +## 导出功能 + +支持导出的接口通常提供 `export` 参数： + +| 格式 | 说明 | +|------|------| +| `excel` | Excel格式 (.xlsx) | +| `csv` | CSV格式 | +| `pdf` | PDF格式 | + +**导出响应示例**: +```json +{ + "success": true, + "data": { + "fileUrl": "https://exports.taiji-ai.com/user-uuid/excel/billing_20251225123000.xlsx", + "format": "excel", + "expiresAt": "2025-12-26T12:30:00Z" + } +} +``` + diff --git a/Docs/前后端调试说明/API文档/10-开发指南.md b/Docs/前后端调试说明/API文档/10-开发指南.md new file mode 100644 index 0000000..8c8a1a5 --- /dev/null +++ b/Docs/前后端调试说明/API文档/10-开发指南.md @@ -0,0 +1,351 @@ +# 开发指南 + +本文档提供API开发和集成的指南，包括交互式文档、代码示例、测试流程和测试账号信息。 + +--- + +## 目录 + +1. [交互式 API 文档](#交互式-api-文档) +2. [前端集成示例](#前端集成示例) +3. [完整 API 测试流程](#完整-api-测试流程) +4. [预置测试账号](#预置测试账号) +5. [注意事项](#注意事项) +6. [更新日志](#更新日志) + +--- + +## 交互式 API 文档 + +### Swagger UI + +- Data Ingestion: `http://localhost:8001/docs` +- MCP Server: `http://localhost:8002/docs` + +### ReDoc + +- Data Ingestion: `http://localhost:8001/redoc` +- MCP Server: `http://localhost:8002/redoc` + +### OpenAPI JSON + +- Data Ingestion: `http://localhost:8001/openapi.json` +- MCP Server: `http://localhost:8002/openapi.json` + +--- + +## 前端集成示例 + +### JavaScript/TypeScript + +```typescript +// 健康检查 +const healthCheck = async () => { + const response = await fetch('http://localhost:8001/health'); + const data = await response.json(); + console.log(data); +}; + +// 登录获取Token +const login = async (email: string, password: string, role: string) => { + const response = await fetch('http://localhost:8002/api/auth/login', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ email, password, role }) + }); + const data = await response.json(); + return data.data.token; +}; + +// 使用Token访问API +const getDashboard = async (token: string) => { + const response = await fetch('http://localhost:8002/api/user/dashboard/stats', { + headers: { 'Authorization': `Bearer ${token}` } + }); + return await response.json(); +}; + +// 完整示例 +async function main() { + const token = await login('admin@taiji-ai.com', 'Admin@123456', 'super_admin'); + const dashboard = await getDashboard(token); + console.log('Dashboard:', dashboard); +} +``` + +### Python + +```python +import requests + +BASE_URL = 'http://localhost:8002' + +# 登录 +def login(email: str, password: str, role: str) -> str: + response = requests.post( + f'{BASE_URL}/api/auth/login', + json={'email': email, 'password': password, 'role': role} + ) + return response.json()['data']['token'] + +# 使用Token访问API +def get_dashboard(token: str) -> dict: + response = requests.get( + f'{BASE_URL}/api/user/dashboard/stats', + headers={'Authorization': f'Bearer {token}'} + ) + return response.json() + +# 创建渠道 +def create_channel(token: str, name: str, email: str, password: str) -> dict: + response = requests.post( + f'{BASE_URL}/api/admin/channels/create', + headers={'Authorization': f'Bearer {token}'}, + json={ + 'name': name, + 'email': email, + 'password': password, + 'commissionRate': 10.0 + } + ) + return response.json() + +# 使用示例 +if __name__ == '__main__': + token = login('superadmin@taiji-ai.com', 'Admin@123456', 'super_admin') + dashboard = get_dashboard(token) + print('Dashboard:', dashboard) +``` + +### cURL + +```bash +# 设置基础URL +BASE_URL="http://localhost:8002" + +# 登录获取Token +TOKEN=$(curl -s -X POST "$BASE_URL/api/auth/login" \ + -H "Content-Type: application/json" \ + -d '{"email":"superadmin@taiji-ai.com","password":"Admin@123456","role":"super_admin"}' \ + | jq -r '.data.token') + +echo "Token: $TOKEN" + +# 使用Token访问API +curl -s "$BASE_URL/api/user/dashboard/stats" \ + -H "Authorization: Bearer $TOKEN" | jq +``` + +--- + +## 完整 API 测试流程 + +以下是一个完整的 API 测试流程示例，涵盖从超级管理员登录到创建渠道、创建租户、分配资源的全过程。 + +### 测试脚本 + +```bash +#!/bin/bash +# 完整 API 测试流程 + +echo "=== 1. 超级管理员登录 ===" +ADMIN_RESPONSE=$(curl -s -X POST "http://localhost:8002/api/auth/login" \ + -H "Content-Type: application/json" \ + -d '{"email":"superadmin@taiji-ai.com","password":"Admin@123456","role":"super_admin"}') +echo $ADMIN_RESPONSE | python3 -m json.tool + +ADMIN_TOKEN=$(echo $ADMIN_RESPONSE | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['token'])") +echo "管理员Token获取成功" + +echo "" +echo "=== 2. 创建渠道 ===" +CHANNEL_RESPONSE=$(curl -s -X POST "http://localhost:8002/api/admin/channels/create" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $ADMIN_TOKEN" \ + -d '{ + "name": "测试渠道Alpha", + "email": "channel-alpha@test.com", + "password": "Channel@123456", + "commissionRate": 10.0 + }') +echo $CHANNEL_RESPONSE | python3 -m json.tool + +echo "" +echo "=== 3. 渠道管理员登录 ===" +CHANNEL_LOGIN_RESPONSE=$(curl -s -X POST "http://localhost:8002/api/auth/login" \ + -H "Content-Type: application/json" \ + -d '{"email":"channel-alpha@test.com","password":"Channel@123456","role":"channel"}') +echo $CHANNEL_LOGIN_RESPONSE | python3 -m json.tool + +CHANNEL_TOKEN=$(echo $CHANNEL_LOGIN_RESPONSE | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['token'])") +echo "渠道Token获取成功" + +echo "" +echo "=== 4. 创建租户 ===" +TENANT_RESPONSE=$(curl -s -X POST "http://localhost:8002/api/channel/tenants/create" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $CHANNEL_TOKEN" \ + -d '{ + "name": "张三", + "email": "zhangsan@company.com", + "password": "User@123456", + "subscriptionTier": "pro" + }') +echo $TENANT_RESPONSE | python3 -m json.tool + +TENANT_ID=$(echo $TENANT_RESPONSE | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['id'])") +echo "租户ID: $TENANT_ID" + +echo "" +echo "=== 5. 为租户分配资源 ===" +curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/resources" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $CHANNEL_TOKEN" \ + -d '{ + "agents": [ + {"agentId": "通用助手", "quantity": 5}, + {"agentId": "代码助手", "quantity": 3} + ], + "models": [ + {"modelName": "OpenAI", "rpm": 100, "tpm": 100000} + ] + }' | python3 -m json.tool + +echo "" +echo "=== 6. 更新租户计费设置 ===" +curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/billing" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $CHANNEL_TOKEN" \ + -d '{"subscriptionTier": "pro", "discount": 10.0}' | python3 -m json.tool + +echo "" +echo "=== 7. 设置授信额度 ===" +curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/credit" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $CHANNEL_TOKEN" \ + -d '{"creditLimit": 10000.0}' | python3 -m json.tool + +echo "" +echo "=== 8. 为租户充值 ===" +curl -s -X POST "http://localhost:8002/api/channel/tenants/${TENANT_ID}/recharge" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $CHANNEL_TOKEN" \ + -d '{"amount": 5000.0}' | python3 -m json.tool + +echo "" +echo "=== 9. 租户登录验证 ===" +curl -s -X POST "http://localhost:8002/api/auth/login" \ + -H "Content-Type: application/json" \ + -d '{"email":"zhangsan@company.com","password":"User@123456","role":"user"}' | python3 -m json.tool + +echo "" +echo "=== 10. 查看渠道下的租户列表 ===" +curl -s "http://localhost:8002/api/channel/tenants" \ + -H "Authorization: Bearer $CHANNEL_TOKEN" | python3 -m json.tool + +echo "" +echo "=== API测试完成 ===" +``` + +--- + +## 预置测试账号 + +系统初始化时会创建以下测试账号： + +| 角色 | 邮箱 | 密码 | 登录role参数 | 可执行操作 | +|------|------|------|-------------|-----------| +| 超级管理员 | superadmin@taiji-ai.com | Admin@123456 | super_admin | 创建管理员、创建渠道、全部管理 | +| 计费管理员 | billing@taiji-ai.com | Admin@123456 | billing_admin | 创建渠道、管理租户、计费操作（完整写入权限） | +| 运维管理员 | ops@taiji-ai.com | Admin@123456 | operations_admin | 查看概览、监控、计费（只读权限） | +| 渠道 | default@channel.com | Channel@123456 | channel | 创建租户、管理租户资源 | +| 测试用户 | user@test.com | User@123456 | user | 使用平台服务 | + +> **权限层级**: super_admin > billing_admin > operations_admin > channel_admin > user + +--- + +## 注意事项 + +1. **端口映射**: + - Data Ingestion: 容器8000 → 主机8001 + - MCP Server: 容器8000 → 主机8002 + +2. **CORS**: 当前配置允许所有来源，生产环境需要限制 + +3. **认证**: `/api/*` 路径需要认证（除login等豁免路径） + +4. **限流**: 建议在生产环境添加限流保护 + +5. **超时设置**: 建议设置合理的请求超时时间 + +--- + +## 更新日志 + +- **v2.6.0** (2025-12-26): **新增计费与资源管理API** + - ✅ 新增配额管理API（用户配额、渠道配额、配额预警） + - ✅ 新增资源监控API（平台概览、用户资源、使用趋势、Agent统计） + - ✅ 新增事件管理API（待处理事件、重试失败、事件统计） + - ✅ 新增追踪管理API（执行追踪详情、追踪查询、追踪统计） + - ✅ 新增审计日志API（日志查询、汇总统计、用户活动历史） + - ✅ 新增供应商健康检查API（健康状态、健康详情、手动检查） + - ✅ 新增模型定价管理API（定价列表、创建/更新定价、成本计算） + - ✅ 新增数据模型：TokenBlacklist、ResourceUsage、QuotaAlert、ModelPricing、ProviderHealthCheck、AgentTrace、BillingEvent + - ✅ 增强JWT认证：登出时将Token加入黑名单 + +- **v2.5.0** (2025-12-26): **权限系统重构** + - ✅ 重新设计权限系统，区分计费管理员和运维管理员 + - ✅ billing_admin（计费管理员）：完整写入权限（创建渠道、管理租户、计费操作、审批申请） + - ✅ operations_admin（运维管理员）：只读权限（仅查看和监控） + - ✅ 更新权限矩阵表格 + - ✅ 更新接口权限验证逻辑 + - ✅ 更新预置测试账号说明 + +- **v2.4.0** (2025-12-26): **新增管理员管理接口** + - ✅ 添加 GET /api/admin/admins - 获取管理员列表（仅超级管理员可用） + - ✅ 添加 POST /api/admin/admins/create - 创建管理员（支持billing_admin/operations_admin角色） + - ✅ 添加 DELETE /api/admin/admins/{admin_id} - 删除管理员（软删除） + - ✅ 区分 super_admin（超级管理员）权限 + - ✅ 更新超级管理员API接口编号 + +- **v2.3.0** (2025-12-25): **新增管理接口** + - ✅ 添加 PUT /api/admin/channels/{channel_id} - 更新渠道信息 + - ✅ 添加 DELETE /api/admin/channels/{channel_id} - 删除渠道（软删除） + - ✅ 添加 DELETE /api/admin/resources/agents/{agent_id} - 删除Agent资源（软删除） + - ✅ 添加 PUT /api/admin/resources/agents/{agent_id}/config - 更新Agent资源配置 + - ✅ 更新超级管理员API接口编号 + +- **v2.2.0** (2025-12-25): **完整API测试验证** + - ✅ 添加完整API测试流程示例 + - ✅ 更新所有curl命令示例 + - ✅ 添加预置测试账号说明 + - ✅ 完善请求参数说明 + - ✅ 添加渠道登录响应示例 + - ✅ 验证所有接口可用性 + +- **v2.1.0** (2025-12-25): **基于实际代码重写** + - ✅ 根据实际代码完全重写文档 + - ✅ 修正所有端口信息（8001, 8002） + - ✅ 更新认证机制说明 + - ✅ 完善实际实现的端点文档 + - ✅ 移除未实现的占位接口 + - ✅ 添加实际响应示例 + - ✅ 更新业务规则和认证说明 + - ✅ 添加前端集成示例 + +- **v2.0.0** (2025-12-25): 基于需求文档的完整实现 + +- **v1.3.0** (2025-12-24): 增加占位API文档 + +- **v1.2.0** (2025-12-22): 初始版本 + +--- + +## 相关文档 + +- 完整需求文档: [BACKEND_REQUIREMENTS.md](../../../BACKEND_REQUIREMENTS.md) +- 实现总结: [BACKEND_IMPLEMENTATION_SUMMARY.md](../../../BACKEND_IMPLEMENTATION_SUMMARY.md) +- 部署指南: [services/mcp-server/DEPLOY_AZURE.md](../../../services/mcp-server/DEPLOY_AZURE.md) +- 快速开始: [QUICK_START.md](../../../QUICK_START.md) + diff --git a/Docs/前后端调试说明/API文档/README.md b/Docs/前后端调试说明/API文档/README.md new file mode 100644 index 0000000..8ba24a9 --- /dev/null +++ b/Docs/前后端调试说明/API文档/README.md @@ -0,0 +1,111 @@ +# taiji-AI-PAD API 接口文档 + +**版本**: v2.6.0 +**更新时间**: 2025年12月26日 +**基础URL**: +- Data Ingestion 服务: `http://localhost:8001` (容器内8000→主机8001) +- MCP Server 服务: `http://localhost:8002` (容器内8000→主机8002) +- API Gateway: `http://localhost:80` +- LiteLLM Gateway: `http://localhost:4000` + +> **重要说明**: 本文档基于实际代码生成并经过完整API测试验证。所有端点均已实现并确认可用。 + +--- + +## 📋 文档索引 + +| 文档 | 说明 | 适用角色 | +|------|------|---------| +| [01-认证与授权](./01-认证与授权.md) | JWT认证、API Key认证、权限说明 | 所有角色 | +| [02-Data-Ingestion服务](./02-Data-Ingestion服务.md) | API同步、OpenAPI解析、工具生成 | 开发者 | +| [03-MCP-Server服务](./03-MCP-Server服务.md) | Agent管理、工具执行、监控、WebSocket | 开发者 | +| [04-用户侧平台](./04-用户侧平台.md) | 仪表板、网关、工具、Agent部署、计费 | 租户用户 | +| [05-渠道合作伙伴](./05-渠道合作伙伴.md) | 租户管理、资源分配、计费统计 | 渠道管理员 | +| [06-超级管理员](./06-超级管理员.md) | 平台统计、渠道管理、审批、监控 | 超级管理员 | +| [07-计费与资源管理](./07-计费与资源管理.md) | 配额、资源监控、事件、追踪、审计 | 计费管理员 | +| [08-供应商管理](./08-供应商管理.md) | 模型供应商CRUD、连接测试 | 管理员 | +| [09-通用规范](./09-通用规范.md) | 响应格式、错误码、业务规则 | 所有角色 | +| [10-开发指南](./10-开发指南.md) | 集成示例、测试流程、测试账号 | 开发者 | + +--- + +## 🔐 快速认证 + +### 获取Token + +```bash +# 超级管理员登录 +curl -s -X POST "http://localhost:8002/api/auth/login" \ + -H "Content-Type: application/json" \ + -d '{"email":"superadmin@taiji-ai.com","password":"Admin@123456","role":"super_admin"}' + +# 渠道管理员登录 +curl -s -X POST "http://localhost:8002/api/auth/login" \ + -H "Content-Type: application/json" \ + -d '{"email":"channel-alpha@test.com","password":"Channel@123456","role":"channel"}' + +# 租户用户登录 +curl -s -X POST "http://localhost:8002/api/auth/login" \ + -H "Content-Type: application/json" \ + -d '{"email":"zhangsan@company.com","password":"User@123456","role":"user"}' +``` + +### 使用Token + +```bash +curl -X GET "http://localhost:8002/api/user/dashboard/stats" \ + -H "Authorization: Bearer $TOKEN" +``` + +--- + +## 👥 角色与权限概览 + +| 角色 | 说明 | 登录role参数 | +|------|------|-------------| +| super_admin | 超级管理员 | super_admin | +| billing_admin | 计费管理员 | billing_admin | +| operations_admin | 运维管理员 | operations_admin | +| channel_admin | 渠道管理员 | channel | +| provider_admin | 供应商管理员 | provider | +| user | 租户用户 | user | + +> **权限层级**: super_admin > billing_admin > operations_admin > channel_admin > user + +--- + +## 🌐 交互式文档 + +| 服务 | Swagger UI | ReDoc | OpenAPI JSON | +|------|-----------|-------|--------------| +| Data Ingestion | [docs](http://localhost:8001/docs) | [redoc](http://localhost:8001/redoc) | [openapi.json](http://localhost:8001/openapi.json) | +| MCP Server | [docs](http://localhost:8002/docs) | [redoc](http://localhost:8002/redoc) | [openapi.json](http://localhost:8002/openapi.json) | + +--- + +## 📝 更新日志 + +- **v2.6.0** (2025-12-26): 新增计费与资源管理API +- **v2.5.0** (2025-12-26): 权限系统重构 +- **v2.4.0** (2025-12-26): 新增管理员管理接口 +- **v2.3.0** (2025-12-25): 新增管理接口 +- **v2.2.0** (2025-12-25): 完整API测试验证 +- **v2.1.0** (2025-12-25): 基于实际代码重写 + +详细更新日志请查看 [10-开发指南](./10-开发指南.md#更新日志) + +--- + +## 📚 相关文档 + +- 完整需求文档: [BACKEND_REQUIREMENTS.md](../../../BACKEND_REQUIREMENTS.md) +- 实现总结: [BACKEND_IMPLEMENTATION_SUMMARY.md](../../../BACKEND_IMPLEMENTATION_SUMMARY.md) +- 部署指南: [services/mcp-server/DEPLOY_AZURE.md](../../../services/mcp-server/DEPLOY_AZURE.md) +- 快速开始: [QUICK_START.md](../../../QUICK_START.md) + +--- + +**文档版本**: v2.6.0 +**最后更新**: 2025年12月26日 +**维护者**: taiji-AI-PAD 项目组 +