feat(auth): 添加二维码登录功能- 实现了二维码登录的前端组件和API接口

- 添加了二维码登录的后端逻辑和数据库设计 - 编写了详细的使用说明和接口文档 - 提供了演示页面和测试工具
2025-09-08 14:57:57 +08:00
parent 7b6fac7c41
commit a67162ee06
12 changed files with 2350 additions and 2 deletions
--- a/docs/qr-login-api.md
+++ b/docs/qr-login-api.md
@@ -0,0 +1,212 @@
+# 二维码登录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`: 服务器内部错误