From e153d27f28780b9d5b75851b0190640823964f98 Mon Sep 17 00:00:00 2001 From: xiaohei Date: Wed, 24 Dec 2025 15:14:31 +0000 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E6=B8=A0=E9=81=93?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Docs/项目文档/项目工作流程.md | 124 ++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 Docs/项目文档/项目工作流程.md diff --git a/Docs/项目文档/项目工作流程.md b/Docs/项目文档/项目工作流程.md new file mode 100644 index 0000000..1a3c782 --- /dev/null +++ b/Docs/项目文档/项目工作流程.md @@ -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 可直接复制示例命令进行联调；后端可据此替换占位逻辑为正式实现。