井云服务中心 API 文档

井云服务中心后端提供完整的 RESTful API 和 gRPC 接口，支持用户认证、智能体管理、支付处理、分销系统等核心业务功能。

🌐 API 架构

网关层

统一入口: 所有 API 请求通过网关服务 (http://localhost:8000)
路由转发: 根据路径转发到对应的微服务
认证鉴权: 统一的 JWT Token 认证和权限控制
错误码区分: token过期返回401，token错误返回402

协议支持

HTTP/REST: 标准的 RESTful API 接口
gRPC: 高性能的 RPC 调用协议
OpenAPI 3.0: 完整的API规范文档

📚 API 服务概览

🔐 认证服务 (Auth Service)

用户认证、登录注册、Token 管理、微信登录

核心功能:

用户名密码登录
短信验证码登录/注册
微信登录（二维码扫码）
Token验证和刷新
租户Token交换

主要接口:

POST /auth/login - 用户登录
POST /auth/register - 用户注册
POST /auth/sms_login - 短信登录
POST /auth/wechat_login - 微信登录
GET /auth/get_login_page - 获取微信登录二维码
POST /auth/validate - 验证Token
POST /auth/tenant/exchange-token - 交换租户Token

👤 用户服务 (User Service)

用户管理、素材管理、分销系统、点数管理

核心功能:

用户信息管理
分销等级和佣金系统
提现申请和处理
素材分类和文件管理
交易历史查询

主要接口:

GET /user/me - 获取当前用户信息
PUT /user/me - 更新当前用户信息
GET /user/distribution/info - 获取我的分销信息
POST /user/distribution/withdrawal - 申请提现
GET /user/materials - 获取素材列表
POST /user/materials - 创建素材

🏢 租户服务 (Tenant Service)

多租户管理、版本管理、权限管理、平台集成

核心功能:

租户创建和管理
版本创建和权限配置
菜单管理（平台级和租户级）
平台集成配置
租户快照管理

主要接口:

POST /tenant/ - 创建租户
GET /tenant/versions - 获取版本列表
POST /tenant/versions - 创建版本
GET /tenant/menus - 获取菜单列表
POST /tenant/menus - 创建菜单

🤖 智能体服务 (Agent Service)

AI智能体管理、分类、配置、平台资产集成

核心功能:

多类型智能体管理（链接、工作流、机器人、提示词）
智能体分类和精选功能
平台资产同步（Coze等）
机器人创建和配置

主要接口:

GET /agent/ - 获取智能体列表
POST /agent/ - 创建智能体
GET /agent/categories - 获取分类列表
POST /agent/categories - 创建分类
POST /agent/fetch_platform_asset - 拉取平台资产

💰 支付服务 (Payment Service)

订单管理、支付处理、微信支付集成

核心功能:

租户订单和版本订单创建
微信支付（Native扫码支付）
支付回调处理
订单状态管理

主要接口:

POST /payment/orders/tenant - 创建租户订单
POST /payment/orders/version - 创建版本订单
POST /payment/wechat-pay - 发起微信支付
POST /payment/wechat-notify - 微信支付回调

🔗 集成服务 (Integration Service)

第三方服务集成、文件上传、短信服务

核心功能:

阿里云OSS文件上传
多平台短信服务
文件上传回调处理
预签名URL生成

主要接口:

GET /integration/oss/signature - 获取OSS签名
POST /integration/oss/callback - OSS上传回调
POST /integration/sms/send - 发送短信

🔐 认证机制

JWT Token 认证

所有需要认证的 API 都需要在请求头中包含 JWT Token：

Authorization: Bearer <your-jwt-token>

错误码说明

401 Unauthorized: Token过期
402 Payment Required: Token错误/无效
401 Unauthorized: 缺少Authorization header或Token格式问题

Token 获取流程

用户登录 → 获取 Access Token 和 Refresh Token
API 调用 → 使用 Access Token 认证
Token 刷新 → Access Token 过期时使用 Refresh Token 刷新

📝 请求格式

HTTP Headers

Content-Type: application/json
Authorization: Bearer <token>
X-Tenant-ID: <tenant-id>  # 多租户请求必需
X-Request-ID: <request-id>  # 请求追踪ID

响应格式

{
  "code": 200,
  "message": "success",
  "data": {
    // 响应数据
  },
  "request_id": "req-123456789",
  "timestamp": "2023-12-18T10:30:00Z"
}

🚨 错误处理

错误响应格式

{
  "code": 401,
  "message": "Token expired",
  "error": "TOKEN_EXPIRED",
  "details": [
    {
      "field": "token",
      "message": "Token has expired"
    }
  ],
  "request_id": "req-123456789",
  "timestamp": "2023-12-18T10:30:00Z"
}

常见错误码

错误码	HTTP状态码	描述
`SUCCESS`	200	请求成功
`TOKEN_EXPIRED`	401	Token过期
`INVALID_TOKEN`	402	Token无效
`UNAUTHORIZED`	401	未授权访问
`FORBIDDEN`	403	权限不足
`NOT_FOUND`	404	资源不存在
`INVALID_PARAMETER`	400	参数验证失败
`INTERNAL_ERROR`	500	内部服务器错误

📊 分页查询

分页参数

GET /agent?page=1&page_size=20&sort=created_at&order=desc

参数说明:

page: 页码，从 1 开始，默认 1
page_size: 每页大小，默认 20，最大 100
sort: 排序字段
order: 排序方向，asc 或 desc

🔗 相关资源

OpenAPI 规范

完整的 API 规范文档：

Swagger UI: http://localhost:8000/swagger/
OpenAPI 文件: /docs/api/openapi.yaml

服务文档

网关服务 - 网关服务详细说明
认证服务 - 认证服务详细说明
用户服务 - 用户服务详细说明
租户服务 - 租户服务详细说明
智能体服务 - 智能体服务详细说明
支付服务 - 支付服务详细说明
集成服务 - 集成服务详细说明

开发指南

开发环境搭建 - 本地开发环境配置
开发规范 - 开发规范和最佳实践
测试规范 - 测试编写规范
Proto样式指南 - Protocol Buffers编写规范

🔐 认证机制

JWT Token 认证

所有需要认证的 API 都需要在请求头中包含 JWT Token：

Authorization: Bearer <your-jwt-token>

Token 获取流程

用户登录 → 获取 Access Token 和 Refresh Token
API 调用 → 使用 Access Token 认证
Token 刷新 → Access Token 过期时使用 Refresh Token 刷新

权限控制

用户权限: 基于用户角色的权限控制
租户权限: 基于租户的数据隔离
功能权限: 基于功能模块的权限控制

📝 请求格式

HTTP Headers

Content-Type: application/json
Authorization: Bearer <token>
X-Tenant-ID: <tenant-id>  # 多租户请求必需
X-Request-ID: <request-id>  # 请求追踪ID

请求体格式

{
  "field1": "value1",
  "field2": {
    "nested_field": "nested_value"
  },
  "array_field": [1, 2, 3]
}

响应格式

{
  "code": 200,
  "message": "success",
  "data": {
    // 响应数据
  },
  "request_id": "req-123456789",
  "timestamp": "2023-12-18T10:30:00Z"
}

🚨 错误处理

错误响应格式

{
  "code": 400,
  "message": "参数验证失败",
  "error": "INVALID_PARAMETER",
  "details": [
    {
      "field": "email",
      "message": "邮箱格式不正确"
    }
  ],
  "request_id": "req-123456789",
  "timestamp": "2023-12-18T10:30:00Z"
}

常见错误码

错误码	HTTP状态码	描述
`SUCCESS`	200	请求成功
`INVALID_PARAMETER`	400	参数验证失败
`UNAUTHORIZED`	401	未授权访问
`FORBIDDEN`	403	权限不足
`NOT_FOUND`	404	资源不存在
`CONFLICT`	409	资源冲突
`RATE_LIMIT_EXCEEDED`	429	请求频率超限
`INTERNAL_ERROR`	500	内部服务器错误
`SERVICE_UNAVAILABLE`	503	服务不可用

📊 分页查询

分页参数

GET /api/v1/users?page=1&page_size=20&sort=created_at&order=desc

参数说明:

page: 页码，从 1 开始，默认 1
page_size: 每页大小，默认 20，最大 100
sort: 排序字段
order: 排序方向，asc 或 desc

分页响应

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      // 数据项
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 100,
      "total_pages": 5,
      "has_next": true,
      "has_prev": false
    }
  }
}

🔍 过滤查询

通用过滤参数

GET /api/v1/agents?status=active&category_id=1&created_at>=2023-12-01&created_at<=2023-12-31

支持的过滤操作:

=: 等于
!=: 不等于
>: 大于
>=: 大于等于
<: 小于
<=: 小于等于
like: 模糊匹配
in: 包含于列表

📚 SDK 和工具

OpenAPI 规范

完整的 API 规范文档可通过以下方式获取：

Swagger UI: http://localhost:8000/swagger/
OpenAPI 文件: /openapi.yaml

Postman Collection

提供完整的 Postman 测试集合，包含所有 API 的示例请求。

代码生成

支持根据 OpenAPI 规范生成多语言客户端 SDK：

# 生成 Go SDK
openapi-generator-cli generate -i openapi.yaml -g go -o ./sdk/go

# 生成 JavaScript SDK
openapi-generator-cli generate -i openapi.yaml -g javascript -o ./sdk/js

# 生成 Python SDK
openapi-generator-cli generate -i openapi.yaml -g python -o ./sdk/python

🧪 测试环境

测试地址

本地环境: http://localhost:8000
测试环境: https://api-test.jingyun.team
生产环境: https://api.jingyun.team

测试账号

环境	用户名	密码	角色
本地	admin@example.com	admin123	管理员
本地	user@example.com	user123	普通用户

📖 相关文档:

API 文档 - 各服务 API 接口说明

🌐 API 架构​

网关层​

协议支持​

📚 API 服务概览​

🔐 认证服务 (Auth Service)​

👤 用户服务 (User Service)​

🏢 租户服务 (Tenant Service)​

🤖 智能体服务 (Agent Service)​

💰 支付服务 (Payment Service)​

🔗 集成服务 (Integration Service)​

🔐 认证机制​

JWT Token 认证​

错误码说明​

Token 获取流程​

📝 请求格式​

HTTP Headers​

响应格式​

🚨 错误处理​

错误响应格式​

常见错误码​

📊 分页查询​

分页参数​

🔗 相关资源​

OpenAPI 规范​

服务文档​

开发指南​

🔐 认证机制​

JWT Token 认证​

Token 获取流程​

权限控制​

📝 请求格式​

HTTP Headers​

请求体格式​

响应格式​

🚨 错误处理​

错误响应格式​

常见错误码​

📊 分页查询​

分页参数​

分页响应​

🔍 过滤查询​

通用过滤参数​

📚 SDK 和工具​

OpenAPI 规范​

Postman Collection​

代码生成​

🧪 测试环境​

测试地址​

测试账号​

🌐 API 架构

网关层

协议支持

📚 API 服务概览

🔐 认证服务 (Auth Service)

👤 用户服务 (User Service)

🏢 租户服务 (Tenant Service)

🤖 智能体服务 (Agent Service)

💰 支付服务 (Payment Service)

🔗 集成服务 (Integration Service)

🔐 认证机制

JWT Token 认证

错误码说明

Token 获取流程

📝 请求格式

HTTP Headers

响应格式

🚨 错误处理

错误响应格式

常见错误码

📊 分页查询

分页参数

🔗 相关资源

OpenAPI 规范

服务文档

开发指南

🔐 认证机制

JWT Token 认证

Token 获取流程

权限控制

📝 请求格式

HTTP Headers

请求体格式

响应格式

🚨 错误处理

错误响应格式

常见错误码

📊 分页查询

分页参数

分页响应

🔍 过滤查询

通用过滤参数

📚 SDK 和工具

OpenAPI 规范

Postman Collection

代码生成

🧪 测试环境

测试地址

测试账号