chaohua_coze/WEIBO_INTEGRATION_GUIDE.md

微博OAuth 2.0 接入指南

一、微博开放平台配置

1. 注册开发者账号

访问 微博开放平台，注册并认证开发者账号。

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 文件，填入真实的微博配置：

# 微博开放平台配置
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}

响应：

{
  "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}

响应：

{
  "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. 测试开发模式

# 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. 测试生产模式

# 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：提交到你的项目仓库