docs: v2.0 全面修订 — 开源优先 + 扁平化用户模型
核心变更: - 产品定位: '像用水电一样使用AI能力，注册即用，按量付费' - 用户模型: 去掉租户概念，扁平化为 订阅用户/非订阅用户 - 认证: Casdoor SSO + 阿里云实名认证（替代 Keycloak） - LLM 网关: NEW API 开源（替代自研 Go 网关） - AI 服务: FastAPI（替代 Go 自研，AI 生态更兼容） - 新增: 欠费不影响已发布能力（核心商业规则） - 新增: 开发者提现模块 - 开发周期: 20周 → 15周（开源组件复用） 文档列表: - 01-PRD-产品需求文档.md (v2.0) - 02-系统架构设计.md (v2.0) - 03-数据库设计.md (v2.0) - 04-API接口规范.md (v2.0) - 05-AGENTS-MiMoCode配置.md (v2.0)
This commit is contained in:
qyyfw committed
1 parent
d9a8a0e93c
commit
8209f15d0a
5 files changed
+1031
-1433
No files matched your search
+199
-261
@@ -1,6 +1,7 @@
|
||||
# AI PaaS 商业平台 — API 接口规范
|
||||
|
||||
> 版本: 1.0 | 日期: 2026-06-27
|
||||
> 版本: 2.0 | 日期: 2026-06-27
|
||||
> 状态: 已修订（扁平化用户模型 + Casdoor/NEW API 集成）
|
||||
> 规范: OpenAPI 3.0 | Base URL: https://api.aipaas.com
|
||||
|
||||
---
|
||||
@@ -11,93 +12,80 @@
|
||||
|
||||
| 方式 | Header | 说明 |
|
||||
|------|--------|------|
|
||||
| JWT | `Authorization: Bearer {access_token}` | Web 前端登录后使用 |
|
||||
| JWT | `Authorization: Bearer {access_token}` | Casdoor 签发，Web 前端使用 |
|
||||
| API Key | `Authorization: Bearer aip_{key}` | 程序化调用 |
|
||||
|
||||
### 1.2 响应格式
|
||||
|
||||
```json
|
||||
// 成功
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": { ... }
|
||||
}
|
||||
{ "code": 0, "message": "success", "data": { ... } }
|
||||
|
||||
// 分页
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"items": [...],
|
||||
"total": 100,
|
||||
"page": 1,
|
||||
"page_size": 20
|
||||
}
|
||||
}
|
||||
{ "code": 0, "message": "success", "data": { "items": [...], "total": 100, "page": 1, "page_size": 20 } }
|
||||
|
||||
// 错误
|
||||
{
|
||||
"code": 40001,
|
||||
"message": "Insufficient balance",
|
||||
"data": null
|
||||
}
|
||||
{ "code": 40001, "message": "Insufficient balance", "data": null }
|
||||
```
|
||||
|
||||
### 1.3 错误码
|
||||
|
||||
| 错误码 | HTTP Status | 说明 |
|
||||
|--------|------------|------|
|
||||
| 错误码 | HTTP | 说明 |
|
||||
|--------|------|------|
|
||||
| 0 | 200 | 成功 |
|
||||
| 40001 | 400 | 请求参数错误 |
|
||||
| 40001 | 400 | 参数错误 |
|
||||
| 40101 | 401 | 未认证 |
|
||||
| 40102 | 401 | API Key 无效 |
|
||||
| 40301 | 403 | 权限不足 |
|
||||
| 40301 | 403 | 权限不足（需订阅） |
|
||||
| 40401 | 404 | 资源不存在 |
|
||||
| 40201 | 402 | Credit 余额不足 |
|
||||
| 42901 | 429 | 请求频率超限 |
|
||||
| 50001 | 500 | 服务内部错误 |
|
||||
| 50201 | 502 | 上游服务不可用 |
|
||||
| 40201 | 402 | 余额不足 |
|
||||
| 40302 | 403 | 未实名认证 |
|
||||
| 42901 | 429 | 频率超限 |
|
||||
|
||||
---
|
||||
|
||||
## 2. Auth 接口
|
||||
## 2. 认证接口（Casdoor 代理）
|
||||
|
||||
### POST /api/v1/auth/register
|
||||
```yaml
|
||||
description: 用户注册
|
||||
description: 注册（手机号 + 验证码）
|
||||
request:
|
||||
body:
|
||||
email: string (required)
|
||||
password: string (required, min 8)
|
||||
name: string (required)
|
||||
phone: string (required)
|
||||
code: string (required, 6位验证码)
|
||||
name: string (optional, 默认 "用户_{phone后4位}")
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
user_id: uuid
|
||||
email: string
|
||||
tenant_id: uuid
|
||||
access_token: string (JWT, 由 Casdoor 签发)
|
||||
refresh_token: string
|
||||
```
|
||||
|
||||
### POST /api/v1/auth/login
|
||||
```yaml
|
||||
description: 用户登录
|
||||
description: 登录（手机号 + 验证码）
|
||||
request:
|
||||
body:
|
||||
phone: string (required)
|
||||
code: string (required)
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
access_token: string
|
||||
refresh_token: string
|
||||
expires_in: integer
|
||||
user: { id, name, phone, verified, subscribed }
|
||||
```
|
||||
|
||||
### POST /api/v1/auth/login/email
|
||||
```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
|
||||
response: 同上
|
||||
```
|
||||
|
||||
### POST /api/v1/auth/refresh
|
||||
@@ -122,18 +110,47 @@ response:
|
||||
data:
|
||||
id: uuid
|
||||
name: string
|
||||
phone: string (脱敏)
|
||||
email: string
|
||||
role: string
|
||||
tenant_id: uuid
|
||||
tenant:
|
||||
name: string
|
||||
verified: boolean # 是否实名认证
|
||||
subscribed: boolean # 是否订阅用户
|
||||
subscription: # 订阅详情（如有）
|
||||
plan: string
|
||||
credit_balance: integer
|
||||
credits_included: integer
|
||||
credits_used: integer
|
||||
period_end: datetime
|
||||
grace_end: datetime # 欠费保护期
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. API Key 接口
|
||||
## 3. 实名认证接口
|
||||
|
||||
### POST /api/v1/auth/verify
|
||||
```yaml
|
||||
description: 实名认证（调用阿里云实名认证 API）
|
||||
auth: JWT
|
||||
request:
|
||||
body:
|
||||
real_name: string (required) # 真实姓名
|
||||
id_card: string (required) # 身份证号
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
verified: true
|
||||
message: "实名认证成功"
|
||||
400:
|
||||
code: 40001
|
||||
message: "身份证号格式错误"
|
||||
400:
|
||||
code: 40303
|
||||
message: "实名认证失败，姓名与身份证号不匹配"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. API Key 管理
|
||||
|
||||
### POST /api/v1/apikeys
|
||||
```yaml
|
||||
@@ -141,14 +158,14 @@ description: 创建 API Key
|
||||
auth: JWT
|
||||
request:
|
||||
body:
|
||||
name: string (required) # 用途标识
|
||||
name: string (required)
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
id: uuid
|
||||
name: string
|
||||
key: string # 仅此一次展示明文
|
||||
key_prefix: string # aip_xxxx
|
||||
key: string # 仅此一次展示明文 aip_xxxxxxxxxxxx
|
||||
key_prefix: string
|
||||
created_at: datetime
|
||||
```
|
||||
|
||||
@@ -160,180 +177,147 @@ response:
|
||||
200:
|
||||
data:
|
||||
items:
|
||||
- id: uuid
|
||||
name: string
|
||||
key_prefix: string
|
||||
last_used_at: datetime
|
||||
status: string
|
||||
created_at: datetime
|
||||
- id, name, key_prefix, last_used_at, status, created_at
|
||||
```
|
||||
|
||||
### DELETE /api/v1/apikeys/{id}
|
||||
```yaml
|
||||
description: 删除 API Key
|
||||
auth: JWT
|
||||
response:
|
||||
200: { code: 0, message: "success" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. LLM 调用接口（OpenAI 兼容）
|
||||
## 5. LLM 调用接口（OpenAI 兼容，通过 NEW API）
|
||||
|
||||
### POST /v1/chat/completions
|
||||
```yaml
|
||||
description: Chat Completion (OpenAI 兼容格式)
|
||||
auth: API Key 或 JWT
|
||||
description: Chat Completion（OpenAI 兼容格式，代理到 NEW API）
|
||||
auth: JWT 或 API Key
|
||||
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)
|
||||
model: string (required)
|
||||
messages: [{ role, content }]
|
||||
temperature: number (0-2, default 1)
|
||||
max_tokens: integer
|
||||
stream: boolean (default false)
|
||||
top_p: number
|
||||
response:
|
||||
200:
|
||||
# 非流式
|
||||
id: string
|
||||
object: "chat.completion"
|
||||
model: string
|
||||
choices:
|
||||
- index: 0
|
||||
message:
|
||||
role: "assistant"
|
||||
content: string
|
||||
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]
|
||||
# 流式: SSE (text/event-stream)
|
||||
```
|
||||
|
||||
### GET /v1/models
|
||||
```yaml
|
||||
description: 可用模型列表
|
||||
auth: API Key 或 JWT
|
||||
description: 可用模型列表（从 NEW API 获取）
|
||||
auth: JWT 或 API Key
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
- id: "deepseek-chat"
|
||||
object: "model"
|
||||
provider: "deepseek"
|
||||
pricing:
|
||||
credits_per_1k: 1.0
|
||||
pricing: { credits_per_1k: 1.0 }
|
||||
- id: "qwen-turbo"
|
||||
object: "model"
|
||||
provider: "qianwen"
|
||||
pricing:
|
||||
credits_per_1k: 0.8
|
||||
pricing: { credits_per_1k: 0.8 }
|
||||
- id: "ollama-qwen2.5"
|
||||
provider: "ollama"
|
||||
pricing: { credits_per_1k: 0.1 }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Billing 接口
|
||||
## 6. 计费与订阅
|
||||
|
||||
### GET /api/v1/billing/balance
|
||||
```yaml
|
||||
description: 查询 Credit 余额
|
||||
description: 查询余额
|
||||
auth: JWT
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
balance: integer # 当前余额 (毫 Credit)
|
||||
balance_display: number # 显示余额 (Credit)
|
||||
balance: integer # 当前余额 (分)
|
||||
balance_display: string # "¥125.80"
|
||||
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
|
||||
plan: string (required) # developer/pro/flagship
|
||||
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
|
||||
payment_url: string # 支付链接
|
||||
```
|
||||
|
||||
### POST /api/v1/billing/topup
|
||||
```yaml
|
||||
description: 充值 Token 包
|
||||
auth: JWT
|
||||
request:
|
||||
body:
|
||||
package: string (required) # 10/50/100
|
||||
payment_method: string # alipay/wechat
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
order_id: string
|
||||
payment_url: string
|
||||
```
|
||||
|
||||
### GET /api/v1/billing/transactions
|
||||
```yaml
|
||||
description: 流水查询
|
||||
auth: JWT
|
||||
request:
|
||||
query:
|
||||
page, page_size, type, start_date, end_date
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
items: [{ id, type, amount, balance_after, description, trace_id, created_at }]
|
||||
total, page, page_size
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Capability Registry 接口
|
||||
## 7. 能力注册
|
||||
|
||||
### POST /api/v1/capabilities
|
||||
```yaml
|
||||
description: 注册新能力
|
||||
description: 创建能力（需订阅用户）
|
||||
auth: JWT
|
||||
precondition: subscribed == true
|
||||
request:
|
||||
body:
|
||||
name: string (required)
|
||||
type: string (required) # agent/mcp/skill/llm/custom
|
||||
version: string (required) # SemVer
|
||||
type: string (required) # agent/mcp/skill/llm/custom
|
||||
version: string (required)
|
||||
description: string
|
||||
tags: array[string]
|
||||
endpoint: string
|
||||
protocol: string # rest/grpc/websocket
|
||||
pricing_config: object
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
@@ -344,65 +328,31 @@ response:
|
||||
### GET /api/v1/capabilities
|
||||
```yaml
|
||||
description: 能力列表
|
||||
auth: JWT 或 API Key
|
||||
auth: 公开
|
||||
request:
|
||||
query:
|
||||
type: string (optional)
|
||||
status: string (optional)
|
||||
tags: string (optional) # 逗号分隔
|
||||
page: integer
|
||||
page_size: integer
|
||||
type, status, tags, page, page_size
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
items:
|
||||
- id: uuid
|
||||
name: string
|
||||
type: string
|
||||
version: string
|
||||
status: string
|
||||
tags: array[string]
|
||||
invoke_count: integer
|
||||
created_at: datetime
|
||||
items: [{ id, name, type, version, status, tags, invoke_count, created_at }]
|
||||
```
|
||||
|
||||
### 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
|
||||
auth: 公开
|
||||
```
|
||||
|
||||
### PUT /api/v1/capabilities/{id}
|
||||
```yaml
|
||||
description: 更新能力
|
||||
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: 注销能力
|
||||
description: 注销能力（已发布的保持在线，标记 deprecated）
|
||||
auth: JWT
|
||||
```
|
||||
|
||||
@@ -417,56 +367,51 @@ request:
|
||||
changelog: string
|
||||
```
|
||||
|
||||
### POST /api/v1/capabilities/{id}/review
|
||||
```yaml
|
||||
description: 提交审核（管理员）
|
||||
auth: JWT (admin)
|
||||
request:
|
||||
body:
|
||||
action: string # approve/reject
|
||||
note: string
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Skills 市场接口
|
||||
## 8. Skills 市场
|
||||
|
||||
### POST /api/v1/skills
|
||||
```yaml
|
||||
description: 发布技能
|
||||
description: 发布技能（需订阅）
|
||||
auth: JWT
|
||||
precondition: subscribed == true
|
||||
request:
|
||||
body:
|
||||
name: string (required)
|
||||
description: string
|
||||
category: string
|
||||
tags: array[string]
|
||||
pricing_model: string # per_call/per_token/subscription/free
|
||||
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: 市场列表
|
||||
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
|
||||
q: string (搜索)
|
||||
category, tags, sort (rating/popular/newest), page, page_size
|
||||
```
|
||||
|
||||
### GET /api/v1/skills/{id}
|
||||
```yaml
|
||||
description: 技能详情
|
||||
auth: 公开
|
||||
```
|
||||
|
||||
### POST /api/v1/skills/{id}/purchase
|
||||
@@ -474,8 +419,7 @@ response:
|
||||
description: 购买技能
|
||||
auth: JWT
|
||||
request:
|
||||
body:
|
||||
# 无需参数，自动扣费
|
||||
body: # 无需参数，自动扣费
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
@@ -486,85 +430,79 @@ response:
|
||||
|
||||
### GET /api/v1/skills/purchased
|
||||
```yaml
|
||||
description: 已购技能列表
|
||||
description: 已购技能
|
||||
auth: JWT
|
||||
```
|
||||
|
||||
### GET /api/v1/skills/developer/dashboard
|
||||
```yaml
|
||||
description: 开发者仪表盘
|
||||
auth: JWT (subscribed)
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
items:
|
||||
- skill_id: uuid
|
||||
name: string
|
||||
purchased_at: datetime
|
||||
total_skills: integer
|
||||
total_purchases: integer
|
||||
total_revenue: integer
|
||||
pending_payout: integer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. IM Bot 接口
|
||||
## 9. 开发者提现
|
||||
|
||||
### POST /api/v1/im/callback/{platform}
|
||||
### POST /api/v1/developer/payout
|
||||
```yaml
|
||||
description: 平台回调 (Webhook)
|
||||
auth: 平台签名验证
|
||||
description: 申请提现
|
||||
auth: JWT (subscribed)
|
||||
request:
|
||||
body: 平台消息格式 (各平台不同)
|
||||
response:
|
||||
200: 平台要求的响应格式
|
||||
body:
|
||||
amount_cents: integer (required, min 10000 = ¥100)
|
||||
method: string # alipay/bank
|
||||
account_info: object # 收款信息（加密传输）
|
||||
```
|
||||
|
||||
### GET /api/v1/im/sessions
|
||||
### GET /api/v1/developer/payouts
|
||||
```yaml
|
||||
description: 会话列表
|
||||
auth: JWT
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
items:
|
||||
- id: uuid
|
||||
platform: string
|
||||
user_identifier: string
|
||||
user_name: string
|
||||
model: string
|
||||
last_active_at: datetime
|
||||
description: 提现记录
|
||||
auth: JWT (subscribed)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Admin 接口
|
||||
## 10. 管理后台
|
||||
|
||||
### GET /api/v1/admin/dashboard
|
||||
```yaml
|
||||
description: 管理仪表盘
|
||||
auth: JWT (admin 角色)
|
||||
auth: JWT (admin)
|
||||
response:
|
||||
200:
|
||||
data:
|
||||
total_users: integer
|
||||
total_tenants: integer
|
||||
total_subscribers: integer
|
||||
total_api_calls: integer (今日)
|
||||
total_revenue: integer (本月)
|
||||
pending_reviews: 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
|
||||
auth: JWT (admin)
|
||||
```
|
||||
|
||||
### POST /api/v1/admin/capabilities/{id}/review
|
||||
```yaml
|
||||
description: 能力审核
|
||||
auth: JWT (admin 角色)
|
||||
request:
|
||||
body:
|
||||
action: string # approve/reject
|
||||
note: string
|
||||
auth: JWT (admin)
|
||||
```
|
||||
|
||||
### POST /api/v1/admin/users/{id}/suspend
|
||||
```yaml
|
||||
description: 封禁用户
|
||||
auth: JWT (admin)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Reference in new issue
Block a user