一、功能介绍

企业微信自动登录页面使用 `snsapi_base` 静默网页授权取得一次性 code，再请求 `/auth/wecom/login` 换取管理端 JWT、登录会话、用户角色和可用站点。自建应用模式使用 CorpId 与可选 AgentId；第三方套件模式把 SuiteId 放在公开配置的 `corpId` 字段中构造授权 URL，后端再通过 `getuserinfo3rd` 取得成员及授权企业 CorpId。

本文说明 `/auth/wecom` 的当前标签页静默登录，不是登录页的 PC 扫码会话，也不包含第三方应用安装、企业授权或应用可见范围管理。

二、功能亮点

  1. 仅接受站内单斜线开头的回跳路径，拒绝外部 URL 和双斜线地址。
  2. OAuth 前把回跳地址写入当前标签页 sessionStorage，企业微信返回时可以恢复目标。
  3. 授权码换令牌失败时最多自动重新发起一次授权，单次自动流程最多 2 次。
  4. 账号只有一个有效角色时直接完成登录，多角色时显示角色按钮。
  5. 登录结果同时缓存可用站点并默认选中后端返回的 currentSiteId，后续请求可注入站点头。
  6. 企微配置未启用、账号或角色异常时可以降级到账号密码登录，并携带安全处理后的站内回跳地址。

三、使用场景

适用于已安装或接入企业微信能力、成员已同步到 NexusClaw SCRM 且账号启用的企业内部人员。它不适用于外部联系人、未同步成员、没有有效角色的账号，也不能替代管理员完成套件授权或组织可见范围配置。多角色选择当前主要改变浏览器用户信息，不能据此证明后端只按所选单一角色授权。

四、使用权限

  1. 授权返回必须包含企业成员 UserId；外部联系人只有 ExternalUserId 时会被拒绝。
  2. 套件模式按企业微信返回的 CorpId 与 qyUserId 精确查找未删除账号；自建模式使用全局 CorpId，极端缺失时才回退旧的仅 qyUserId 查询。
  3. 账号 status 必须为 1；未激活、已删除、空值或其他状态均拒绝登录。
  4. 账号至少要有一条 status=1 的角色关系，否则前端拒绝完成登录。但后端在校验角色非空之前已签发并缓存令牌，无角色时只有前端拒绝完成登录；不能将这一前端提示当成服务端拒绝证据。
  5. 登录角色列表不过滤角色本身的启停状态，已停用角色仍可返回到选择列表；管理员停用角色时必须同时停用员工-角色关系并清理会话。
  6. 后端在换取 code 后已经签发不含所选 roleId 的 JWT，并返回账号全部有效关系角色。多角色页面不会把选择提交后端或重新签发令牌。
  7. 前端权限同步会优先读取 user.roles；多角色登录保存时仍保留全部角色数组，因此所选角色不能作为服务端单角色权限边界。
  8. 最终权限必须以服务端每个接口的授权守卫和数据范围校验为准，不能只看角色按钮、菜单或本地 roleId。

五、前置条件

  1. 确认使用正确的系统入口 `https://scrm.console.nexusclaw.cn/`，并在受信浏览器环境打开。
  2. 确认部署启用企微自建应用或第三方套件模式；自建模式需要有效 CorpId，AgentId 可按配置附加。
  3. 确认企业微信授权回调域名包含当前系统来源和 `/auth/wecom` 路径。
  4. 确认成员已同步，qyUserId 与当前授权企业 CorpId 能匹配未删除且 status=1 的管理端账号。
  5. 确认至少一条有效角色关系存在，并检查角色菜单及服务端权限配置。
  6. 确认企业至少有可用站点，或接受登录后 currentSiteId 为空；有站点时默认取后端列表第一条。
  7. 浏览器 localStorage 会保存访问令牌和用户信息；只能在可信设备使用，公共电脑完成后必须退出并清理站点数据。
  8. 不要记录、复制或通过聊天发送 URL 中的一次性 code。

六、操作步骤

  1. 进入系统登录页并选择企业微信自动登录，或访问 `/auth/wecom?redirect=/目标路径`。redirect 必须是站内相对路径。
  2. 页面先解析 URL redirect，再读取 sessionStorage 中的 `wecom_auth_redirect`；两者都无效时回到首页 `/`。
  3. 没有 code 时页面读取公开企微配置，将当前 origin 与 pathname 作为回调地址，保存回跳目标并跳转企业微信 `snsapi_base` 授权。
  4. 企业微信回调携带 code 后，页面调用 `/auth/wecom/login`。不要刷新或复制回调地址；code 一次性有效。
  5. 后端验证 code 非空且不超过 512 字符，换取企业成员身份，按授权企业查账号并检查状态。
  6. 登录服务先签发 JWT、写入 Redis 会话、记录登录活动，再查询角色关系和启用站点。若页面提示“未配置角色”，管理员应同时注销该次已创建的会话，不只是配置角色后让用户重试。
  7. 只有一个角色时直接保存登录信息。多个角色时页面展示按钮；选择后只在浏览器合并 roleId/roleName，令牌和后端会话不会重新生成。若列表出现已停用角色，不要选择，退回并请管理员停用关系。
  8. 登录完成后核对当前企业、站点、角色显示、菜单和一项受控数据。由于角色数组仍包含全部角色，还要用服务端实际接口验证所需最小权限。
  9. 授权失败且当前自动尝试少于 2 次时页面重新授权；达到上限后选择账号密码登录。点击手动“重试”会清零计数并重新开始，因此连续失败时不要无限点击。
  10. 账号密码降级会附带 `wecomAutoLogin=failed`，防止登录页在企微环境再次自动跳回；错误文字也会放入 `auto_login_error` 查询参数供页面显示。
  11. 退出公共或共享设备前使用系统退出动作，并确认 localStorage 中访问令牌、用户、站点和追踪会话信息已清除。
本地候选版本的企业微信扫码入口；页面提示“二维码不可用”时会同时显示失败原因和刷新二维码入口。

本地候选版本的企业微信扫码入口；页面提示“二维码不可用”时会同时显示失败原因和刷新二维码入口。

NexusClaw SCRM 企业微信扫码入口显示二维码不可用提示
授权接口异常时，页面保留重试和账号密码登录两种恢复路径。

授权接口异常时，页面保留重试和账号密码登录两种恢复路径。

企业微信自动登录失败后的重试和账号密码登录入口
使用系统退出动作退出登录，确认令牌与站点信息清除后返回登录页。

使用系统退出动作退出登录，确认令牌与站点信息清除后返回登录页。

退出登录后返回登录页截图

七、字段与规则说明

  1. 授权范围：固定 `snsapi_base`，用于识别企业成员，不请求手动填写账号密码。
  2. appid：自建模式为 CorpId；套件模式公开响应沿用 corpId 字段名但实际值为 SuiteId。
  3. agentid：仅配置存在时附加；套件模式返回空。
  4. state：当前固定为 `wecom`，没有生成随机请求标识，也没有在页面回调中校验返回 state。
  5. 回调地址：当前 origin + pathname，主动去掉查询参数；业务回跳另存 sessionStorage。
  6. 自动尝试：sessionStorage 计数上限 2；手动重试会清零。
  7. 令牌有效期：后端按 jwt.expiration 换算秒数；只有响应缺少 expiresIn 时前端才回退 43200 秒。
  8. 令牌存储：accessToken、空或真实 refreshToken、过期时间、用户信息、站点和追踪会话均写入 localStorage。
  9. 角色选择：前端写 roleId/roleName，但保留后端返回的全部 roles；JWT 本身不包含所选角色。
  10. 默认站点：后端取启用站点列表第一条，前端优先采用 currentSiteId，否则再次回退第一条。

八、风险与限制

OAuth state 使用固定值且回调不校验，不能提供一次请求一次绑定的标准防重放/登录 CSRF 证据。访问令牌位于 localStorage，页面发生 XSS 时可能被读取。后端登录日志会记录授权码前 10 个字符，不应把日志视为无敏感凭据。后端在角色非空检查之前已签发令牌，且登录角色列表不排除角色本身已停用的记录。多角色选择不产生角色范围令牌，当前显示选择不能证明服务端权限已缩小。手动重试可以反复清零自动尝试计数。登录接口直接信任 X-Forwarded-For 等请求头，代理未清洗时审计 IP 可被伪造。

注意

只在可信域名和设备完成授权。若登录后企业、账号、站点或数据范围异常，立即退出并停止继续操作；不要依赖页面所选角色判断最小权限，应由管理员核对服务端角色关系、接口守卫、会话注销和审计日志。

九、常见问题

  1. 提示企微配置不完整：公开配置没有可用 appid；自建模式检查 CorpId，套件模式检查 SuiteId。
  2. 提示当前部署未启用企微自动登录：点击账号密码登录，不要持续重试。
  3. 提示非企业成员：企业微信返回的不是内部成员 UserId，外部联系人不能登录管理端。
  4. 提示用户不存在：当前授权企业 CorpId 与 qyUserId 未匹配到未删除管理端账号。
  5. 提示用户未激活或状态异常：管理员需检查账号 status，不是重新授权可以解决。
  6. 提示当前账号未配置角色：存在账号但没有 status=1 的角色关系。
  7. 为什么选择一个角色后仍看到其他角色能力？当前选择只写本地 roleId，roles 数组和 JWT 没有缩小为单一角色。
  8. 为什么刷新回调页后失败？code 只能使用一次；让页面重新发起授权或回到密码登录。
  9. 为什么登录后进入首页而非原页面？redirect 不是站内单斜线路径，或跨标签页后 sessionStorage 备份不存在。
  10. 为什么默认站点不正确？登录默认选择后端启用站点列表第一条，进入后应核对并切换。
  11. 为什么两次失败后点击重试还能继续？手动重试会清除尝试计数并启动新流程。
  12. 退出登录会清除哪些本地信息？会清除访问令牌并清空 localStorage 中的站点与追踪数据，然后回到登录页；2026-09-12 实测 sessionStorage 仍保留 user_info 一项，共享设备建议退出后关闭全部标签页。

十、相关指南

登录成功后阅读《认识 NexusClaw SCRM》核对导航，再通过《配置角色权限》检查菜单、按钮与数据范围；业务查询可继续阅读《查看和筛选客户》。

说明

页面入口：/auth/wecom；本文不包含 PC 扫码登录会话