chaohua_coze/WEIBO_INTEGRATION_GUIDE.md

# 微博OAuth 2.0 接入指南

## 一、微博开放平台配置

### 1. 注册开发者账号

访问 [微博开放平台](https://open.weibo.com/)，注册并认证开发者账号。

### 2. 创建应用

1. 登录微博开放平台
2. 点击"创建应用"
3. 选择"网页应用"或"移动应用"
4. 填写应用信息：
   - 应用名称：你的小程序名称
   - 应用类型：选择合适类型
   - 应用描述：简要说明应用功能

### 3. 获取App Key和App Secret

创建应用后，在应用详情页可以看到：
- **App Key**：应用的唯一标识
- **App Secret**：应用的密钥（需保密）

### 4. 配置回调地址

在应用设置中，配置授权回调地址：
```
https://your-domain.com/api/weibo/callback
```

开发环境可配置为：
```
http://localhost:3000/api/weibo/callback
```

---

## 二、环境变量配置

编辑 `server/.env` 文件，填入真实的微博配置：

```bash
# 微博开放平台配置
WEIBO_APP_KEY=你的App_Key
WEIBO_APP_SECRET=你的App_Secret
WEIBO_REDIRECT_URI=http://localhost:3000/api/weibo/callback

# JWT配置
JWT_SECRET=你的JWT密钥（建议使用随机字符串）
```

**注意**：
- `WEIBO_REDIRECT_URI` 必须与微博开放平台配置的回调地址一致
- `JWT_SECRET` 建议使用强密码，用于签名JWT Token

---

## 三、OAuth 2.0授权流程

### 流程图

```
用户 → 点击"绑定微博" → 跳转微博授权页 → 用户授权 → 回调到你的应用 → 获取access_token → 保存绑定信息
```

### 详细步骤

#### 1. 获取授权URL

**请求**：
```
GET /api/weibo/bind-url
Authorization: Bearer {微信JWT Token}
```

**响应**：
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "bindUrl": "https://api.weibo.com/oauth2/authorize?client_id={app_key}&redirect_uri={redirect_uri}&response_type=code&state={state}",
    "devMode": false
  }
}
```

#### 2. 用户授权

前端跳转到 `bindUrl`，用户在微博页面登录并授权。

#### 3. 处理回调

用户授权后，微博会重定向到：
```
{redirect_uri}?code={授权码}&state={state}
```

后端自动处理回调，获取access_token并保存绑定信息。

#### 4. 检查绑定状态

**请求**：
```
GET /api/weibo/status
Authorization: Bearer {微信JWT Token}
```

**响应**：
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "bound": true,
    "weiboName": "微博昵称"
  }
}
```

---

## 四、开发模式 vs 生产模式

系统自动判断运行模式：

### 开发模式（未配置微博App Key）

**触发条件**：
- `WEIBO_APP_KEY` 为空或为 `your_weibo_app_key`

**行为**：
- 使用模拟数据
- 不需要真实的微博账号
- 适合开发和测试

### 生产模式（已配置真实App Key）

**触发条件**：
- `WEIBO_APP_KEY` 为真实的App Key

**行为**：
- 调用真实的微博API
- 需要用户真实授权
- 获取真实的微博用户信息

---

## 五、超话功能说明

### 重要警告

⚠️ **微博官方不提供超话API**，所有超话功能均基于移动端API逆向分析实现。

### 技术方案

#### 1. 获取超话列表

**接口**（非官方）：
```
GET https://m.weibo.cn/api/container/getIndex?containerid=100803
Headers: Cookie: SUB={access_token}
```

#### 2. 超话签到

**接口**（非官方）：
```
POST https://m.weibo.cn/ajax/statuses/checkin
Headers: Cookie: SUB={access_token}
Body: containerid=100808{超话ID}
```

### 风险提示

1. **接口不稳定**：微博可能随时更改接口
2. **账号风险**：频繁调用可能导致账号被限制
3. **法律风险**：使用非官方API可能违反微博服务条款

### 当前实现

系统目前使用**模拟数据**，真实实现需要：
1. 修改 `topic.service.ts` 中的 `mockWeiboSignin` 方法
2. 实现真实的API调用逻辑
3. 处理各种异常情况

---

## 六、测试流程

### 1. 测试开发模式

```bash
# 1. 确保.env中的微博配置为默认值
WEIBO_APP_KEY=your_weibo_app_key

# 2. 启动服务
cd /workspace/projects
coze dev

# 3. 测试登录
curl -X POST http://localhost:3000/api/auth/dev-login

# 4. 测试绑定微博
curl -X POST http://localhost:3000/api/weibo/dev-bind \
  -H "Authorization: Bearer {token}"
```

### 2. 测试生产模式

```bash
# 1. 配置真实的微博App Key
WEIBO_APP_KEY=真实的App_Key
WEIBO_APP_SECRET=真实的App_Secret

# 2. 启动服务
coze dev

# 3. 获取授权URL
curl -X GET http://localhost:3000/api/weibo/bind-url \
  -H "Authorization: Bearer {token}"

# 4. 在浏览器中访问授权URL，完成授权
# 5. 检查绑定状态
curl -X GET http://localhost:3000/api/weibo/status \
  -H "Authorization: Bearer {token}"
```

---

## 七、常见问题

### Q1: 授权后回调失败？

**原因**：回调地址配置不一致

**解决**：
1. 检查微博开放平台的回调地址配置
2. 确保 `.env` 中的 `WEIBO_REDIRECT_URI` 与平台配置一致
3. 注意URL编码问题

### Q2: access_token过期怎么办？

**原因**：微博OAuth Token有效期有限

**解决**：
1. 微博OAuth2.0没有refresh_token
2. 需要用户重新授权
3. 在 `weibo.service.ts` 中实现Token刷新逻辑

### Q3: 超话签到失败？

**原因**：非官方API不稳定

**解决**：
1. 检查access_token是否有效
2. 降低调用频率
3. 添加重试机制

### Q4: 如何在生产环境部署？

**步骤**：
1. 申请微博开发者账号
2. 创建应用并配置回调地址
3. 配置生产环境的环境变量
4. 部署后端服务
5. 配置前端域名

---

## 八、API接口文档

### 认证相关

#### POST /api/auth/dev-login
开发环境模拟登录

#### POST /api/auth/wechat-login
微信登录（需配置微信AppID）

#### GET /api/auth/me
获取当前用户信息

### 微博相关

#### GET /api/weibo/bind-url
获取微博授权URL

#### GET /api/weibo/callback
微博授权回调（自动处理）

#### POST /api/weibo/dev-bind
开发环境模拟绑定微博

#### GET /api/weibo/status
获取微博绑定状态

#### DELETE /api/weibo/unbind
解除微博绑定

### 超话相关

#### GET /api/topic/list
获取超话列表

#### POST /api/topic/signin
单个超话签到

#### POST /api/topic/batch-signin
批量签到

#### GET /api/topic/records
获取签到记录

---

## 九、技术架构

```
微信用户登录（JWT认证）
    ↓
微博账号绑定（OAuth 2.0）
    ↓
超话数据同步（非官方API）
    ↓
签到功能（模拟实现）
```

### 数据流转

1. 用户通过微信登录 → 获得JWT Token
2. 使用Token调用绑定接口 → 跳转微博授权
3. 微博授权成功 → 获取access_token → 保存到数据库
4. 使用access_token调用超话API → 获取超话列表
5. 用户点击签到 → 调用签到API → 记录签到数据

---

## 十、安全建议

1. **保护App Secret**：不要在代码中硬编码，使用环境变量
2. **HTTPS传输**：生产环境必须使用HTTPS
3. **Token管理**：妥善保存用户Token，定期清理过期Token
4. **频率限制**：避免频繁调用微博API
5. **数据加密**：敏感数据（如access_token）应加密存储

---

## 联系支持

如有问题，请联系：
- 微博开放平台：https://open.weibo.com/
- 项目Issue：提交到你的项目仓库