# 微博扫码登录功能说明

## 功能概述

实现了基于微博网页版扫码登录接口的账号添加功能，无需注册微博开放平台应用，直接使用微博官方的扫码登录 API。

## 实现原理

通过逆向微博网页版（weibo.com）的扫码登录流程，调用微博的内部 API：

1. **生成二维码**：调用 `https://login.sina.com.cn/sso/qrcode/image` 获取二维码图片
2. **轮询状态**：调用 `https://login.sina.com.cn/sso/qrcode/check` 检查扫码状态
3. **获取 Cookie**：扫码成功后通过跳转 URL 获取登录 Cookie
4. **获取用户信息**：使用 Cookie 调用微博 API 获取用户 UID 和昵称
5. **自动添加账号**：将获取的信息自动添加到系统

## 使用流程

### 用户操作

1. 登录系统后，进入"添加账号"页面
2. 切换到"扫码添加"标签页
3. 点击"生成二维码"按钮
4. 使用手机微博 APP 扫描二维码
5. 在手机上点击"确认登录"
6. 等待页面自动完成账号添加
7. 自动跳转到 Dashboard

### 技术流程

```
用户点击生成二维码
    ↓
调用 /api/weibo/qrcode/generate
    ↓
请求微博 API 获取二维码
    ↓
显示二维码图片
    ↓
前端开始轮询 /api/weibo/qrcode/check/<qrid>
    ↓
后端轮询微博 API 检查状态
    ↓
状态变化：waiting → scanned → success
    ↓
获取跳转 URL 和 Cookie
    ↓
调用微博 API 获取用户信息
    ↓
前端调用 /api/weibo/qrcode/add-account
    ↓
添加账号到系统
    ↓
跳转到 Dashboard
```

## API 接口

### 1. 生成二维码

```
POST /api/weibo/qrcode/generate
```

返回：
```json
{
  "success": true,
  "qrid": "qr_id_string",
  "qr_image": "data:image/png;base64,...",
  "expires_in": 180
}
```

### 2. 检查扫码状态

```
GET /api/weibo/qrcode/check/<qrid>
```

返回：
```json
{
  "status": "waiting|scanned|success|expired|cancelled|error",
  "weibo_uid": "123456789",  // 仅在 success 时返回
  "screen_name": "用户昵称"   // 仅在 success 时返回
}
```

状态说明：
- `waiting`: 等待扫码
- `scanned`: 已扫码，等待确认
- `success`: 确认成功
- `expired`: 二维码过期
- `cancelled`: 取消登录
- `error`: 发生错误

### 3. 添加账号

```
POST /api/weibo/qrcode/add-account
Content-Type: application/json

{
  "qrid": "qr_id_string",
  "remark": "备注（可选）"
}
```

返回：
```json
{
  "success": true,
  "message": "Account added successfully",
  "account": {...}
}
```

## 微博 API 说明

### 生成二维码接口

```
GET https://login.sina.com.cn/sso/qrcode/image?entry=weibo&size=180&callback=STK_xxx
```

返回 JSONP 格式：
```javascript
STK_xxx({
  "retcode": 20000000,
  "qrid": "xxx",
  "image": "data:image/png;base64,..."
})
```

### 检查扫码状态接口

```
GET https://login.sina.com.cn/sso/qrcode/check?entry=weibo&qrid=xxx&callback=STK_xxx
```

返回 JSONP 格式：
```javascript
STK_xxx({
  "retcode": 20000000,  // 或其他状态码
  "alt": "跳转URL"       // 仅在登录成功时返回
})
```

状态码说明：
- `20000000`: 等待扫码
- `50050001`: 已扫码，等待确认
- `20000001`: 确认成功
- `50050002`: 二维码过期
- `50050004`: 取消授权

### 获取用户信息接口

```
GET https://weibo.com/ajax/profile/info
Cookie: xxx
```

返回：
```json
{
  "ok": 1,
  "data": {
    "user": {
      "idstr": "123456789",
      "screen_name": "用户昵称",
      ...
    }
  }
}
```

## 优势

1. **无需注册应用**：不需要在微博开放平台注册应用
2. **无需配置**：不需要配置 APP_KEY 和 APP_SECRET
3. **真实 Cookie**：获取的是真实的登录 Cookie，可用于签到
4. **用户体验好**：扫码即可完成，无需手动复制 Cookie

## 注意事项

1. **接口稳定性**：使用的是微博内部 API，可能会变化
2. **Cookie 有效期**：获取的 Cookie 有效期通常较长，但仍可能过期
3. **安全性**：Cookie 会被加密存储在数据库中
4. **二维码有效期**：默认 3 分钟，过期后需重新生成
5. **轮询频率**：前端每 2 秒轮询一次状态

## 故障排查

### 问题1：生成二维码失败

- 检查网络连接
- 检查微博 API 是否可访问
- 查看后端日志

### 问题2：扫码后长时间无响应

- 检查轮询是否正常
- 查看浏览器控制台是否有错误
- 刷新页面重试

### 问题3：添加账号失败

- 检查后端 API 服务是否正常
- 查看后端日志排查错误
- 确认 Cookie 是否有效

### 问题4：二维码过期

- 默认有效期 3 分钟
- 重新生成二维码即可

## 与 OAuth2 方案对比

| 特性 | 扫码登录（当前方案） | OAuth2 授权 |
|------|---------------------|-------------|
| 需要注册应用 | ❌ 不需要 | ✅ 需要 |
| 配置复杂度 | 低 | 高 |
| 获取的凭证 | 真实 Cookie | Access Token |
| 接口稳定性 | 中（内部 API） | 高（官方 API） |
| 用户体验 | 好 | 好 |
| 适用场景 | 个人项目 | 商业项目 |

## 未来改进

1. 添加错误重试机制
2. 优化轮询策略（WebSocket）
3. 添加二维码刷新功能
4. 支持多账号批量添加
5. 添加扫码记录和统计

## 参考资料

- 微博网页版：https://weibo.com
- 微博登录页面：https://login.sina.com.cn