企业微信登录与通知 - 前端联调方案

涉及页面

• 登录页（src/views/_core/authentication/login.vue）
• 第三方授权回调中转页（src/views/_core/authentication/social-login.vue）
• 二维码登录页（src/views/_core/authentication/qrcode-login.vue）

本次变更概述

API

1. 获取企业微信授权地址

请求参数：

响应：

{
  "code": 0,
  "data": "https://open.work.weixin.qq.com/wwopen/sso/qrConnect?appid=xxx&agentid=xxx&redirect_uri=xxx&state=xxx"
}

前端拿到 data 后直接跳转该地址，用户扫码确认后企业微信会带 code 和 state 回跳到 redirectUri。

2. 使用 code 换取登录令牌

请求参数：

响应（首次登录与再次登录结构一致）：

{
  "code": 0,
  "data": {
    "userId": 123,
    "accessToken": "xxx",
    "refreshToken": "xxx",
    "expiresTime": "2026-09-29T12:00:00"
  }
}

业务流程与数据带入

1. 用户点击「企业微信登录」→ 调用 social-auth-redirect（type=30）→ 拿到跳转地址 → 浏览器跳转到企业微信扫码页
2. 用户扫码确认 → 企业微信回跳到 redirectUri，URL 携带 code 和 state → 由 social-login 页面承接
3. social-login 页面读取 URL 上的 type、code、state → 调用 social-login
4. 后端判断该企业微信账号是否已绑定系统用户：

• 已绑定 → 直接签发令牌返回
• 未绑定（首次） → 自动创建系统用户并绑定 → 签发令牌返回

1. 前端拿到 accessToken → 写入访问令牌存储 → 拉取权限信息 → 跳转首页

关键点：第 4 步无论首次还是再次登录，返回结构完全一致，前端不需要区分两条分支。

字段展示规则

业务规则说明

注意事项

• 企业微信授权登录要求**已备案域名**且备案主体与企业微信认证主体一致，本地 localhost 调试需用内网穿透并保证域名备案。
• 首次自动注册会跳过"注册功能已关闭"配置项（system.user.register-enabled），但**仍受租户账号配额限制**，配额用尽时返回 USER_COUNT_MAX。
• 自动注册生成的用户名以 wx_ 开头，便于与人工创建的账号区分；如需限制企业微信登录的用户范围，需在业务侧按用户名前缀或角色做二次管控。
• 默认角色 wxcp_user 必须先在库里存在。该角色及其「会员管理」授权已写进 docs/sql/wxcp_menu.sql 末尾（合并脚本 config_export_all_<日期>.sql 阶段三末尾同步了一份），新库初始化会自动建出来；**已建过的老库要补执行这一段**，否则扫码新账号能登录但菜单空白。代码按**角色编码**查找而非角色编号，换库不会失效。
• 回调接口 /admin-api/wxcp/callback 已加入免登录白名单，**不需要也不应该带前端令牌**。
• 前端原有的「未绑定 → 弹出绑定账号密码弹窗」逻辑，对企业微信场景不再触发；若产品上仍希望首次登录先绑定既有账号，需要另行明确，当前实现为直接自动注册。

部署配置清单（缺一不可）

企业微信登录要跑通，以下三处配置**必须同时存在**：

第 2 项容易漏掉：AuthRequestFactory 需要先从 yaml 拿到"社交平台基类配置"才能构造出对应的 AuthRequest 实例，之后才会用数据库里的密钥覆盖它。所以即使密钥全都配在数据库，yaml 里也必须保留一份占位配置。

第 2 项里 ignore-check-redirect-uri: true 最容易漏。yudao 的设计是 redirect-uri 不写死——SocialClientServiceImpl.getAuthorizeUrl 最后会用 HttpUtils.replaceUrlQuery 把 redirect_uri 换成前端按当前浏览器地址传进来的值。但 JustAuth 的 AuthDefaultRequest 构造时会调 AuthChecker.checkConfig(AuthConfig, AuthSource)：

if (config.isIgnoreCheckRedirectUri()) {
    return;                                    // 有这个开关才放行
}
if (StringUtils.isEmpty(redirectUri)) {
    throw new AuthException(AuthResponseStatus.ILLEGAL_REDIRECT_URI, source);
}

也就是说**不写 redirect-uri 的前提就是打开这个开关**，两者缺一不可。只删 redirect-uri 而漏了开关，扫码时会在 AuthRequestFactory.getDefaultRequest 构造 AuthWeChatEnterpriseQrcodeRequest 的那一刻抛 AuthException: Illegal redirect uri [WECHAT_ENTERPRISE]——异常发生在构造期，早于用数据库密钥覆盖的那一步，所以配置了 system_social_client 也救不了。

第 2 项为什么放 application.yaml 而不是某个 profile：YudaoJustAuthConfiguration 上的 @ConditionalOnProperty(prefix = "justauth", value = {"enabled"}, havingValue = "true", matchIfMissing = true) 让 AuthRequestFactory 无论配没配都会创建。缺配置不等于"关闭社交登录"，而是一个运行期才暴露的坑：请求走到 AuthRequestFactory.get() 时先按 justauth.type 查不到，再回落到 justauth.extend 分支，而 JustAuthProperties.extend 默认就是 null，直接 NullPointerException。

这段配置历史上只存在于 application-local.yaml，导致用 dev / test / chdl / kyzn / wtxc / yzfx / zsjc 任一 profile 启动时，企业微信扫码登录必炸，并且报的是 AuthRequestFactory.get 第 104 行的 NPE，很难一眼看出是配置缺失。上移到全局配置文件后，这一类问题从结构上被消除。

代码层兜底：AuthRequestFactory.get() 已加判空守卫——properties.getExtend() 为 null 时跳过自定义分支，由既有逻辑抛出可读的 AuthException，不再抛 NullPointerException。

回调 URL 配置

在企业微信管理后台 → 应用管理 → 自建应用 → 「接收消息」→「设置API接收」：

• URL：https://<已备案域名>/admin-api/wxcp/callback
• Token：与 wx.cp.token 完全一致
• EncodingAESKey：与 wx.cp.aes-key 完全一致

点「保存」时企业微信会立即发起一次 GET 验证，返回 echostr 明文即为通过。