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/integration/test_store_api.py

@@ -830,3 +830,248 @@ class TestAdjustPointsRoleGate:
         assert response.status_code == 200
         data = response.json()
         assert data["success"] is True
+
+
+# ============================================================================
+# Item 4: Cross-store enrollment
+# ============================================================================
+
+
+@pytest.fixture
+def cross_store_setup(db, loyalty_platform):
+    """Setup with two stores under the same merchant for cross-store tests.
+
+    Creates: merchant → store1 + store2 (each with its own user),
+    program, customer at store1 with card.
+    """
+    from app.modules.customers.models.customer import Customer
+    from app.modules.tenancy.models import Merchant, Store
+    from app.modules.tenancy.models.store import StoreUser
+    from app.modules.tenancy.models.store_platform import StorePlatform
+    from middleware.auth import AuthManager
+
+    auth = AuthManager()
+    uid = uuid.uuid4().hex[:8]
+
+    # Owner for store1
+    owner1 = User(
+        email=f"xs1own_{uid}@test.com",
+        username=f"xs1own_{uid}",
+        hashed_password=auth.hash_password("storepass123"),
+        role="merchant_owner",
+        is_active=True,
+        is_email_verified=True,
+    )
+    db.add(owner1)
+    db.commit()
+    db.refresh(owner1)
+
+    merchant = Merchant(
+        name=f"Cross-Store Merchant {uid}",
+        owner_user_id=owner1.id,
+        contact_email=owner1.email,
+        is_active=True,
+        is_verified=True,
+    )
+    db.add(merchant)
+    db.commit()
+    db.refresh(merchant)
+
+    # Store 1
+    store1 = Store(
+        merchant_id=merchant.id,
+        store_code=f"XS1_{uid.upper()}",
+        subdomain=f"xs1{uid}",
+        name=f"Cross Store 1 {uid}",
+        is_active=True,
+        is_verified=True,
+    )
+    db.add(store1)
+    db.commit()
+    db.refresh(store1)
+
+    su1 = StoreUser(store_id=store1.id, user_id=owner1.id, is_active=True)
+    db.add(su1)
+    sp1 = StorePlatform(store_id=store1.id, platform_id=loyalty_platform.id)
+    db.add(sp1)
+    db.commit()
+
+    # Separate user for store2 (login always binds to user's first store)
+    owner2 = User(
+        email=f"xs2own_{uid}@test.com",
+        username=f"xs2own_{uid}",
+        hashed_password=auth.hash_password("storepass123"),
+        role="merchant_owner",
+        is_active=True,
+        is_email_verified=True,
+    )
+    db.add(owner2)
+    db.commit()
+    db.refresh(owner2)
+
+    # Store 2
+    store2 = Store(
+        merchant_id=merchant.id,
+        store_code=f"XS2_{uid.upper()}",
+        subdomain=f"xs2{uid}",
+        name=f"Cross Store 2 {uid}",
+        is_active=True,
+        is_verified=True,
+    )
+    db.add(store2)
+    db.commit()
+    db.refresh(store2)
+
+    su2 = StoreUser(store_id=store2.id, user_id=owner2.id, is_active=True)
+    db.add(su2)
+    sp2 = StorePlatform(store_id=store2.id, platform_id=loyalty_platform.id)
+    db.add(sp2)
+    db.commit()
+
+    # Customer at store1
+    customer_email = f"xscust_{uid}@test.com"
+    customer = Customer(
+        email=customer_email,
+        first_name="Cross",
+        last_name="StoreCustomer",
+        hashed_password="!unused!",  # noqa: SEC001
+        customer_number=f"XSC-{uid.upper()}",
+        store_id=store1.id,
+        is_active=True,
+    )
+    db.add(customer)
+    db.commit()
+    db.refresh(customer)
+
+    # Program
+    program = LoyaltyProgram(
+        merchant_id=merchant.id,
+        loyalty_type=LoyaltyType.POINTS.value,
+        points_per_euro=10,
+        welcome_bonus_points=0,
+        minimum_redemption_points=100,
+        minimum_purchase_cents=0,
+        cooldown_minutes=0,
+        max_daily_stamps=10,
+        require_staff_pin=False,
+        card_name="Cross Store Rewards",
+        card_color="#4F46E5",
+        is_active=True,
+        points_rewards=[],
+    )
+    db.add(program)
+    db.commit()
+    db.refresh(program)
+
+    # Card enrolled at store1
+    card = LoyaltyCard(
+        merchant_id=merchant.id,
+        program_id=program.id,
+        customer_id=customer.id,
+        enrolled_at_store_id=store1.id,
+        is_active=True,
+        last_activity_at=datetime.now(UTC),
+    )
+    db.add(card)
+    db.commit()
+    db.refresh(card)
+
+    return {
+        "owner1": owner1,
+        "owner2": owner2,
+        "merchant": merchant,
+        "store1": store1,
+        "store2": store2,
+        "customer": customer,
+        "customer_email": customer_email,
+        "program": program,
+        "card": card,
+    }
+
+
+@pytest.fixture
+def cross_store_headers_store2(client, cross_store_setup):
+    """JWT auth headers bound to store2 (via owner2 who only belongs to store2)."""
+    owner2 = cross_store_setup["owner2"]
+    response = client.post(
+        "/api/v1/store/auth/login",
+        json={"email_or_username": owner2.username, "password": "storepass123"},
+    )
+    assert response.status_code == 200
+    token = response.json()["access_token"]
+    return {"Authorization": f"Bearer {token}"}
+
+
+@pytest.mark.integration
+@pytest.mark.api
+@pytest.mark.loyalty
+class TestCrossStoreEnrollment:
+    """Integration tests for enrollment across stores under the same merchant."""
+
+    def test_enroll_same_email_at_store2_returns_409(
+        self, client, cross_store_headers_store2, cross_store_setup
+    ):
+        """With cross-location enabled (default), enrolling the same email
+        at store2 returns 409 because the customer already has a card under
+        this merchant."""
+        response = client.post(
+            f"{BASE}/cards/enroll",
+            json={"email": cross_store_setup["customer_email"]},
+            headers=cross_store_headers_store2,
+        )
+        assert response.status_code == 409
+
+    def test_enroll_new_customer_at_store2_succeeds(
+        self, client, cross_store_headers_store2, cross_store_setup, db
+    ):
+        """A fresh customer at store2 (no existing card) enrolls normally."""
+        from app.modules.customers.models.customer import Customer
+
+        # Pre-create a customer at store2 (store API requires existing customer)
+        store2 = cross_store_setup["store2"]
+        new_customer = Customer(
+            email=f"newcust_{uuid.uuid4().hex[:8]}@test.com",
+            first_name="New",
+            last_name="Customer",
+            hashed_password="!unused!",  # noqa: SEC001
+            customer_number=f"NEW-{uuid.uuid4().hex[:6].upper()}",
+            store_id=store2.id,
+            is_active=True,
+        )
+        db.add(new_customer)
+        db.commit()
+        db.refresh(new_customer)
+
+        response = client.post(
+            f"{BASE}/cards/enroll",
+            json={"customer_id": new_customer.id},
+            headers=cross_store_headers_store2,
+        )
+        assert response.status_code == 201
+        data = response.json()
+        assert data["card_number"] is not None
+
+    def test_enroll_cross_location_disabled_allows_store2_card(
+        self, client, cross_store_headers_store2, cross_store_setup, db
+    ):
+        """With cross-location disabled, enrolling the same email at store2
+        creates a second card for that store."""
+        # Disable cross-location
+        from app.modules.loyalty.services.program_service import program_service
+
+        settings = program_service.get_or_create_merchant_settings(
+            db, cross_store_setup["merchant"].id
+        )
+        settings.allow_cross_location_redemption = False
+        db.commit()
+
+        response = client.post(
+            f"{BASE}/cards/enroll",
+            json={"email": cross_store_setup["customer_email"]},
+            headers=cross_store_headers_store2,
+        )
+        assert response.status_code == 201
+        data = response.json()
+        assert data["card_number"] is not None
+        # Different card from the original
+        assert data["id"] != cross_store_setup["card"].id