服务态认证与 AuthContext 说明

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

查看文档来源信息

来源目录：addons/sys_base/docs
来源文件：契约说明/服务态认证与AuthContext说明.md

## 适用范围 - `/sys_base/public/auth/*` 公共认证接口。 - `/sys_base/public/service/*` 服务态受控接口。 - 中间件内部服务态调用链路。

当前正式口径

/sys_base/public/service/* 是服务态受控接口，只允许携带 X-System-Key 调用。
/sys_base/public/auth/* 是认证与用户上下文相关接口，不再承载微信应用支付资料同步能力。
微信应用支付资料同步统一走 /sys_base/public/service/syncWechatAppsInfo。
微信应用 AccessToken 获取统一走 /sys_base/public/service/getAccessTokenCheck。
X-App-Key 的正式语义是 tempKey，不允许把 permanent key 当作运行时请求头长期使用。
permanent key 只用于调用 exchangeTempKey 换取 tempKey。

AuthContext 定义

当前中间件在认证中间件中统一注入 AuthContext，字段如下：

type AuthContext struct {
    Mode       string
    AppID      string
    AddonsType string
    ClientIP   string
    Claims     *CustomClaims
    DeepOrgIds []uint
    AreaUuids  []string
}

注入规则

X-System-Key 命中系统只读白名单时，Mode=system_read_only。
X-System-Key 命中系统级受控接口时，Mode=system_api。
X-App-Key 通过 tempKey 校验且未携带用户 token 时，Mode=service。
X-App-Key 通过 tempKey 校验且同时携带有效 x-token 时，Mode=user，并补齐 Claims、DeepOrgIds、AreaUuids。
app-id、addons-type、客户端 IP 和 trace 信息由中间件统一写入请求上下文。

双模式接口正式行为

以下接口允许 service + user 双模式：

接口	正式行为
`getUserInfosBatch`	按当前用户组织范围过滤可见用户
`getUserIdsByAuthorityIds`	按当前用户组织范围过滤角色用户
`getSubOrgUserIdsByUser`	按当前用户组织范围过滤下级组织用户
`getUserAreaPermission`	返回当前用户可用校区范围
`getUserOrgInfo`	返回当前用户组织信息
`batchGetAreaInfo`	按当前用户校区范围过滤校区详情
`getAreaListByApp`	按应用和模块返回可见校区列表

认证侧应用资料查询口径不再是正式接口，也不再作为服务态或用户态应用资料同步入口。

服务态受控接口

接口	正式用途
`/sys_base/public/service/syncWechatAppsInfo`	同步微信入口应用和服务商支付主体资料
`/sys_base/public/service/getAccessTokenCheck`	获取当前应用可用的微信 AccessToken

syncWechatAppsInfo 只同步配置资料，不返回 accessToken、notifyHost、业务回调地址和业务子商户归属。

getAccessTokenCheck 只返回运行时 AccessToken，不承担配置同步职责。默认优先读取 Redis；forceRefresh=true 时必须真实请求微信刷新，并把 refreshReason、errCode、tokenHash 作为诊断信息写入日志。

不允许的做法

不允许下游继续调用认证侧应用资料查询口径同步微信应用资料。
不允许把 accessToken 放入应用资料同步结果。
不允许把原始 AccessToken 写入日志、业务表或同步快照；需要标识失败 token 时只能传 tokenHash。
不允许把 notifyHost、支付回调路径、退款回调路径、业务子应用或业务子商户归属放入中间件应用同步结果。
不允许用 campusCode、authUuid 或 sys_area.uuid 推导唯一微信应用。
不允许下游直连中间件数据库读取 app_wechat_apps_info。
不允许把 permanent key 当作运行时 X-App-Key 长期使用。

维护提示

新增服务态接口时，优先挂载到 /sys_base/public/service/* 并使用 X-System-Key。
新增公共认证接口时，必须明确它是服务模式、用户模式还是双模式。
新增微信应用资料字段时，必须同步更新 syncWechatAppsInfo 文档，明确是否允许下游同步。

服务态认证与 AuthContext 说明 ​

当前正式口径 ​

AuthContext 定义 ​

注入规则 ​

双模式接口正式行为 ​

服务态受控接口 ​

不允许的做法 ​

维护提示 ​