OneAuth/doc/api.md

# VBase API 文档

## 概述

VBase 是一个多租户身份认证与访问管理(IAM)系统，支持用户管理、组织管理、RBAC权限控制和OAuth2.0服务。

**基础信息**
- 基础URL: `https://api.example.com`
- 请求格式: `application/json`
- 响应格式: `application/json`
- 认证方式: Bearer Token (JWT)

**通用响应格式**
```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

**错误响应**
```json
{
  "code": 400,
  "message": "error message",
  "data": null
}
```

---

## 认证相关

### 用户登录

**POST** `/auth/login`

用户登录获取访问令牌。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | 用户名/邮箱/手机号 |
| password | string | 是 | 密码 |
| remember | bool | 否 | 记住登录 |

**响应示例**
```json
{
  "code": 200,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user": {
      "id": "user-id",
      "username": "admin",
      "nickname": "管理员",
      "email": "admin@example.com",
      "avatar": "https://..."
    }
  }
}
```

---

### 用户注册

**POST** `/auth/register`

注册新用户。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | 用户名(2-50字符) |
| password | string | 是 | 密码(至少8位) |
| email | string | 否 | 邮箱 |
| phone | string | 否 | 手机号 |
| nickname | string | 否 | 昵称 |

---

### 刷新Token

**POST** `/auth/refresh`

使用刷新令牌获取新的访问令牌。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| refresh_token | string | 是 | 刷新令牌 |

---

### 用户登出

**POST** `/auth/logout`

用户登出，使当前Token失效。

**请求头**
- Authorization: Bearer {access_token}

---

### 支持的第三方登录提供商

**GET** `/auth/providers`

获取系统支持的第三方登录提供商列表。

**响应示例**
```json
{
  "code": 200,
  "data": [
    {
      "name": "google",
      "display_name": "Google",
      "icon": "google",
      "enabled": true
    },
    {
      "name": "github",
      "display_name": "GitHub",
      "icon": "github",
      "enabled": true
    }
  ]
}
```

---

### 第三方登录授权

**GET** `/auth/authorize/thirdparty`

获取第三方登录授权URL。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| provider | string | 是 | 提供商: google/github/wechat |
| redirect | string | 否 | 登录成功后重定向地址 |
| bind_mode | bool | 否 | 是否为绑定模式 |

**响应示例**
```json
{
  "code": 200,
  "data": {
    "auth_url": "https://github.com/login/oauth/authorize?...",
    "state": "random-state-string"
  }
}
```

---

### 第三方登录回调

**GET** `/auth/callback/{provider}`

处理第三方登录回调。

**路径参数**
- provider: 提供商名称

**查询参数**
- code: 授权码
- state: 状态值

**响应示例（已绑定）**
```json
{
  "code": 200,
  "data": {
    "need_bind": false,
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user": {...}
  }
}
```

**响应示例（未绑定）**
```json
{
  "code": 200,
  "data": {
    "need_bind": true,
    "provider": "github",
    "provider_id": "12345",
    "auth_url": "/auth/bind?token=xxx"
  }
}
```

---

### 绑定第三方账号

**POST** `/auth/bind`

将第三方账号绑定到已有账号。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| temp_token | string | 是 | 临时绑定令牌 |
| username | string | 是 | 用户名/邮箱/手机号 |
| password | string | 是 | 密码 |

---

## 当前用户

### 获取当前用户信息

**GET** `/me`

获取当前登录用户的信息。

**请求头**
- Authorization: Bearer {access_token}

**响应示例**
```json
{
  "code": 200,
  "data": {
    "id": "user-id",
    "username": "admin",
    "nickname": "管理员",
    "email": "admin@example.com",
    "avatar": "https://...",
    "status": 1,
    "email_verified": true
  }
}
```

---

### 更新当前用户信息

**PATCH** `/me`

更新当前用户的基本信息。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| nickname | string | 否 | 昵称 |
| avatar | string | 否 | 头像URL |
| email | string | 否 | 邮箱 |

---

### 修改密码

**POST** `/me/change-password`

修改当前用户密码。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| old_password | string | 是 | 旧密码 |
| new_password | string | 是 | 新密码(至少8位) |

---

### 获取第三方绑定列表

**GET** `/me/bindings`

获取当前用户绑定的第三方账号列表。

**响应示例**
```json
{
  "code": 200,
  "data": [
    {
      "provider": "github",
      "provider_name": "GitHub User",
      "avatar": "https://...",
      "email": "user@example.com",
      "created_at": "2024-01-01 10:00:00"
    }
  ]
}
```

---

### 解绑第三方账号

**DELETE** `/me/bindings/{provider}`

解除指定提供商的账号绑定。

**路径参数**
- provider: 提供商名称 (google/github/wechat)

---

## 用户管理

### 用户列表

**GET** `/users`

获取用户列表（需要权限）。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认10 |
| keyword | string | 否 | 搜索关键词 |
| status | int | 否 | 状态筛选 |

**响应示例**
```json
{
  "code": 200,
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "page_size": 10,
    "total_pages": 10
  }
}
```

---

### 创建用户

**POST** `/users`

创建新用户（需要权限）。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
| nickname | string | 否 | 昵称 |
| email | string | 否 | 邮箱 |
| phone | string | 否 | 手机号 |
| status | int | 否 | 状态 |

---

### 获取用户详情

**GET** `/users/{user_id}`

获取指定用户的详细信息。

**路径参数**
- user_id: 用户ID

---

### 更新用户

**PATCH** `/users/{user_id}`

更新指定用户的信息。

**路径参数**
- user_id: 用户ID

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| nickname | string | 否 | 昵称 |
| avatar | string | 否 | 头像 |
| email | string | 否 | 邮箱 |
| phone | string | 否 | 手机号 |
| status | int | 否 | 状态 |

---

### 删除用户

**DELETE** `/users/{user_id}`

删除指定用户（软删除）。

---

### 更新用户状态

**PATCH** `/users/{user_id}/status`

更新用户状态。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | int | 是 | 0:禁用 1:正常 2:未激活 |

---

## 组织管理

### 组织列表

**GET** `/orgs`

获取当前用户的组织列表。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| page_size | int | 否 | 每页数量 |
| keyword | string | 否 | 搜索关键词 |

**响应示例**
```json
{
  "code": 200,
  "data": {
    "items": [
      {
        "id": "org-id",
        "name": "技术部",
        "code": "tech",
        "owner_id": "user-id",
        "path": "/tech",
        "level": 0,
        "status": 1,
        "my_roles": ["admin"],
        "my_status": 1
      }
    ],
    "total": 10
  }
}
```

---

### 创建组织

**POST** `/orgs`

创建新组织。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 组织名称 |
| code | string | 是 | 组织编码(唯一) |
| parent_id | string | 否 | 父组织ID |
| description | string | 否 | 描述 |
| max_members | int | 否 | 最大成员数 |

---

### 获取组织详情

**GET** `/orgs/{org_id}`

获取组织详细信息。

---

### 更新组织

**PATCH** `/orgs/{org_id}`

更新组织信息（仅所有者）。

---

### 删除组织

**DELETE** `/orgs/{org_id}`

删除组织（仅所有者，需无子组织）。

---

### 组织树

**GET** `/orgs/tree`

获取当前用户的组织树结构。

**响应示例**
```json
{
  "code": 200,
  "data": [
    {
      "id": "org-id",
      "name": "总公司",
      "children": [
        {
          "id": "sub-org-id",
          "name": "技术部"
        }
      ]
    }
  ]
}
```

---

### 组织成员列表

**GET** `/orgs/{org_id}/members`

获取组织成员列表。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| page_size | int | 否 | 每页数量 |
| status | int | 否 | 状态筛选 |

---

## OAuth2.0 服务端

### 授权端点

**GET** `/oauth/authorize`

OAuth2.0 授权端点，获取授权码。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| response_type | string | 是 | code/token |
| client_id | string | 是 | 客户端ID |
| redirect_uri | string | 是 | 回调地址 |
| scope | string | 否 | 权限范围 |
| state | string | 是 | CSRF防护 |
| code_challenge | string | 否 | PKCE挑战码 |
| code_challenge_method | string | 否 | S256/plain |

---

### 令牌端点

**POST** `/oauth/token`

OAuth2.0 令牌端点，交换授权码获取访问令牌。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| grant_type | string | 是 | authorization_code/refresh_token/client_credentials |
| code | string | 条件 | 授权码 |
| redirect_uri | string | 条件 | 回调地址 |
| client_id | string | 是 | 客户端ID |
| client_secret | string | 是 | 客户端密钥 |
| refresh_token | string | 条件 | 刷新令牌 |
| code_verifier | string | 条件 | PKCE验证器 |

---

### 撤销令牌

**POST** `/oauth/revoke`

撤销访问令牌或刷新令牌。

---

### 令牌内省

**POST** `/oauth/introspect`

查询令牌信息（RFC 7662）。

---

### 用户信息

**GET** `/oauth/userinfo`

OIDC 用户信息端点。

---

### OIDC 发现文档

**GET** `/.well-known/openid-configuration`

获取 OIDC 配置信息。

---

### JWKS

**GET** `/oauth/jwks`

获取 JWT 签名公钥。

---

## OAuth 客户端管理

### 客户端列表

**GET** `/oauth/clients`

获取 OAuth 客户端列表。

---

### 创建客户端

**POST** `/oauth/clients`

创建新的 OAuth 客户端。

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 应用名称 |
| description | string | 否 | 描述 |
| redirect_uris | []string | 是 | 回调地址列表 |
| grant_types | []string | 否 | 授权类型 |
| allowed_scopes | []string | 否 | 允许的范围 |

**响应示例**
```json
{
  "code": 200,
  "data": {
    "id": "client-id",
    "name": "My App",
    "client_id": "abc123...",
    "client_secret": "secret...",
    "redirect_uris": ["https://app.com/callback"],
    "grant_types": ["authorization_code", "refresh_token"]
  }
}
```

---

### 获取客户端详情

**GET** `/oauth/clients/{client_id}`

获取 OAuth 客户端详情。

---

### 更新客户端

**PATCH** `/oauth/clients/{client_id}`

更新 OAuth 客户端信息。

---

### 删除客户端

**DELETE** `/oauth/clients/{client_id}`

删除 OAuth 客户端。

---

### 重新生成密钥

**POST** `/oauth/clients/{client_id}/regenerate-secret`

重新生成客户端密钥。

---

## 请求头说明

### 认证头

```
Authorization: Bearer {access_token}
```

### 组织上下文

```
X-Org-ID: {organization_id}
```

用于指定当前操作的组织上下文。

---

## 状态码说明

| 状态码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未认证 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |