fix(loyalty): cross-store enrollment, card scoping, i18n flicker

Fix duplicate card creation when the same email enrolls at different
stores under the same merchant, and implement cross-location-aware
enrollment behavior.

- Cross-location enabled (default): one card per customer per merchant.
  Re-enrolling at another store returns the existing card with a
  "works at all our locations" message + store list.
- Cross-location disabled: one card per customer per store. Enrolling
  at a different store creates a separate card for that store.

Changes:
- Migration loyalty_004: replace (merchant_id, customer_id) unique
  index with (enrolled_at_store_id, customer_id). Per-merchant
  uniqueness enforced at application layer when cross-location enabled.
- card_service.resolve_customer_id: cross-store email lookup via
  merchant_id param to find existing cardholders at other stores.
- card_service.enroll_customer: branch duplicate check on
  allow_cross_location_redemption setting.
- card_service.search_card_for_store: cross-store email search when
  cross-location enabled so staff at store2 can find cards from store1.
- card_service.get_card_by_customer_and_store: new service method.
- storefront enrollment: catch LoyaltyCardAlreadyExistsException,
  return existing card with already_enrolled flag, locations, and
  cross-location context. Server-rendered i18n via Jinja2 tojson.
- enroll-success.html: conditional cross-store/single-store messaging,
  server-rendered translations and context, i18n_modules block added.
- dashboard.html, history.html: replace $t() with server-side _() to
  fix i18n flicker across all storefront templates.
- Fix device-mobile icon → phone icon.
- 4 new i18n keys in 4 locales (en, fr, de, lb).
- Docs: updated data-model, business-logic, production-launch-plan,
  user-journeys with cross-location behavior and E2E test checklist.
- 12 new unit tests + 3 new integration tests (334 total pass).

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

app/modules/loyalty/tests/unit/test_card_service.py

@@ -153,6 +153,69 @@ class TestSearchCardForStore:
         result = self.service.search_card_for_store(db, test_store.id, "nobody@nowhere.com")
         assert result is None
 
+    def test_search_email_finds_cross_store_card(self, db, loyalty_store_setup):
+        """Email search at store2 finds a card enrolled at store1 when
+        cross-location is enabled."""
+        setup = loyalty_store_setup
+        customer = setup["customer"]
+        card = setup["card"]
+        merchant = setup["merchant"]
+
+        from app.modules.tenancy.models import Store
+
+        store2 = Store(
+            merchant_id=merchant.id,
+            store_code=f"XSRCH_{uuid.uuid4().hex[:6].upper()}",
+            subdomain=f"xsrch{uuid.uuid4().hex[:6]}",
+            name="Cross Search Store",
+            is_active=True,
+            is_verified=True,
+        )
+        db.add(store2)
+        db.commit()
+
+        # Cross-location is enabled by default — should find the card
+        result = self.service.search_card_for_store(
+            db, store2.id, customer.email
+        )
+        assert result is not None
+        assert result.id == card.id
+
+    def test_search_email_no_cross_store_when_disabled(
+        self, db, loyalty_store_setup
+    ):
+        """Email search at store2 does NOT find cross-store cards when
+        cross-location is disabled."""
+        setup = loyalty_store_setup
+        customer = setup["customer"]
+        merchant = setup["merchant"]
+
+        from app.modules.loyalty.services.program_service import program_service
+
+        settings = program_service.get_or_create_merchant_settings(
+            db, merchant.id
+        )
+        settings.allow_cross_location_redemption = False
+        db.commit()
+
+        from app.modules.tenancy.models import Store
+
+        store2 = Store(
+            merchant_id=merchant.id,
+            store_code=f"NOSRCH_{uuid.uuid4().hex[:6].upper()}",
+            subdomain=f"nosrch{uuid.uuid4().hex[:6]}",
+            name="No Cross Search Store",
+            is_active=True,
+            is_verified=True,
+        )
+        db.add(store2)
+        db.commit()
+
+        result = self.service.search_card_for_store(
+            db, store2.id, customer.email
+        )
+        assert result is None
+
 
 @pytest.mark.unit
 @pytest.mark.loyalty
@@ -405,3 +468,232 @@ class TestReactivateCardAudit:
 
         card = self.service.reactivate_card(db, test_loyalty_card.id)
         assert card.is_active is True
+
+
+@pytest.mark.unit
+@pytest.mark.loyalty
+class TestGetCardByCustomerAndStore:
+    """Tests for the per-store card lookup."""
+
+    def setup_method(self):
+        self.service = CardService()
+
+    def test_finds_card_at_store(self, db, loyalty_store_setup):
+        """Returns card when customer has one at the given store."""
+        setup = loyalty_store_setup
+        result = self.service.get_card_by_customer_and_store(
+            db, setup["customer"].id, setup["store"].id
+        )
+        assert result is not None
+        assert result.id == setup["card"].id
+
+    def test_returns_none_at_different_store(self, db, loyalty_store_setup):
+        """Returns None when customer has no card at the given store."""
+        from app.modules.tenancy.models import Store
+
+        setup = loyalty_store_setup
+        store2 = Store(
+            merchant_id=setup["merchant"].id,
+            store_code=f"NOCARD_{uuid.uuid4().hex[:6].upper()}",
+            subdomain=f"nocard{uuid.uuid4().hex[:6]}",
+            name="No Card Store",
+            is_active=True,
+            is_verified=True,
+        )
+        db.add(store2)
+        db.commit()
+
+        result = self.service.get_card_by_customer_and_store(
+            db, setup["customer"].id, store2.id
+        )
+        assert result is None
+
+
+@pytest.mark.unit
+@pytest.mark.loyalty
+class TestCrossStoreEnrollment:
+    """
+    Tests for cross-store enrollment with merchant_id-aware resolution.
+
+    The customer model is store-scoped, but loyalty cards are merchant-scoped.
+    When a customer enrolls at store1 and then at store2 (same merchant),
+    resolve_customer_id should find the existing customer from store1 via
+    the cross-store loyalty card lookup.
+    """
+
+    def setup_method(self):
+        self.service = CardService()
+
+    def test_resolve_finds_existing_cardholder_across_stores(
+        self, db, loyalty_store_setup
+    ):
+        """Same email at a different store returns the original customer_id
+        when merchant_id is provided and they already have a card."""
+        setup = loyalty_store_setup
+        merchant = setup["merchant"]
+        customer = setup["customer"]  # Already has a card at store1
+
+        # Create a second store under the same merchant
+        from app.modules.tenancy.models import Store
+
+        store2 = Store(
+            merchant_id=merchant.id,
+            store_code=f"SECOND_{uuid.uuid4().hex[:6].upper()}",
+            subdomain=f"second{uuid.uuid4().hex[:6]}",
+            name="Second Store",
+            is_active=True,
+            is_verified=True,
+        )
+        db.add(store2)
+        db.commit()
+        db.refresh(store2)
+
+        # Resolve with the same email at store2 — should find
+        # the existing customer from store1 via the loyalty card join
+        result = self.service.resolve_customer_id(
+            db,
+            customer_id=None,
+            email=customer.email,
+            store_id=store2.id,
+            merchant_id=merchant.id,
+            create_if_missing=True,
+        )
+
+        assert result == customer.id
+
+    def test_resolve_without_merchant_id_creates_new_customer(
+        self, db, loyalty_store_setup
+    ):
+        """Without merchant_id, the cross-store lookup is skipped and
+        a new customer is created at the new store."""
+        setup = loyalty_store_setup
+        merchant = setup["merchant"]
+        customer = setup["customer"]
+
+        from app.modules.tenancy.models import Store
+
+        store2 = Store(
+            merchant_id=merchant.id,
+            store_code=f"NOMID_{uuid.uuid4().hex[:6].upper()}",
+            subdomain=f"nomid{uuid.uuid4().hex[:6]}",
+            name="No Merchant ID Store",
+            is_active=True,
+            is_verified=True,
+        )
+        db.add(store2)
+        db.commit()
+
+        result = self.service.resolve_customer_id(
+            db,
+            customer_id=None,
+            email=customer.email,
+            store_id=store2.id,
+            # No merchant_id — cross-store lookup skipped
+            create_if_missing=True,
+            customer_name="New Customer",
+        )
+
+        assert result != customer.id  # Different customer created
+
+    def test_enroll_cross_location_enabled_rejects_duplicate(
+        self, db, loyalty_store_setup
+    ):
+        """With cross-location enabled (default), enrolling the same
+        customer_id at a different store raises AlreadyExists."""
+        from app.modules.loyalty.exceptions import (
+            LoyaltyCardAlreadyExistsException,
+        )
+
+        setup = loyalty_store_setup
+        merchant = setup["merchant"]
+        customer = setup["customer"]  # Already has a card
+
+        from app.modules.tenancy.models import Store
+
+        store2 = Store(
+            merchant_id=merchant.id,
+            store_code=f"DUP_{uuid.uuid4().hex[:6].upper()}",
+            subdomain=f"dup{uuid.uuid4().hex[:6]}",
+            name="Dup Store",
+            is_active=True,
+            is_verified=True,
+        )
+        db.add(store2)
+        db.commit()
+
+        with pytest.raises(LoyaltyCardAlreadyExistsException):
+            self.service.enroll_customer_for_store(
+                db, customer.id, store2.id
+            )
+
+    def test_enroll_cross_location_disabled_allows_second_card(
+        self, db, loyalty_store_setup
+    ):
+        """With cross-location disabled, the same customer can enroll
+        at a different store and get a separate card."""
+        setup = loyalty_store_setup
+        merchant = setup["merchant"]
+        customer = setup["customer"]
+
+        # Disable cross-location
+        from app.modules.loyalty.services.program_service import (
+            program_service,
+        )
+
+        settings = program_service.get_or_create_merchant_settings(
+            db, merchant.id
+        )
+        settings.allow_cross_location_redemption = False
+        db.commit()
+
+        from app.modules.tenancy.models import Store
+
+        store2 = Store(
+            merchant_id=merchant.id,
+            store_code=f"XLOC_{uuid.uuid4().hex[:6].upper()}",
+            subdomain=f"xloc{uuid.uuid4().hex[:6]}",
+            name="Cross-Loc Store",
+            is_active=True,
+            is_verified=True,
+        )
+        db.add(store2)
+        db.commit()
+        db.refresh(store2)
+
+        # Should succeed — different store, cross-location disabled
+        card2 = self.service.enroll_customer_for_store(
+            db, customer.id, store2.id
+        )
+        assert card2.enrolled_at_store_id == store2.id
+        assert card2.merchant_id == merchant.id
+        assert card2.customer_id == customer.id
+        # Original card still exists
+        assert setup["card"].id != card2.id
+
+    def test_enroll_cross_location_disabled_rejects_same_store(
+        self, db, loyalty_store_setup
+    ):
+        """With cross-location disabled, re-enrolling at the SAME store
+        still raises AlreadyExists."""
+        from app.modules.loyalty.exceptions import (
+            LoyaltyCardAlreadyExistsException,
+        )
+
+        setup = loyalty_store_setup
+        merchant = setup["merchant"]
+        customer = setup["customer"]
+
+        from app.modules.loyalty.services.program_service import (
+            program_service,
+        )
+
+        settings = program_service.get_or_create_merchant_settings(
+            db, merchant.id
+        )
+        settings.allow_cross_location_redemption = False
+        db.commit()
+
+        with pytest.raises(LoyaltyCardAlreadyExistsException):
+            self.service.enroll_customer_for_store(
+                db, customer.id, setup["store"].id
+            )