# /opt/docker/dev/service_finder/backend/app/core/capabilities.py """ 🎯 SYSTEM CAPABILITIES MATRIX (RBAC Phase 1) Fine-grained, capability-driven permission matrix for system-level roles. Each role maps to a set of boolean capabilities that define what the role can do within the platform. Architecture: - SUPERADMIN: Full system access (rank 100) - ADMIN: Full admin panel access (rank 90) - MODERATOR: Content moderation capabilities (rank 75) - SALES_REP: Sales & discount management (rank 30) - SERVICE_MGR: Service provider & taxonomy management (rank 40) - USER: Basic platform user (rank 10) """ from typing import Dict, Set # ────────────────────────────────────────────── # CAPABILITY KEYS (for type-safe references) # ────────────────────────────────────────────── class Capability: """Central registry of all capability keys.""" # ── Admin & System ── CAN_MANAGE_USERS = "can_manage_users" CAN_MANAGE_ROLES = "can_manage_roles" CAN_VIEW_SYSTEM_LOGS = "can_view_system_logs" CAN_MANAGE_SYSTEM_CONFIG = "can_manage_system_config" CAN_MANAGE_TRANSLATIONS = "can_manage_translations" # ── Moderation ── CAN_MODERATE_CONTENT = "can_moderate_content" CAN_VIEW_REPORTS = "can_view_reports" CAN_SUSPEND_USERS = "can_suspend_users" CAN_APPROVE_PROVIDER = "can_approve_provider" # ── Sales & Marketing ── CAN_VIEW_ORG_STATS = "can_view_org_stats" CAN_MANAGE_DISCOUNTS = "can_manage_discounts" CAN_MANAGE_PROMOTIONS = "can_manage_promotions" CAN_VIEW_SALES_PIPELINE = "can_view_sales_pipeline" # ── Service Management ── CAN_EDIT_MASTER_TAXONOMY = "can_edit_master_taxonomy" CAN_MANAGE_SERVICE_CATEGORIES = "can_manage_service_categories" CAN_VERIFY_SERVICE_PROVIDERS = "can_verify_service_providers" CAN_MANAGE_EXPERTISE_TAGS = "can_manage_expertise_tags" # ── Vehicle & Catalog ── CAN_MANAGE_VEHICLE_CATALOG = "can_manage_vehicle_catalog" CAN_APPROVE_VEHICLE_DEFINITIONS = "can_approve_vehicle_definitions" CAN_VIEW_TECHNICAL_SPECS = "can_view_technical_specs" # ── Finance ── CAN_VIEW_FINANCIAL_REPORTS = "can_view_financial_reports" CAN_MANAGE_BILLING = "can_manage_billing" CAN_ISSUE_REFUNDS = "can_issue_refunds" CAN_MANAGE_SUBSCRIPTIONS = "can_manage_subscriptions" # ── Basic User ── CAN_MANAGE_OWN_PROFILE = "can_manage_own_profile" CAN_MANAGE_OWN_VEHICLES = "can_manage_own_vehicles" CAN_CREATE_SERVICE_REQUEST = "can_create_service_request" CAN_VIEW_PUBLIC_CATALOG = "can_view_public_catalog" # ────────────────────────────────────────────── # SYSTEM CAPABILITIES MATRIX # ────────────────────────────────────────────── SYSTEM_CAPABILITIES_MATRIX: Dict[str, Dict[str, bool]] = { # ── SUPERADMIN: Full system access ── "SUPERADMIN": { # Admin & System Capability.CAN_MANAGE_USERS: True, Capability.CAN_MANAGE_ROLES: True, Capability.CAN_VIEW_SYSTEM_LOGS: True, Capability.CAN_MANAGE_SYSTEM_CONFIG: True, Capability.CAN_MANAGE_TRANSLATIONS: True, # Moderation Capability.CAN_MODERATE_CONTENT: True, Capability.CAN_VIEW_REPORTS: True, Capability.CAN_SUSPEND_USERS: True, Capability.CAN_APPROVE_PROVIDER: True, # Sales Capability.CAN_VIEW_ORG_STATS: True, Capability.CAN_MANAGE_DISCOUNTS: True, Capability.CAN_MANAGE_PROMOTIONS: True, Capability.CAN_VIEW_SALES_PIPELINE: True, # Service Management Capability.CAN_EDIT_MASTER_TAXONOMY: True, Capability.CAN_MANAGE_SERVICE_CATEGORIES: True, Capability.CAN_VERIFY_SERVICE_PROVIDERS: True, Capability.CAN_MANAGE_EXPERTISE_TAGS: True, # Vehicle & Catalog Capability.CAN_MANAGE_VEHICLE_CATALOG: True, Capability.CAN_APPROVE_VEHICLE_DEFINITIONS: True, Capability.CAN_VIEW_TECHNICAL_SPECS: True, # Finance Capability.CAN_VIEW_FINANCIAL_REPORTS: True, Capability.CAN_MANAGE_BILLING: True, Capability.CAN_ISSUE_REFUNDS: True, Capability.CAN_MANAGE_SUBSCRIPTIONS: True, # Basic User Capability.CAN_MANAGE_OWN_PROFILE: True, Capability.CAN_MANAGE_OWN_VEHICLES: True, Capability.CAN_CREATE_SERVICE_REQUEST: True, Capability.CAN_VIEW_PUBLIC_CATALOG: True, }, # ── ADMIN: Full admin panel access ── "ADMIN": { Capability.CAN_MANAGE_USERS: True, Capability.CAN_MANAGE_ROLES: False, Capability.CAN_VIEW_SYSTEM_LOGS: True, Capability.CAN_MANAGE_SYSTEM_CONFIG: False, Capability.CAN_MANAGE_TRANSLATIONS: True, Capability.CAN_MODERATE_CONTENT: True, Capability.CAN_VIEW_REPORTS: True, Capability.CAN_SUSPEND_USERS: True, Capability.CAN_APPROVE_PROVIDER: True, Capability.CAN_VIEW_ORG_STATS: True, Capability.CAN_MANAGE_DISCOUNTS: True, Capability.CAN_MANAGE_PROMOTIONS: True, Capability.CAN_VIEW_SALES_PIPELINE: True, Capability.CAN_EDIT_MASTER_TAXONOMY: True, Capability.CAN_MANAGE_SERVICE_CATEGORIES: True, Capability.CAN_VERIFY_SERVICE_PROVIDERS: True, Capability.CAN_MANAGE_EXPERTISE_TAGS: True, Capability.CAN_MANAGE_VEHICLE_CATALOG: True, Capability.CAN_APPROVE_VEHICLE_DEFINITIONS: True, Capability.CAN_VIEW_TECHNICAL_SPECS: True, Capability.CAN_VIEW_FINANCIAL_REPORTS: True, Capability.CAN_MANAGE_BILLING: False, Capability.CAN_ISSUE_REFUNDS: False, Capability.CAN_MANAGE_SUBSCRIPTIONS: True, Capability.CAN_MANAGE_OWN_PROFILE: True, Capability.CAN_MANAGE_OWN_VEHICLES: True, Capability.CAN_CREATE_SERVICE_REQUEST: True, Capability.CAN_VIEW_PUBLIC_CATALOG: True, }, # ── MODERATOR: Content moderation ── "MODERATOR": { Capability.CAN_MANAGE_USERS: False, Capability.CAN_MANAGE_ROLES: False, Capability.CAN_VIEW_SYSTEM_LOGS: False, Capability.CAN_MANAGE_SYSTEM_CONFIG: False, Capability.CAN_MANAGE_TRANSLATIONS: True, Capability.CAN_MODERATE_CONTENT: True, Capability.CAN_VIEW_REPORTS: True, Capability.CAN_SUSPEND_USERS: False, Capability.CAN_APPROVE_PROVIDER: True, Capability.CAN_VIEW_ORG_STATS: False, Capability.CAN_MANAGE_DISCOUNTS: False, Capability.CAN_MANAGE_PROMOTIONS: False, Capability.CAN_VIEW_SALES_PIPELINE: False, Capability.CAN_EDIT_MASTER_TAXONOMY: False, Capability.CAN_MANAGE_SERVICE_CATEGORIES: True, Capability.CAN_VERIFY_SERVICE_PROVIDERS: True, Capability.CAN_MANAGE_EXPERTISE_TAGS: True, Capability.CAN_MANAGE_VEHICLE_CATALOG: False, Capability.CAN_APPROVE_VEHICLE_DEFINITIONS: False, Capability.CAN_VIEW_TECHNICAL_SPECS: True, Capability.CAN_VIEW_FINANCIAL_REPORTS: False, Capability.CAN_MANAGE_BILLING: False, Capability.CAN_ISSUE_REFUNDS: False, Capability.CAN_MANAGE_OWN_PROFILE: True, Capability.CAN_MANAGE_OWN_VEHICLES: True, Capability.CAN_CREATE_SERVICE_REQUEST: True, Capability.CAN_VIEW_PUBLIC_CATALOG: True, }, # ── SALES_REP: Sales & discount management ── "SALES_REP": { Capability.CAN_MANAGE_USERS: False, Capability.CAN_MANAGE_ROLES: False, Capability.CAN_VIEW_SYSTEM_LOGS: False, Capability.CAN_MANAGE_SYSTEM_CONFIG: False, Capability.CAN_MANAGE_TRANSLATIONS: False, Capability.CAN_MODERATE_CONTENT: False, Capability.CAN_VIEW_REPORTS: False, Capability.CAN_SUSPEND_USERS: False, Capability.CAN_APPROVE_PROVIDER: False, Capability.CAN_VIEW_ORG_STATS: True, Capability.CAN_MANAGE_DISCOUNTS: True, Capability.CAN_MANAGE_PROMOTIONS: True, Capability.CAN_VIEW_SALES_PIPELINE: True, Capability.CAN_EDIT_MASTER_TAXONOMY: False, Capability.CAN_MANAGE_SERVICE_CATEGORIES: False, Capability.CAN_VERIFY_SERVICE_PROVIDERS: False, Capability.CAN_MANAGE_EXPERTISE_TAGS: False, Capability.CAN_MANAGE_VEHICLE_CATALOG: False, Capability.CAN_APPROVE_VEHICLE_DEFINITIONS: False, Capability.CAN_VIEW_TECHNICAL_SPECS: False, Capability.CAN_VIEW_FINANCIAL_REPORTS: False, Capability.CAN_MANAGE_BILLING: False, Capability.CAN_ISSUE_REFUNDS: False, Capability.CAN_MANAGE_OWN_PROFILE: True, Capability.CAN_MANAGE_OWN_VEHICLES: True, Capability.CAN_CREATE_SERVICE_REQUEST: True, Capability.CAN_VIEW_PUBLIC_CATALOG: True, }, # ── SERVICE_MGR: Service provider & taxonomy management ── "SERVICE_MGR": { Capability.CAN_MANAGE_USERS: False, Capability.CAN_MANAGE_ROLES: False, Capability.CAN_VIEW_SYSTEM_LOGS: False, Capability.CAN_MANAGE_SYSTEM_CONFIG: False, Capability.CAN_MANAGE_TRANSLATIONS: False, Capability.CAN_MODERATE_CONTENT: False, Capability.CAN_VIEW_REPORTS: False, Capability.CAN_SUSPEND_USERS: False, Capability.CAN_APPROVE_PROVIDER: True, Capability.CAN_VIEW_ORG_STATS: False, Capability.CAN_MANAGE_DISCOUNTS: False, Capability.CAN_MANAGE_PROMOTIONS: False, Capability.CAN_VIEW_SALES_PIPELINE: False, Capability.CAN_EDIT_MASTER_TAXONOMY: True, Capability.CAN_MANAGE_SERVICE_CATEGORIES: True, Capability.CAN_VERIFY_SERVICE_PROVIDERS: True, Capability.CAN_MANAGE_EXPERTISE_TAGS: True, Capability.CAN_MANAGE_VEHICLE_CATALOG: False, Capability.CAN_APPROVE_VEHICLE_DEFINITIONS: False, Capability.CAN_VIEW_TECHNICAL_SPECS: True, Capability.CAN_VIEW_FINANCIAL_REPORTS: False, Capability.CAN_MANAGE_BILLING: False, Capability.CAN_ISSUE_REFUNDS: False, Capability.CAN_MANAGE_OWN_PROFILE: True, Capability.CAN_MANAGE_OWN_VEHICLES: True, Capability.CAN_CREATE_SERVICE_REQUEST: True, Capability.CAN_VIEW_PUBLIC_CATALOG: True, }, # ── USER: Basic platform user ── "USER": { Capability.CAN_MANAGE_USERS: False, Capability.CAN_MANAGE_ROLES: False, Capability.CAN_VIEW_SYSTEM_LOGS: False, Capability.CAN_MANAGE_SYSTEM_CONFIG: False, Capability.CAN_MANAGE_TRANSLATIONS: False, Capability.CAN_MODERATE_CONTENT: False, Capability.CAN_VIEW_REPORTS: False, Capability.CAN_SUSPEND_USERS: False, Capability.CAN_APPROVE_PROVIDER: False, Capability.CAN_VIEW_ORG_STATS: False, Capability.CAN_MANAGE_DISCOUNTS: False, Capability.CAN_MANAGE_PROMOTIONS: False, Capability.CAN_VIEW_SALES_PIPELINE: False, Capability.CAN_EDIT_MASTER_TAXONOMY: False, Capability.CAN_MANAGE_SERVICE_CATEGORIES: False, Capability.CAN_VERIFY_SERVICE_PROVIDERS: False, Capability.CAN_MANAGE_EXPERTISE_TAGS: False, Capability.CAN_MANAGE_VEHICLE_CATALOG: False, Capability.CAN_APPROVE_VEHICLE_DEFINITIONS: False, Capability.CAN_VIEW_TECHNICAL_SPECS: False, Capability.CAN_VIEW_FINANCIAL_REPORTS: False, Capability.CAN_MANAGE_BILLING: False, Capability.CAN_ISSUE_REFUNDS: False, Capability.CAN_MANAGE_OWN_PROFILE: True, Capability.CAN_MANAGE_OWN_VEHICLES: True, Capability.CAN_CREATE_SERVICE_REQUEST: True, Capability.CAN_VIEW_PUBLIC_CATALOG: True, }, } def get_capabilities_for_role(role_key: str) -> Dict[str, bool]: """Return the capability dict for a given role key. Args: role_key: The role key (e.g. 'SUPERADMIN', 'ADMIN', 'USER') Returns: Dict of capability -> bool, or empty dict if role not found. """ return SYSTEM_CAPABILITIES_MATRIX.get(role_key.upper(), {}) def role_has_capability(role_key: str, capability: str) -> bool: """Check if a role has a specific capability. Args: role_key: The role key (e.g. 'SUPERADMIN', 'ADMIN') capability: The capability key (e.g. 'can_manage_users') Returns: True if the role has the capability, False otherwise. """ caps = get_capabilities_for_role(role_key) return caps.get(capability, False)