# -*- coding: utf-8 -*- """⑤.7 配置台三级 RBAC 权限模型 —— issue #62 / PRD ⑤.7。 配置台面向**多角色协作**：实施工程师配模板，行业工程师调参数，运维/管理者 发布上线。直接对所有人开放写权限会带来误改与不可溯源风险。本模块用三级 RBAC（基于角色的访问控制）锁定"谁能对哪类配置做什么"，并把每次权限判定 的**理由**一并返回，对齐 PRD「可解释可溯源」。 三级角色（由低到高，后者继承前者全部权限）： - ``readonly`` （只读）：查看配置 / 预览 / 历史版本，不可写； - ``engineer`` （行业工程师）：只读权限 + 编辑/校验/导入配置（模型超参 / RAG / 布局 / 点位字典），但**不能发布与回滚**； - ``admin`` （管理员）：工程师权限 + 发布 / 回滚 / 推送内核 / 用户管理。 权限判定核心为 ``has_permission(user, resource, action)``，返回 ``PermissionDecision``（allow + reason），便于配置台前端把"为什么拒绝" 直接展示给操作者，而不是一个干瘪的 403。 零运行时依赖：仅用 dataclass / Enum / 标准库。 """ from __future__ import annotations from dataclasses import dataclass, field from enum import Enum from typing import Dict, List, Optional, Set # --------------------------------------------------------------------------- # 权限维度：资源 × 动作 # --------------------------------------------------------------------------- class Resource(str, Enum): """配置台可管控的资源（对齐 #63~#67 子模块）。""" POINT_DICT = "point_dict" # 点位字典（#63） MODEL_PARAM = "model_param" # 模型超参配置（#64） RAG_CONFIG = "rag_config" # RAG 知识库配置（#64） LAYOUT = "layout" # 驾驶舱布局配置（#64/#65） PREVIEW = "preview" # 预览（#65） RELEASE = "release" # 版本发布/回滚（#66） PUSH = "push" # 配置推送内核（#67） USER = "user" # 用户/角色管理 class Action(str, Enum): """对资源可执行的动作。""" VIEW = "view" # 查看 / 预览 / 列表 EDIT = "edit" # 新增 / 修改 / 删除 / 导入 / 校验 PUBLISH = "publish" # 发布版本 / 回滚 / 推送内核 MANAGE = "manage" # 用户与角色管理 class RoleKind(str, Enum): """三级角色枚举（值即配置资产中的角色标识）。""" READONLY = "readonly" ENGINEER = "engineer" ADMIN = "admin" # 各资源的「写」动作等价集合：EDIT 含新增/修改/删除/导入/校验。 # PUBLISH 含发布/回滚/推送。这样配置台前端只需关心粗粒度动作。 _WRITE_ACTIONS: Set[Action] = {Action.EDIT, Action.PUBLISH, Action.MANAGE} # --------------------------------------------------------------------------- # 权限模型 # --------------------------------------------------------------------------- @dataclass(frozen=True) class Permission: """一条权限授予（角色 → 资源 → 动作）。 ``meaning`` 解释该权限的业务含义，用于审计日志与配置台权限矩阵展示。 注意：权限**匹配**基于 ``resource:action``（资源×动作），与授予角色无关—— 这正是角色继承能生效的关键（admin 继承 engineer 的 edit，匹配键相同）。 ``role`` 仅作为审计元数据，记录"是谁授予的"。 """ role: RoleKind resource: Resource action: Action meaning: str = "" def key(self) -> str: """权限匹配键（资源:动作）—— 角色继承据此累计。""" return f"{self.resource.value}:{self.action.value}" def audit_key(self) -> str: """审计唯一键（角色/资源/动作三元组，含授予者）。""" return f"{self.role.value}:{self.resource.value}:{self.action.value}" @dataclass class Role: """一个角色：权限集合 + 继承的父角色。""" kind: RoleKind label: str # 中文展示名 permissions: List[Permission] = field(default_factory=list) inherits: Optional[RoleKind] = None # 继承的低一级角色 description: str = "" # 角色职责说明（可解释性） def permission_keys(self) -> Set[str]: """本角色直接授予的权限键集合。""" return {p.key() for p in self.permissions} @dataclass class User: """配置台用户。""" username: str role: RoleKind display_name: str = "" # 可选资源级收窄：即便角色允许，列表中的资源也会被额外限制为只读。 # 用于"只允许工程师改某几类配置"的细粒度场景。 restricted_to_readonly: List[Resource] = field(default_factory=list) @dataclass class PermissionDecision: """``has_permission`` 的判定结果（带理由，可解释）。""" allow: bool reason: str # 人类可读的判定理由（允许/拒绝原因） role: RoleKind resource: Resource action: Action source: str = "explicit" # explicit（本角色直接授予）/ inherited（继承自父角色） # --------------------------------------------------------------------------- # 角色注册表：三级权限矩阵（对齐 PRD ⑤.7「三级 RBAC」） # --------------------------------------------------------------------------- def _build_role_registry() -> Dict[RoleKind, Role]: """构建三级角色及其权限矩阵。 权限设计依据（PRD ⑤.7）： - readonly：可查看所有配置/预览/历史，但不能改、不能发； - engineer：在 readonly 基础上，可编辑/校验/导入四类业务配置， 但**发布/回滚/推送/用户管理仍归 admin**（避免未经评审上线）； - admin：在 engineer 基础上，可发布/回滚/推送 + 管理用户角色。 """ ro = Role( kind=RoleKind.READONLY, label="只读", description="实施/运维只读角色：查看配置、预览、历史版本，不可写。", permissions=[ Permission(RoleKind.READONLY, Resource.POINT_DICT, Action.VIEW, "查看点位字典与校验报告"), Permission(RoleKind.READONLY, Resource.MODEL_PARAM, Action.VIEW, "查看模型超参配置"), Permission(RoleKind.READONLY, Resource.RAG_CONFIG, Action.VIEW, "查看 RAG 知识库配置"), Permission(RoleKind.READONLY, Resource.LAYOUT, Action.VIEW, "查看驾驶舱布局配置"), Permission(RoleKind.READONLY, Resource.PREVIEW, Action.VIEW, "查看配置预览"), Permission(RoleKind.READONLY, Resource.RELEASE, Action.VIEW, "查看历史发布版本"), ], ) engineer = Role( kind=RoleKind.ENGINEER, label="行业工程师", inherits=RoleKind.READONLY, description="行业工程师：编辑/校验/导入业务配置，但不能发布与推送。", permissions=[ Permission(RoleKind.ENGINEER, Resource.POINT_DICT, Action.EDIT, "导入/编辑/校验点位字典 CSV"), Permission(RoleKind.ENGINEER, Resource.MODEL_PARAM, Action.EDIT, "调整模型超参配置"), Permission(RoleKind.ENGINEER, Resource.RAG_CONFIG, Action.EDIT, "编辑 RAG 知识库配置"), Permission(RoleKind.ENGINEER, Resource.LAYOUT, Action.EDIT, "编辑驾驶舱布局配置"), Permission(RoleKind.ENGINEER, Resource.PREVIEW, Action.VIEW, "预览配置效果（编辑后必看）"), ], ) admin = Role( kind=RoleKind.ADMIN, label="管理员", inherits=RoleKind.ENGINEER, description="管理员：在工程师基础上负责发布/回滚/推送与用户管理。", permissions=[ Permission(RoleKind.ADMIN, Resource.RELEASE, Action.PUBLISH, "发布新版本与回滚到历史版本"), Permission(RoleKind.ADMIN, Resource.PUSH, Action.PUBLISH, "把已发布配置推送给内核"), Permission(RoleKind.ADMIN, Resource.USER, Action.MANAGE, "管理用户与角色分配"), Permission(RoleKind.ADMIN, Resource.POINT_DICT, Action.PUBLISH, "确认点位字典上线（审批环节）"), Permission(RoleKind.ADMIN, Resource.MODEL_PARAM, Action.PUBLISH, "确认模型超参上线"), Permission(RoleKind.ADMIN, Resource.LAYOUT, Action.PUBLISH, "确认布局上线"), ], ) return {RoleKind.READONLY: ro, RoleKind.ENGINEER: engineer, RoleKind.ADMIN: admin} _ROLES: Dict[RoleKind, Role] = _build_role_registry() def get_role(kind: RoleKind) -> Role: """获取角色定义。""" return _ROLES[kind] def all_roles() -> List[Role]: """全部角色（按权限由低到高）。""" return [_ROLES[RoleKind.READONLY], _ROLES[RoleKind.ENGINEER], _ROLES[RoleKind.ADMIN]] def effective_permissions(kind: RoleKind) -> Set[str]: """角色有效权限键（含继承链）。 继承解析：admin 继承 engineer 继承 readonly，递归向上累计权限键。 """ role = _ROLES[kind] keys: Set[str] = set(role.permission_keys()) if role.inherits is not None: keys |= effective_permissions(role.inherits) return keys # --------------------------------------------------------------------------- # 判定 API # --------------------------------------------------------------------------- def has_permission( user: User, resource: Resource, action: Action, ) -> PermissionDecision: """判定用户对某资源执行某动作是否被允许（带理由）。 判定顺序： 1. 计算角色有效权限（含继承），命中即允许并标注来源（本角色/继承）； 2. 命中后若该资源在用户 ``restricted_to_readonly`` 列表且动作是写动作， 则降级拒绝（细粒度收窄）； 3. 未命中则拒绝，理由标注缺失的权限三元组。 Args: user: 配置台用户； resource: 目标资源； action: 目标动作。 Returns: PermissionDecision：allow + reason（可直接展示给操作者）。 """ target = f"{resource.value}:{action.value}" eff = effective_permissions(user.role) # 细粒度收窄：即便角色允许，特定资源也被限制为只读 if resource in user.restricted_to_readonly and action in _WRITE_ACTIONS: return PermissionDecision( allow=False, reason=(f"用户 '{user.username}' 对资源 '{resource.value}' 被收窄为只读，" f"禁止执行 '{action.value}' 动作"), role=user.role, resource=resource, action=action, source="restricted", ) if target in eff: # 判定来源：本角色直接授予 or 继承自父角色 own = get_role(user.role).permission_keys() source = "explicit" if target in own else "inherited" src_label = "本角色直接授予" if source == "explicit" else "继承自低级角色" return PermissionDecision( allow=True, reason=(f"用户 '{user.username}'（{get_role(user.role).label}）" f"允许对 '{resource.value}' 执行 '{action.value}'（{src_label}）"), role=user.role, resource=resource, action=action, source=source, ) return PermissionDecision( allow=False, reason=(f"用户 '{user.username}'（{get_role(user.role).label}）缺少权限 " f"{user.role.value}:{resource.value}:{action.value}；" f"该动作需更高角色或审批"), role=user.role, resource=resource, action=action, source="denied", ) def can_publish(user: User) -> bool: """便捷判定：用户是否具备发布（发布/回滚/推送）能力。""" return has_permission(user, Resource.RELEASE, Action.PUBLISH).allow def user_summary(user: User) -> Dict[str, object]: """用户权限概览（供配置台用户卡片/审计日志展示）。""" role = get_role(user.role) return { "username": user.username, "display_name": user.display_name or user.username, "role": user.role.value, "role_label": role.label, "description": role.description, "effective_permission_count": len(effective_permissions(user.role)), "restricted_to_readonly": [r.value for r in user.restricted_to_readonly], }