# 二维码登录API接口文档（已适配后端）

## 概述

二维码登录功能允许用户通过手机APP或小程序扫描Web端生成的二维码来完成登录，提供更便捷和安全的登录体验。

**后端实现状态：** ✅ 已完成
**前端适配状态：** ✅ 已完成

## 接口列表

### 1. 生成登录二维码

**接口地址：** `POST /api/qr-login/generate`

**请求参数：** 无

**响应数据：**
```json
{
  "code": 0,
  "message": "生成成功",
  "data": {
    "token": "abc123def456",
    "qrCode": "qr-login:abc123def456",
    "expiresIn": 300
  }
}
```

**字段说明：**
- `token`: 二维码唯一标识token，用于后续状态查询
- `qrCode`: 二维码内容（后端生成的原始内容）
- `expiresIn`: 过期时间（秒），默认300秒（5分钟）

### 2. 检查二维码状态

**接口地址：** `GET /api/qr-login/status/{token}`

**请求参数：**
- `token`: 二维码token（路径参数）

**响应数据：**
```json
{
  "code": 0,
  "message": "查询成功",
  "data": {
    "status": "pending",
    "expiresIn": 280
  }
}
```

**状态说明：**
- `pending`: 等待扫码
- `scanned`: 已扫码，等待确认
- `confirmed`: 已确认登录
- `expired`: 已过期

**登录成功时的响应：**
```json
{
  "code": 0,
  "message": "登录成功",
  "data": {
    "status": "confirmed",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userInfo": {
      "userId": 1,
      "username": "admin",
      "nickname": "管理员",
      "avatar": "https://example.com/avatar.jpg"
    },
    "expiresIn": 60
  }
}
```

### 3. 扫码标记

**接口地址：** `POST /api/qr-login/scan/{token}`

**请求参数：**
- `token`: 二维码token（路径参数）

**响应数据：**
```json
{
  "code": 0,
  "message": "操作成功",
  "data": true
}
```

### 4. 确认登录

**接口地址：** `POST /api/qr-login/confirm`

**请求参数：**
```json
{
  "token": "abc123def456",
  "userId": 1,
  "platform": "web"
}
```

**响应数据：**
```json
{
  "code": 0,
  "message": "确认成功",
  "data": {
    "status": "confirmed",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userInfo": {
      "userId": 1,
      "username": "admin",
      "nickname": "管理员"
    },
    "expiresIn": 60
  }
}
```

### 5. 微信小程序确认登录

**接口地址：** `POST /api/qr-login/wechat-confirm`

**请求参数：**
```json
{
  "token": "abc123def456",
  "userId": 1,
  "platform": "miniprogram",
  "wechatInfo": {
    "openid": "wx_openid_123",
    "unionid": "wx_unionid_456",
    "nickname": "微信用户",
    "avatar": "https://wx.qlogo.cn/..."
  }
}
```

**响应数据：**
```json
{
  "code": 0,
  "message": "微信小程序登录确认成功",
  "data": {
    "status": "confirmed",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userInfo": {...},
    "expiresIn": 60
  }
}
```

## 实现流程

### Web端流程：
1. 用户点击扫码登录
2. 前端调用 `/qr-login/generate` 生成二维码
3. 显示二维码给用户
4. 前端轮询调用 `/qr-login/status` 检查状态
5. 当状态为 `confirmed` 时，获取token完成登录

### 移动端流程：
1. 用户扫描二维码，跳转到确认页面
2. 页面加载时调用 `/qr-login/scan` 标记已扫码
3. 用户点击确认后调用 `/qr-login/confirm` 确认登录
4. 或用户点击取消后调用 `/qr-login/cancel` 取消登录

## 安全考虑

1. **二维码有效期**：建议设置5分钟有效期，过期后需要重新生成
2. **一次性使用**：每个二维码只能使用一次，确认或取消后立即失效
3. **用户验证**：移动端需要验证用户的登录状态
4. **IP限制**：可以记录生成二维码的IP，限制异地登录
5. **频率限制**：限制同一IP生成二维码的频率

## 数据库设计建议

```sql
CREATE TABLE qr_login_records (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  qr_code_key VARCHAR(64) UNIQUE NOT NULL COMMENT '二维码唯一标识',
  status ENUM('waiting', 'scanned', 'confirmed', 'expired', 'cancelled') DEFAULT 'waiting' COMMENT '状态',
  user_id BIGINT NULL COMMENT '扫码用户ID',
  client_ip VARCHAR(45) COMMENT '客户端IP',
  user_agent TEXT COMMENT '用户代理',
  expire_time DATETIME NOT NULL COMMENT '过期时间',
  scan_time DATETIME NULL COMMENT '扫码时间',
  confirm_time DATETIME NULL COMMENT '确认时间',
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  INDEX idx_qr_code_key (qr_code_key),
  INDEX idx_status (status),
  INDEX idx_expire_time (expire_time)
);
```

## 错误码说明

- `0`: 成功
- `400`: 参数错误
- `401`: 未授权
- `404`: 二维码不存在
- `410`: 二维码已过期
- `429`: 请求过于频繁
- `500`: 服务器内部错误