mp-vue/docs/qr-login-api.md

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

概述

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

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

接口列表

1. 生成登录二维码

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

请求参数： 无

响应数据：

{
  "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（路径参数）

响应数据：

{
  "code": 0,
  "message": "查询成功",
  "data": {
    "status": "pending",
    "expiresIn": 280
  }
}

状态说明：

• pending: 等待扫码
• scanned: 已扫码，等待确认
• confirmed: 已确认登录
• expired: 已过期

登录成功时的响应：

{
  "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（路径参数）

响应数据：

{
  "code": 0,
  "message": "操作成功",
  "data": true
}

4. 确认登录

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

请求参数：

{
  "token": "abc123def456",
  "userId": 1,
  "platform": "web"
}

响应数据：

{
  "code": 0,
  "message": "确认成功",
  "data": {
    "status": "confirmed",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userInfo": {
      "userId": 1,
      "username": "admin",
      "nickname": "管理员"
    },
    "expiresIn": 60
  }
}

5. 微信小程序确认登录

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

请求参数：

{
  "token": "abc123def456",
  "userId": 1,
  "platform": "miniprogram",
  "wechatInfo": {
    "openid": "wx_openid_123",
    "unionid": "wx_unionid_456",
    "nickname": "微信用户",
    "avatar": "https://wx.qlogo.cn/..."
  }
}

响应数据：

{
  "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生成二维码的频率

数据库设计建议

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: 服务器内部错误