taijibaga/taiji-AI-PAD
9
0
Fork 0
forked from xiaohei/taiji-AI-PAD
Code Pull Requests Activity
Files
31fb4a764c51d99a327d81542dd25f979fabbaf9
taiji-AI-PAD/Docs/项目文档/项目工作流程.md
T
Ubuntu 31fb4a764c 更新计费管理员
2025-12-26 04:14:27 +00:00

19 KiB
Raw Blame History

taiji-AI-PAD 项目工作流程总览

适用对象：前后端开发、QA、产品。阅读完本稿，可快速了解系统模块、可用 API、典型业务路径以及本地联调方法。

重要更新 (2025-12-25): 基于 BACKEND_REQUIREMENTS.md v3.0 完整实现了四大子系统API，不再依赖占位接口。

1. 架构与服务

  • Data Ingestion (8001): OpenAPI/Swagger 解析、RapidAPI 同步、工具生成。
  • MCP Server (8000): 完整实现的四大子系统API（用户侧、渠道、管理员、供应商）。
  • Model Gateway (80 或 8000 部分能力): 模型转发（LiteLLM 配置）。
  • 监控与网关: Nginx、Prometheus、Grafana（见 config/）。

端口变更说明

服务 旧端口 新端口 说明
MCP Server 8002 8000 与需求文档保持一致
Data Ingestion 8001 8001 保持不变

2. 启动与基础信息

  • 本地基础 URL:
    • Data Ingestion: http://localhost:8001
    • MCP Server: http://localhost:8002
    • MCP Server API: http://localhost:8000/api
  • 认证:
    • ✅ 已启用完整的JWT + API Key双认证机制
    • ✅ 豁免路径：/health, /metrics, /docs, /redoc, /openapi.json
    • ✅ 所有 /api/** 路径需要认证（通过 Authorization: Bearer <token> 或 X-API-Key: <key>）
  • 内容类型: JSON；统一使用 UTF-8。
  • 响应格式: 统一返回格式 { "success": true/false, "data": {...}, "message": "..." }

3. 核心数据流与职责

  • 认证与权限: 支持七种角色（user、channel_admin、billing_admin、operations_admin、admin、super_admin、provider_admin），JWT Token有效期24小时。
    • billing_admin: 计费管理员，负责计费、充值等财务操作
    • operations_admin: 运营管理员，负责租户和资源的日常运营管理
    • admin: 管理员，平台管理员，拥有除超级管理员外的大部分权限
    • super_admin: 超级管理员，拥有全部权限
  • Agent 与工具: Agent 元信息与执行记录存储在 PostgreSQL；工具生成和列表由 MCP Server 完整实现。
  • 计费与余额:
    • EU计算规则：1 EU = 10秒，不足10秒按1 EU
    • 计费价格：1 EU = ¥0.01（可配置）
    • 可用额度 = 账户余额 + 授信额度
    • Billing、Balance 表保存计费记录和余额信息
  • 渠道/租户: Channel、User(作为租户)、ResourceAllocation 管理渠道与租户、配额与权限。
  • 供应商与模型: ModelProvider 表登记模型供应商与速率限制；支持完整的CRUD操作。
  • 网关 API: GatewayAPI 表记录用户上传的 JSON/URL 类型 API 定义，用于后续编排。
  • 工作流: Workflow 表存储工作流定义，最多支持3个Agent节点。

4. 典型业务流程

4.0 认证流程（新增）

  1. 用户登录: POST /api/auth/login

    curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@taiji-ai.com","password":"admin123","role":"user"}'

  2. 获取API密钥: GET /api/auth/keys/info (需要 Bearer Token)

  3. 重新生成密钥: POST /api/auth/keys/regenerate

  4. 修改密码: PUT /api/auth/password

4.1 用户侧仪表盘

  1. 获取总览：GET /api/user/dashboard/stats -> 活跃 Agent、总请求数、EU 余额、系统健康度。
  2. 最近执行：GET /api/user/agents/activity?period=7d -> 最近活动数据。
  3. （已弃用）资源消耗：使用 /api/user/billing/balance 代替。

4.2 服务网关配置

  1. 选择网关：POST /api/user/gateway/select，body: { "gatewayType": "MCP" | "A2A" | "API" }。
  2. 创建网关 API：POST /api/user/gateway/api/create，body: { "name": "demo", "method": "json", "content": "{...}" }。
  3. 查看列表：GET /api/user/gateway/apis。
  4. 监控概览：GET /api/user/gateway/monitoring。

4.3 数据与工具

  1. 生成工具：POST /api/user/tools/generate，body 需包含 name、frameworkTemplate、config 等；写入 Tool 表。
  2. （注意）工具列表从 Data Ingestion 服务获取：GET http://localhost:8001/tools
  3. 数据模板：POST /api/user/data-templates/create，body: { "name": "orders", "type": "json_api", "config": {"apiUrl": "..."} }。

4.4 代理工厂与编排

  1. 平台 Agent 列表：GET /api/user/agents/platform。
  2. 部署 Agent：POST /api/user/agents/deploy，body: { "agentId": "...", "instances": 2, "model": "gpt-4o-mini", "gateway": "MCP" }。
  3. （已弃用）已部署列表 - 使用数据库直接查询。
  4. 创建工作流：POST /api/user/workflows/create，body 含 name、gateway、nodes（最多3个）。
  5. （已弃用）更新/删除工作流 - 将在未来版本实现。

4.5 计费与余额

  1. 查询余额：GET /api/user/billing/balance -> 返回余额、本月消费、货币。
  2. 计费历史：GET /api/user/billing/history?startTime=...&endTime=...&page=1&pageSize=20 -> 支持筛选和分页。
  3. 充值：POST /api/user/billing/recharge，body: { "amount": 100, "paymentMethod": "alipay" } -> 返回支付URL。
  4. 导出记录：GET /api/user/billing/history?...&export=excel -> 返回文件下载URL。

4.6 渠道合作伙伴

  1. 登录：POST /api/auth/login，body: {"email":"...","password":"...","role":"channel"}。
  2. （已弃用）概览 - 使用 dashboard/stats 代替。
  3. 租户管理：
    • 列表：GET /api/channel/tenants
    • 创建：POST /api/channel/tenants/create，body 包含 name、email、password、subscriptionTier
    • 分配资源：PUT /api/channel/tenants/{id}/resources，包含 agents、models、customAgentResources
    • 更新计费：PUT /api/channel/tenants/{id}/billing
    • 充值（新增）: POST /api/channel/tenants/{id}/recharge，body: {"amount": 1000}
    • 设置授信（新增）: PUT /api/channel/tenants/{id}/credit，body: {"creditLimit": 5000}
  4. 资源申请：POST /api/channel/resources/apply，type 可选 model 或 agent。
  5. 计费统计：GET /api/channel/billing/stats?startTime=...&endTime=... -> 租户统计和调用记录。
  6. （已弃用）管理员管理 - 将在未来版本实现。

4.7 超级管理员

  1. 登录：POST /api/auth/login，body: {"email":"...","password":"...","role":"admin"}。
  2. 平台概览：GET /api/admin/dashboard/stats -> 渠道/租户/Agent/调用/收入统计。
  3. 渠道管理：
    • 列表：GET /api/admin/channels
    • 创建：POST /api/admin/channels/create
    • 统一资源管理（新增）: PUT /api/admin/channels/{id}/resources -> 分配模型、Agent、自定义资源、授信额度
  4. 申请审批（新增）：
    • 查看申请：GET /api/admin/channels/applications
    • 审批：PUT /api/admin/channels/applications/{id}/review，body: {"approved": true, "reason": "..."}
  5. 资源管理：
    • 模型列表：GET /api/admin/resources/models
    • Agent列表：GET /api/admin/resources/agents
  6. 监控：GET /api/admin/monitoring/agents -> Agent健康状态和性能指标。
  7. 计费总览（三维度）：GET /api/admin/billing/overview?startTime=...&endTime=... -> 渠道/租户/调用三个维度的统计。

4.8 供应商中心

  1. 登录：POST /api/auth/login，body: {"email":"...","password":"...","role":"provider"}。
  2. 模型列表：GET /api/providers/models -> 所有模型供应商。
  3. 新增模型：POST /api/providers/models/create，包含 name、provider、apiUrl、apiKey、supportedModels、rpm、tpm。
  4. 获取详情：GET /api/providers/models/{id}。
  5. 更新配置：PUT /api/providers/models/{id}。
  6. 删除供应商：DELETE /api/providers/models/{id} -> 软删除。
  7. 测试连接：POST /api/providers/models/{id}/test -> 返回连接状态和延迟。

4.9 Data Ingestion（工具生成前置）

保持不变，详见原文档...

  1. 健康检查：GET http://localhost:8001/health。
  2. RapidAPI 同步：POST /rapidapi/sync?category=...&limit=...。
  3. RapidAPI 测试：POST /rapidapi/test（含 endpoint/method/params/headers）。
  4. 解析 OpenAPI：POST /openapi/parse?url=...。
  5. APILLAMA 处理：POST /apillama/process，可输出 pydantic/json_schema/openapi。
  6. 从端点生成工具：POST /tools/generate（Data Ingestion 服务）
  7. 工具列表：GET /tools（Data Ingestion 服务）

5. 快速联调脚本示例（MCP Server 8000）

认证相关

# 1. 用户登录（获取Token）
TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@taiji-ai.com","password":"admin123","role":"user"}' \
  | jq -r '.data.token')

echo "Token: $TOKEN"

# 2. 获取API密钥信息
curl -s http://localhost:8000/api/auth/keys/info \
  -H "Authorization: Bearer $TOKEN" | jq

# 3. 重新生成API密钥
curl -s -X POST http://localhost:8000/api/auth/keys/regenerate \
  -H "Authorization: Bearer $TOKEN" | jq

用户侧平台

# 仪表板总览（需要认证）
curl -s http://localhost:8000/api/user/dashboard/stats \
  -H "Authorization: Bearer $TOKEN" | jq

# Agent活动数据
curl -s http://localhost:8000/api/user/agents/activity?period=7d \
  -H "Authorization: Bearer $TOKEN" | jq

# 选择网关
curl -s -X POST http://localhost:8000/api/user/gateway/select \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"gatewayType":"MCP"}' | jq

# 创建网关API
curl -s -X POST http://localhost:8000/api/user/gateway/api/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo","method":"json","content":"{\"ping\":true}"}' | jq

# 生成工具
curl -s -X POST http://localhost:8000/api/user/tools/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"calculate-tool",
    "description":"数学计算",
    "frameworkTemplate":"API",
    "gateway":"gateway-1",
    "agentCount":2,
    "cpu":2.0,
    "memory":4.0,
    "maxScale":10,
    "model":"gpt-4o-mini"
  }' | jq

# 平台Agent列表
curl -s http://localhost:8000/api/user/agents/platform \
  -H "Authorization: Bearer $TOKEN" | jq

# 创建工作流（最多3个节点）
curl -s -X POST http://localhost:8000/api/user/workflows/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"订单处理",
    "description":"自动化订单处理",
    "gateway":"MCP",
    "nodes":[
      {"agentId":"agent-1","agentType":"platform","agentName":"验证","order":1},
      {"agentId":"agent-2","agentType":"custom","agentName":"库存","order":2},
      {"agentId":"agent-3","agentType":"platform","agentName":"支付","order":3}
    ]
  }' | jq

# 余额查询
curl -s http://localhost:8000/api/user/billing/balance \
  -H "Authorization: Bearer $TOKEN" | jq

# 充值
curl -s -X POST http://localhost:8000/api/user/billing/recharge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount":500,"paymentMethod":"alipay"}' | jq

# 计费历史（分页）
curl -s "http://localhost:8000/api/user/billing/history?startTime=2025-12-01T00:00:00Z&endTime=2025-12-31T23:59:59Z&page=1&pageSize=20" \
  -H "Authorization: Bearer $TOKEN" | jq

# 导出计费记录
curl -s "http://localhost:8000/api/user/billing/history?startTime=2025-12-01T00:00:00Z&endTime=2025-12-31T23:59:59Z&export=excel" \
  -H "Authorization: Bearer $TOKEN" | jq

渠道合作伙伴

# 渠道登录
CHANNEL_TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"channel@demo.com","password":"pass123","role":"channel"}' \
  | jq -r '.data.token')

# 租户列表
curl -s http://localhost:8000/api/channel/tenants \
  -H "Authorization: Bearer $CHANNEL_TOKEN" | jq

# 创建租户
curl -s -X POST http://localhost:8000/api/channel/tenants/create \
  -H "Authorization: Bearer $CHANNEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"企业客户A",
    "email":"client@company-a.com",
    "password":"client123",
    "subscriptionTier":"pro"
  }' | jq

# 为租户充值
curl -s -X POST http://localhost:8000/api/channel/tenants/{tenant-id}/recharge \
  -H "Authorization: Bearer $CHANNEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount":1000}' | jq

# 设置租户授信额度
curl -s -X PUT http://localhost:8000/api/channel/tenants/{tenant-id}/credit \
  -H "Authorization: Bearer $CHANNEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"creditLimit":5000}' | jq

# 分配资源
curl -s -X PUT http://localhost:8000/api/channel/tenants/{tenant-id}/resources \
  -H "Authorization: Bearer $CHANNEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agents":[{"agentId":"agent-1","quantity":10}],
    "models":[{"modelName":"gpt-4o-mini","rpm":60,"tpm":60000}],
    "customAgentResources":{"cpu":4.0,"memory":8.0}
  }' | jq

# 申请资源
curl -s -X POST http://localhost:8000/api/channel/resources/apply \
  -H "Authorization: Bearer $CHANNEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type":"model",
    "modelName":"gpt-4",
    "rpm":100,
    "tpm":100000,
    "reason":"客户需求增长"
  }' | jq

# 计费统计
curl -s "http://localhost:8000/api/channel/billing/stats?startTime=2025-12-01T00:00:00Z&endTime=2025-12-31T23:59:59Z" \
  -H "Authorization: Bearer $CHANNEL_TOKEN" | jq

超级管理员

# 管理员登录
ADMIN_TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@taiji-ai.com","password":"admin123","role":"admin"}' \
  | jq -r '.data.token')

# 平台统计
curl -s http://localhost:8000/api/admin/dashboard/stats \
  -H "Authorization: Bearer $ADMIN_TOKEN" | jq

# 渠道列表
curl -s http://localhost:8000/api/admin/channels \
  -H "Authorization: Bearer $ADMIN_TOKEN" | jq

# 创建渠道
curl -s -X POST http://localhost:8000/api/admin/channels/create \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"合作渠道A",
    "email":"partner@channel-a.com",
    "password":"channel123",
    "commissionRate":10.0
  }' | jq

# 统一管理渠道资源
curl -s -X PUT http://localhost:8000/api/admin/channels/{channel-id}/resources \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "models":["provider-1","provider-2"],
    "agents":[{"agentId":"agent-1","quantity":50}],
    "customAgentResources":{"cpu":4.0,"memory":8.0},
    "channelCredit":100000.00
  }' | jq

# 查看申请列表
curl -s http://localhost:8000/api/admin/channels/applications \
  -H "Authorization: Bearer $ADMIN_TOKEN" | jq

# 审批申请
curl -s -X PUT http://localhost:8000/api/admin/channels/applications/{app-id}/review \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"approved":true,"reason":"审批通过"}' | jq

# 模型供应商列表
curl -s http://localhost:8000/api/admin/resources/models \
  -H "Authorization: Bearer $ADMIN_TOKEN" | jq

# Agent列表
curl -s http://localhost:8000/api/admin/resources/agents \
  -H "Authorization: Bearer $ADMIN_TOKEN" | jq

# 监控Agent
curl -s http://localhost:8000/api/admin/monitoring/agents \
  -H "Authorization: Bearer $ADMIN_TOKEN" | jq

# 三维度计费统计
curl -s "http://localhost:8000/api/admin/billing/overview?startTime=2025-12-01T00:00:00Z&endTime=2025-12-31T23:59:59Z" \
  -H "Authorization: Bearer $ADMIN_TOKEN" | jq

供应商管理

# 供应商登录
PROVIDER_TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"provider@taiji-ai.com","password":"provider123","role":"provider"}' \
  | jq -r '.data.token')

# 模型列表
curl -s http://localhost:8000/api/providers/models \
  -H "Authorization: Bearer $PROVIDER_TOKEN" | jq

# 创建模型供应商
curl -s -X POST http://localhost:8000/api/providers/models/create \
  -H "Authorization: Bearer $PROVIDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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
  }' | jq

# 测试连接
curl -s -X POST http://localhost:8000/api/providers/models/{provider-id}/test \
  -H "Authorization: Bearer $PROVIDER_TOKEN" | jq

6. 数据持久化与注意事项

  • 数据库模型: 见 services/mcp-server/models.py；核心表包含：

    • 用户与认证: User、Channel、APIKey
    • Agent与工具: Agent、Tool、Execution
    • 计费: BillingRecord、RechargeRecord
    • 资源: ResourceAllocation、ModelProvider
    • 网关与模板: GatewayAPI、DataTemplate、Workflow
    • 申请审批: Application

  • 完整实现: v2.0.0 版本已完整实现所有API，不再依赖占位接口。

  • 认证与授权:

    • ✅ 已启用完整的 API Key/JWT 鉴权（middleware 强制验证 /api/** 路径）
    • ✅ 支持四种角色：user、channel_admin、super_admin、provider_admin
    • ✅ 豁免路径：/health, /metrics, /docs, /redoc, /openapi.json

  • 业务规则:

    • ✅ EU计算：1 EU = 10秒，不足10秒按1 EU
    • ✅ 计费价格：1 EU = ¥0.01
    • ✅ 余额与授信：可用额度 = 账户余额 + 授信额度
    • ✅ 工作流限制：最多3个Agent节点
    • ✅ 平台Agent资源：CPU 2核，内存 4GB（固定）
    • ✅ 资源分配层级：超级管理员 → 渠道 → 租户

  • CORS: 默认允许全部来源，生产请收敛。

  • 监控: /metrics 暴露 Prometheus 指标；Grafana 可导入 config/grafana/dashboards。

  • 部署:

    • ✅ 已配置完整的Azure AKS部署方案
    • ✅ 支持Docker容器化部署
    • ✅ 包含K8s配置和自动部署脚本

7. 参考文档

  • 功能与接口详解: Docs/前后端调试说明/API接口文档.md (v2.0.0)
  • 完整需求文档: BACKEND_REQUIREMENTS.md (v3.0)
  • 实现总结: BACKEND_IMPLEMENTATION_SUMMARY.md
  • 部署指南: services/mcp-server/DEPLOY_AZURE.md
  • 验证清单: BACKEND_VERIFICATION.md
  • 快速开始: QUICK_START.md
  • 监控与配置: config/ 下的 nginx/prometheus/grafana 配置

8. 重要变更说明（v2.0.0）

端口变更

  • MCP Server端口从 8002 变更为 8000
  • 所有API请求需要更新基础URL

认证必需

  • 除豁免路径外，所有 /api/** 路径都需要JWT Token或API Key
  • 登录后获取Token，在后续请求中携带

响应格式统一

  • 所有成功响应：{ "success": true, "data": {...}, "message": "..." }
  • 所有错误响应：{ "success": false, "error": {"code": "...", "message": "..."} }

API路径变更

  • 用户侧API：/api/user/* (新增 /user 前缀)
  • 渠道API：/api/channel/* (保持不变)
  • 管理员API：/api/admin/* (保持不变)
  • 供应商API：/api/providers/* (保持不变)

弃用的API

  • /api/user/resources/usage - 使用 /api/user/billing/balance 代替
  • /api/agents/deployed - 直接查询数据库
  • /api/workflows/{id} (PUT/DELETE) - 将在未来版本实现

此文档重点回答：有哪些模块、能做什么、如何快速调用。前端/QA 可直接复制示例命令进行联调；后端已完整实现所有业务逻辑，可直接使用。

最后更新: 2025年12月25日
文档版本: v2.0.0

View Git Blame Copy Permalink