"""Reward redemption lifecycle aggregate — Phase 7.3.""" from __future__ import annotations import uuid from datetime import datetime from sqlalchemy import DateTime, Index, Integer, String, UniqueConstraint from sqlalchemy.orm import Mapped, mapped_column from sqlalchemy.types import JSON from app.core.database import Base from app.models.base import TenantMixin, TimestampMixin, UUIDPrimaryKeyMixin from app.models.types import GUID, RedemptionStatus class RewardRedemption( Base, UUIDPrimaryKeyMixin, TenantMixin, TimestampMixin, ): """Reward redemption lifecycle record. Points ledger remains the source of truth.""" __tablename__ = "reward_redemptions" program_id: Mapped[uuid.UUID] = mapped_column(GUID(), nullable=False) reward_id: Mapped[uuid.UUID] = mapped_column(GUID(), nullable=False) member_id: Mapped[uuid.UUID] = mapped_column(GUID(), nullable=False) point_account_id: Mapped[uuid.UUID] = mapped_column(GUID(), nullable=False) status: Mapped[RedemptionStatus] = mapped_column( default=RedemptionStatus.PENDING, nullable=False ) points_spent: Mapped[int] = mapped_column(Integer, default=0, nullable=False) ledger_entry_id: Mapped[uuid.UUID | None] = mapped_column(GUID(), nullable=True) voucher_code: Mapped[str] = mapped_column(String(50), nullable=False) idempotency_key: Mapped[str | None] = mapped_column(String(100), nullable=True) reason: Mapped[str | None] = mapped_column(String(500), nullable=True) cancel_reason: Mapped[str | None] = mapped_column(String(500), nullable=True) fulfilled_at: Mapped[datetime | None] = mapped_column( DateTime(timezone=True), nullable=True ) cancelled_at: Mapped[datetime | None] = mapped_column( DateTime(timezone=True), nullable=True ) metadata_json: Mapped[dict | None] = mapped_column(JSON, nullable=True) actor_user_id: Mapped[str | None] = mapped_column(String(100), nullable=True) __table_args__ = ( UniqueConstraint( "tenant_id", "idempotency_key", name="uq_reward_redemptions_tenant_idempotency", ), Index("ix_reward_redemptions_reward", "tenant_id", "reward_id"), Index("ix_reward_redemptions_member", "tenant_id", "member_id"), Index("ix_reward_redemptions_status", "tenant_id", "status"), )