docs: 补全基础设施文档 (DB设计/API规范/MiMoCode配置)
- 03-数据库设计.md: ER图 + 12张表定义 + Redis数据结构 + Migration策略 - 04-API接口规范.md: OpenAPI 3.0 约定 + 全部接口定义 (Auth/APIKey/LLM/Billing/Registry/Skills/IM/Admin) - 05-AGENTS-MiMoCode配置.md: MiMo Code 核心配置文件，包含项目结构/技术栈/开发规范/模块说明 至此 docs/ 目录包含完整的6份基础设计文档，可作为 MiMo Code 的上下文输入
This commit is contained in:
qyyfw committed
1 parent
67c3270aad
commit
d9a8a0e93c
5 files changed
+2099
No files matched your search
@@ -0,0 +1,572 @@
|
||||
# AI PaaS 商业平台 — API 接口规范
|
||||
|
||||
> 版本: 1.0 | 日期: 2026-06-27
|
||||
> 规范: OpenAPI 3.0 | Base URL: https://api.aipaas.com
|
||||
|
||||
---
|
||||
|
||||
## 1. 通用约定
|
||||
|
||||
### 1.1 认证方式
|
||||
|
||||
| 方式 | Header | 说明 |
|
||||
|------|--------|------|
|
||||
| JWT | `Authorization: Bearer {access_token}` | Web 前端登录后使用 |
|
||||
| API Key | `Authorization: Bearer aip_{key}` | 程序化调用 |
|
||||
|
||||
### 1.2 响应格式
|
||||
|
||||
```json
|
||||
// 成功
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": { ... }
|
||||
}
|
||||
|
||||
// 分页
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"items": [...],
|
||||
"total": 100,
|
||||
"page": 1,
|
||||
"page_size": 20
|
||||
}
|
||||
}
|
||||
|
||||
// 错误
|
||||
{
|
||||
"code": 40001,
|
||||
"message": "Insufficient balance",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
### 1.3 错误码
|
||||
|
||||
| 错误码 | HTTP Status | 说明 |
|
||||
|--------|------------|------|
|
||||
| 0 | 200 | 成功 |
|
||||
| 40001 | 400 | 请求参数错误 |
|
||||
| 40101 | 401 | 未认证 |
|
||||
| 40102 | 401 | API Key 无效 |
|
||||
| 40301 | 403 | 权限不足 |
|
||||
| 40401 | 404 | 资源不存在 |
|
||||
| 40201 | 402 | Credit 余额不足 |
|
||||
| 42901 | 429 | 请求频率超限 |
|
||||
| 50001 | 500 | 服务内部错误 |
|
||||
| 50201 | 502 | 上游服务不可用 |
|
||||
|
||||
---
|
||||
|
||||
## 2. Auth 接口
|
||||
|
||||
### POST /api/v1/auth/register
|
||||
```yaml
|
||||
description: 用户注册
|
||||
request:
|
||||
body:
|
||||
email: string (required)
|
||||
password: string (required, min 8)
|
||||
name: string (required)
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
user_id: uuid
|
||||
email: string
|
||||
tenant_id: uuid
|
||||
```
|
||||
|
||||
### POST /api/v1/auth/login
|
||||
```yaml
|
||||
description: 用户登录
|
||||
request:
|
||||
body:
|
||||
email: string (required)
|
||||
password: string (required)
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
access_token: string (JWT, 1h)
|
||||
refresh_token: string (JWT, 7d)
|
||||
expires_in: integer (seconds)
|
||||
user:
|
||||
id: uuid
|
||||
name: string
|
||||
email: string
|
||||
role: string
|
||||
tenant_id: uuid
|
||||
```
|
||||
|
||||
### POST /api/v1/auth/refresh
|
||||
```yaml
|
||||
description: 刷新 Token
|
||||
request:
|
||||
body:
|
||||
refresh_token: string (required)
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
access_token: string
|
||||
expires_in: integer
|
||||
```
|
||||
|
||||
### GET /api/v1/auth/me
|
||||
```yaml
|
||||
description: 获取当前用户信息
|
||||
auth: JWT
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
id: uuid
|
||||
name: string
|
||||
email: string
|
||||
role: string
|
||||
tenant_id: uuid
|
||||
tenant:
|
||||
name: string
|
||||
plan: string
|
||||
credit_balance: integer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. API Key 接口
|
||||
|
||||
### POST /api/v1/apikeys
|
||||
```yaml
|
||||
description: 创建 API Key
|
||||
auth: JWT
|
||||
request:
|
||||
body:
|
||||
name: string (required) # 用途标识
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
id: uuid
|
||||
name: string
|
||||
key: string # 仅此一次展示明文
|
||||
key_prefix: string # aip_xxxx
|
||||
created_at: datetime
|
||||
```
|
||||
|
||||
### GET /api/v1/apikeys
|
||||
```yaml
|
||||
description: API Key 列表
|
||||
auth: JWT
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
items:
|
||||
- id: uuid
|
||||
name: string
|
||||
key_prefix: string
|
||||
last_used_at: datetime
|
||||
status: string
|
||||
created_at: datetime
|
||||
```
|
||||
|
||||
### DELETE /api/v1/apikeys/{id}
|
||||
```yaml
|
||||
description: 删除 API Key
|
||||
auth: JWT
|
||||
response:
|
||||
200: { code: 0, message: "success" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. LLM 调用接口（OpenAI 兼容）
|
||||
|
||||
### POST /v1/chat/completions
|
||||
```yaml
|
||||
description: Chat Completion (OpenAI 兼容格式)
|
||||
auth: API Key 或 JWT
|
||||
request:
|
||||
body:
|
||||
model: string (required) # deepseek-chat, qwen-turbo, etc.
|
||||
messages:
|
||||
- role: string # system/user/assistant
|
||||
content: string
|
||||
temperature: number (optional, 0-2, default 1)
|
||||
max_tokens: integer (optional)
|
||||
stream: boolean (optional, default false)
|
||||
top_p: number (optional)
|
||||
stop: string | array (optional)
|
||||
response:
|
||||
200:
|
||||
# 非流式
|
||||
id: string
|
||||
object: "chat.completion"
|
||||
model: string
|
||||
choices:
|
||||
- index: 0
|
||||
message:
|
||||
role: "assistant"
|
||||
content: string
|
||||
finish_reason: "stop"
|
||||
usage:
|
||||
prompt_tokens: integer
|
||||
completion_tokens: integer
|
||||
total_tokens: integer
|
||||
# 流式 (SSE)
|
||||
# Content-Type: text/event-stream
|
||||
# data: {"id":"...","choices":[{"delta":{"content":"token"}}]}
|
||||
# data: [DONE]
|
||||
```
|
||||
|
||||
### GET /v1/models
|
||||
```yaml
|
||||
description: 可用模型列表
|
||||
auth: API Key 或 JWT
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
- id: "deepseek-chat"
|
||||
object: "model"
|
||||
provider: "deepseek"
|
||||
pricing:
|
||||
credits_per_1k: 1.0
|
||||
- id: "qwen-turbo"
|
||||
object: "model"
|
||||
provider: "qianwen"
|
||||
pricing:
|
||||
credits_per_1k: 0.8
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Billing 接口
|
||||
|
||||
### GET /api/v1/billing/balance
|
||||
```yaml
|
||||
description: 查询 Credit 余额
|
||||
auth: JWT
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
balance: integer # 当前余额 (毫 Credit)
|
||||
balance_display: number # 显示余额 (Credit)
|
||||
plan: string
|
||||
credits_included: integer
|
||||
credits_used: integer
|
||||
period_end: datetime
|
||||
```
|
||||
|
||||
### POST /api/v1/billing/topup
|
||||
```yaml
|
||||
description: 充值
|
||||
auth: JWT
|
||||
request:
|
||||
body:
|
||||
amount: integer (required) # 充值金额 (分)
|
||||
payment_method: string # alipay/wechat
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
order_id: string
|
||||
payment_url: string # 支付链接
|
||||
```
|
||||
|
||||
### GET /api/v1/billing/transactions
|
||||
```yaml
|
||||
description: Credit 流水查询
|
||||
auth: JWT
|
||||
request:
|
||||
query:
|
||||
page: integer (default 1)
|
||||
page_size: integer (default 20)
|
||||
type: string (optional) # usage/topup/subscription
|
||||
start_date: date (optional)
|
||||
end_date: date (optional)
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
items:
|
||||
- id: uuid
|
||||
type: string
|
||||
amount: integer
|
||||
balance_after: integer
|
||||
description: string
|
||||
trace_id: string
|
||||
created_at: datetime
|
||||
total: integer
|
||||
page: integer
|
||||
page_size: integer
|
||||
```
|
||||
|
||||
### POST /api/v1/billing/subscribe
|
||||
```yaml
|
||||
description: 订阅管理
|
||||
auth: JWT
|
||||
request:
|
||||
body:
|
||||
plan: string (required) # pro/team
|
||||
billing_cycle: string # monthly/yearly
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
subscription_id: uuid
|
||||
plan: string
|
||||
price_cents: integer
|
||||
credits_included: integer
|
||||
period_start: datetime
|
||||
period_end: datetime
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Capability Registry 接口
|
||||
|
||||
### POST /api/v1/capabilities
|
||||
```yaml
|
||||
description: 注册新能力
|
||||
auth: JWT
|
||||
request:
|
||||
body:
|
||||
name: string (required)
|
||||
type: string (required) # agent/mcp/skill/llm/custom
|
||||
version: string (required) # SemVer
|
||||
description: string
|
||||
tags: array[string]
|
||||
endpoint: string
|
||||
protocol: string # rest/grpc/websocket
|
||||
pricing_config: object
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
id: uuid
|
||||
status: "draft"
|
||||
```
|
||||
|
||||
### GET /api/v1/capabilities
|
||||
```yaml
|
||||
description: 能力列表
|
||||
auth: JWT 或 API Key
|
||||
request:
|
||||
query:
|
||||
type: string (optional)
|
||||
status: string (optional)
|
||||
tags: string (optional) # 逗号分隔
|
||||
page: integer
|
||||
page_size: integer
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
items:
|
||||
- id: uuid
|
||||
name: string
|
||||
type: string
|
||||
version: string
|
||||
status: string
|
||||
tags: array[string]
|
||||
invoke_count: integer
|
||||
created_at: datetime
|
||||
```
|
||||
|
||||
### GET /api/v1/capabilities/{id}
|
||||
```yaml
|
||||
description: 能力详情
|
||||
auth: JWT 或 API Key
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
id: uuid
|
||||
name: string
|
||||
type: string
|
||||
version: string
|
||||
description: string
|
||||
tags: array[string]
|
||||
endpoint: string
|
||||
protocol: string
|
||||
pricing_config: object
|
||||
status: string
|
||||
invoke_count: integer
|
||||
created_at: datetime
|
||||
```
|
||||
|
||||
### PUT /api/v1/capabilities/{id}
|
||||
```yaml
|
||||
description: 更新能力
|
||||
auth: JWT
|
||||
request:
|
||||
body:
|
||||
name: string (optional)
|
||||
description: string (optional)
|
||||
tags: array[string] (optional)
|
||||
endpoint: string (optional)
|
||||
pricing_config: object (optional)
|
||||
```
|
||||
|
||||
### DELETE /api/v1/capabilities/{id}
|
||||
```yaml
|
||||
description: 注销能力
|
||||
auth: JWT
|
||||
```
|
||||
|
||||
### POST /api/v1/capabilities/{id}/versions
|
||||
```yaml
|
||||
description: 发布新版本
|
||||
auth: JWT
|
||||
request:
|
||||
body:
|
||||
version: string (required)
|
||||
endpoint: string
|
||||
changelog: string
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Skills 市场接口
|
||||
|
||||
### POST /api/v1/skills
|
||||
```yaml
|
||||
description: 发布技能
|
||||
auth: JWT
|
||||
request:
|
||||
body:
|
||||
name: string (required)
|
||||
description: string
|
||||
category: string
|
||||
tags: array[string]
|
||||
pricing_model: string # per_call/per_token/subscription/free
|
||||
price_credits: integer
|
||||
endpoint: string
|
||||
documentation: string
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
id: uuid
|
||||
```
|
||||
|
||||
### GET /api/v1/skills
|
||||
```yaml
|
||||
description: 市场列表
|
||||
auth: 公开
|
||||
request:
|
||||
query:
|
||||
q: string (optional) # 搜索关键词
|
||||
category: string (optional)
|
||||
tags: string (optional)
|
||||
sort: string # rating/popular/newest
|
||||
page: integer
|
||||
page_size: integer
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
items:
|
||||
- id: uuid
|
||||
name: string
|
||||
description: string
|
||||
category: string
|
||||
pricing_model: string
|
||||
price_credits: integer
|
||||
rating: number
|
||||
purchase_count: integer
|
||||
developer:
|
||||
name: string
|
||||
```
|
||||
|
||||
### POST /api/v1/skills/{id}/purchase
|
||||
```yaml
|
||||
description: 购买技能
|
||||
auth: JWT
|
||||
request:
|
||||
body:
|
||||
# 无需参数，自动扣费
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
purchase_id: uuid
|
||||
credits_deducted: integer
|
||||
balance_after: integer
|
||||
```
|
||||
|
||||
### GET /api/v1/skills/purchased
|
||||
```yaml
|
||||
description: 已购技能列表
|
||||
auth: JWT
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
items:
|
||||
- skill_id: uuid
|
||||
name: string
|
||||
purchased_at: datetime
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. IM Bot 接口
|
||||
|
||||
### POST /api/v1/im/callback/{platform}
|
||||
```yaml
|
||||
description: 平台回调 (Webhook)
|
||||
auth: 平台签名验证
|
||||
request:
|
||||
body: 平台消息格式 (各平台不同)
|
||||
response:
|
||||
200: 平台要求的响应格式
|
||||
```
|
||||
|
||||
### GET /api/v1/im/sessions
|
||||
```yaml
|
||||
description: 会话列表
|
||||
auth: JWT
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
items:
|
||||
- id: uuid
|
||||
platform: string
|
||||
user_identifier: string
|
||||
user_name: string
|
||||
model: string
|
||||
last_active_at: datetime
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Admin 接口
|
||||
|
||||
### GET /api/v1/admin/dashboard
|
||||
```yaml
|
||||
description: 管理仪表盘
|
||||
auth: JWT (admin 角色)
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
total_users: integer
|
||||
total_tenants: integer
|
||||
total_api_calls: integer (今日)
|
||||
total_revenue: integer (本月)
|
||||
system_status: object
|
||||
```
|
||||
|
||||
### GET /api/v1/admin/users
|
||||
```yaml
|
||||
description: 用户列表
|
||||
auth: JWT (admin 角色)
|
||||
request:
|
||||
query:
|
||||
q: string (optional)
|
||||
status: string (optional)
|
||||
page: integer
|
||||
page_size: integer
|
||||
```
|
||||
|
||||
### POST /api/v1/admin/capabilities/{id}/review
|
||||
```yaml
|
||||
description: 能力审核
|
||||
auth: JWT (admin 角色)
|
||||
request:
|
||||
body:
|
||||
action: string # approve/reject
|
||||
note: string
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*文档结束*
|
||||
Reference in new issue
Block a user