登录与身份切换使用说明
查看文档来源信息
- 来源目录：
addons/sys_base/docs - 来源文件：
功能说明/登录与身份切换使用说明.md
入口位置
- 登录页
- 顶部“当前身份”切换入口
使用前提
- 登录请求必须带上当前应用和模块标识。
- 普通角色上下文要求用户在当前模块下拥有可用角色。
- 超级管理员上下文只要求当前用户具备超级管理员身份。
操作方法
- 账号密码登录成功后，若后端要求选择身份，则在身份弹窗中选择目标上下文。
- 登录完成后立即读取
getUserInfo，以当前正式运行上下文初始化菜单、权限和默认页。 - 登录后如需切换身份，在顶部“当前身份”中发起
switchCurrentAuthorityContext。 - 切换成功后先接管新 token，再读取
getUserInfo，重新构建菜单、权限和默认页。
规则说明
- 当前正式上下文只有
role和super_admin两种。 super_admin上下文下selectedAuthorityId=0是正式结果，不视为异常。- 超级管理员用户即使当前模块下没有普通角色，也允许进入
super_admin上下文。 - 登录页验证码按客户端 IP 做频控；同一账号或同一 IP 在短时间内连续失败达到阈值后，会进入临时锁定窗口。
- 切换上下文后，必须以新 token 和新
getUserInfo结果为准，不能继续沿用切换前的局部状态。 - 后端切换链路必须先创建新 session、写回当前运行上下文，再失效旧 session，不能先踢会话再生成新上下文。
- 超级管理员切到普通角色后，正式治理接口按普通角色校验；切回超级管理员后，再恢复超管放行结果。
- 登录审计中的 IP 归属查询不得阻塞登录主链路；本地和内网 IP 直接记录为“本地地址”或“内网地址”，公网 IP 先记录为“查询中”，再由后台队列异步补齐归属地。
常见结果
- 超级管理员用户可以在普通角色上下文和
super_admin上下文之间双向切换。 - 普通角色用户只能进入自己的普通角色上下文，切换到
super_admin会被正式拦截。 - 切换成功后，默认页、菜单和动作权限会按当前上下文重新生效。
- 账号或 IP 命中登录失败阈值后，会直接收到“临时锁定”提示；等待锁定窗口结束后才允许继续尝试。
维护提示
- 遇到登录后页面放行异常，先核对
getUserInfo返回的currentContext、contextOptions和defaultPage。 - 遇到身份切换异常，先核对
switchCurrentAuthorityContext返回，再看服务日志中的selectedAuthorityId、accessMode、isSuperAdmin、isSuperAdminContext。 - 遇到登录前就被拦截的情况，优先检查验证码频控和登录失败锁定是否已命中，再继续排查密码或上下文配置。
- 遇到登录变慢时，先确认登录记录写入没有同步等待公网 IP 归属服务；公网归属服务异常只允许影响后台补齐，不允许影响 token 返回、菜单初始化或权限初始化。
2026-04-24 联调补充说明
- 超级管理员账号进入中间件后，可在头部身份区域在普通角色上下文与“超级管理员（超级管理员上下文）”之间双向切换。
- 切到超级管理员上下文后，正式治理页按超级管理员上下文放行；切回普通角色上下文后，页面、按钮和默认页立即恢复普通角色授权结果。
- 本轮真实联调已确认部门页会随着身份切换同步刷新：普通角色上下文只看到本角色范围内部门，切回超级管理员后恢复全量部门数据。