更新渠道

2025-12-24 15:14:31 +00:00
parent fa696b0aac
commit e153d27f28
1 changed files with 124 additions and 0 deletions
@@ -0,0 +1,124 @@
+# taiji-AI-PAD 项目工作流程总览
+
+适用对象：前后端开发、QA、产品。阅读完本稿，可快速了解系统模块、可用 API、典型业务路径以及本地联调方法。
+
+## 1. 架构与服务
+- Data Ingestion（8001）：OpenAPI/Swagger 解析、RapidAPI 同步、工具生成。
+- MCP Server（8002）：Checklist 占位 API、Agent/Tool/计费/渠道/超级管理员/供应商等前端联调接口。
+- Model Gateway（80 或 8002 部分能力）：模型转发（Litellm 配置）。
+- 监控与网关：Nginx、Prometheus、Grafana（见 config/）。
+
+## 2. 启动与基础信息
+- 本地基础 URL：
+  - Data Ingestion: http://localhost:8001
+  - MCP Server: http://localhost:8002/api
+- 认证：Checklist 占位接口当前免认证（/api 前缀直接可用）；正式环境需开启 API Key/JWT（app/auth.py）。
+- 内容类型：JSON；统一使用 UTF-8。
+
+## 3. 核心数据流与职责
+- Agent 与工具：Agent 元信息与执行记录存库；工具生成和列表由 MCP Server 占位接口写入/读取数据库（Tool 表）。
+- 计费与余额：Billing、Balance 表保存 EU 消耗与充值记录；占位接口支持充值与历史查询。
+- 渠道/租户：Channel、Tenant、ChannelAgentQuota 管理渠道与租户、配额与权限。
+- 供应商与模型：ProviderModel 表登记模型供应商与速率限制；可通过占位接口新增。
+- 网关 API：GatewayAPI 表记录用户上传的 JSON/URL 类型 API 定义，用于后续编排。
+
+## 4. 典型业务流程
+### 4.1 用户侧仪表盘
+1) 获取总览：`GET /api/user/dashboard/stats` -> 活跃 Agent、总请求数、EU 余额、系统健康度。
+2) 最近执行：`GET /api/user/agents/activity` -> 最近 20 条执行记录。
+3) 资源消耗：`GET /api/user/resources/usage` -> EU/CPU/内存汇总。
+
+### 4.2 服务网关配置
+1) 选择网关：`POST /api/gateway/select`，body: `{ "gatewayType": "MCP" | "A2A" | "API" }`。
+2) 创建网关 API：`POST /api/gateway/api/create`，body: `{ "name": "demo", "method": "json", "content": "{...}" }`。
+3) 查看列表：`GET /api/gateway/apis`。
+4) 监控概览：`GET /api/gateway/monitoring`。
+
+### 4.3 数据与工具
+1) 生成工具：`POST /api/tools/generate`，body 需包含 `name`、`frameworkTemplate`、`config` 等；写入 Tool 表。
+2) 列出工具：`GET /api/tools/list`（最新 100 条）。
+3) 数据模板：`POST /api/data-templates/create`，body: `{ "name": "orders", "type": "json_api", "config": {"apiUrl": "..."} }`。
+
+### 4.4 代理工厂与编排
+1) 平台 Agent 列表：`GET /api/agents/platform`。
+2) 部署占位记录：`POST /api/agents/deploy`，body: `{ "agentId": "...", "instances": 2, "model": "gpt-4.1", "gateway": "MCP" }`。
+3) 已部署列表：`GET /api/agents/deployed`。
+4) 创建工作流：`POST /api/workflows/create`，body 含 name、gateway、nodes（<=3）。
+5) 更新/删除工作流：`PUT /api/workflows/{id}` / `DELETE /api/workflows/{id}`。
+
+### 4.5 计费与余额
+1) 查询余额：`GET /api/billing/balance`。
+2) 计费历史：`GET /api/billing/history`。
+3) 充值：`POST /api/billing/recharge`，body: `{ "amount": 100 }`。
+
+### 4.6 渠道合作伙伴
+1) 登录：`POST /api/channel/auth/login`。
+2) 概览：`GET /api/channel/dashboard/stats`。
+3) 租户管理：
+   - 列表：`GET /api/channel/tenants`
+   - 创建：`POST /api/channel/tenants/create`
+   - 资源/计费：`PUT /api/channel/tenants/{id}/resources` / `PUT /api/channel/tenants/{id}/billing`
+4) 资源与申请：`GET /api/channel/resources/agents`，`GET /api/channel/resources/models`，`POST /api/channel/resources/apply`。
+5) 计费统计：`GET /api/channel/billing/stats`。
+6) 管理员：`GET /api/channel/admins`，`POST /api/channel/admins/create`，`PUT /api/channel/admins/{id}/permissions`。
+
+### 4.7 超级管理员
+1) 登录：`POST /api/admin/auth/login`。
+2) 平台概览：`GET /api/admin/dashboard/stats`。
+3) 渠道管理：列表/创建/佣金/资源 -> `GET|POST|PUT /api/admin/channels...`。
+4) 资源模型：`GET /api/admin/resources/models`，`POST /api/admin/resources/models/add`。
+5) 计费总览：`GET /api/admin/billing/overview`。
+6) 监控：`GET /api/admin/monitoring/agents`，`GET /api/admin/providers/stats`，`GET /api/admin/channels/backend/stats`。
+
+### 4.8 供应商中心
+1) 登录：`POST /api/providers/auth/login`。
+2) 模型列表：`GET /api/providers/models`。
+3) 新增模型：`POST /api/providers/models/add`。
+4) 数据概览：`GET /api/providers/data`。
+
+### 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 8002）
+```bash
+# 用户仪表盘
+curl -s http://localhost:8002/api/user/dashboard/stats | jq
+
+# 选择网关 + 创建 API
+curl -s -X POST http://localhost:8002/api/gateway/select -H "Content-Type: application/json" -d '{"gatewayType":"MCP"}'
+curl -s -X POST http://localhost:8002/api/gateway/api/create -H "Content-Type: application/json" -d '{"name":"demo","method":"json","content":"{\\"ping\\":true}"}' | jq
+
+# 生成工具
+curl -s -X POST http://localhost:8002/api/tools/generate -H "Content-Type: application/json" -d '{"name":"hello","frameworkTemplate":"API","config":{"msg":{"type":"string"}}}' | jq
+
+# 余额与充值
+curl -s http://localhost:8002/api/billing/balance | jq
+curl -s -X POST http://localhost:8002/api/billing/recharge -H "Content-Type: application/json" -d '{"amount":50}' | jq
+
+# 渠道创建租户
+curl -s -X POST http://localhost:8002/api/channel/tenants/create -H "Content-Type: application/json" -d '{"name":"tenant-a","subscriptionTier":"pro"}' | jq
+
+# 管理员创建渠道
+curl -s -X POST http://localhost:8002/api/admin/channels/create -H "Content-Type: application/json" -d '{"name":"partner-a","email":"owner@partner.com"}' | jq
+```
+
+## 6. 数据持久化与注意事项
+- 数据库模型：见 services/mcp-server/models.py；核心表包含 Agent、Tool、Execution、Billing、Balance、Channel、Tenant、ProviderModel、GatewayAPI、DataTemplate 等。
+- Checklist 占位接口当前写真实表，但逻辑简化；后续可替换为正式业务实现。
+- 认证与授权：middleware 当前放行 /api；生产需开启 API Key/JWT 校验（auth.authenticate_request）。
+- CORS：默认允许全部来源，生产请收敛。
+- 监控：/metrics 暴露 Prometheus 指标；Grafana 可导入 config/grafana/dashboards。
+
+## 7. 参考文档
+- 功能与接口详解：Docs/前后端调试说明/API接口文档.md
+- 后端对接清单：BACKEND_INTEGRATION_CHECKLIST.md
+- 监控与配置：config/ 下的 nginx/prometheus/grafana 配置
+
+---
+此文档重点回答：有哪些模块、能做什么、如何快速调用。前端/QA 可直接复制示例命令进行联调；后端可据此替换占位逻辑为正式实现。