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/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]