perms-system-server/internal/logic/auth/access.go

package auth

import (
	"context"
	"errors"
	"math"
	"strings"

	"perms-system-server/internal/consts"
	"perms-system-server/internal/loaders"
	"perms-system-server/internal/middleware"
	memberModel "perms-system-server/internal/model/productmember"
	roleModel "perms-system-server/internal/model/role"
	userModel "perms-system-server/internal/model/user"
	"perms-system-server/internal/response"
	"perms-system-server/internal/svc"

	"github.com/zeromicro/go-zero/core/stores/sqlx"
)

func memberTypePriority(memberType string) int {
	switch memberType {
	case consts.MemberTypeSuperAdmin:
		return 0
	case consts.MemberTypeAdmin:
		return 1
	case consts.MemberTypeDeveloper:
		return 2
	case consts.MemberTypeMember:
		return 3
	default:
		return math.MaxInt32
	}
}

// ManageAccessOption 给 CheckManageAccess 的可选参数；主要用来传递调用方已经拿到的目标用户对象，
// 避免 checkDeptHierarchy 内部再做一次 FindOne(targetUserId)（见审计 M-5）。
type ManageAccessOption func(*manageAccessOpts)

type manageAccessOpts struct {
	prefetchedTarget *userModel.SysUser
	memberSink       **memberModel.SysProductMember
}

// WithPrefetchedTarget 供调用方透传已获取的目标用户数据。仅在 target.Id == targetUserId 时有效，
// 调用方负责保证一致性；不一致时该选项被忽略，回落到普通 FindOne。
func WithPrefetchedTarget(target *userModel.SysUser) ManageAccessOption {
	return func(o *manageAccessOpts) {
		o.prefetchedTarget = target
	}
}

// WithMemberSink 让调用方接住 checkPermLevel 内部顺带 FindOneByProductCodeUserId 取到的
// targetMember，避免调用方再打一次同查询（审计 M-R10-5）。注意：
//   - 仅在走进 checkPermLevel 的分支（caller 非 SuperAdmin 且非本人）才会被写入；
//   - caller=SuperAdmin 时整个 CheckManageAccess 短路不查 member，sink 将保持 nil，调用方
//     需要在 sink==nil 的情况下自己兜底 FindOneByProductCodeUserId（或按业务规则跳过）。
func WithMemberSink(sink **memberModel.SysProductMember) ManageAccessOption {
	return func(o *manageAccessOpts) {
		o.memberSink = sink
	}
}

// CheckManageAccess 检查当前操作者是否有权管理目标用户。
// 规则：
//  1. SUPER_ADMIN 完全豁免
//  2. 操作自己豁免
//  3. 部门检查：目标用户须在操作者本部门或下级子部门（ADMIN 豁免）
//  4. 权限级别检查：操作者的级别必须严格高于目标用户
//     - 先比 memberType 优先级（SUPER_ADMIN > ADMIN > DEVELOPER > MEMBER）
//     - 同 memberType 时比 permsLevel（数值越小权限越高）
func CheckManageAccess(ctx context.Context, svcCtx *svc.ServiceContext, targetUserId int64, productCode string, opts ...ManageAccessOption) error {
	caller := middleware.GetUserDetails(ctx)
	if caller == nil {
		return response.ErrUnauthorized("未登录")
	}

	if caller.IsSuperAdmin {
		return nil
	}
	if caller.UserId == targetUserId {
		return nil
	}

	options := &manageAccessOpts{}
	for _, opt := range opts {
		opt(options)
	}
	prefetched := options.prefetchedTarget
	if prefetched != nil && prefetched.Id != targetUserId {
		prefetched = nil
	}

	if err := checkDeptHierarchy(ctx, svcCtx, caller, targetUserId, prefetched); err != nil {
		return err
	}

	return checkPermLevel(ctx, svcCtx, caller, targetUserId, productCode, options.memberSink)
}

// CheckMemberTypeAssignment 检查操作者是否有权分配指定的 memberType。
func CheckMemberTypeAssignment(ctx context.Context, assignedType string) error {
	caller := middleware.GetUserDetails(ctx)
	if caller == nil {
		return response.ErrUnauthorized("未登录")
	}
	if caller.IsSuperAdmin {
		return nil
	}
	if caller.MemberType == "" {
		return response.ErrForbidden("缺少产品成员上下文")
	}
	if memberTypePriority(caller.MemberType) >= memberTypePriority(assignedType) {
		return response.ErrForbidden("无权分配该成员类型，不能分配与自己同级或更高级别的类型")
	}
	return nil
}

// RequireSuperAdmin 要求当前操作者必须是超级管理员。
func RequireSuperAdmin(ctx context.Context) error {
	caller := middleware.GetUserDetails(ctx)
	if caller == nil {
		return response.ErrUnauthorized("未登录")
	}
	if !caller.IsSuperAdmin {
		return response.ErrForbidden("仅超级管理员可执行此操作")
	}
	return nil
}

// RequireProductAdminFor 要求当前操作者是超级管理员或指定产品的管理员。
func RequireProductAdminFor(ctx context.Context, targetProductCode string) error {
	caller := middleware.GetUserDetails(ctx)
	if caller == nil {
		return response.ErrUnauthorized("未登录")
	}
	if caller.IsSuperAdmin {
		return nil
	}
	if caller.MemberType == consts.MemberTypeAdmin && caller.ProductCode == targetProductCode {
		return nil
	}
	return response.ErrForbidden("仅超级管理员或该产品的管理员可执行此操作")
}

// ResolveOwnRoleOr404 把"根据 roleId 拉取角色 + 归属产品判定"这段通用前置抽出来供
// UpdateRole / DeleteRole / BindRolePerms 等 role 维度的管理接口复用（审计 L-R14-1）。
//
// 必须与 RoleDetailLogic（M-N3）的收敛口径保持一致：非超管调用者看到"属于其他产品的
// 角色"时，必须返回与"角色不存在"完全一致的 404 + 文案 "角色不存在"，否则任何已登录
// 用户都能靠 404 vs 403 的响应码差异做顺序 id 扫描，画出跨产品 roleId 分布图。
//
// 返回值约定：
//   - 成功：返回带完整字段的 *SysRole，调用方随后可直接 `authHelper.RequireProductAdminFor(role.ProductCode)`
//     做最终授权判定；
//   - err != nil：调用方应立即返回该 err，不要再访问 role（除了超管路径外，我们不向响应体暴露 role.ProductCode）。
//
// 契约说明：
//   - 未登录 → 返回 ErrUnauthorized，避免把"未登录"与"无此角色"混为 404（登录态下的
//     401 响应对攻击者意义不同，且让中间件/运维识别"缺登录态"路径更容易）；
//   - 超管：即使 role.ProductCode 与 caller.ProductCode 不同也直接放行，用于平台级维护
//     场景（超管本来就能跨产品，不存在 enum oracle）。
func ResolveOwnRoleOr404(ctx context.Context, svcCtx *svc.ServiceContext, roleId int64) (*roleModel.SysRole, error) {
	caller := middleware.GetUserDetails(ctx)
	if caller == nil {
		return nil, response.ErrUnauthorized("未登录")
	}
	role, err := svcCtx.SysRoleModel.FindOne(ctx, roleId)
	if err != nil {
		return nil, response.ErrNotFound("角色不存在")
	}
	if !caller.IsSuperAdmin && role.ProductCode != caller.ProductCode {
		return nil, response.ErrNotFound("角色不存在")
	}
	return role, nil
}

// GuardRoleLevelAssignable 校验调用者能否把 rolePermsLevel 这一等级的角色分配给他人。
// 约束："只能分配严格低于自身的等级"（数字更大 = 更低），与 checkPermLevel 的 ">=" 拦截口径对齐，
// 避免调用者把下属拉到与自己平级后彻底失去管控（见审计 H-3）。
// 拥有产品全权（SuperAdmin / ADMIN / DEVELOPER）的调用者直接放行。
//
// 授权依据直接走 DB 强一致查询，而不是 caller 的 UD 缓存：
// 超管刚把 caller 从高级降到中级时，如果 UD 缓存的 Clean 因为 Redis 抖动失败，caller 的缓存里还
// 是旧的高 MinPermsLevel；缓存 TTL 窗口内 caller 仍可凭旧级别批量分配超出当前权限的角色
// （审计 M-3 TOCTOU + 缓存失效延迟）。这里按"最小代价避开缓存"的原则，只在 assignment 决策点
// 打一条 FindMinPermsLevelByUserIdAndProductCode 走 NoCache 查询。
func GuardRoleLevelAssignable(ctx context.Context, svcCtx *svc.ServiceContext, caller *loaders.UserDetails, rolePermsLevel int64) error {
	snap, err := LoadCallerAssignableLevel(ctx, svcCtx, caller)
	if err != nil {
		return err
	}
	return CheckRoleLevelAgainst(snap, rolePermsLevel)
}

// AssignableLevelSnapshot 是 "caller 在分配角色时的可分配等级快照"。调用方通常在一次业务
// 请求里对多个 role 做同一 caller 的等级校验，拿着这个快照重复 CheckRoleLevelAgainst 不再打 DB。
type AssignableLevelSnapshot struct {
	// HasFullPerms 为 true 时直接全放行（SuperAdmin / ADMIN / DEVELOPER）。
	HasFullPerms bool
	// NoRole 表示 caller 在当前产品下没有任何活跃角色；即便 HasFullPerms=false 也不能分配任何角色。
	NoRole bool
	// Level 是 caller 的最小 permsLevel；仅在 HasFullPerms=false && NoRole=false 时有效。
	Level int64
}

// LoadCallerAssignableLevel 封装"拉取一次 caller 的可分配等级 snapshot"的 DB 读。用于把 BindRoles
// 这类批量分配循环里的 N 次 loadFreshMinPermsLevel 合并为 1 次（见审计 M-R10-3）。
// 对 SuperAdmin / ADMIN / DEVELOPER 走短路，不打 DB；其他情况走 NoCache DB 读，保持与
// GuardRoleLevelAssignable 完全一致的 TOCTOU 闭环契约。
func LoadCallerAssignableLevel(ctx context.Context, svcCtx *svc.ServiceContext, caller *loaders.UserDetails) (AssignableLevelSnapshot, error) {
	if HasFullProductPerms(caller) {
		return AssignableLevelSnapshot{HasFullPerms: true}, nil
	}
	if caller == nil {
		return AssignableLevelSnapshot{NoRole: true}, nil
	}
	level, notFound, err := loadFreshMinPermsLevel(ctx, svcCtx, caller.UserId, caller.ProductCode)
	if err != nil {
		return AssignableLevelSnapshot{}, err
	}
	if notFound {
		return AssignableLevelSnapshot{NoRole: true}, nil
	}
	return AssignableLevelSnapshot{Level: level}, nil
}

// CheckRoleLevelAgainst 用预取的 snapshot 判定一个角色等级是否可被 caller 分配。保持与
// GuardRoleLevelAssignable 完全一致的错误文案与边界条件（">=" 含同级拦截，ErrNotFound→403）。
func CheckRoleLevelAgainst(snap AssignableLevelSnapshot, rolePermsLevel int64) error {
	if snap.HasFullPerms {
		return nil
	}
	if snap.NoRole {
		return response.ErrForbidden("您没有可分配的角色等级")
	}
	if rolePermsLevel <= snap.Level {
		return response.ErrForbidden("不能分配权限级别高于自身的角色（含同级）")
	}
	return nil
}

// GuardCreateRolePermsLevel 校验 caller 能否在本产品下创建 `reqLevel` 等级的新角色（审计 H-R17-3）。
//
// 与 GuardRoleLevelAssignable / CheckRoleLevelAgainst 的差异：
//   - **分配侧**（BindRoles / SetUserPerms）允许 HasFullPerms 的 caller 无条件分配任意 permsLevel
//     的既有角色——因为 ADMIN / DEVELOPER 在本产品内已经是全权，多分配不会凭空拉高下属权级；
//     真正的越权边界由既有角色的 permsLevel 事先决定（UpdateRole 的 L-R12-3 拒非超管提升）。
//   - **创建侧**却是弹药制造：product ADMIN 可以 CreateRole(PermsLevel=1) 造出"顶格角色"，再
//     走 BindRoles(userId=D, roleIds=[R_super]) 把下属 MEMBER/DEVELOPER 的 UD.MinPermsLevel
//     顶到 1，绕过 GuardRoleLevelAssignable 的同级拦截——等价于横向提权。因此 CreateRole
//     必须在 caller permsLevel 与 reqLevel 之间建立与 assignment 侧**不**对称的新约束。
//
// 规则：
//   - SuperAdmin：任意 reqLevel 放行（系统管理员不受产品内 perm 等级约束）；
//   - 非超管的 HasFullPerms 调用者（product ADMIN）：reqLevel 必须 >= 2，把"permsLevel=1"
//     的顶格角色语义保留给 SuperAdmin 所生；同级（ADMIN 自己对应 sentinel 0）不可建；
//   - 无 FullPerms 的普通调用者：走 CheckRoleLevelAgainst 的标准路径（严格低于 snap.Level）。
//     目前 RequireProductAdminFor 已经把 DEVELOPER/MEMBER 挡在 CreateRole 外，但把语义写全
//     可以应对未来把"DEVELOPER 可建 sub-role"放开的扩展（到时候只需松开 RequireProductAdminFor）。
func GuardCreateRolePermsLevel(ctx context.Context, svcCtx *svc.ServiceContext, caller *loaders.UserDetails, reqLevel int64) error {
	if caller == nil {
		return response.ErrUnauthorized("未登录")
	}
	if caller.IsSuperAdmin {
		return nil
	}
	snap, err := LoadCallerAssignableLevel(ctx, svcCtx, caller)
	if err != nil {
		return err
	}
	if snap.HasFullPerms {
		// Product ADMIN / DEVELOPER 的 snap 在 assignment 侧等价于顶格（sentinel 0），
		// 创建侧必须人为把 permsLevel=1 留给 SuperAdmin，避免 ADMIN 通过"建 R_super + BindRoles"
		// 间接把下属提到 ADMIN 线——横向提权攻击路径（见审计 H-R17-3 描述）。
		if reqLevel <= 1 {
			return response.ErrForbidden("非超级管理员不能创建权限级别为 1 的顶格角色")
		}
		return nil
	}
	return CheckRoleLevelAgainst(snap, reqLevel)
}

// loadFreshMinPermsLevel 统一的"授权决策点"接口：强一致读 DB，取 userId 在 productCode 下的
// 最小 permsLevel。返回三元组方便调用方按业务语义决定"无角色"对应放行还是拒绝。
//   - level:     命中时的最小 permsLevel
//   - notFound:  caller 在该产品下没有任何活跃角色（底层 sqlx.ErrNotFound）
//   - err:       其他 DB 错误，已包装成 500 fail-close；避免抖动被同化为"无角色 = 最低级"放行超权
//
// GuardRoleLevelAssignable（分配侧）与 checkPermLevel（管理侧）共享此 helper，保证两条 TOCTOU
// 路径的 DB 口径完全对称（审计 M-3 封了"授角色"一半 / H-2 封"直接管人"另一半）。
func loadFreshMinPermsLevel(ctx context.Context, svcCtx *svc.ServiceContext, userId int64, productCode string) (int64, bool, error) {
	level, err := svcCtx.SysRoleModel.FindMinPermsLevelByUserIdAndProductCode(ctx, userId, productCode)
	if err != nil {
		if errors.Is(err, sqlx.ErrNotFound) {
			return 0, true, nil
		}
		return 0, false, response.NewCodeError(500, "校验权限级别失败，请稍后重试")
	}
	return level, false, nil
}

// HasFullProductPerms 判断调用者是否拥有当前产品的全部权限（无需做 permsLevel 校验）。
// SuperAdmin / ADMIN / DEVELOPER 均视为全权；loadPerms 对此三者走全权分支。
// 所有依赖"调用者已拥有全权"的短路逻辑应复用此函数，变更只需改一处。
func HasFullProductPerms(caller *loaders.UserDetails) bool {
	if caller == nil {
		return false
	}
	return caller.IsSuperAdmin ||
		caller.MemberType == consts.MemberTypeAdmin ||
		caller.MemberType == consts.MemberTypeDeveloper
}

// CheckAddMemberAccess 校验 caller 是否有权把 target 作为**新成员**拉进产品。与 CheckManageAccess 的
// 差异：
//  1. 不做 memberType / permsLevel 比对——AddMember 时 target 还不是成员，checkPermLevel 的
//     FindOneByProductCodeUserId 必定落空报 403，整个流程对产品 ADMIN 直接不可用；
//  2. 对产品 ADMIN 也强制执行部门链校验（checkDeptHierarchy 的 ADMIN bypass 不生效），防止
//     ADMIN 从部门树外 / HR / 财务把人强拉入自己的产品（见审计 H-3）；
//  3. SuperAdmin 仍完全豁免，自改自加场景由上层业务规则另行屏蔽。
//
// 调用方应先走 RequireProductAdminFor 保证 caller 本身有"添加成员"的基线权限，再调这一步过部门链。
func CheckAddMemberAccess(ctx context.Context, svcCtx *svc.ServiceContext, target *userModel.SysUser) error {
	caller := middleware.GetUserDetails(ctx)
	if caller == nil {
		return response.ErrUnauthorized("未登录")
	}
	if caller.IsSuperAdmin {
		return nil
	}
	if target == nil {
		return response.ErrBadRequest("缺少目标用户信息")
	}
	if caller.UserId == target.Id {
		return nil
	}

	// 不走 checkDeptHierarchy 的 ADMIN 分支：ADMIN bypass 设计本意是"product ADMIN 对产品内既有
	// 成员有全面管理权"，但 AddMember 还没把 target 拉进产品，这里的 ADMIN bypass 会变成一个
	// "随手拉部门树外的人进来"的漏洞（审计 H-3）。
	if caller.DeptId == 0 || caller.DeptPath == "" {
		return response.ErrForbidden("您未归属任何部门，无权添加产品成员")
	}
	if target.DeptId == 0 {
		return response.ErrForbidden("目标用户未归属部门，仅超管可将其添加为成员")
	}
	targetDept, err := svcCtx.SysDeptModel.FindOne(ctx, target.DeptId)
	if err != nil {
		return response.ErrForbidden("无法校验目标用户部门")
	}
	if !strings.HasPrefix(targetDept.Path, caller.DeptPath) {
		return response.ErrForbidden("无权将其他部门的用户添加为产品成员")
	}
	return nil
}

// ValidateStatusChange 校验状态变更的合法性（不允许自改状态、不允许冻结超管）。
// UpdateUser 和 UpdateUserStatus 共用此函数以确保校验逻辑一致。
//
// 返回校验通过时对应的目标用户对象，方便调用方透传给 CheckManageAccess 的 WithPrefetchedTarget
// 选项和后续业务使用，避免同一请求内重复 FindOne（见审计 M-5）。
func ValidateStatusChange(ctx context.Context, svcCtx *svc.ServiceContext, callerId, targetUserId int64) (*userModel.SysUser, error) {
	if callerId == targetUserId {
		return nil, response.ErrBadRequest("不能修改自己的状态")
	}
	target, err := svcCtx.SysUserModel.FindOne(ctx, targetUserId)
	if err != nil {
		return nil, response.ErrNotFound("用户不存在")
	}
	if target.IsSuperAdmin == consts.IsSuperAdminYes {
		return nil, response.ErrForbidden("不能修改超级管理员的状态")
	}
	return target, nil
}

func checkDeptHierarchy(ctx context.Context, svcCtx *svc.ServiceContext, caller *loaders.UserDetails, targetUserId int64, prefetchedTarget *userModel.SysUser) error {
	if caller.MemberType == consts.MemberTypeAdmin {
		return nil
	}

	// TODO(L-3 / L-6 / L-7): H-4 落地之后，新建 MEMBER/DEVELOPER 不会再出现 DeptId=0；迁移/老数据
	// 里仍可能存在 "MemberType!=ADMIN 且 DeptId=0" 的幽灵账号。
	//   - 管理自己的路径：已经在 CheckManageAccess 顶部的 `caller.UserId == targetUserId` 短路
	//     里放行（L-7），这里不再重复兜底；
	//   - 管理其他用户的路径：幽灵账号必须由运维一次性 data fix 归入默认部门（审计给的示例 SQL：
	//       UPDATE sys_user SET deptId = <DEFAULT_NORMAL_DEPT_ID>
	//       WHERE deptId = 0 AND isSuperAdmin = 0 AND (userId NOT IN SysProductMember OR ...);
	//     并同步 UserDetailsLoader.CleanByUserIds 批量刷缓存），本层维持 fail-close 403，
	//     避免"没部门 → 默认放行"被用作绕过部门边界的旁路。若未来确有业务需要放宽，记得连带收紧
	//     checkPermLevel，不要把"部门校验绕过"默默扩大成"部门+级别都绕过"。
	//
	// TC-0993：两条分叉（DeptId==0 与 DeptPath==""）对运维都是"幽灵账号 → 需要数据迁移"
	// 的同一类信号，合一为单一文案 "您未归属任何部门，无权管理其他用户"，便于前端按固定
	// 关键字触发迁移工单。原先 DeptPath=="" 的 "部门信息异常" 虽更"精确"（deptId 存在但
	// dept 行丢失），但对业务侧而言处置动作完全相同，拆两条只是增加了运维分类负担。
	if caller.DeptId == 0 || caller.DeptPath == "" {
		return response.ErrForbidden("您未归属任何部门，无权管理其他用户")
	}

	target := prefetchedTarget
	if target == nil {
		t, err := svcCtx.SysUserModel.FindOne(ctx, targetUserId)
		if err != nil {
			return response.ErrNotFound("目标用户不存在")
		}
		target = t
	}
	if target.DeptId == 0 {
		return response.ErrForbidden("目标用户未归属部门，仅超管或产品管理员可管理")
	}

	targetDept, err := svcCtx.SysDeptModel.FindOne(ctx, target.DeptId)
	if err != nil {
		return response.ErrForbidden("无权操作")
	}

	if !strings.HasPrefix(targetDept.Path, caller.DeptPath) {
		return response.ErrForbidden("无权管理其他部门的用户")
	}
	return nil
}

func checkPermLevel(ctx context.Context, svcCtx *svc.ServiceContext, caller *loaders.UserDetails, targetUserId int64, productCode string, memberSink **memberModel.SysProductMember) error {
	if productCode == "" {
		return response.ErrBadRequest("缺少产品上下文，无法进行权限级别判定")
	}

	targetMember, err := svcCtx.SysProductMemberModel.FindOneByProductCodeUserId(ctx, productCode, targetUserId)
	if err != nil {
		return response.ErrForbidden("目标用户不是当前产品的成员，无法执行管理操作")
	}
	// 把 targetMember 写回调用方的 sink（若请求了），避免调用方再 FindOneByProductCodeUserId
	// 一次做 status 或 memberType 判定（审计 M-R10-5）。
	if memberSink != nil {
		*memberSink = targetMember
	}
	targetMemberType := targetMember.MemberType

	callerPri := memberTypePriority(caller.MemberType)
	targetPri := memberTypePriority(targetMemberType)

	if callerPri > targetPri {
		return response.ErrForbidden("无权管理权限级别高于您的用户")
	}
	if callerPri < targetPri {
		return nil
	}

	// memberType 相同，比较 permsLevel
	targetLevel, err := svcCtx.SysRoleModel.FindMinPermsLevelByUserIdAndProductCode(ctx, targetUserId, productCode)
	if err != nil {
		// 区分"无角色 → 等价最低等级"与"DB 抖动 → 未知"：只有 ErrNotFound 语义的场景才允许
		// 降级为 MaxInt64 放行管辖；其余错误一律视作不确定，fail-close 返回 500，避免 DB 抖动
		// 被同化成"目标无角色"造成越权放行（见审计 L-4）。
		if !errors.Is(err, sqlx.ErrNotFound) {
			return response.NewCodeError(500, "校验权限级别失败，请稍后重试")
		}
		targetLevel = math.MaxInt64
	}

	// 审计 H-2：caller.MinPermsLevel 来自 UserDetailsLoader 5 分钟 TTL 缓存；超管刚把 caller 降级
	// 时若 Clean 因 Redis 抖动失败，缓存里的旧级别会让降级 admin 继续管辖本应够不到的目标。
	// 与 GuardRoleLevelAssignable 对称：决策点一律走 DB 强一致复核（loadFreshMinPermsLevel），
	// 把 TOCTOU 窗口从 TTL 级压到单次查询级。caller 当前无产品角色时等同最低级，对同级管辖拒绝。
	callerLevel, callerNoRole, err := loadFreshMinPermsLevel(ctx, svcCtx, caller.UserId, productCode)
	if err != nil {
		return err
	}
	if callerNoRole || callerLevel >= targetLevel {
		return response.ErrForbidden("无权管理权限级别高于或等于您的用户")
	}
	return nil
}