feat: implement super admin and platform admin roles

Add multi-platform admin authorization system with:
- AdminPlatform junction table for admin-platform assignments
- is_super_admin flag on User model for global admin access
- Platform selection flow for platform admins after login
- JWT token updates to include platform context
- New API endpoints for admin user management (super admin only)
- Auth dependencies for super admin and platform access checks

Includes comprehensive test coverage:
- Unit tests for AdminPlatform model and User admin methods
- Unit tests for AdminPlatformService operations
- Integration tests for admin users API endpoints

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

models/database/__init__.py

@@ -8,6 +8,7 @@ from .admin import (
     AdminSetting,
     PlatformAlert,
 )
+from .admin_platform import AdminPlatform
 from .architecture_scan import (
     ArchitectureScan,
     ArchitectureViolation,
@@ -83,6 +84,7 @@ __all__ = [
     # Admin-specific models
     "AdminAuditLog",
     "AdminNotification",
+    "AdminPlatform",
     "AdminSetting",
     "PlatformAlert",
     "AdminSession",

models/database/admin_platform.py

@@ -0,0 +1,161 @@
+# models/database/admin_platform.py
+"""
+AdminPlatform junction table for many-to-many relationship between Admin Users and Platforms.
+
+This enables platform-scoped admin access:
+- Super Admins: Have is_super_admin=True on User model, bypass this table
+- Platform Admins: Assigned to specific platforms via this junction table
+
+A platform admin CAN be assigned to multiple platforms (e.g., both OMS and Loyalty).
+"""
+
+from datetime import UTC, datetime
+
+from sqlalchemy import (
+    Boolean,
+    Column,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import relationship
+
+from app.core.database import Base
+from models.database.base import TimestampMixin
+
+
+class AdminPlatform(Base, TimestampMixin):
+    """
+    Junction table linking admin users to platforms they can manage.
+
+    Allows a platform admin to:
+    - Manage specific platforms only (not all)
+    - Be assigned to multiple platforms
+    - Have assignment tracked for audit purposes
+
+    Example:
+    - User "john@example.com" (admin) can manage OMS platform only
+    - User "jane@example.com" (admin) can manage both OMS and Loyalty platforms
+    """
+
+    __tablename__ = "admin_platforms"
+
+    id = Column(Integer, primary_key=True, index=True)
+
+    # ========================================================================
+    # Foreign Keys
+    # ========================================================================
+
+    user_id = Column(
+        Integer,
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+        comment="Reference to the admin user",
+    )
+
+    platform_id = Column(
+        Integer,
+        ForeignKey("platforms.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+        comment="Reference to the platform",
+    )
+
+    # ========================================================================
+    # Assignment Status
+    # ========================================================================
+
+    is_active = Column(
+        Boolean,
+        default=True,
+        nullable=False,
+        comment="Whether the admin assignment is active",
+    )
+
+    # ========================================================================
+    # Audit Fields
+    # ========================================================================
+
+    assigned_at = Column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(UTC),
+        nullable=False,
+        comment="When the admin was assigned to this platform",
+    )
+
+    assigned_by_user_id = Column(
+        Integer,
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+        comment="Super admin who made this assignment",
+    )
+
+    # ========================================================================
+    # Relationships
+    # ========================================================================
+
+    user = relationship(
+        "User",
+        foreign_keys=[user_id],
+        back_populates="admin_platforms",
+    )
+
+    platform = relationship(
+        "Platform",
+        back_populates="admin_platforms",
+    )
+
+    assigned_by = relationship(
+        "User",
+        foreign_keys=[assigned_by_user_id],
+    )
+
+    # ========================================================================
+    # Constraints & Indexes
+    # ========================================================================
+
+    __table_args__ = (
+        # Each admin can only be assigned to a platform once
+        UniqueConstraint(
+            "user_id",
+            "platform_id",
+            name="uq_admin_platform",
+        ),
+        # Performance indexes
+        Index(
+            "idx_admin_platform_active",
+            "user_id",
+            "platform_id",
+            "is_active",
+        ),
+        Index(
+            "idx_admin_platform_user_active",
+            "user_id",
+            "is_active",
+        ),
+    )
+
+    # ========================================================================
+    # Properties
+    # ========================================================================
+
+    @property
+    def platform_code(self) -> str | None:
+        """Get the platform code for this assignment."""
+        return self.platform.code if self.platform else None
+
+    @property
+    def platform_name(self) -> str | None:
+        """Get the platform name for this assignment."""
+        return self.platform.name if self.platform else None
+
+    def __repr__(self) -> str:
+        return (
+            f"<AdminPlatform("
+            f"user_id={self.user_id}, "
+            f"platform_id={self.platform_id}, "
+            f"is_active={self.is_active})>"
+        )

models/database/platform.py

@@ -192,6 +192,13 @@ class Platform(Base, TimestampMixin):
         foreign_keys="SubscriptionTier.platform_id",
     )
 
+    # Admin assignments for this platform
+    admin_platforms = relationship(
+        "AdminPlatform",
+        back_populates="platform",
+        cascade="all, delete-orphan",
+    )
+
     # ========================================================================
     # Indexes
     # ========================================================================

models/database/user.py

@@ -46,6 +46,11 @@ class User(Base, TimestampMixin):
     is_email_verified = Column(Boolean, default=False, nullable=False)
     last_login = Column(DateTime, nullable=True)
 
+    # Super admin flag (only meaningful when role='admin')
+    # Super admins have access to ALL platforms and global settings
+    # Platform admins (is_super_admin=False) are assigned to specific platforms
+    is_super_admin = Column(Boolean, default=False, nullable=False)
+
     # Language preference (NULL = use context default: vendor dashboard_language or system default)
     # Supported: en, fr, de, lb
     preferred_language = Column(String(5), nullable=True)
@@ -59,6 +64,15 @@ class User(Base, TimestampMixin):
         "VendorUser", foreign_keys="[VendorUser.user_id]", back_populates="user"
     )
 
+    # Admin-platform assignments (for platform admins only)
+    # Super admins don't need assignments - they have access to all platforms
+    admin_platforms = relationship(
+        "AdminPlatform",
+        foreign_keys="AdminPlatform.user_id",
+        back_populates="user",
+        cascade="all, delete-orphan",
+    )
+
     def __repr__(self):
         """String representation of the User object."""
         return f"<User(id={self.id}, username='{self.username}', email='{self.email}', role='{self.role}')>"
@@ -128,3 +142,49 @@ class User(Base, TimestampMixin):
                     return True
 
         return False
+
+    # =========================================================================
+    # Admin Platform Access Methods
+    # =========================================================================
+
+    @property
+    def is_super_admin_user(self) -> bool:
+        """Check if user is a super admin (can access all platforms)."""
+        return self.role == UserRole.ADMIN.value and self.is_super_admin
+
+    @property
+    def is_platform_admin(self) -> bool:
+        """Check if user is a platform admin (access to assigned platforms only)."""
+        return self.role == UserRole.ADMIN.value and not self.is_super_admin
+
+    def can_access_platform(self, platform_id: int) -> bool:
+        """
+        Check if admin can access a specific platform.
+
+        - Super admins can access all platforms
+        - Platform admins can only access assigned platforms
+        - Non-admins return False
+        """
+        if not self.is_admin:
+            return False
+        if self.is_super_admin:
+            return True
+        return any(
+            ap.platform_id == platform_id and ap.is_active
+            for ap in self.admin_platforms
+        )
+
+    def get_accessible_platform_ids(self) -> list[int] | None:
+        """
+        Get list of platform IDs this admin can access.
+
+        Returns:
+            - None for super admins (means ALL platforms)
+            - List of platform IDs for platform admins
+            - Empty list for non-admins
+        """
+        if not self.is_admin:
+            return []
+        if self.is_super_admin:
+            return None  # None means ALL platforms
+        return [ap.platform_id for ap in self.admin_platforms if ap.is_active]