xiaoxia-saas/docs/API-GUIDE.md

小虾 SaaS API 使用指南

📖 概述

小虾 SaaS 是一个完整的多租户 SaaS 平台，提供用户认证、工作空间管理、团队协作和订阅管理功能。

基础 URL: http://localhost:8000 (开发环境)

API 文档:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

🔐 认证流程

1. 注册用户

POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123",
  "username": "myusername",
  "display_name": "My Name"
}

响应:

{
  "user_id": "abc123...",
  "email": "user@example.com",
  "username": "myusername",
  "display_name": "My Name",
  "email_verification_sent": true
}

2. 验证邮箱

点击邮件中的链接，或访问：

GET /api/v1/auth/verify-email?token=VERIFICATION_TOKEN

3. 登录

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123"
}

响应:

{
  "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：

Authorization: Bearer YOUR_ACCESS_TOKEN

---

🏢 工作空间管理

1. 创建工作空间

POST /api/v1/workspaces
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "我的团队",
  "subscription_plan": "free"
}

响应:

{
  "workspace_id": "ws123...",
  "name": "我的团队",
  "subscription_plan": "free",
  "max_projects": 3,
  "max_storage_gb": 10
}

2. 获取工作空间列表

GET /api/v1/workspaces
Authorization: Bearer YOUR_TOKEN

响应:

{
  "workspaces": [
    {
      "workspace_id": "ws123...",
      "name": "我的团队",
      "subscription_plan": "free",
      "max_projects": 3,
      "max_storage_gb": 10,
      "member_count": 1,
      "user_role": "owner"
    }
  ]
}

3. 获取工作空间详情

GET /api/v1/workspaces/{workspace_id}
Authorization: Bearer YOUR_TOKEN

---

👥 成员管理

1. 邀请成员

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. 获取成员列表

GET /api/v1/workspaces/{workspace_id}/members
Authorization: Bearer YOUR_TOKEN

3. 修改成员角色

PATCH /api/v1/workspaces/{workspace_id}/members/{user_id}/role
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "role": "admin"
}

4. 移除成员

DELETE /api/v1/workspaces/{workspace_id}/members/{user_id}
Authorization: Bearer YOUR_TOKEN

5. 离开工作空间

POST /api/v1/workspaces/{workspace_id}/leave
Authorization: Bearer YOUR_TOKEN

---

🎟️ 邀请管理

1. 接受邀请

POST /api/v1/workspaces/invitations/{token}/accept
Authorization: Bearer YOUR_TOKEN

2. 拒绝邀请

POST /api/v1/workspaces/invitations/{token}/decline

---

💳 订阅管理

1. 升级订阅

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. 取消订阅

POST /api/v1/workspaces/{workspace_id}/subscription/cancel
Authorization: Bearer YOUR_TOKEN

3. 查看配额状态

GET /api/v1/workspaces/{workspace_id}/quota
Authorization: Bearer YOUR_TOKEN

响应:

{
  "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. 忘记密码

POST /api/v1/auth/password/forgot
Content-Type: application/json

{
  "email": "user@example.com"
}

2. 重置密码

POST /api/v1/auth/password/reset
Content-Type: application/json

{
  "token": "RESET_TOKEN_FROM_EMAIL",
  "new_password": "NewSecurePass123"
}

3. 登出

POST /api/v1/auth/logout
Authorization: Bearer YOUR_TOKEN

登出所有设备:

POST /api/v1/auth/logout?logout_all_devices=true
Authorization: Bearer YOUR_TOKEN

---

⚠️ 错误处理

所有错误响应遵循统一格式：

{
  "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. 错误处理

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