登录运行上下文契约说明

构建时间2026-06-26 20:10:33（Asia/Shanghai）来源项目中间件文档 / 中间件后端来源仓../cl-midserver-2026来源提交号69b951a07311e75887b57e0400d888f89dd72cac

查看文档来源信息

• 来源目录：addons/sys_base/docs
• 来源文件：契约说明/登录运行上下文契约说明.md

## 适用范围 - PCWEB 登录主链 - 头部身份切换 - JWT / Claims / CommonScope - 菜单运行时 - 权限运行时

上下文定义

1. 正式运行上下文只分两种：role、super_admin。
2. role 上下文来源于 sys_user_authority、sys_authority_app、sys_authorities.addons_type 的交集结果。
3. super_admin 上下文来源于 sys_users.is_super_admin=true，不依赖任何角色记录。

候选上下文规则

1. 候选上下文 = 当前应用 + 当前模块下可用的普通角色上下文。
2. 用户 is_super_admin=true 时，再额外追加一个 super_admin 上下文。
3. “1 个普通角色 + 超级管理员”属于两个候选上下文。
4. “多个普通角色 + 超级管理员”同样属于多个候选上下文。

登录选择顺序

1. 请求明确指定了 accessMode + authorityId 时，优先按本次指定进入。
2. 未指定时，先读取 sys_user_auth_addons 中当前 app-id + addons-type 的上次运行上下文。
3. 上次上下文仍有效时直接进入，不弹选择框。
4. 上次上下文无效时重新计算候选上下文。
5. 候选上下文只有一个时直接进入。
6. 候选上下文大于一个时返回选择列表。
7. 当前模块没有普通角色，但用户是超级管理员时，直接进入 super_admin 上下文。
8. 当前模块没有普通角色且用户不是超级管理员时，明确失败。

上次运行上下文存储

1. sys_user_auth_addons 的正式语义是“上次运行上下文”，不再是“上次角色”。
2. 表结构正式包含 access_mode 字段，当前值只允许 role、super_admin。
3. role 模式下 authority_id 必须是有效角色 ID。
4. super_admin 模式下 authority_id 正式允许为 0。
5. 历史数据未写 access_mode 时按 role 处理。
6. 中间件管理端更新用户角色后，若 role 模式的上次运行上下文指向已被移除的角色，必须清理该上下文，后续登录或切换时重新计算候选上下文。

JWT 与 CommonScope 口径

1. JWT / Claims / CommonScope 必须同时表达：
   • accessMode
   • isSuperAdmin
   • isSuperAdminContext
   • selectedAuthorityId
2. super_admin 上下文下：
   • accessMode=super_admin
   • isSuperAdmin=true
   • isSuperAdminContext=true
   • selectedAuthorityId=0
   • roleId=0
3. role 上下文下：
   • accessMode=role
   • isSuperAdmin 表示账号身份
   • isSuperAdminContext=false
   • selectedAuthorityId 为当前角色 ID

菜单与权限运行时规则

1. super_admin 上下文下，菜单运行时返回当前模块已发布正式菜单的完整树。
2. super_admin 上下文下，页面与动作权限全量放行。
3. role 上下文下，菜单运行时与权限运行时继续按角色授权结果生效。
4. 任何运行时接口都不得因为 super_admin 上下文的 selectedAuthorityId=0 直接报错。

登录审计规则

1. 登录主链路只负责认证、上下文解析、会话创建、token 返回和登录记录落库。
2. 登录记录中的 IP 归属地属于审计补充信息，不得参与登录成败、默认页、菜单或权限判断。
3. 本地和内网 IP 不访问公网归属服务，直接记录为“本地地址”或“内网地址”。
4. 公网 IP 归属查询必须异步执行；公网归属服务超时、失败或返回未知时，不得阻塞登录响应。

切换规则

1. 头部切换列表必须展示当前模块下所有普通角色上下文。
2. 当前账号是超级管理员时，切换列表必须额外展示“超级管理员”。
3. 普通角色与超级管理员上下文允许双向切换。
4. 切换成功时，后端必须先创建新 session 并换发新 token，再写回当前模块运行上下文，最后失效旧 session。
5. 切换成功后，前后端都必须重建用户资料、菜单、默认页、权限状态。
6. 超级管理员切到普通角色后，后端所有正式治理接口都必须回到 role 口径校验；切回 super_admin 后再按超管上下文正式放行。

不允许的做法

• 不允许新增伪超级管理员角色。
• 不允许往角色表、用户角色表、角色应用表里插假数据伪造超级管理员能力。
• 不允许保留“超级管理员必须先有角色才能登录”的旧逻辑。

2026-04-24 联调补充口径

1. 超级管理员是否放行，正式依据是当前运行上下文 accessMode=super_admin 与 isSuperAdminContext=true，不是“账号本身是超管用户”这一条单独条件。
2. 超级管理员用户切到普通角色上下文后，所有正式治理接口都必须回到 role 口径校验，不得再按超管用户身份直接越过角色授权。
3. 菜单运行态、角色授权状态、Key 管理、校区管理、图片管理、运行日志、字典管理、请求日志、登录日志、系统配置等正式治理接口，均按当前上下文进入正式判定链路。
4. 普通角色上下文读取自身授权状态属于正式允许场景；普通角色上下文伪装读取 super_admin 状态属于正式拒绝场景。
5. 本轮真实联调已确认：超级管理员账号在部门页可从普通角色上下文切回 super_admin，且日志正式落出 selectedAuthorityId=0、accessMode=super_admin。