扫一扫登录 - MOMpro平台文档

# 扫一扫登录

## 概述

扫一扫登录是一种通过扫描二维码进行登录的方式，用户通过扫描二维码，可以在不输入用户名和密码的情况下完成登录。
分为以下几个步骤：

1. PC端请求生成二维码
2. PC端轮询查询二维码状态
3. 移动端扫描二维码
4. 移动端确认登录
5. PC端接收登录确认

## PC端生成二维码

POST /orbit/security/qrCode/create

Authorization: No Authorization

### 参数

| Name   | Location | Type   | Required | Description |
| ------ | -------- | ------ | -------- | ----------- |
| width  | query    | int | yes      | 二维码宽度  |
| height | query    | int | yes      | 二维码高度  |

### 接口返回

```json
{
  "uuid": "3e176cef-5381-4b3a-93d7-8cab6884b40a",
  "expireAt": "1700000000",
  "type": "login",
  "loginAddress": "广东省",
  "loginIp": "113.65.69.221",
  "qrCode": "data:image/png;base64,XXXX"
}
```

返回base64格式的二维码png图片

二维码解析后的内容为json格式，包含二维码的uuid和过期时间以及type。

2024/3/16更新 ：新增loginIp以及loginAddress字段 用于判断登录环境

```json
{
  "uuid": "3e176cef-5381-4b3a-93d7-8cab6884b40a",
  "expireAt": "1700000000",
  "type": "login",
  "loginAddress": "广东省",
  "loginIp": "113.65.69.221"
}
```

名词解释：

- uuid: 该二维码的唯一标识
- expireAt: 二维码的过期时间
- type: 二维码类型，login表示登录二维码

## PC查询二维码状态

POST /orbit/security/qrCode/status

Authorization: No Authorization

### 请求参数

> 请求示例

```json
{
  "uuid": "3e176cef-5381-4b3a-93d7-8cab6884b40a"
}
```

| Name | Location | Type   | Required | Description |
| ---- | -------- | ------ | -------- | ----------- |
| uuid | body     | string | yes      | 二维码uuid  |

### 接口返回

| HTTP Status Code | Meaning                                              | Description | Data schema |
| ---------------- | ---------------------------------------------------- | ----------- | ----------- |
| 200              | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | 成功        | Inline      |

HTTP Status Code **200**

| Name             | Type    | Required | Restrictions | Title | description |
| ---------------- | ------- | -------- | ------------ | ----- | ----------- |
| » code          | integer | true     | none         |       | none        |
| » message       | string  | true     | none         |       | none        |
| » data          | null    | true     | none         |       | none        |
| » data.status   | string  | true     |              |       | 二维码状态  |
| » data.expireAt | string  | true     |              |       | 过期时间    |

> 返回体示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "status": "not_scan",
    "expireAt": "1700000000"
  }
}
```

> 确认登录后返回Token示例

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRfaWQiOm51bGwsImF1ZCI6WyJyZXMxIl0sInVzZXJfbmFtZSI6Im9yYml0Iiwic2NvcGUiOlsiYWxsIl0sImNsaWVudElwIjoiMTkyLjE2OC4xLjIzMyIsImV4cCI6MTcxMDQ5MDMzNiwiYXV0aG9yaXRpZXMiOlsiYWRtaW4iXSwianRpIjoiMTZlMDc4MGQtZjEzNy00NzYyLTkwZTctNWFjNWE2ZGVkNWNlIiwiY2xpZW50X2lkIjoiYzEifQ.y0KO4MugZ23DEzQKp51xRV-WaP0Jp4RLW_AVnafpeoc",
        "expireAt": "1708416795863",
        "status": "verified"
    }
}
```

2024/3/16更新：当二维码状态为已扫描时会带上扫描用户的用户名以及头像信息

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "userInfo": {
            "userAvatar": "/theme/upload/jj/2024/02/头像1.png",
            "userName": "管理员"
        },
        "expireAt": "1710559010696",
        "status": "scanned"
    }
}
```

二维码状态说明：
not_scan: 未扫描
scanned: 已扫描,未确认
expired: 已过期
verified: 已确认登录
cancel: 取消登录

必须要在expireAt时间之前扫描二维码或进行确认操作，否则二维码会过期，需要重新生成。

## App扫描二维码

POST /orbit/security/qrCode/scan

Authorization: Bearer {token}

> 返回示例

```json
{
  "uuid": "9d85f787-6eed-467f-950b-4f7271b0a556"
}
```

### 请求参数

| Name | Location | Type   | Required | Description |
| ---- | -------- | ------ | -------- | ----------- |
| body | body     | object | no       | none        |

### 接口返回

HTTP Status Code **200**

| Name       | Type    | Required | Restrictions | Title | description |
| ---------- | ------- | -------- | ------------ | ----- | ----------- |
| » code    | integer | true     | none         |       | none        |
| » message | string  | true     | none         |       | none        |
| » data    | string  | true     | none         |       | none        |

> 返回示例

```json
{
  "code": 200,
  "message": "success",
  "data": ""
}
```

## App确认登录

需要在扫描二维码后，移动端调用此接口确认登录，此接口会返回access_token和refresh_token，用于后续的请求。

POST /orbit/security/qrCode/confirm

Authorization: Bearer {token}

> 请求示例

```json
{
  "uuid": "ccbf4929-a002-4f46-9810-f346cff6c884"
}
```

### 请求参数

| Name | Location | Type   | Required | Description |
| ---- | -------- | ------ | -------- | ----------- |
| body | body     | object | no       | none        |

### 接口返回

> 返回示例

```json
{
    "code": 200,
    "message": "success",
    "data": ""
}
```

> 错误返回示例

````json
{
    "code": 1001,
    "message": "expired",
    "data": ""
}
````

## App取消登录

取消登录，取消登录后，二维码会失效。拒绝登录的情况下，需要调用此接口。

POST /orbit/security/qrCode/cancel

Authorization: Bearer {token}

> 请求示例

```json
{
  "uuid": "ccbf4929-a002-4f46-9810-f346cff6c884"
}
```

### 请求参数

| Name | Location | Type   | Required | Description |
| ---- | -------- | ------ | -------- | ----------- |
| body | body     | object | no       | none        |

### 接口返回

> 返回示例

```json
{
  "code": 200,
  "message": "success",
  "data": ""
}
```

> 错误返回示例

```json
{
    "code": 1001,
    "message": "expired",
    "data": ""
}
```