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

## 概述

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

## 支持的平台

- ✅ **网页端** - 传统的网页扫码登录
- ✅ **移动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无效
- `用户已被冻结` - 用户状态异常

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