feat(arch): implement soft delete for business-critical models

Adds SoftDeleteMixin (deleted_at + deleted_by_id) with automatic query
filtering via do_orm_execute event. Soft-deleted records are invisible
by default; bypass with execution_options={"include_deleted": True}.

Models: User, Merchant, Store, StoreUser, Customer, Order, Product,
LoyaltyProgram, LoyaltyCard.

Infrastructure:
- SoftDeleteMixin in models/database/base.py
- Auto query filter registered on SessionLocal and test sessions
- soft_delete(), restore(), soft_delete_cascade() in app/core/soft_delete.py
- Alembic migration adding columns to 9 tables
- Partial unique indexes on users.email/username, stores.store_code/subdomain

Service changes:
- admin_service: delete_user, delete_store → soft_delete/soft_delete_cascade
- merchant_service: delete_merchant → soft_delete_cascade (stores→children)
- store_team_service: remove_team_member → soft_delete (fixes is_active bug)
- product_service: delete_product → soft_delete
- program_service: delete_program → soft_delete_cascade

Admin API:
- include_deleted/only_deleted query params on admin list endpoints
- PUT restore endpoints for users, merchants, stores

Tests: 9 unit tests for soft-delete infrastructure.
Docs: docs/backend/soft-delete.md + follow-up proposals.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

app/modules/tenancy/services/admin_platform_service.py

@@ -443,6 +443,8 @@ class AdminPlatformService:
         include_super_admins: bool = True,
         is_active: bool | None = None,
         search: str | None = None,
+        include_deleted: bool = False,
+        only_deleted: bool = False,
     ) -> tuple[list[User], int]:
         """
         List all admin users with optional filtering.
@@ -454,6 +456,8 @@ class AdminPlatformService:
             include_super_admins: Whether to include super admins
             is_active: Filter by active status
             search: Search term for username/email/name
+            include_deleted: Include soft-deleted users
+            only_deleted: Show only soft-deleted users
 
         Returns:
             Tuple of (list of User objects, total count)
@@ -462,6 +466,12 @@ class AdminPlatformService:
             User.role.in_(["super_admin", "platform_admin"])
         )
 
+        # Soft-delete visibility
+        if include_deleted or only_deleted:
+            query = query.execution_options(include_deleted=True)
+        if only_deleted:
+            query = query.filter(User.deleted_at.isnot(None))
+
         if not include_super_admins:
             query = query.filter(User.role == "platform_admin")
 

app/modules/tenancy/services/admin_service.py

@@ -322,8 +322,10 @@ class AdminService:
                 owned_count=len(user.owned_merchants),
             )
 
+        from app.core.soft_delete import soft_delete
+
         username = user.username
-        db.delete(user)
+        soft_delete(db, user, deleted_by_id=current_admin_id)
 
         logger.info(f"Admin {current_admin_id} deleted user {username}")
         return f"User {username} deleted successfully"
@@ -477,12 +479,20 @@ class AdminService:
         is_active: bool | None = None,
         is_verified: bool | None = None,
         merchant_id: int | None = None,
+        include_deleted: bool = False,
+        only_deleted: bool = False,
     ) -> tuple[list[Store], int]:
         """Get paginated list of all stores with filtering."""
         try:
             # Eagerly load merchant relationship to avoid N+1 queries
             query = db.query(Store).options(joinedload(Store.merchant))
 
+            # Soft-delete visibility
+            if include_deleted or only_deleted:
+                query = query.execution_options(include_deleted=True)
+            if only_deleted:
+                query = query.filter(Store.deleted_at.isnot(None))
+
             # Filter by merchant
             if merchant_id is not None:
                 query = query.filter(Store.merchant_id == merchant_id)
@@ -506,6 +516,10 @@ class AdminService:
 
             # Get total count (without joinedload for performance)
             count_query = db.query(Store)
+            if include_deleted or only_deleted:
+                count_query = count_query.execution_options(include_deleted=True)
+            if only_deleted:
+                count_query = count_query.filter(Store.deleted_at.isnot(None))
             if merchant_id is not None:
                 count_query = count_query.filter(Store.merchant_id == merchant_id)
             if search:
@@ -596,17 +610,16 @@ class AdminService:
         store = self._get_store_by_id_or_raise(db, store_id)
 
         try:
+            from app.core.soft_delete import soft_delete_cascade
+
             store_code = store.store_code
 
-            # TODO: Delete associated data in correct order
-            # - Delete orders
-            # - Delete customers
-            # - Delete products
-            # - Delete team members
-            # - Delete roles
-            # - Delete import jobs
-
-            db.delete(store)
+            soft_delete_cascade(db, store, deleted_by_id=None, cascade_rels=[
+                ("products", []),
+                ("customers", []),
+                ("orders", []),
+                ("store_users", []),
+            ])
 
             logger.warning(f"Store {store_code} and all associated data deleted")
             return f"Store {store_code} successfully deleted"

app/modules/tenancy/services/merchant_service.py

@@ -148,6 +148,8 @@ class MerchantService:
         search: str | None = None,
         is_active: bool | None = None,
         is_verified: bool | None = None,
+        include_deleted: bool = False,
+        only_deleted: bool = False,
     ) -> tuple[list[Merchant], int]:
         """
         Get paginated list of merchants with optional filters.
@@ -159,15 +161,25 @@ class MerchantService:
             search: Search term for merchant name
             is_active: Filter by active status
             is_verified: Filter by verified status
+            include_deleted: Include soft-deleted merchants
+            only_deleted: Show only soft-deleted merchants (trash view)
 
         Returns:
             Tuple of (merchants list, total count)
         """
+        exec_opts = {}
+        if include_deleted or only_deleted:
+            exec_opts["include_deleted"] = True
+
         query = select(Merchant).options(
             joinedload(Merchant.stores),
             joinedload(Merchant.owner),
         )
 
+        # Soft-delete filter
+        if only_deleted:
+            query = query.where(Merchant.deleted_at.isnot(None))
+
         # Apply filters
         if search:
             query = query.where(Merchant.name.ilike(f"%{search}%"))
@@ -178,13 +190,13 @@ class MerchantService:
 
         # Get total count
         count_query = select(func.count()).select_from(query.subquery())
-        total = db.execute(count_query).scalar()
+        total = db.execute(count_query, execution_options=exec_opts).scalar()
 
         # Apply pagination and order
         query = query.order_by(Merchant.name).offset(skip).limit(limit)
 
         # Use unique() when using joinedload with collections to avoid duplicate rows
-        merchants = list(db.execute(query).scalars().unique().all())
+        merchants = list(db.execute(query, execution_options=exec_opts).scalars().unique().all())
 
         return merchants, total
 
@@ -228,11 +240,19 @@ class MerchantService:
         Raises:
             MerchantNotFoundException: If merchant not found
         """
+        from app.core.soft_delete import soft_delete_cascade
+
         merchant = self.get_merchant_by_id(db, merchant_id)
 
-        # Due to cascade="all, delete-orphan", associated stores will be deleted
-        db.delete(merchant)
-        db.flush()
+        MERCHANT_CASCADE = [
+            ("stores", [
+                ("products", []),
+                ("customers", []),
+                ("orders", []),
+                ("store_users", []),
+            ]),
+        ]
+        soft_delete_cascade(db, merchant, deleted_by_id=None, cascade_rels=MERCHANT_CASCADE)
         logger.info(f"Deleted merchant ID {merchant_id} and associated stores")
 
     def toggle_verification(