feat(auth): 添加微信小程序扫码登录功能

- 新增扫码登录接口和相关服务 - 实现微信小程序端扫码登录逻辑 - 更新文档，添加微信小程序扫码登录指南 - 调整微信登录相关接口，使用 release 版本 - 新增 JWT 配置项
2025-09-01 14:39:16 +08:00
parent fabccddab2
commit 9280f6284b
12 changed files with 784 additions and 2 deletions
--- a/docs/WECHAT_MINIPROGRAM_QR_LOGIN_GUIDE.md
+++ b/docs/WECHAT_MINIPROGRAM_QR_LOGIN_GUIDE.md
@@ -0,0 +1,213 @@
+# 微信小程序扫码登录使用指南
+
+## 概述
+
+扫码登录接口现已全面支持微信小程序端，用户可以通过微信小程序扫码快速登录网页端或其他平台。
+
+## 支持的平台
+
+- ✅ **网页端** - 传统的网页扫码登录
+- ✅ **移动APP** - 原生移动应用扫码登录  
+- ✅ **微信小程序** - 微信小程序扫码登录（新增）
+
+## 接口说明
+
+### 1. 生成扫码登录token
+```
+POST /api/qr-login/generate
+```
+
+**响应示例：**
+```json
+{
+  "code": 0,
+  "message": "生成成功",
+  "data": {
+    "token": "abc123def456",
+    "qrCode": "qr-login:abc123def456",
+    "expiresIn": 300
+  }
+}
+```
+
+### 2. 检查扫码登录状态
+```
+GET /api/qr-login/status/{token}
+```
+
+**响应示例：**
+```json
+{
+  "code": 0,
+  "message": "查询成功",
+  "data": {
+    "status": "confirmed",
+    "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
+    "userInfo": {
+      "userId": 123,
+      "username": "user123",
+      "nickname": "张三"
+    },
+    "expiresIn": 60
+  }
+}
+```
+
+### 3. 微信小程序确认登录（专用接口）
+```
+POST /api/qr-login/wechat-confirm
+```
+
+**请求示例：**
+```json
+{
+  "token": "abc123def456",
+  "userId": 123,
+  "platform": "miniprogram",
+  "wechatInfo": {
+    "openid": "oABC123DEF456",
+    "unionid": "uXYZ789ABC123",
+    "nickname": "张三",
+    "avatar": "https://wx.qlogo.cn/..."
+  }
+}
+```
+
+## 微信小程序端实现示例
+
+### 1. 扫码功能
+```javascript
+// 小程序扫码
+wx.scanCode({
+  success: (res) => {
+    const qrContent = res.result; // 例如: "qr-login:abc123def456"
+    if (qrContent.startsWith('qr-login:')) {
+      const token = qrContent.replace('qr-login:', '');
+      this.confirmLogin(token);
+    }
+  }
+});
+```
+
+### 2. 确认登录
+```javascript
+confirmLogin(token) {
+  // 获取用户信息
+  wx.getUserProfile({
+    desc: '用于扫码登录',
+    success: (userRes) => {
+      // 调用确认登录接口
+      wx.request({
+        url: 'https://your-api.com/api/qr-login/wechat-confirm',
+        method: 'POST',
+        data: {
+          token: token,
+          userId: this.data.currentUserId, // 当前登录用户ID
+          platform: 'miniprogram',
+          wechatInfo: {
+            openid: this.data.openid,
+            unionid: this.data.unionid,
+            nickname: userRes.userInfo.nickName,
+            avatar: userRes.userInfo.avatarUrl
+          }
+        },
+        success: (res) => {
+          if (res.data.code === 0) {
+            wx.showToast({
+              title: '登录确认成功',
+              icon: 'success'
+            });
+          }
+        }
+      });
+    }
+  });
+}
+```
+
+## 网页端轮询状态示例
+
+```javascript
+// 网页端轮询检查登录状态
+function checkLoginStatus(token) {
+  const interval = setInterval(() => {
+    fetch(`/api/qr-login/status/${token}`)
+      .then(res => res.json())
+      .then(data => {
+        if (data.code === 0) {
+          const status = data.data.status;
+          
+          switch(status) {
+            case 'pending':
+              console.log('等待扫码...');
+              break;
+            case 'scanned':
+              console.log('已扫码，等待确认...');
+              break;
+            case 'confirmed':
+              console.log('登录成功！');
+              localStorage.setItem('token', data.data.accessToken);
+              clearInterval(interval);
+              // 跳转到主页
+              window.location.href = '/dashboard';
+              break;
+            case 'expired':
+              console.log('二维码已过期');
+              clearInterval(interval);
+              // 重新生成二维码
+              generateNewQrCode();
+              break;
+          }
+        }
+      });
+  }, 2000); // 每2秒检查一次
+}
+```
+
+## 状态流转
+
+```
+pending (等待扫码)
+    ↓
+scanned (已扫码) 
+    ↓
+confirmed (已确认) → 返回JWT token
+    ↓
+expired (已过期)
+```
+
+## 特殊功能
+
+### 1. 微信信息自动更新
+当微信小程序用户确认登录时，系统会自动更新用户的微信相关信息：
+- openid
+- unionid  
+- 昵称（如果用户昵称为空）
+- 头像（如果用户头像为空）
+
+### 2. 平台识别
+系统会记录用户通过哪个平台进行的扫码登录，便于后续分析和统计。
+
+### 3. 安全特性
+- Token有效期5分钟
+- 确认后Token立即失效，防止重复使用
+- 支持过期自动清理
+- JWT token有效期24小时
+
+## 注意事项
+
+1. **微信小程序需要配置扫码权限**
+2. **确保用户已在小程序中登录**
+3. **处理用户拒绝授权的情况**
+4. **网页端需要定期轮询状态**
+5. **处理网络异常和超时情况**
+
+## 错误处理
+
+常见错误码：
+- `token不能为空` - 请求参数缺失
+- `扫码登录token不存在或已过期` - Token无效
+- `用户不存在` - 用户ID无效
+- `用户已被冻结` - 用户状态异常
+
+建议在小程序端添加适当的错误提示和重试机制。