taiji-AI-PAD/Docs/前后端调试说明/API文档/10-开发指南.md

开发指南

本文档提供API开发和集成的指南，包括交互式文档、代码示例、测试流程和测试账号信息。

---

目录

1. 交互式 API 文档
2. 前端集成示例
3. 完整 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

// 健康检查
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

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

# 设置基础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 测试流程示例，涵盖从超级管理员登录到创建渠道、创建租户、分配资源的全过程。

测试脚本

#!/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_IMPLEMENTATION_SUMMARY.md
• 部署指南: services/mcp-server/DEPLOY_AZURE.md
• 快速开始: QUICK_START.md