第3章 角色权限未生效：现象与影响范围、角色分配表核对、缓存同步诊断、角色继承关系修复、预防方案

本章围绕“角色权限未生效”这一高频故障，严格按照故障排查六阶段（现象识别→数据采集→原因定位→修复动作→复测→预防）展开。你将掌握从用户报障到彻底修复的完整排查链路，学会区分“显式分配失效”与“继承权限断裂”两种根因，并建立长效预防机制。

3.1 现象识别

表现特征：用户登录B2B系统后，点击特定功能模块（如“创建采购订单”、“查看财务报表”），页面直接返回 403 Forbidden 或前端弹窗提示“暂无权限，请联系管理员”。

影响范围评估：在排查前，需快速界定故障边界，避免无效排查。

3.2 数据采集：角色分配表核对

在确认影响范围后，第一步是采集权限中心的数据，核对 用户-角色分配表。核心目标是判断“系统里有没有这条分配记录”。

排查步骤：

1. 获取报障用户的 user_id 和 tenant_id。
2. 查询角色分配表，确认是否存在显式分配记录。
3. 查询组织-角色关联表，确认是否存在隐式继承关系。

-- 步骤1：检查直接分配（user_role_assignment）
SELECT role_id, role_name, is_enabled, assigned_at
FROM permission.user_role_assignment
WHERE user_id = 'user_abc_123'
  AND tenant_id = 'tnt_b2b_corp'
  AND is_enabled = TRUE;

-- 步骤2：检查通过组织的继承分配（user_org + org_role_assignment）
SELECT uo.org_id, oa.role_id, oa.is_enabled
FROM permission.user_org uo
JOIN permission.org_role_assignment oa ON uo.org_id = oa.org_id
WHERE uo.user_id = 'user_abc_123';

3.3 原因定位：缓存同步诊断

当数据库中存在正确的分配记录，但用户依然无权限时，首先怀疑 缓存同步延迟。权限系统通常使用 Redis 缓存用户的权限集合，以提升鉴权性能。如果缓存未刷新，老旧数据会导致鉴权失败。

诊断步骤：

• 连接 Redis 缓存实例，查找对应用户的权限缓存键。
• 对比缓存中的角色列表与数据库中的角色列表是否一致。
• 检查缓存 TTL（过期时间），判断是否由于 TTL 过长导致未及时更新。

# 连接 Redis
redis-cli -h prod-redis.perm.cache -p 6379 -a [password]

# 获取用户权限缓存（Key格式可能为 perm:{tenant_id}:{user_id}）
GET perm:tnt_b2b_corp:user_abc_123

# 检查缓存剩余存活时间
TTL perm:tnt_b2b_corp:user_abc_123

# 手动清除用户缓存（修复动作）
DEL perm:tnt_b2b_corp:user_abc_123

3.4 原因定位与修复：角色继承关系修复

如果数据库查不到分配记录，或者用户是通过组织树继承获得的权限，则必须检查 角色继承链 是否完整。B2B 系统中，常见场景是：用户被移出了组织，或者父组织的角色被禁用，导致子组织用户权限失效。

排查动作：

1. 向上递归查询用户所在组织的父组织。
2. 检查组级联关系是否断裂（如中间节点被软删除）。
3. 确认父级组织是否已分配该角色且状态为启用。

-- 递归查询组织父级（使用MySQL递归CTE）
WITH RECURSIVE org_tree AS (
    SELECT org_id, parent_org_id, org_name, 1 AS level
    FROM permission.org_hierarchy
    WHERE org_id = (SELECT org_id FROM permission.user_org WHERE user_id = 'user_abc_123')
    UNION ALL
    SELECT p.org_id, p.parent_org_id, p.org_name, t.level + 1
    FROM permission.org_hierarchy p
    JOIN org_tree t ON p.org_id = t.parent_org_id
)
SELECT * FROM org_tree;

修复动作：

• 继承断裂：重建用户-组织关联 INSERT INTO user_org (user_id, org_id) VALUES ('user_abc_123', 'org_fix_id');
• 父角色禁用：启用父角色 UPDATE role SET is_enabled = TRUE WHERE role_id = 'role_parent';
• 数据不一致：调用权限中心的“同步继承关系”接口或脚本。

3.5 复测验证

修复完成后，必须进行严格复测，确保问题闭环。复测应覆盖前后端两个维度。

1. 缓存验证：确认 Redis 中用户的缓存键已被清除或更新为最新数据。
2. 接口验证：使用用户的 Token 调用之前返回 403 的 API。
3. 前端验证：让用户退出登录，重新登录后访问对应功能模块。

# 接口级复测命令
curl -X POST https://api.b2b.com/v1/finance/reports \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"report_type": "monthly", "period": "2025-03"}' \
  -w "\nHTTP Status: %{http_code}\n"

预期结果：返回 HTTP Status: 200，并正确返回业务数据。如果返回 403 则说明修复未生效，需要回到步骤 3.3 重新诊断。

3.6 预防方案与预防清单

为避免同样问题反复出现，需建立以下预防机制：