feat: RBAC Phase 1 — consolidate user roles into 4-value enum

Consolidate User.role (2-value: admin/store) + User.is_super_admin (boolean)
into a single 4-value UserRole enum: super_admin, platform_admin,
merchant_owner, store_member. Drop stale StoreUser.user_type column.
Fix role="user" bug in merchant creation.

Key changes:
- Expand UserRole enum from 2 to 4 values with computed properties
  (is_admin, is_super_admin, is_platform_admin, is_merchant_owner, is_store_user)
- Add Alembic migration (tenancy_003) for data migration + column drops
- Remove is_super_admin from JWT token payload
- Update all auth dependencies, services, routes, templates, JS, and tests
- Update all RBAC documentation

66 files changed, 1219 unit tests passing.

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

scripts/seed/seed_demo.py

@@ -217,7 +217,6 @@ DEMO_TEAM_MEMBERS = [
         "first_name": "Alice",
         "last_name": "Manager",
         "store_codes": ["WIZATECH", "WIZAGADGETS"],  # manages two stores
-        "user_type": "member",
     },
     {
         "merchant_index": 0,
@@ -226,7 +225,6 @@ DEMO_TEAM_MEMBERS = [
         "first_name": "Charlie",
         "last_name": "Staff",
         "store_codes": ["WIZAHOME"],
-        "user_type": "member",
     },
     # Fashion Group team
     {
@@ -236,7 +234,6 @@ DEMO_TEAM_MEMBERS = [
         "first_name": "Diana",
         "last_name": "Stylist",
         "store_codes": ["FASHIONHUB", "FASHIONOUTLET"],
-        "user_type": "member",
     },
     {
         "merchant_index": 1,
@@ -245,7 +242,6 @@ DEMO_TEAM_MEMBERS = [
         "first_name": "Eric",
         "last_name": "Sales",
         "store_codes": ["FASHIONOUTLET"],
-        "user_type": "member",
     },
     # BookWorld team
     {
@@ -255,7 +251,6 @@ DEMO_TEAM_MEMBERS = [
         "first_name": "Fiona",
         "last_name": "Editor",
         "store_codes": ["BOOKSTORE", "BOOKDIGITAL"],
-        "user_type": "member",
     },
 ]
 
@@ -505,7 +500,9 @@ def check_environment():
 def check_admin_exists(db: Session) -> bool:
     """Check if admin user exists."""
 
-    admin = db.execute(select(User).where(User.role == "admin").limit(1)).scalar_one_or_none()
+    admin = db.execute(
+        select(User).where(User.role.in_(["super_admin", "platform_admin"])).limit(1)
+    ).scalar_one_or_none()
 
     if not admin:
         print_error("No admin user found!")
@@ -574,7 +571,7 @@ def reset_all_data(db: Session):
             db.execute(delete(table))
 
     # Delete non-admin users
-    db.execute(delete(User).where(User.role != "admin"))
+    db.execute(delete(User).where(User.role.not_in(["super_admin", "platform_admin"])))
 
     db.commit()
     print_success("All data deleted (admin preserved)")
@@ -618,7 +615,7 @@ def create_demo_merchants(db: Session, auth_manager: AuthManager) -> list[Mercha
                 hashed_password=auth_manager.hash_password(  # noqa: SEC001
                     merchant_data["owner_password"]
                 ),
-                role="store",
+                role="merchant_owner",
                 first_name=merchant_data["owner_first_name"],
                 last_name=merchant_data["owner_last_name"],
                 is_active=True,
@@ -706,15 +703,7 @@ def create_demo_stores(
         db.add(store)  # noqa: PERF006
         db.flush()
 
-        # Link merchant owner to store as owner
-        store_user_link = StoreUser(
-            store_id=store.id,
-            user_id=merchant.owner_user_id,
-            user_type="owner",
-            is_active=True,
-            created_at=datetime.now(UTC),
-        )
-        db.add(store_user_link)  # noqa: PERF006
+        # Owner relationship is via Merchant.owner_user_id — no StoreUser needed
 
         # Create store theme
         theme_colors = THEME_PRESETS.get(
@@ -781,7 +770,7 @@ def create_demo_team_members(
                 username=member_data["email"].split("@")[0],
                 email=member_data["email"],
                 hashed_password=auth_manager.hash_password(member_data["password"]),  # noqa: SEC001
-                role="store",
+                role="store_member",
                 first_name=member_data["first_name"],
                 last_name=member_data["last_name"],
                 is_active=True,
@@ -820,12 +809,11 @@ def create_demo_team_members(
             store_user = StoreUser(
                 store_id=store.id,
                 user_id=user.id,
-                user_type=member_data["user_type"],
                 is_active=True,
                 created_at=datetime.now(UTC),
             )
             db.add(store_user)  # noqa: PERF006
-            print_success(f"  Assigned {user.first_name} to {store.name} as {member_data['user_type']}")
+            print_success(f"  Assigned {user.first_name} to {store.name} as team member")
 
     db.flush()
     return team_users
@@ -1110,7 +1098,7 @@ def print_summary(db: Session):
     merchant_count = db.query(Merchant).count()
     store_count = db.query(Store).count()
     user_count = db.query(User).count()
-    team_member_count = db.query(StoreUser).filter(StoreUser.user_type == "member").count()
+    team_member_count = db.query(StoreUser).count()
     customer_count = db.query(Customer).count()
     product_count = db.query(Product).count()
     platform_pages = db.query(ContentPage).filter(ContentPage.store_id is None).count()
@@ -1172,7 +1160,8 @@ def print_summary(db: Session):
             for su in store_users:
                 user = db.query(User).filter(User.id == su.user_id).first()
                 if user:
-                    print(f"    Team:      {user.email} ({su.user_type})")
+                    role_name = su.role.name if su.role else "owner"
+                    print(f"    Team:      {user.email} ({role_name})")
 
     print("\n🔐 Demo Merchant Owner Credentials:")
     print("─" * 70)