Xiaoxia AI
cbb1d81988
- Create detailed API usage guide with examples - Cover all 19 API endpoints with request/response samples - Add authentication flow documentation - Include error handling and best practices - Add rate limiting and token management guide - Create CHANGELOG.md tracking all Phase 4 changes Phase 4 Task 34/68 completed
418 lines
6.9 KiB
Markdown
418 lines
6.9 KiB
Markdown
# 小虾 SaaS API 使用指南
|
||
|
||
## 📖 概述
|
||
|
||
小虾 SaaS 是一个完整的多租户 SaaS 平台，提供用户认证、工作空间管理、团队协作和订阅管理功能。
|
||
|
||
**基础 URL:** `http://localhost:8000` (开发环境)
|
||
|
||
**API 文档:**
|
||
- Swagger UI: http://localhost:8000/docs
|
||
- ReDoc: http://localhost:8000/redoc
|
||
|
||
---
|
||
|
||
## 🔐 认证流程
|
||
|
||
### 1. 注册用户
|
||
|
||
```http
|
||
POST /api/v1/auth/register
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"email": "user@example.com",
|
||
"password": "SecurePass123",
|
||
"username": "myusername",
|
||
"display_name": "My Name"
|
||
}
|
||
```
|
||
|
||
**响应:**
|
||
```json
|
||
{
|
||
"user_id": "abc123...",
|
||
"email": "user@example.com",
|
||
"username": "myusername",
|
||
"display_name": "My Name",
|
||
"email_verification_sent": true
|
||
}
|
||
```
|
||
|
||
### 2. 验证邮箱
|
||
|
||
点击邮件中的链接，或访问：
|
||
```http
|
||
GET /api/v1/auth/verify-email?token=VERIFICATION_TOKEN
|
||
```
|
||
|
||
### 3. 登录
|
||
|
||
```http
|
||
POST /api/v1/auth/login
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"email": "user@example.com",
|
||
"password": "SecurePass123"
|
||
}
|
||
```
|
||
|
||
**响应:**
|
||
```json
|
||
{
|
||
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
|
||
"refresh_token": "abc123...",
|
||
"token_type": "bearer",
|
||
"user_id": "...",
|
||
"email": "user@example.com",
|
||
"username": "myusername",
|
||
"display_name": "My Name",
|
||
"expires_in": 1800
|
||
}
|
||
```
|
||
|
||
### 4. 使用 Access Token
|
||
|
||
在所有需要认证的接口中添加 Header：
|
||
```http
|
||
Authorization: Bearer YOUR_ACCESS_TOKEN
|
||
```
|
||
|
||
---
|
||
|
||
## 🏢 工作空间管理
|
||
|
||
### 1. 创建工作空间
|
||
|
||
```http
|
||
POST /api/v1/workspaces
|
||
Authorization: Bearer YOUR_TOKEN
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"name": "我的团队",
|
||
"subscription_plan": "free"
|
||
}
|
||
```
|
||
|
||
**响应:**
|
||
```json
|
||
{
|
||
"workspace_id": "ws123...",
|
||
"name": "我的团队",
|
||
"subscription_plan": "free",
|
||
"max_projects": 3,
|
||
"max_storage_gb": 10
|
||
}
|
||
```
|
||
|
||
### 2. 获取工作空间列表
|
||
|
||
```http
|
||
GET /api/v1/workspaces
|
||
Authorization: Bearer YOUR_TOKEN
|
||
```
|
||
|
||
**响应:**
|
||
```json
|
||
{
|
||
"workspaces": [
|
||
{
|
||
"workspace_id": "ws123...",
|
||
"name": "我的团队",
|
||
"subscription_plan": "free",
|
||
"max_projects": 3,
|
||
"max_storage_gb": 10,
|
||
"member_count": 1,
|
||
"user_role": "owner"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 3. 获取工作空间详情
|
||
|
||
```http
|
||
GET /api/v1/workspaces/{workspace_id}
|
||
Authorization: Bearer YOUR_TOKEN
|
||
```
|
||
|
||
---
|
||
|
||
## 👥 成员管理
|
||
|
||
### 1. 邀请成员
|
||
|
||
```http
|
||
POST /api/v1/workspaces/{workspace_id}/members/invite
|
||
Authorization: Bearer YOUR_TOKEN
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"email": "member@example.com",
|
||
"role": "member"
|
||
}
|
||
```
|
||
|
||
**角色类型:**
|
||
- `owner` - 所有者（自动分配，不可邀请）
|
||
- `admin` - 管理员
|
||
- `member` - 成员
|
||
- `viewer` - 查看者
|
||
|
||
### 2. 获取成员列表
|
||
|
||
```http
|
||
GET /api/v1/workspaces/{workspace_id}/members
|
||
Authorization: Bearer YOUR_TOKEN
|
||
```
|
||
|
||
### 3. 修改成员角色
|
||
|
||
```http
|
||
PATCH /api/v1/workspaces/{workspace_id}/members/{user_id}/role
|
||
Authorization: Bearer YOUR_TOKEN
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"role": "admin"
|
||
}
|
||
```
|
||
|
||
### 4. 移除成员
|
||
|
||
```http
|
||
DELETE /api/v1/workspaces/{workspace_id}/members/{user_id}
|
||
Authorization: Bearer YOUR_TOKEN
|
||
```
|
||
|
||
### 5. 离开工作空间
|
||
|
||
```http
|
||
POST /api/v1/workspaces/{workspace_id}/leave
|
||
Authorization: Bearer YOUR_TOKEN
|
||
```
|
||
|
||
---
|
||
|
||
## 🎟️ 邀请管理
|
||
|
||
### 1. 接受邀请
|
||
|
||
```http
|
||
POST /api/v1/workspaces/invitations/{token}/accept
|
||
Authorization: Bearer YOUR_TOKEN
|
||
```
|
||
|
||
### 2. 拒绝邀请
|
||
|
||
```http
|
||
POST /api/v1/workspaces/invitations/{token}/decline
|
||
```
|
||
|
||
---
|
||
|
||
## 💳 订阅管理
|
||
|
||
### 1. 升级订阅
|
||
|
||
```http
|
||
POST /api/v1/workspaces/{workspace_id}/subscription/upgrade
|
||
Authorization: Bearer YOUR_TOKEN
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"new_plan": "pro"
|
||
}
|
||
```
|
||
|
||
**订阅计划:**
|
||
- `free` - 免费版（3 projects, 10GB）
|
||
- `pro` - 专业版（无限 projects, 100GB）
|
||
- `enterprise` - 企业版（无限 projects, 1TB）
|
||
|
||
### 2. 取消订阅
|
||
|
||
```http
|
||
POST /api/v1/workspaces/{workspace_id}/subscription/cancel
|
||
Authorization: Bearer YOUR_TOKEN
|
||
```
|
||
|
||
### 3. 查看配额状态
|
||
|
||
```http
|
||
GET /api/v1/workspaces/{workspace_id}/quota
|
||
Authorization: Bearer YOUR_TOKEN
|
||
```
|
||
|
||
**响应:**
|
||
```json
|
||
{
|
||
"workspace_id": "ws123...",
|
||
"subscription_plan": "free",
|
||
"projects": {
|
||
"used": 2,
|
||
"limit": 3,
|
||
"unlimited": false,
|
||
"usage_percent": 66.67
|
||
},
|
||
"storage": {
|
||
"used_gb": 5.5,
|
||
"limit_gb": 10,
|
||
"remaining_gb": 4.5,
|
||
"usage_percent": 55.0
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔑 密码管理
|
||
|
||
### 1. 忘记密码
|
||
|
||
```http
|
||
POST /api/v1/auth/password/forgot
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"email": "user@example.com"
|
||
}
|
||
```
|
||
|
||
### 2. 重置密码
|
||
|
||
```http
|
||
POST /api/v1/auth/password/reset
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"token": "RESET_TOKEN_FROM_EMAIL",
|
||
"new_password": "NewSecurePass123"
|
||
}
|
||
```
|
||
|
||
### 3. 登出
|
||
|
||
```http
|
||
POST /api/v1/auth/logout
|
||
Authorization: Bearer YOUR_TOKEN
|
||
```
|
||
|
||
**登出所有设备:**
|
||
```http
|
||
POST /api/v1/auth/logout?logout_all_devices=true
|
||
Authorization: Bearer YOUR_TOKEN
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 错误处理
|
||
|
||
所有错误响应遵循统一格式：
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "ERROR_CODE",
|
||
"message": "Human readable error message",
|
||
"details": [] // 可选，仅在验证错误时出现
|
||
}
|
||
}
|
||
```
|
||
|
||
**常见错误码:**
|
||
- `AUTH_ERROR` - 认证失败
|
||
- `PERMISSION_DENIED` - 权限不足
|
||
- `NOT_FOUND` - 资源不存在
|
||
- `VALIDATION_ERROR` - 请求验证失败
|
||
- `RATE_LIMIT_EXCEEDED` - 请求过于频繁
|
||
- `INTERNAL_ERROR` - 服务器内部错误
|
||
|
||
**HTTP 状态码:**
|
||
- `200` - 成功
|
||
- `201` - 创建成功
|
||
- `204` - 成功（无内容）
|
||
- `400` - 请求错误
|
||
- `401` - 未认证
|
||
- `403` - 权限不足
|
||
- `404` - 资源不存在
|
||
- `422` - 验证失败
|
||
- `429` - 请求过于频繁
|
||
- `500` - 服务器错误
|
||
|
||
---
|
||
|
||
## 🚀 最佳实践
|
||
|
||
### 1. Token 管理
|
||
|
||
- Access Token 有效期 30 分钟
|
||
- Refresh Token 有效期 30 天
|
||
- Token 过期时自动使用 Refresh Token 获取新的 Access Token
|
||
- 在登出时清除本地存储的 Token
|
||
|
||
### 2. 错误处理
|
||
|
||
```javascript
|
||
try {
|
||
const response = await fetch('/api/v1/workspaces', {
|
||
headers: {
|
||
'Authorization': `Bearer ${accessToken}`,
|
||
'Content-Type': 'application/json'
|
||
}
|
||
});
|
||
|
||
if (!response.ok) {
|
||
const error = await response.json();
|
||
console.error(`Error: ${error.error.code} - ${error.error.message}`);
|
||
}
|
||
|
||
const data = await response.json();
|
||
return data;
|
||
} catch (error) {
|
||
console.error('Network error:', error);
|
||
}
|
||
```
|
||
|
||
### 3. 分页
|
||
|
||
目前 API 不支持分页，返回所有结果。后续版本将添加分页支持。
|
||
|
||
### 4. 速率限制
|
||
|
||
- 默认限制：100 请求/分钟（每个 IP）
|
||
- 超出限制返回 429 错误
|
||
- 响应头包含：
|
||
- `X-RateLimit-Limit` - 限制数量
|
||
- `X-RateLimit-Remaining` - 剩余请求数
|
||
|
||
---
|
||
|
||
## 🧪 测试环境
|
||
|
||
**测试账号:**
|
||
```
|
||
Email: demo@example.com
|
||
Password: Demo123456
|
||
```
|
||
|
||
**测试工作空间:**
|
||
```
|
||
Workspace ID: ws-demo-001
|
||
Name: Demo Workspace
|
||
```
|
||
|
||
---
|
||
|
||
## 📞 技术支持
|
||
|
||
- **文档:** http://localhost:8000/docs
|
||
- **问题反馈:** GitHub Issues
|
||
- **邮箱:** support@xiaoxia-saas.com
|
||
|
||
---
|
||
|
||
**最后更新:** 2026-06-17
|