perms-system-server/internal/loaders/userDetailsLoader.go

package loaders

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"math"
	"time"

	"perms-system-server/internal/consts"
	"perms-system-server/internal/model"
	"perms-system-server/internal/model/productmember"

	"github.com/zeromicro/go-zero/core/logx"
	"github.com/zeromicro/go-zero/core/stores/redis"
	"github.com/zeromicro/go-zero/core/stores/sqlx"
	"golang.org/x/sync/singleflight"
)

const (
	defaultCacheTTL = 300 // 5 分钟
	// negativeCacheTTL 控制"用户不存在/已删除"的短期负缓存窗口；必须显著短于 defaultCacheTTL，避免
	// 刚刚 createUser 的合法用户被误判为不存在，但又要足够长到能吸收一波由离职用户残留 token 带来的
	// 无效流量（审计 M-3 所说的 DB DoS 放大路径）。
	// 第 7 轮审计 L-6：gRPC GetUserPerms 可被外部凭证批量预探测未来自增 userId，把 ud:userId:*
	// 负缓存哨兵抢先写上，撞到真实 CreateUser 后导致新用户首次访问被误判为"已删除"。通过
	//   (1) 将 TTL 从 30s 压到 10s，显著缩短投毒窗口；
	//   (2) Load 在写入哨兵前对 SysUserModel 再做一次 FindOne 强一致复核（Insert 成功会 DEL 用户
	//       主键缓存，复核会打到 DB 取到真实行，从而跳过哨兵写入）；
	// 组合把这条路径的可利用性压到微秒级竞态。
	negativeCacheTTL = 10 // 10s
	// negativeCacheMarker 是写入 Redis 的哨兵字符串；选用非合法 JSON，确保任何升级带来的 schema
	// 变动都不会把它误解析为真实 UserDetails。
	negativeCacheMarker = "_NOT_FOUND_"
)

// ErrLoaderDegraded 表示 UserDetails 的子段加载（dept / product / membership / roles / perms）
// 中至少有一段因基础设施抖动失败。调用方（HTTP 中间件 / gRPC 拦截器）应映射为 503 / codes.Unavailable
// 让客户端走临时故障重试策略，**绝不能**与"用户不存在（ud.Username == ""）"同化成 401/403
// （见审计 M-N1：半成品 ud 被当作"产品禁用 / 无权限"会把一次 DB 抖动放大成全站 403，监控侧完全
// 观测不到基础设施故障）。
var ErrLoaderDegraded = errors.New("user details loader degraded: partial load failure")

// -------- UserDetails 及子结构 --------

// UserDetails 用户完整信息，包含用户、部门、产品、成员、角色、权限等所有有效字段。
// 由 UserDetailsLoader 一次性加载，可用于中间件 context 注入、login/userInfo 响应、Claims 构造等。
type UserDetails struct {
	// 用户基本信息 (sys_user)
	UserId             int64  `json:"userId"`
	Username           string `json:"username"`
	Nickname           string `json:"nickname"`
	Avatar             string `json:"avatar"`
	Email              string `json:"email"`
	Phone              string `json:"phone"`
	Remark             string `json:"remark"`
	IsSuperAdmin       bool   `json:"isSuperAdmin"`
	IsSuperAdminRaw    int64  `json:"isSuperAdminRaw"`
	MustChangePassword bool   `json:"mustChangePassword"`
	MustChangePwdRaw   int64  `json:"mustChangePwdRaw"`
	Status             int64  `json:"status"`
	TokenVersion       int64  `json:"tokenVersion"`

	// 部门信息 (sys_dept)
	DeptId     int64  `json:"deptId"`
	DeptName   string `json:"deptName"`
	DeptPath   string `json:"deptPath"`
	DeptType   string `json:"deptType"`
	DeptStatus int64  `json:"deptStatus"`

	// 产品上下文 (sys_product)
	ProductCode   string `json:"productCode"`
	ProductName   string `json:"productName"`
	ProductStatus int64  `json:"productStatus"`

	// 成员信息 (sys_product_member)
	MemberType string `json:"memberType"`

	// 角色列表 (sys_role，当前产品下已启用的角色)
	Roles []RoleInfo `json:"roles"`

	// 权限列表 (计算后的权限 code 集合)
	Perms []string `json:"perms"`

	// 当前产品下最小 permsLevel（无角色时为 math.MaxInt64）
	MinPermsLevel int64 `json:"minPermsLevel"`
}

// RoleInfo 角色摘要信息。
type RoleInfo struct {
	Id         int64  `json:"id"`
	Name       string `json:"name"`
	Remark     string `json:"remark"`
	PermsLevel int64  `json:"permsLevel"`
}

// -------- UserDetailsLoader --------

// UserDetailsLoader 负责加载、缓存、失效用户详细信息。
// 优先从 Redis 读取完整 UserDetails，miss 时查 DB 并回填。
type UserDetailsLoader struct {
	rds       *redis.Redis
	keyPrefix string
	ttl       int
	models    *model.Models
	sf        singleflight.Group
}

func NewUserDetailsLoader(rds *redis.Redis, keyPrefix string, models *model.Models) *UserDetailsLoader {
	return &UserDetailsLoader{
		rds:       rds,
		keyPrefix: keyPrefix,
		ttl:       defaultCacheTTL,
		models:    models,
	}
}

func (l *UserDetailsLoader) cacheKey(userId int64, productCode string) string {
	return fmt.Sprintf("%s:ud:%d:%s", l.keyPrefix, userId, productCode)
}

func (l *UserDetailsLoader) userIndexKey(userId int64) string {
	return fmt.Sprintf("%s:ud:idx:u:%d", l.keyPrefix, userId)
}

func (l *UserDetailsLoader) productIndexKey(productCode string) string {
	return fmt.Sprintf("%s:ud:idx:p:%s", l.keyPrefix, productCode)
}

// Load 根据 userId 和 productCode 加载完整的 UserDetails。
//
// 返回 (ud, nil) 的两种成功语义：
//  1. DB 有该用户 → ud.Username != ""，为真实数据；
//  2. DB 确认用户不存在 → ud.Username == ""（调用方据此返回"用户不存在/已删除"）；
//     同时会在 Redis 写入短 TTL 负缓存哨兵，避免残余 token 持续打 DB（见审计 M-3）。
//
// 返回 (nil, err) 语义：DB/Redis 等基础设施短时不可用。**这种情况必须与"用户不存在"严格区分**，
// 否则单次 DB 抖动会把全站在线用户同化为"用户已被删除"并要求重新登录，反过来把更多流量打到 DB
// 形成雪崩（见审计 M-1）。调用方（HTTP / gRPC 中间件）应据此返回 503/临时不可用，而不是 401。
//
// 特别地，当 loadFromDB 内任一子步骤（perm / role / dept / product / membership）失败时，
// 本函数返回 `ErrLoaderDegraded`（见审计 M-N1）；该错误同样应映射为 503 / Unavailable，
// 绝不能被吞成"产品已禁用" / "无权限"。此时本次加载不会写入 5 分钟正缓存，交给下一次 Load 重试，
// 避免把"半残 UD"固化到缓存里持续影响授权判定（见审计 H-1 / L-3）。
func (l *UserDetailsLoader) Load(ctx context.Context, userId int64, productCode string) (*UserDetails, error) {
	key := l.cacheKey(userId, productCode)

	if val, err := l.rds.GetCtx(ctx, key); err == nil && val != "" {
		if val == negativeCacheMarker {
			return &UserDetails{UserId: userId, ProductCode: productCode}, nil
		}
		var ud UserDetails
		if err := json.Unmarshal([]byte(val), &ud); err == nil {
			return &ud, nil
		}
	}

	v, sfErr, _ := l.sf.Do(key, func() (interface{}, error) {
		ud, loadOk, err := l.loadFromDB(ctx, userId, productCode)
		if err != nil {
			return nil, err
		}
		if ud.Username == "" {
			// 第 7 轮 L-6：负缓存投毒防御。写哨兵前再用 FindOne 做一次强一致复核；若用户主键缓存
			// 已被 Insert 的 ExecCtx 清掉（参见 sysUserModel_gen.go:Insert 传入 sysUserIdKey），
			// 此次 FindOne 会直接打 DB 并拿到真实行，从而识别出"在本轮 Load 期间刚被创建"的并发
			// 场景，跳过哨兵写入，避免新用户首次 Load 撞到我们自己写的 _NOT_FOUND_。
			if fresh, ferr := l.models.SysUserModel.FindOne(ctx, userId); ferr == nil && fresh != nil {
				return ud, nil
			}
			// 第 6 轮测试报告 §9.5#2：把"stale token/ticket 命中已删除用户"的事件沉淀成一条
			// 可搜索的 INFO 级审计日志。新契约下 M-8 的 ErrTokenVersionMismatch 已经对外不泄
			// 存在性，但线上排障仍需要能拿到"哪条 userId 正在被刷/验/查却已不存在"的 trace。
			// 字段 audit=user_details_load_missing 便于日志系统按 tag 建看板与告警。
			logx.WithContext(ctx).Infow("user details load hit deleted/unknown user",
				logx.Field("audit", "user_details_load_missing"),
				logx.Field("userId", userId),
				logx.Field("productCode", productCode),
			)
			// 不走 registerCacheKey：负缓存短窗口自然过期即可，也避免 Clean/CleanByProduct 路径误
			// 把哨兵 key 当成真实 UserDetails key 扫出来。
			if err := l.rds.SetexCtx(ctx, key, negativeCacheMarker, negativeCacheTTL); err != nil {
				logx.WithContext(ctx).Errorf("set user details negative cache failed: %v", err)
			}
			return ud, nil
		}
		if !loadOk {
			// 审计 M-N1：部分子加载失败属于基础设施故障，必须以 error 向上冒。历史实现把这里
			// 同化为 "(ud, nil) 的半成品" 并由调用方各自判断 DeptPath=="" / Perms==nil，在
			// jwtauth 中间件 / refreshToken / gRPC VerifyToken 里分别会被当成 "产品已禁用" /
			// "无权限" 返 403，让一次 DB 抖动彻底静默、SOC 完全看不到基础设施信号。现统一返
			// ErrLoaderDegraded，由调用方映射为 503 / codes.Unavailable。
			// 不写 5 分钟正缓存的语义保留：等下次 Load 重试（见审计 M-1 / H-1 / L-3）。
			return nil, ErrLoaderDegraded
		}
		if val, err := json.Marshal(ud); err == nil {
			if err := l.rds.SetexCtx(ctx, key, string(val), l.ttl); err != nil {
				logx.WithContext(ctx).Errorf("set user details cache failed: %v", err)
			}
			l.registerCacheKey(ctx, key, userId, productCode)
		}
		return ud, nil
	})

	if sfErr != nil {
		logx.WithContext(ctx).Errorf("load user details from DB failed: %v", sfErr)
		return nil, sfErr
	}

	ud, ok := v.(*UserDetails)
	if !ok || ud == nil {
		return &UserDetails{UserId: userId, ProductCode: productCode}, nil
	}
	return ud, nil
}

// Del 删除指定用户在指定产品下的缓存。
func (l *UserDetailsLoader) Del(ctx context.Context, userId int64, productCode string) {
	key := l.cacheKey(userId, productCode)
	if _, err := l.rds.DelCtx(ctx, key); err != nil {
		// 审计 L-R13-5 方案 B：ctx 取消 / 超时单独打 tag，便于运维把"请求被中断"与
		// "Redis 真的挂了"拆开建告警；其它错误维持原 Errorf 语义。
		logCacheInvalidationErr(ctx, "userDetailsLoader.Del", key, err)
	}
	l.unregisterCacheKey(ctx, key, userId, productCode)
}

// Clean 清除指定用户所有产品下的缓存。
func (l *UserDetailsLoader) Clean(ctx context.Context, userId int64) {
	idxKey := l.userIndexKey(userId)
	l.cleanByIndex(ctx, idxKey)
}

// CleanByUserIds 批量清除多个用户在所有产品下的缓存：利用 Redis SUNION 把 N 个用户索引集合合并，
// 配合一次批量 DEL，RTT 从"N × 3"压到常数 2，用于部门字段批量变更后的一次性缓存失效（见审计 M-1）。
// 调用方（如 UpdateDeptLogic）需要先拿到受影响的 userIds 再整体调用一次，避免在 handler 里串行清理
// 几百个用户的 Clean 把请求时长推到秒级。
func (l *UserDetailsLoader) CleanByUserIds(ctx context.Context, userIds []int64) {
	if len(userIds) == 0 {
		return
	}
	idxKeys := make([]string, 0, len(userIds))
	for _, uid := range userIds {
		idxKeys = append(idxKeys, l.userIndexKey(uid))
	}

	cacheKeys, err := l.rds.SunionCtx(ctx, idxKeys...)
	if err != nil {
		logCacheInvalidationErr(ctx, "userDetailsLoader.CleanByUserIds.sunion", "", err)
		return
	}

	toDelete := make([]string, 0, len(cacheKeys)+len(idxKeys))
	toDelete = append(toDelete, cacheKeys...)
	toDelete = append(toDelete, idxKeys...)
	if len(toDelete) == 0 {
		return
	}
	if _, err := l.rds.DelCtx(ctx, toDelete...); err != nil {
		logCacheInvalidationErr(ctx, "userDetailsLoader.CleanByUserIds.del", "", err)
	}
}

// CleanByProduct 清除指定产品下所有用户的缓存。
func (l *UserDetailsLoader) CleanByProduct(ctx context.Context, productCode string) {
	idxKey := l.productIndexKey(productCode)
	l.cleanByIndex(ctx, idxKey)
}

// BatchDel 批量删除多个用户在指定产品下的缓存。
// 审计 M-N2：历史实现对每个用户串行调用 unregisterCacheKey，触发 2N 次 SREM 串行 RTT，
// "角色下绑千人"的业务场景里会把 UpdateRole / BindRoles 的尾延迟抬到秒级；更糟糕的是
// go-zero 的请求 ctx 超时兜不住时会命中"DB 已更新但缓存未清"分支。改为：
//   (1) 主 key 批 DEL（和原来一致，一次 RTT）；
//   (2) 所有 userIndex / productIndex 的 SREM 合进一次 Pipelined RTT，把 2N 串行压到常数。
func (l *UserDetailsLoader) BatchDel(ctx context.Context, userIds []int64, productCode string) {
	if len(userIds) == 0 {
		return
	}
	keys := make([]string, 0, len(userIds))
	for _, uid := range userIds {
		keys = append(keys, l.cacheKey(uid, productCode))
	}
	if _, err := l.rds.DelCtx(ctx, keys...); err != nil {
		logCacheInvalidationErr(ctx, "userDetailsLoader.BatchDel.del", "", err)
	}
	l.batchUnregister(ctx, userIds, keys, productCode)
}

// batchUnregister 把一批 (userId, cacheKey) 的 userIndex SREM 以及（可选的）productIndex
// SREM 全部合进同一次 Pipelined 调用；相比 per-user 串行的 unregisterCacheKey，RTT 数从 2N 降到 1。
// 调用方应保证 len(userIds) == len(cacheKeys) 且索引语义一一对应。
func (l *UserDetailsLoader) batchUnregister(ctx context.Context, userIds []int64, cacheKeys []string, productCode string) {
	if len(userIds) == 0 {
		return
	}
	pIdxKey := ""
	if productCode != "" {
		pIdxKey = l.productIndexKey(productCode)
	}
	err := l.rds.PipelinedCtx(ctx, func(pipe redis.Pipeliner) error {
		for i, uid := range userIds {
			pipe.SRem(ctx, l.userIndexKey(uid), cacheKeys[i])
			if pIdxKey != "" {
				pipe.SRem(ctx, pIdxKey, cacheKeys[i])
			}
		}
		return nil
	})
	if err != nil {
		logCacheInvalidationErr(ctx, "userDetailsLoader.batchUnregister", "", err)
	}
}

func (l *UserDetailsLoader) cleanByIndex(ctx context.Context, indexKey string) {
	keys, err := l.rds.SmembersCtx(ctx, indexKey)
	if err != nil {
		logCacheInvalidationErr(ctx, "userDetailsLoader.cleanByIndex.smembers", indexKey, err)
		return
	}
	if len(keys) > 0 {
		if _, err := l.rds.DelCtx(ctx, keys...); err != nil {
			logCacheInvalidationErr(ctx, "userDetailsLoader.cleanByIndex.del", indexKey, err)
		}
	}
	if _, err := l.rds.DelCtx(ctx, indexKey); err != nil {
		logCacheInvalidationErr(ctx, "userDetailsLoader.cleanByIndex.delIndex", indexKey, err)
	}
}

func (l *UserDetailsLoader) registerCacheKey(ctx context.Context, cacheKey string, userId int64, productCode string) {
	// 索引维护使用 pipeline 把 SADD + EXPIRE（以及 productCode 维度的另一对）合并为单次 RTT，
	// 避免大产品启动瞬间 N 个并发 Load 各自打 4 次 RTT 把 Redis 连接队列打满（见审计 L-3）。
	uIdxKey := l.userIndexKey(userId)
	expireSec := time.Duration(l.ttl+60) * time.Second
	err := l.rds.PipelinedCtx(ctx, func(pipe redis.Pipeliner) error {
		pipe.SAdd(ctx, uIdxKey, cacheKey)
		pipe.Expire(ctx, uIdxKey, expireSec)
		if productCode != "" {
			pIdxKey := l.productIndexKey(productCode)
			pipe.SAdd(ctx, pIdxKey, cacheKey)
			pipe.Expire(ctx, pIdxKey, expireSec)
		}
		return nil
	})
	if err != nil {
		logx.WithContext(ctx).Errorf("registerCacheKey pipeline failed: %v", err)
	}
}

func (l *UserDetailsLoader) unregisterCacheKey(ctx context.Context, cacheKey string, userId int64, productCode string) {
	if _, err := l.rds.SremCtx(ctx, l.userIndexKey(userId), cacheKey); err != nil {
		logCacheInvalidationErr(ctx, "userDetailsLoader.unregisterCacheKey.userIndex", cacheKey, err)
	}
	if productCode != "" {
		if _, err := l.rds.SremCtx(ctx, l.productIndexKey(productCode), cacheKey); err != nil {
			logCacheInvalidationErr(ctx, "userDetailsLoader.unregisterCacheKey.productIndex", cacheKey, err)
		}
	}
}

// -------- 内部加载逻辑 --------

// loadFromDB 并行顺序加载各段 UserDetails。返回值含义：
//   - err != nil：用户主体加载失败（NotFound 除外），基础设施问题，上层 Load 直接返回 error；
//   - (ud, false, nil)：主体加载成功但 dept / product / membership / roles / perms 中任一段失败。
//     该 ud 可以返回给上层观测（例如 Username 已定），但**不能写 5 分钟正缓存**，
//     避免 5 分钟内用户命中残缺 perm 出现"间歇性 403"（见审计 M-1 / H-1 / L-3）。
//   - (ud, true, nil)：全量加载成功，可写缓存。
func (l *UserDetailsLoader) loadFromDB(ctx context.Context, userId int64, productCode string) (*UserDetails, bool, error) {
	ud := &UserDetails{
		UserId:        userId,
		ProductCode:   productCode,
		MinPermsLevel: math.MaxInt64,
	}

	if err := l.loadUser(ctx, ud); err != nil {
		return ud, false, err
	}
	if ud.Username == "" {
		return ud, true, nil
	}
	loadOk := true
	if err := l.loadDept(ctx, ud); err != nil {
		loadOk = false
	}
	if err := l.loadProduct(ctx, ud); err != nil {
		loadOk = false
	}
	if err := l.loadMembership(ctx, ud); err != nil {
		loadOk = false
	}
	if err := l.loadRoles(ctx, ud); err != nil {
		loadOk = false
	}
	if err := l.loadPerms(ctx, ud); err != nil {
		loadOk = false
	}

	return ud, loadOk, nil
}

func (l *UserDetailsLoader) loadUser(ctx context.Context, ud *UserDetails) error {
	u, err := l.models.SysUserModel.FindOne(ctx, ud.UserId)
	if err != nil {
		if errors.Is(err, sqlx.ErrNotFound) {
			return nil
		}
		logx.WithContext(ctx).Errorf("userDetailsLoader: query user %d failed: %v", ud.UserId, err)
		return err
	}
	ud.Username = u.Username
	ud.Nickname = u.Nickname
	ud.Avatar = u.Avatar.String
	ud.Email = u.Email
	ud.Phone = u.Phone
	ud.Remark = u.Remark
	ud.DeptId = u.DeptId
	ud.IsSuperAdminRaw = u.IsSuperAdmin
	ud.IsSuperAdmin = u.IsSuperAdmin == consts.IsSuperAdminYes
	ud.MustChangePwdRaw = u.MustChangePassword
	ud.MustChangePassword = u.MustChangePassword == consts.MustChangePasswordYes
	ud.Status = u.Status
	ud.TokenVersion = u.TokenVersion
	return nil
}

func (l *UserDetailsLoader) loadDept(ctx context.Context, ud *UserDetails) error {
	if ud.DeptId == 0 {
		return nil
	}
	d, err := l.models.SysDeptModel.FindOne(ctx, ud.DeptId)
	if err != nil {
		// DeptPath 为空会让 checkDeptHierarchy 一刀切 403；必须向上传递 error 让 Load 跳过缓存写入
		// （见审计 M-1）。
		logx.WithContext(ctx).Errorf("userDetailsLoader: query dept %d failed: %v", ud.DeptId, err)
		return err
	}
	ud.DeptName = d.Name
	ud.DeptPath = d.Path
	ud.DeptType = d.DeptType
	ud.DeptStatus = d.Status
	return nil
}

func (l *UserDetailsLoader) loadProduct(ctx context.Context, ud *UserDetails) error {
	if ud.ProductCode == "" {
		return nil
	}
	p, err := l.models.SysProductModel.FindOneByCode(ctx, ud.ProductCode)
	if err != nil {
		logx.WithContext(ctx).Errorf("userDetailsLoader: query product %s failed: %v", ud.ProductCode, err)
		return err
	}
	ud.ProductName = p.Name
	ud.ProductStatus = p.Status
	return nil
}

func (l *UserDetailsLoader) loadMembership(ctx context.Context, ud *UserDetails) error {
	if ud.IsSuperAdmin {
		ud.MemberType = consts.MemberTypeSuperAdmin
	}
	if ud.ProductCode == "" {
		return nil
	}
	if ud.IsSuperAdmin {
		return nil
	}
	member, err := l.models.SysProductMemberModel.FindOneByProductCodeUserId(ctx, ud.ProductCode, ud.UserId)
	if err != nil {
		// 审计 M-R18-3：与 loadUser 的 errors.Is(err, sqlx.ErrNotFound) 口径对齐。
		// productmember.ErrNotFound = sqlx.ErrNotFound 的裸等值比较在当前版本成立，但未来若
		// model 层引入 fmt.Errorf("%w", ...) 任一层包装，裸等值会失效让"用户不是本产品成员"
		// 的正常业务语义退化成 ErrLoaderDegraded 503。
		if errors.Is(err, productmember.ErrNotFound) {
			return nil
		}
		logx.WithContext(ctx).Errorf("userDetailsLoader: query member failed: %v", err)
		return err
	}
	if member.Status != consts.StatusEnabled {
		return nil
	}
	ud.MemberType = member.MemberType
	return nil
}

func (l *UserDetailsLoader) loadRoles(ctx context.Context, ud *UserDetails) error {
	if ud.ProductCode == "" {
		return nil
	}
	roleIds, err := l.models.SysUserRoleModel.FindRoleIdsByUserIdForProduct(ctx, ud.UserId, ud.ProductCode)
	if err != nil {
		logx.WithContext(ctx).Errorf("userDetailsLoader: query role ids failed: %v", err)
		return err
	}
	if len(roleIds) == 0 {
		return nil
	}
	roles, err := l.models.SysRoleModel.FindByIds(ctx, roleIds)
	if err != nil {
		logx.WithContext(ctx).Errorf("userDetailsLoader: query roles failed: %v", err)
		return err
	}
	ud.Roles = make([]RoleInfo, 0)
	minLevel := int64(math.MaxInt64)
	for _, r := range roles {
		if r.Status == consts.StatusEnabled {
			ud.Roles = append(ud.Roles, RoleInfo{
				Id:         r.Id,
				Name:       r.Name,
				Remark:     r.Remark,
				PermsLevel: r.PermsLevel,
			})
			if r.PermsLevel < minLevel {
				minLevel = r.PermsLevel
			}
		}
	}
	if minLevel < math.MaxInt64 {
		ud.MinPermsLevel = minLevel
	}
	return nil
}

func (l *UserDetailsLoader) loadPerms(ctx context.Context, ud *UserDetails) error {
	// 审计 L-R18-3：Perms 字段在响应体里期望恒为 JSON 数组。Go 的 []string(nil) 经
	// encoding/json 会输出 `null`，与"有 perm 但 deny 全部过滤掉"输出 `[]` 产生两种不同的
	// "空"表达，给下游前端 / gRPC 客户端增加了冗余 defensive check 成本。以 `[]string{}`
	// 作为统一的"空"，各子分支只在真的能计算出 codes 时再覆盖。
	ud.Perms = []string{}

	if ud.ProductCode == "" {
		return nil
	}

	if ud.ProductStatus != consts.StatusEnabled {
		return nil
	}

	if !ud.IsSuperAdmin && ud.MemberType == "" {
		return nil
	}

	// 审计 H-R18-2：UpdateDeptLogic 的 normalDeptFrozen 分支语义为"冻结本部门所有活动，一并吊销"；
	// 但历史实现仅 tokenVersion+1 踢下线，对 loadPerms 全量分支没有任何影响——被冻结部门的
	// ADMIN / DEVELOPER / MEMBER 重登后 Perms 完全恢复，审计日志里的 "revokedSessions" 变成"过眼云烟"。
	// 这里把 DeptStatus 提升为 loadPerms 全流程前置条件（超管不受产品内部门约束）：
	//   - 与 ProductStatus 检查对称：ProductStatus Disabled → 无权限；DeptStatus Disabled → 无权限；
	//   - 与 jwtauthMiddleware / ValidateProductLogin 的 DeptStatus 硬拦截共同闭合"冻结即失权"。
	// 仅作用于 DeptId>0 的场景，规避 DeptId=0 且 DeptStatus=0（默认零值）被误判为"冻结"。
	if !ud.IsSuperAdmin && ud.DeptId > 0 && ud.DeptStatus != consts.StatusEnabled {
		return nil
	}

	// 超管 / ADMIN / DEVELOPER / 研发部门的有效成员 → 全量权限
	if ud.IsSuperAdmin ||
		ud.MemberType == consts.MemberTypeAdmin ||
		ud.MemberType == consts.MemberTypeDeveloper ||
		(ud.MemberType != "" && ud.DeptType == consts.DeptTypeDev && ud.DeptStatus == consts.StatusEnabled) {
		codes, err := l.models.SysPermModel.FindAllCodesByProductCode(ctx, ud.ProductCode)
		if err != nil {
			// fail-close：权限查询失败时 Perms 留空并把错误往上传，让 Load 决定是否写缓存，
			// 绝不把"查失败 → 0 perms"或"查失败 → 残缺集"的半成品污染 5 分钟缓存
			// （见审计 H-1 / L-3）。
			logx.WithContext(ctx).Errorf("userDetailsLoader: query all perms failed: %v", err)
			return err
		}
		ud.Perms = codes
		return nil
	}

	// 普通成员：角色权限 + 用户附加权限 - 用户拒绝权限
	rolePermIds := make([]int64, 0)
	if len(ud.Roles) > 0 {
		roleIds := make([]int64, 0, len(ud.Roles))
		for _, r := range ud.Roles {
			roleIds = append(roleIds, r.Id)
		}
		ids, err := l.models.SysRolePermModel.FindPermIdsByRoleIds(ctx, roleIds)
		if err != nil {
			// 角色权限丢失会让"有角色的成员"降成 0 perm，与 deny 查询失败同样严重，
			// 必须 fail-close 不写缓存（见审计 L-3）。
			logx.WithContext(ctx).Errorf("userDetailsLoader: load role perms failed: %v", err)
			return err
		}
		rolePermIds = ids
	}

	allowIds, err := l.models.SysUserPermModel.FindPermIdsByUserIdAndEffectForProduct(ctx, ud.UserId, consts.PermEffectAllow, ud.ProductCode)
	if err != nil {
		logx.WithContext(ctx).Errorf("userDetailsLoader: load allow perms failed: %v", err)
		return err
	}
	// deny 查询必须 fail-close：deny 往往是"临时撤销某敏感权限"的最后闸门，一次 DB 抖动就把
	// deny 旁路 5 分钟会直接放出越权（见审计 H-1）。这里与 allow 对称处理，不能降级成"空 deny"。
	denyIds, err := l.models.SysUserPermModel.FindPermIdsByUserIdAndEffectForProduct(ctx, ud.UserId, consts.PermEffectDeny, ud.ProductCode)
	if err != nil {
		logx.WithContext(ctx).Errorf("userDetailsLoader: load deny perms failed: %v", err)
		return err
	}

	denySet := make(map[int64]bool, len(denyIds))
	for _, id := range denyIds {
		denySet[id] = true
	}

	permIdSet := make(map[int64]bool)
	for _, id := range rolePermIds {
		if !denySet[id] {
			permIdSet[id] = true
		}
	}
	for _, id := range allowIds {
		if !denySet[id] {
			permIdSet[id] = true
		}
	}

	finalIds := make([]int64, 0, len(permIdSet))
	for id := range permIdSet {
		finalIds = append(finalIds, id)
	}

	if len(finalIds) > 0 {
		perms, err := l.models.SysPermModel.FindByIds(ctx, finalIds)
		if err != nil {
			// 与其他分支对称处理：按 id 反查 perm 代号失败时不允许"静默空集"写缓存
			// （见审计 L-3）。
			logx.WithContext(ctx).Errorf("userDetailsLoader: findByIds perms failed: %v", err)
			return err
		}
		codes := make([]string, 0, len(perms))
		for _, p := range perms {
			if p.Status == consts.StatusEnabled {
				codes = append(codes, p.Code)
			}
		}
		ud.Perms = codes
	}
	return nil
}