sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Samir Boulahtit
2026-05-05 21:04:56 +02:00
parent c267452dc6
commit d99633345f
7 changed files with 182 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
app/modules/loyalty/migrations/versions/loyalty_011_add_acting_terminal_device.py Normal file
View File

@@ -0,0 +1,51 @@
"""loyalty 011 - add acting_terminal_device_id to loyalty_transactions
Lets the audit log distinguish between actions a human user performed
directly via the web terminal and actions a paired POS tablet
performed via its device JWT. The principal-of-record stays the
pairing user (so existing reports keep working); this column adds
"which tablet did it" alongside.
Revision ID: loyalty_011
Revises: loyalty_010
Create Date: 2026-05-05
"""
import sqlalchemy as sa
from alembic import op
revision = "loyalty_011"
down_revision = "loyalty_010"
branch_labels = None
depends_on = None
def upgrade() -> None:
op.add_column(
"loyalty_transactions",
sa.Column(
"acting_terminal_device_id",
sa.Integer(),
sa.ForeignKey(
"loyalty_terminal_devices.id", ondelete="SET NULL"
),
nullable=True,
comment=(
"Paired POS terminal device that performed this transaction "
"(NULL when the action came from a human user via the web)"
),
),
)
op.create_index(
"ix_loyalty_transactions_acting_terminal_device_id",
"loyalty_transactions",
["acting_terminal_device_id"],
)
def downgrade() -> None:
op.drop_index(
"ix_loyalty_transactions_acting_terminal_device_id",
table_name="loyalty_transactions",
)
op.drop_column("loyalty_transactions", "acting_terminal_device_id")

14
app/modules/loyalty/models/loyalty_transaction.py
View File

@@ -105,6 +105,16 @@ class LoyaltyTransaction(Base, TimestampMixin):
index=True,
comment="Staff PIN used for this operation",
)
acting_terminal_device_id = Column(
Integer,
ForeignKey("loyalty_terminal_devices.id", ondelete="SET NULL"),
nullable=True,
index=True,
comment=(
"Paired POS terminal device that performed this transaction "
"(NULL when the action came from a human user via the web)"
),
)
category_ids = Column(
JSON,
nullable=True,
@@ -220,6 +230,10 @@ class LoyaltyTransaction(Base, TimestampMixin):
card = relationship("LoyaltyCard", back_populates="transactions")
store = relationship("Store", backref="loyalty_transactions")
staff_pin = relationship("StaffPin", backref="transactions")
acting_terminal_device = relationship(
"TerminalDevice",
backref="transactions",
)
related_transaction = relationship(
"LoyaltyTransaction",
remote_side=[id],

14
app/modules/loyalty/routes/api/store.py
View File

@@ -703,7 +703,12 @@ def enroll_customer(
merchant_id=merchant_id,
)
card = card_service.enroll_customer_for_store(db, customer_id, store_id)
card = card_service.enroll_customer_for_store(
db,
customer_id,
store_id,
acting_terminal_device_id=current_user.terminal_device_id,
)
program = card.program
@@ -794,6 +799,7 @@ def add_stamp(
ip_address=ip,
user_agent=user_agent,
notes=data.notes,
acting_terminal_device_id=current_user.terminal_device_id,
)
return StampResponse(**result)
@@ -821,6 +827,7 @@ def redeem_stamps(
ip_address=ip,
user_agent=user_agent,
notes=data.notes,
acting_terminal_device_id=current_user.terminal_device_id,
)
return StampRedeemResponse(**result)
@@ -850,6 +857,7 @@ def void_stamps(
ip_address=ip,
user_agent=user_agent,
notes=data.notes,
acting_terminal_device_id=current_user.terminal_device_id,
)
return StampVoidResponse(**result)
@@ -885,6 +893,7 @@ def earn_points(
ip_address=ip,
user_agent=user_agent,
notes=data.notes,
acting_terminal_device_id=current_user.terminal_device_id,
)
return PointsEarnResponse(**result)
@@ -913,6 +922,7 @@ def redeem_points(
ip_address=ip,
user_agent=user_agent,
notes=data.notes,
acting_terminal_device_id=current_user.terminal_device_id,
)
return PointsRedeemResponse(**result)
@@ -943,6 +953,7 @@ def void_points(
ip_address=ip,
user_agent=user_agent,
notes=data.notes,
acting_terminal_device_id=current_user.terminal_device_id,
)
return PointsVoidResponse(**result)
@@ -973,6 +984,7 @@ def adjust_points(
staff_pin=data.staff_pin,
ip_address=ip,
user_agent=user_agent,
acting_terminal_device_id=current_user.terminal_device_id,
)
return PointsAdjustResponse(**result)

18
app/modules/loyalty/services/card_service.py
View File

@@ -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),
)

8
app/modules/loyalty/services/points_service.py
View File

@@ -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,

6
app/modules/loyalty/services/stamp_service.py
View File

@@ -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,

73
app/modules/loyalty/tests/integration/test_terminal_devices.py
View File

@@ -184,3 +184,76 @@ class TestStoreAPIBearerAuth:
headers={"Authorization": f"Bearer {token}"},
)
assert response.status_code in (400, 401)
@pytest.mark.integration
@pytest.mark.api
@pytest.mark.loyalty
class TestActingDeviceAudit:
"""Transactions performed via a device JWT carry acting_terminal_device_id."""
def test_points_earn_via_device_stamps_audit_column(
self, client, loyalty_merchant_headers, loyalty_store_setup, db
):
from app.modules.loyalty.models import LoyaltyTransaction
from app.modules.loyalty.models.loyalty_transaction import TransactionType
store = loyalty_store_setup["store"]
card = loyalty_store_setup["card"]
paired = client.post(
f"{MERCHANT_BASE}/devices",
json={"store_id": store.id, "label": "Counter 1"},
headers=loyalty_merchant_headers,
).json()
device_id = paired["id"]
token = paired["setup_token"]
response = client.post(
f"{STORE_BASE}/points/earn",
json={"card_id": card.id, "purchase_amount_cents": 1500},
headers={"Authorization": f"Bearer {token}"},
)
assert response.status_code == 200, response.text
tx = (
db.query(LoyaltyTransaction)
.filter(
LoyaltyTransaction.card_id == card.id,
LoyaltyTransaction.transaction_type
== TransactionType.POINTS_EARNED.value,
)
.order_by(LoyaltyTransaction.id.desc())
.first()
)
assert tx is not None
assert tx.acting_terminal_device_id == device_id
def test_user_token_leaves_audit_column_null(
self, client, loyalty_store_headers, loyalty_store_setup, db
):
"""Web-terminal user JWT must NOT stamp acting_terminal_device_id."""
from app.modules.loyalty.models import LoyaltyTransaction
from app.modules.loyalty.models.loyalty_transaction import TransactionType
card = loyalty_store_setup["card"]
response = client.post(
f"{STORE_BASE}/points/earn",
json={"card_id": card.id, "purchase_amount_cents": 1500},
headers=loyalty_store_headers,
)
assert response.status_code == 200, response.text
tx = (
db.query(LoyaltyTransaction)
.filter(
LoyaltyTransaction.card_id == card.id,
LoyaltyTransaction.transaction_type
== TransactionType.POINTS_EARNED.value,
)
.order_by(LoyaltyTransaction.id.desc())
.first()
)
assert tx is not None
assert tx.acting_terminal_device_id is None