weibo_signin/WEIBO_OAUTH_SETUP.md

# 微博 OAuth2 扫码授权配置指南

## 功能说明

实现了微博 OAuth2 扫码授权功能，用户可以通过手机微博 APP 扫码快速添加账号，无需手动复制 Cookie。

## 配置步骤

### 1. 注册微博开放平台应用

1. 访问 [微博开放平台](https://open.weibo.com/)
2. 登录你的微博账号
3. 进入"微连接" > "网站接入"
4. 创建新应用，填写应用信息：
   - 应用名称：Weibo-HotSign（或自定义）
   - 应用简介：微博自动签到系统
   - 应用类型：网站
   - 应用地址：http://localhost:5000（开发环境）

5. 提交审核（测试阶段可以使用未审核的应用）

### 2. 配置回调地址

在应用管理页面：
1. 进入"应用信息" > "高级信息"
2. 设置"授权回调页"为：`http://localhost:5000/auth/weibo/callback`
3. 保存设置

### 3. 获取 APP KEY 和 APP SECRET

在应用管理页面：
1. 进入"应用信息" > "基本信息"
2. 复制 `App Key` 和 `App Secret`

### 4. 配置环境变量

编辑 `backend/.env` 和 `frontend/.env` 文件：

```env
# 微博 OAuth2 配置
WEIBO_APP_KEY=你的_App_Key
WEIBO_APP_SECRET=你的_App_Secret
WEIBO_REDIRECT_URI=http://localhost:5000/auth/weibo/callback
```

### 5. 重启服务

```bash
# 停止所有服务
stop_all.bat

# 启动所有服务
start_all.bat
```

## 使用流程

### 用户端操作

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

### 技术流程

1. **生成授权 URL**
   - 前端调用 `/auth/weibo/authorize` 接口
   - 后端生成包含 `state` 参数的授权 URL
   - 前端使用 QRCode.js 生成二维码

2. **用户扫码授权**
   - 用户用手机微博扫码
   - 跳转到微博授权页面（移动端适配）
   - 用户点击"同意授权"

3. **微博回调**
   - 微博跳转到 `/auth/weibo/callback?code=xxx&state=xxx`
   - 后端用 `code` 换取 `access_token`
   - 调用微博 API 获取用户信息
   - 更新授权状态为成功

4. **前端轮询**
   - 前端每 2 秒轮询 `/auth/weibo/check/<state>`
   - 检测到授权成功后，调用 `/api/weibo/add-account`
   - 自动添加账号到系统

5. **完成添加**
   - 账号添加成功
   - 跳转到 Dashboard

## API 接口说明

### 1. 生成授权 URL

```
GET /auth/weibo/authorize
```

返回：
```json
{
  "auth_url": "https://api.weibo.com/oauth2/authorize?...",
  "state": "random_state_string",
  "expires_in": 180
}
```

### 2. 检查授权状态

```
GET /auth/weibo/check/<state>
```

返回：
```json
{
  "status": "pending|success|error|expired",
  "account_info": {...}  // 仅在 success 时返回
}
```

### 3. 微博回调

```
GET /auth/weibo/callback?code=xxx&state=xxx
```

返回 HTML 页面，显示授权结果

### 4. 添加账号

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

{
  "state": "state_string",
  "remark": "备注（可选）"
}
```

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

## 安全说明

1. **State 参数**：用于防止 CSRF 攻击，每次授权生成唯一的 state
2. **Session 存储**：授权状态临时存储在 session 中（生产环境建议使用 Redis）
3. **Token 加密**：access_token 会被加密存储在数据库中
4. **HTTPS**：生产环境必须使用 HTTPS

## 生产环境配置

### 1. 更新回调地址

```env
WEIBO_REDIRECT_URI=https://yourdomain.com/auth/weibo/callback
```

### 2. 在微博开放平台更新回调地址

进入应用管理 > 高级信息 > 授权回调页：
```
https://yourdomain.com/auth/weibo/callback
```

### 3. 使用 Redis 存储授权状态

修改 `frontend/app.py`，将 session 存储改为 Redis 存储。

## 故障排查

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

- 检查 `WEIBO_APP_KEY` 是否配置正确
- 检查网络连接

### 问题2：扫码后提示"回调地址不匹配"

- 检查 `WEIBO_REDIRECT_URI` 是否与微博开放平台配置一致
- 确保包含协议（http:// 或 https://）

### 问题3：授权成功但添加账号失败

- 检查后端 API 服务是否正常运行
- 查看后端日志排查错误

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

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

## 注意事项

1. 微博开放平台应用需要审核，测试阶段可以使用未审核的应用
2. 未审核的应用只能授权给应用创建者和测试账号
3. 建议使用小号或测试账号进行测试
4. access_token 有效期通常为 30 天，过期后需要重新授权
5. 生产环境必须使用 HTTPS

## 参考文档

- [微博 OAuth2 文档](https://open.weibo.com/wiki/Oauth2)
- [微博 API 文档](https://open.weibo.com/wiki/API)