三方登录
三方登录用于接入微信、企业微信、钉钉等外部身份平台，让用户通过授权码完成快捷登录或账号绑定。RuoYi Office 将三方登录拆成“社交客户端”和“社交用户”两类管理能力，并在认证接口中提供授权跳转和社交快捷登录。
本地实现位置
| 层 | 位置 |
|---|---|
| 社交客户端页面 | ruoyi-office-vben/apps/web-antd/src/views/system/social/client |
| 社交用户页面 | ruoyi-office-vben/apps/web-antd/src/views/system/social/user |
| 用户管理 DocAlert | views/system/user/index.vue |
| 认证 Controller | AuthController.java |
| 社交客户端 Controller | SocialClientController.java |
| 社交用户 Controller | SocialUserController.java |
注意：后端包路径中存在历史目录名
socail，这是代码标识符，文档中描述业务时统一写作“social / 社交”。
整体链路
社交客户端
社交客户端保存各平台应用配置。表单字段来自 views/system/social/client/data.ts：
| 字段 | 说明 |
|---|---|
name | 应用名，便于管理端识别 |
socialType | 社交平台，来自字典 SYSTEM_SOCIAL_TYPE |
userType | 用户类型，区分后台管理员、会员等 |
clientId | 客户端编号，对应平台 appKey/appId |
clientSecret | 客户端密钥，对应平台 appSecret |
agentId | 企业微信等场景的网页应用 ID，有则填写 |
publicKey | 部分平台需要的公钥配置 |
status | 是否启用 |
管理接口：
| 操作 | 接口 | 权限标识 |
|---|---|---|
| 创建客户端 | POST /system/social-client/create | system:social-client:create |
| 更新客户端 | PUT /system/social-client/update | system:social-client:update |
| 删除客户端 | DELETE /system/social-client/delete | system:social-client:delete |
| 客户端分页 | GET /system/social-client/page | 页面查询使用 |
| 发送订阅消息 | POST /system/social-client/send-subscribe-message | 测试小程序订阅消息 |
社交用户
社交用户是外部平台账号与系统用户的绑定记录。页面支持按社交平台、昵称、openid、创建时间筛选，并查看 token、原始用户数据、最后一次认证 code/state 等详情。
| 操作 | 接口 | 说明 |
|---|---|---|
| 社交用户分页 | GET /system/social-user/page | 管理端列表查询 |
| 社交用户详情 | GET /system/social-user/get | 查看 openid、token、原始数据等 |
| 绑定社交用户 | POST /system/social-user/bind | 登录后绑定当前管理员账号 |
| 取消绑定 | DELETE /system/social-user/unbind | 解绑当前管理员账号 |
| 我的绑定列表 | GET /system/social-user/get-bind-list | 个人中心展示当前账号绑定关系 |
登录与绑定接口
AuthController 提供未登录场景的三方登录入口：
| 接口 | 用途 |
|---|---|
GET /system/auth/social-auth-redirect | 根据 type 和 redirectUri 生成第三方授权 URL |
POST /system/auth/social-login | 使用授权 code 快捷登录，适合社交账号已绑定系统用户 |
SocialUserController#bind 用于已登录用户绑定社交账号；AuthController#social-login 用于未登录时直接通过已绑定社交账号登录。
接入步骤
- 在第三方平台创建应用，配置回调地址。
- 在 RuoYi Office 新建社交客户端，选择平台、用户类型并填写 appId/appSecret。
- 在登录页或个人中心触发
/system/auth/social-auth-redirect获取授权 URL。 - 第三方平台回调后，前端携带
code、state调用绑定或登录接口。 - 在“社交用户”页面确认 openid、昵称、头像和原始 token 信息是否写入。
排查清单
| 现象 | 排查方向 |
|---|---|
| 获取授权 URL 失败 | 检查社交客户端是否启用，socialType 和 userType 是否匹配 |
| 回调后登录失败 | 检查该 openid 是否已经绑定系统用户，或改走绑定流程 |
| 绑定成功但快捷登录失败 | 检查用户状态、社交客户端状态和绑定记录用户类型 |
| 平台提示 redirect_uri 不合法 | 检查第三方平台后台和前端传入的 redirectUri 是否完全一致 |
| 头像或昵称异常 | 查看社交用户详情中的原始 User 数据，确认平台返回字段 |
