feat(loyalty): attribute transactions to the acting POS tablet

Adds acting_terminal_device_id to loyalty_transactions so the audit log can distinguish between operations performed via the web terminal (human user JWT) and operations performed via a paired tablet (device JWT). The principal-of-record stays the pairing user — existing reports keep working — and this column adds "which tablet did it" alongside. Threaded through every store-API endpoint that creates a transaction (stamp add/redeem/void, points earn/redeem/void/adjust, enrollment + welcome bonus, card deactivate/reactivate). The route reads current_user.terminal_device_id, which the bearer-auth dep populates when a device JWT is presented. User-token requests leave the column NULL, as covered by the new test. Bulk admin operations (GDPR anonymization, bulk deactivate) and Celery tasks (point expiration) are not threaded — they always come from a human admin or the scheduler, never a tablet. - Migration loyalty_011 + LoyaltyTransaction.acting_terminal_device_id - 9 service signatures gain the optional kwarg - 8 store-API routes pass it through - Integration tests: device JWT populates the column, user JWT leaves it NULL Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 21:04:56 +02:00
parent c267452dc6
commit d99633345f
7 changed files with 182 additions and 2 deletions
--- a/app/modules/loyalty/services/card_service.py
+++ b/app/modules/loyalty/services/card_service.py
@@ -520,6 +520,7 @@ class CardService:
        merchant_id: int,
        *,
        enrolled_at_store_id: int | None = None,
+        acting_terminal_device_id: int | None = None,
    ) -> LoyaltyCard:
        """
        Enroll a customer in a merchant's loyalty program.
@@ -594,6 +595,7 @@ class CardService:
            merchant_id=merchant_id,
            card_id=card.id,
            store_id=enrolled_at_store_id,
+            acting_terminal_device_id=acting_terminal_device_id,
            transaction_type=TransactionType.CARD_CREATED.value,
            transaction_at=datetime.now(UTC),
        )
@@ -607,6 +609,7 @@ class CardService:
                merchant_id=merchant_id,
                card_id=card.id,
                store_id=enrolled_at_store_id,
+                acting_terminal_device_id=acting_terminal_device_id,
                transaction_type=TransactionType.WELCOME_BONUS.value,
                points_delta=program.welcome_bonus_points,
                points_balance_after=card.points_balance,
@@ -653,6 +656,8 @@ class CardService:
        db: Session,
        customer_id: int,
        store_id: int,
+        *,
+        acting_terminal_device_id: int | None = None,
    ) -> LoyaltyCard:
        """
        Enroll a customer through a specific store.
@@ -663,6 +668,7 @@ class CardService:
            db: Database session
            customer_id: Customer ID
            store_id: Store ID
+            acting_terminal_device_id: Paired tablet that initiated the enrollment

        Returns:
            Created loyalty card
@@ -678,6 +684,7 @@ class CardService:
            customer_id,
            store.merchant_id,
            enrolled_at_store_id=store_id,
+            acting_terminal_device_id=acting_terminal_device_id,
        )

    def deactivate_card(
@@ -686,6 +693,7 @@ class CardService:
        card_id: int,
        *,
        store_id: int | None = None,
+        acting_terminal_device_id: int | None = None,
    ) -> LoyaltyCard:
        """Deactivate a loyalty card."""
        card = self.require_card(db, card_id)
@@ -696,6 +704,7 @@ class CardService:
            merchant_id=card.merchant_id,
            card_id=card.id,
            store_id=store_id,
+            acting_terminal_device_id=acting_terminal_device_id,
            transaction_type=TransactionType.CARD_DEACTIVATED.value,
            transaction_at=datetime.now(UTC),
        )
@@ -708,7 +717,13 @@ class CardService:

        return card

-    def reactivate_card(self, db: Session, card_id: int) -> LoyaltyCard:
+    def reactivate_card(
+        self,
+        db: Session,
+        card_id: int,
+        *,
+        acting_terminal_device_id: int | None = None,
+    ) -> LoyaltyCard:
        """Reactivate a deactivated loyalty card."""
        card = self.require_card(db, card_id)
        card.is_active = True
@@ -717,6 +732,7 @@ class CardService:
        transaction = LoyaltyTransaction(
            merchant_id=card.merchant_id,
            card_id=card.id,
+            acting_terminal_device_id=acting_terminal_device_id,
            transaction_type=TransactionType.CARD_REACTIVATED.value,
            transaction_at=datetime.now(UTC),
        )
--- a/app/modules/loyalty/services/points_service.py
+++ b/app/modules/loyalty/services/points_service.py
@@ -53,6 +53,7 @@ class PointsService:
        ip_address: str | None = None,
        user_agent: str | None = None,
        notes: str | None = None,
+        acting_terminal_device_id: int | None = None,
    ) -> dict:
        """
        Earn points from a purchase.
@@ -196,6 +197,7 @@ class PointsService:
            card_id=card.id,
            store_id=store_id,
            staff_pin_id=verified_pin.id if verified_pin else None,
+            acting_terminal_device_id=acting_terminal_device_id,
            category_ids=category_ids,
            transaction_type=TransactionType.POINTS_EARNED.value,
            points_delta=points_earned,
@@ -249,6 +251,7 @@ class PointsService:
        ip_address: str | None = None,
        user_agent: str | None = None,
        notes: str | None = None,
+        acting_terminal_device_id: int | None = None,
    ) -> dict:
        """
        Redeem points for a reward.
@@ -331,6 +334,7 @@ class PointsService:
            card_id=card.id,
            store_id=store_id,
            staff_pin_id=verified_pin.id if verified_pin else None,
+            acting_terminal_device_id=acting_terminal_device_id,
            transaction_type=TransactionType.POINTS_REDEEMED.value,
            points_delta=-points_required,
            stamps_balance_after=card.stamp_count,
@@ -385,6 +389,7 @@ class PointsService:
        ip_address: str | None = None,
        user_agent: str | None = None,
        notes: str | None = None,
+        acting_terminal_device_id: int | None = None,
    ) -> dict:
        """
        Void points for a return.
@@ -482,6 +487,7 @@ class PointsService:
            card_id=card.id,
            store_id=store_id,
            staff_pin_id=verified_pin.id if verified_pin else None,
+            acting_terminal_device_id=acting_terminal_device_id,
            transaction_type=TransactionType.POINTS_VOIDED.value,
            points_delta=-actual_voided,
            stamps_balance_after=card.stamp_count,
@@ -529,6 +535,7 @@ class PointsService:
        staff_pin: str | None = None,
        ip_address: str | None = None,
        user_agent: str | None = None,
+        acting_terminal_device_id: int | None = None,
    ) -> dict:
        """
        Manually adjust points (admin/store operation).
@@ -578,6 +585,7 @@ class PointsService:
            card_id=card.id,
            store_id=store_id,
            staff_pin_id=verified_pin.id if verified_pin else None,
+            acting_terminal_device_id=acting_terminal_device_id,
            transaction_type=TransactionType.POINTS_ADJUSTMENT.value,
            points_delta=points_delta,
            stamps_balance_after=card.stamp_count,
--- a/app/modules/loyalty/services/stamp_service.py
+++ b/app/modules/loyalty/services/stamp_service.py
@@ -50,6 +50,7 @@ class StampService:
        ip_address: str | None = None,
        user_agent: str | None = None,
        notes: str | None = None,
+        acting_terminal_device_id: int | None = None,
    ) -> dict:
        """
        Add a stamp to a loyalty card.
@@ -144,6 +145,7 @@ class StampService:
            card_id=card.id,
            store_id=store_id,
            staff_pin_id=verified_pin.id if verified_pin else None,
+            acting_terminal_device_id=acting_terminal_device_id,
            category_ids=category_ids,
            transaction_type=TransactionType.STAMP_EARNED.value,
            stamps_delta=1,
@@ -219,6 +221,7 @@ class StampService:
        ip_address: str | None = None,
        user_agent: str | None = None,
        notes: str | None = None,
+        acting_terminal_device_id: int | None = None,
    ) -> dict:
        """
        Redeem stamps for a reward.
@@ -287,6 +290,7 @@ class StampService:
            card_id=card.id,
            store_id=store_id,
            staff_pin_id=verified_pin.id if verified_pin else None,
+            acting_terminal_device_id=acting_terminal_device_id,
            transaction_type=TransactionType.STAMP_REDEEMED.value,
            stamps_delta=-stamps_redeemed,
            stamps_balance_after=card.stamp_count,
@@ -339,6 +343,7 @@ class StampService:
        ip_address: str | None = None,
        user_agent: str | None = None,
        notes: str | None = None,
+        acting_terminal_device_id: int | None = None,
    ) -> dict:
        """
        Void stamps for a return.
@@ -422,6 +427,7 @@ class StampService:
            card_id=card.id,
            store_id=store_id,
            staff_pin_id=verified_pin.id if verified_pin else None,
+            acting_terminal_device_id=acting_terminal_device_id,
            transaction_type=TransactionType.STAMP_VOIDED.value,
            stamps_delta=-actual_voided,
            stamps_balance_after=card.stamp_count,