## 所需插件 **超能力插件：** 必须对使用此技能的所有工作处于活动状态。在整个构建管道中使用——设计决策、代码生成、调试、质量检查以及它提供增强功能的任何任务。如果超级大国提供了更好的方法来完成某件事，那么优先选择它而不是默认方法。 # Mobile RBAC - Android 权限系统 ## 架构概述移动 RBAC 使用 **混合客户端+服务器** 方法： 1. **后端强制** \- PermissionMiddleware 检查的每个 API 调用（如果被拒绝则返回 403） 2. **客户端门 UI** \- UX 的缓存权限控制按钮/选项卡/屏幕可见性 3. **故障安全** \- 如果权限未知，则拒绝访问（从不授予） 4. **支持离线** \- 缓存权限无需网络即可工作 **后端环境：** 开发 (Windows/MySQL 8.4.7)、暂存 (Ubuntu/MySQL 8.x)、生产 (Debian/MySQL 8.x)。权限 API 在所有环境中的行为必须相同。使用 Gradle 构建风格来构建特定于环境的基本 URL。登录 → 获取权限 → 缓存在 EncryptedSharedPreferences → UI Gates ↕（刷新）↕（403 后备）后端始终强制←────────────────────────────────────┘ ## 快速参考主题 |参考文件|何时使用 ---|---|--- **架构与缓存** |这个文件 |权限流程、缓存策略、刷新触发器 **实施模式** | `references/implementation-patterns.md` | PermissionManager、PermissionGate 等的代码模板 **权限映射** | `references/permission-map.md` |什么权限控制什么功能 ## 核心原则 ### 1\.两层门控层|它控制什么 |隐藏/禁用时 ---|---|--- **模块门** |底部导航标签 |特许经营尚未订阅模块 **权限门** |屏幕、按钮、操作 |用户角色缺少权限 **规则：** 模块完全隐藏选项卡。权限禁用或隐藏单个操作。 ### 2\.权限解析（后端）后端使用5级优先级解析权限： 1. 用户拒绝（显式拒绝）→ 始终拒绝 2. 用户授予（显式授予）→ 始终授予 3. 特许经营覆盖→租户定制 4.角色权限→角色默认 5.超级管理员/所有者→所有权限移动客户端**永远不会在本地解析权限**。它通过“GET /user/permissions”从后端接收解析集并按原样使用它。 ### 3\.存储：EncryptedSharedPreferences 权限是一组约 20-50 个字符串代码。对于房间来说太轻了。 “user_permissions” → 设置 {“POS_CREATE_SALE”，“DASHBOARD_VIEW”，...} “user_modules”→ Set {“POS”，“库存”，...} “user_roles”→ Set {“收银员”，...} “user_type”→字符串“staff” “permissions_updated” → 长（纪元毫秒） ### 4\.刷新策略触发|行动 ---|--- 登录后 |立即获取应用程序启动（冷）|如果 > 15 分钟陈旧则获取 App简历（温馨）|如果 > 15 分钟陈旧则获取 403 来自后端 |立即获取，然后重试拉动刷新 |立即获取 ### 5\.线下行为 * 使用缓存的权限（最后一次正确） * 如果不存在缓存（全新安装），则拒绝所有 * 绝不允许比上次授予的同步次数更多的离线访问权限 ## 权限管理器（单例）中央权限存储，通过 Hilt 注入： @辛格尔顿类 PermissionManager @Inject 构造函数（ @ApplicationContext上下文：上下文）{ // 用于 Compose 反应性的 StateFlow val 权限流：StateFlow> val moduleFlow: StateFlow> // 检查 fun hasPermission（代码：字符串）：布尔值 fun hasAnyPermission(codes: Collection): 布尔值 fun hasAllPermissions(代码: Collection): 布尔值 fun hasModule（代码：字符串）：布尔值 fun isOwner(): 布尔值 fun isSuperAdmin(): 布尔值 fun isStale()：布尔值 // 存储 fun savePermissions(权限: Set) 有趣的 saveModules(模块: Set) fun clear() // 注销时调用 } **所有者和超级管理员绕过所有权限检查。** 首先检查“user_type”。 ## 用户界面模式 ### 模式 1：PermissionGate（显示/隐藏） @可组合有趣的权限门（权限管理器：权限管理器，权限：字符串， hide: Boolean = true, // true = 被拒绝时不渲染任何内容拒绝内容：@Composable (() -> 单位)？ = 空，内容：@Composable() -> 单位） **用于：** FAB、操作按钮、卡片、如果用户缺乏权限则应完全隐藏的部分。 **图标政策：** 仅使用自定义 PNG 图标；遵循“android-custom-icons”并更新“PROJECT_ICONS.md”。 **报告表策略：** 如果许可的屏幕包含超过 25 行的报告，请使用表格布局（请参阅“android-report-tables”）。 // 如果用户无法创建 PO，则隐藏“创建 PO”FAB PermissionGate(permissionManager, Permission.INVENTORY_PO_CREATE) { FloatingActionButton(onClick = onCreatePO) { Icon(painterResource(R.drawable.add), "创建PO") } } ### 模式 2：PermissionButton（通过消息禁用） @可组合有趣的权限按钮（权限管理器：权限管理器，权限：字符串， onClick: () -> 单位, 文本：字符串， DeniedMessage: String = "您没有权限" ） **用途：** 用户应该看到但无法执行的主要操作（批准、发送、接收、收费）。 //“批准”按钮 - 可见，但如果没有权限则禁用权限按钮( 权限管理器 = 权限管理器, 权限= Permission.INVENTORY_PO_APPROVE， onClick = { viewModel.approve() }, 文本=“批准”， DeniedMessage =“批准受到限制” ） ### 模式 3：ModuleGate（选项卡可见性） @可组合有趣的模块门（权限管理器：权限管理器，模块：字符串，内容：@Composable() -> 单位） **用于：** 底部导航选项卡、整个功能部分。 // 按模块访问过滤底部导航项 val items = buildList { add(BottomNavItem.Dashboard) // 始终可见 if (permissionManager.hasModule(Module.POS)) 添加(BottomNavItem.POS) if (permissionManager.hasModule(Module.INVENTORY)) add(BottomNavItem.Inventory) add(BottomNavItem.Settings) // 始终可见 } ### 模式 4：导航守卫 // 在 NavHost 中：保护敏感路由可组合（“创建采购订单”）{ if (permissionManager.hasPermission(Permission.INVENTORY_PO_CREATE)) { 创建采购订单屏幕（...） } 否则{ 权限被拒绝屏幕（权限=“创建采购订单”， onBack = { navController.popBackStack() } ） } } ### 模式 5：PermissionDeniedScreen 导航卫士的全屏拦截器： @可组合有趣的权限拒绝屏幕（ Permission: String, // 人类可读的名称 onBack: () -> 单位） // 显示：锁定图标+“访问受限”+说明+“返回”按钮 ## 用户体验指南场景 |用户体验模式|为什么 ---|---|--- 用户无法访问的选项卡 | **隐藏选项卡** |干净的导航，没有混乱用户无法使用的按钮 | **禁用+灰色+消息** |用户知道该功能存在卡片/分区用户看不到 | **隐藏** |布局简洁屏幕用户通过深层链接导航到 | **权限拒绝屏幕** |优美块 403 来自服务器（过时的缓存）|自动刷新权限，显示 toast |透明恢复使用缓存权限离线 |正常使用缓存的权限 |无缝离线离线且无缓存权限 |全部拒绝，显示离线横幅 |故障安全 ## 后端集成 ### API 端点：GET /用户/权限 { “成功”：真实， “数据”：{ “用户id”：10014， “特许经营id”：3， "user_type": "工作人员", "角色": [{"代码": "收银员", "姓名": "收银员"}], “权限”：[“DASHBOARD_VIEW”，“POS_CREATE_SALE”，...]， “模块”：[ {"code": "POS", "name": "销售点", "is_enabled": true}, {“code”：“库存”，“名称”：“库存”，“is_enabled”：false} ] } } ### 403 响应处理 { “成功”：假， "message": "您无权执行此操作", “错误”：{ “代码”：“PERMISSION_DENIED”， “required_permission”：“INVENTORY_PO_APPROVE” } } 客户回应： 1.从错误中解析`required_permission` 2.通过`/user/permissions`自动刷新权限 3. 显示友好消息：“您的权限已更新” ## CompositionLocal（方便） val LocalPermissionManager = staticCompositionLocalOf { 错误（“没有提供权限管理器”） } // 在主脚手架中： CompositionLocalProvider(LocalPermissionManager提供permissionManager) { // 所有子可组合项通过 LocalPermissionManager.current 访问 } ## 安全规则 1. **永远不要相信仅客户端检查** \- 后端始终验证权限 2. **加密存储** \- 使用 EncryptedSharedPreferences，切勿使用纯 SharedPrefs 3. **注销时清除** \- 注销流程中的 `permissionManager.clear()` 4. **特许经营隔离** \- 权限范围仅限于 JWT 中的特许经营_id 5. **日志中没有权限代码** \- 不记录完整的权限集 ## 与其他技能的整合 Dual-auth-rbac（后端）→ 定义权限表、解析逻辑、中间件 ↓ mobile-rbac（此技能）→ Android 特定权限缓存、UI 门、离线 ↓ jetpack-compose-ui → PermissionGate 可组合项遵循 Material 3 模式 ↓ android-development → Hilt DI、MVVM、Clean Architecture 集成 ## 反模式不要|而是做 ---|--- 从角色本地解析权限 |从后端获取解析集在普通 SharedPrefs 中存储权限 |使用加密共享首选项仅检查客户端的权限 |后端必须强制执行（深度防御）在没有缓存的情况下离线时授予访问权限 |拒绝全部（故障安全）硬编码角色名称（`if role == "ADMIN"`）|检查权限代码每个屏幕创建单独的权限检查 |使用可重用的“PermissionGate”可组合项隐藏按钮，无需解释 |显示禁用状态和消息 403 之后跳过权限刷新 |自动刷新并重新评估

移动RBAC

包含技能