mp-java/docs/WECHAT_MINIPROGRAM_QR_LOGIN_GUIDE.md

微信小程序扫码登录使用指南

概述

扫码登录接口现已全面支持微信小程序端，用户可以通过微信小程序扫码快速登录网页端或其他平台。

支持的平台

• ✅ 网页端 - 传统的网页扫码登录
• ✅ 移动APP - 原生移动应用扫码登录
• ✅ 微信小程序 - 微信小程序扫码登录（新增）

接口说明

1. 生成扫码登录token

POST /api/qr-login/generate

响应示例：

{
  "code": 0,
  "message": "生成成功",
  "data": {
    "token": "abc123def456",
    "qrCode": "qr-login:abc123def456",
    "expiresIn": 300
  }
}

2. 检查扫码登录状态

GET /api/qr-login/status/{token}

响应示例：

{
  "code": 0,
  "message": "查询成功",
  "data": {
    "status": "confirmed",
    "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
    "userInfo": {
      "userId": 123,
      "username": "user123",
      "nickname": "张三"
    },
    "expiresIn": 60
  }
}

3. 微信小程序确认登录（专用接口）

POST /api/qr-login/wechat-confirm

请求示例：

{
  "token": "abc123def456",
  "userId": 123,
  "platform": "miniprogram",
  "wechatInfo": {
    "openid": "oABC123DEF456",
    "unionid": "uXYZ789ABC123",
    "nickname": "张三",
    "avatar": "https://wx.qlogo.cn/..."
  }
}

微信小程序端实现示例

1. 扫码功能

// 小程序扫码
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. 确认登录

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'
            });
          }
        }
      });
    }
  });
}

网页端轮询状态示例

// 网页端轮询检查登录状态
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无效
• 用户已被冻结 - 用户状态异常

建议在小程序端添加适当的错误提示和重试机制。