# 认证模块

> 模块标识：auth  |  接口数量：4

## 1. 用户注册
**方法**：	POST

**路径**：				/auth/register

**功能说明**：
系统用户注册接口。如果 individualism=true，会为用户创建独立站点和独立数据库，并自动创建超级管理员角色。

### 请求参数
```json
{
  "body": {
    "name": "string｜必填，用户名",
    "phone": "string｜必填，手机号",
    "password": "string｜必填，登录密码",
    "roles": "array｜可选，角色ID数组"
  }
}
```

### 响应示例
```json
{
  "success": {
    "code": "0000",
    "message": "注册成功",
    "data": {
      "userId": "USER0001",
      "token": "jwt-token",
      "scopeKeys": [
        {
          "key": "uuid-personal",
          "type": "personal",
          "label": "个人"
        },
        {
          "key": "uuid-org",
          "type": "organization",
          "organizationId": 1,
          "label": "示例公司"
        }
      ],
      "defaultScopeKey": "uuid-org"
    }
  },
  "failure": {
    "code": "4000",
    "message": "注册失败",
    "data": null
  }
}
```

### 注意事项
- 如果 individualism=true，系统会：1. 创建独立数据库 2. 在独立数据库中创建用户副本 3. 创建超级管理员角色并绑定用户
- 注册成功后，用户记录在所属站点数据库创建，同时在独立数据库中创建副本用于角色绑定
- 响应 data 包含 scopeKeys（可用 scope 列表）与 defaultScopeKey（默认 scope，有组织时为组织 key）


## 2. 用户登录
**方法**：	POST

**路径**：				/auth/login

**功能说明**：
系统用户登录接口。如果用户有多个可用站点，会返回站点列表供前端选择。

### 请求参数
```json
{
  "body": {
    "phone": "string｜必填，手机号",
    "password": "string｜必填，登录密码"
  }
}
```

### 响应示例
```json
{
  "success": {
    "code": "0000",
    "message": "登录成功",
    "data": {
      "token": "jwt-token",
      "user": {
        "id": "USER0001",
        "name": "系统管理员"
      },
      "scopeKeys": [
        {
          "key": "uuid-personal",
          "type": "personal",
          "label": "个人"
        },
        {
          "key": "uuid-org",
          "type": "organization",
          "organizationId": 1,
          "label": "示例公司"
        }
      ],
      "defaultScopeKey": "uuid-org"
    }
  },
  "failure": {
    "code": "4000",
    "message": "登录失败",
    "data": null
  }
}
```

### 注意事项
- 如果用户有独立站点，availableSites 会包含两个站点：所属站点（type: owner）和个人站点（type: personal）
- 前端可以通过 X-Site header 切换站点，切换后所有 API 请求将使用对应站点的数据库
- 默认使用所属站点（isDefault: true），如需切换到个人站点，在后续请求中传递个人站点的 siteKey
- 响应 data 包含 scopeKeys（可用 scope 列表）与 defaultScopeKey（默认 scope，有组织时为组织 key）


## 3. 客户端用户注册
**方法**：	POST

**路径**：				/auth/client/register

**功能说明**：
客户端用户注册接口。如果 individualism=true，会为用户创建独立站点和独立数据库，并自动创建超级管理员角色。

### 请求参数
```json
{
  "body": {
    "name": "string｜必填，客户端用户姓名",
    "phone": "string｜必填，手机号",
    "password": "string｜必填，登录密码"
  }
}
```

### 响应示例
```json
{
  "success": {
    "code": "0000",
    "message": "注册成功",
    "data": {
      "clientUserId": "CU0001",
      "token": "jwt-token",
      "scopeKeys": [
        {
          "key": "uuid-personal",
          "type": "personal",
          "label": "个人"
        },
        {
          "key": "uuid-org",
          "type": "organization",
          "organizationId": 1,
          "label": "示例公司"
        }
      ],
      "defaultScopeKey": "uuid-org"
    }
  },
  "failure": {
    "code": "4000",
    "message": "注册失败",
    "data": null
  }
}
```

### 注意事项
- 如果 individualism=true，系统会：1. 创建独立数据库 2. 在独立数据库中创建用户副本 3. 创建超级管理员角色并绑定用户
- 注册成功后，用户记录在所属站点数据库创建，同时在独立数据库中创建副本用于角色绑定
- 响应 data 包含 scopeKeys（可用 scope 列表）与 defaultScopeKey（默认 scope，有组织时为组织 key）


## 4. 客户端用户登录
**方法**：	POST

**路径**：				/auth/client/login

**功能说明**：
客户端用户登录接口。如果用户有多个可用站点，会返回站点列表供前端选择。

### 请求参数
```json
{
  "body": {
    "phone": "string｜必填，手机号",
    "password": "string｜必填，登录密码"
  }
}
```

### 响应示例
```json
{
  "success": {
    "code": "0000",
    "message": "登录成功",
    "data": {
      "token": "jwt-token",
      "user": {
        "id": "CU0001",
        "name": "客户端管理员"
      },
      "scopeKeys": [
        {
          "key": "uuid-personal",
          "type": "personal",
          "label": "个人"
        },
        {
          "key": "uuid-org",
          "type": "organization",
          "organizationId": 1,
          "label": "示例公司"
        }
      ],
      "defaultScopeKey": "uuid-org"
    }
  },
  "failure": {
    "code": "4000",
    "message": "登录失败",
    "data": null
  }
}
```

### 注意事项
- 如果用户有独立站点，availableSites 会包含两个站点：所属站点（type: owner）和个人站点（type: personal）
- 前端可以通过 X-Site header 切换站点，切换后所有 API 请求将使用对应站点的数据库
- 默认使用所属站点（isDefault: true），如需切换到个人站点，在后续请求中传递个人站点的 siteKey
- 响应 data 包含 scopeKeys（可用 scope 列表）与 defaultScopeKey（默认 scope，有组织时为组织 key）