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/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})>"
+        )