Customer entitlement

Purpose

TBD by human

Identity & key fields

• Primary key: id (uuid, default gen_random_uuid()).
• customerPassId (uuid, NOT NULL, FK → passes.customer_pass.id, on-delete restrict).
• activityId (uuid, NOT NULL, FK → activities.activities.id, on-delete restrict).
• sessionsLimit (nullable integer) — snapshot from template; NULL = unlimited.
• sessionsUsed (integer, NOT NULL, default 0).
• isActive (boolean, NOT NULL, default true).

business meaning: TBD by human

Invariants

• customerPassId, activityId both NOT NULL with ON DELETE RESTRICT — a pass or activity cannot be hard-deleted while an entitlement points at it (enforced in tktspace-backend/libs/shared/data-access-db/src/lib/schema/passes.schema.ts).
• sessionsUsed defaults to 0; isActive defaults to true (enforced in tktspace-backend/libs/shared/data-access-db/src/lib/schema/passes.schema.ts).
• Index customer_entitlement_customer_pass_id_idx on (customerPassId) supports nightly low-sessions notification scan (per schema comment “Audit fix #6”) (enforced in tktspace-backend/libs/shared/data-access-db/src/lib/schema/passes.schema.ts).

business invariants: TBD by human

Lifecycle

No status column; soft-deactivated via isActive=false. Increment sessionsUsed on each booking that consumes this entitlement.

Relationships

• Customer pass (ENT-028) — customerPassId → passes.customer_pass.id, on-delete restrict. N:1.
• Activity (ENT-005) — activityId → activities.activities.id, on-delete restrict. N:1.
• Pass entitlement template (ENT-031) — snapshotted from, but no FK on this row.
• Booking (ENT-003) — referenced by bookings.bookings.customer_entitlement_id (on-delete set null). 1:N.
• Booking extra (ENT-004) — referenced by bookings.booking_extras.covered_by_entitlement_id (on-delete set null). 1:N.

API surfaces

Surface	Exposed	Notes
client	yes — /companies/{companyId}/passes/activities/{activityId}/my-entitlements (MyEntitlementDto, MyEntitlementForActivityDto, PassEntitlementClientDto)	Swagger UI
business	yes — CustomerEntitlementResponseDto	Swagger UI
super-admin	no	—

Known gotchas / open questions

• ON DELETE RESTRICT on the activity FK means archiving an activity that has live entitlements requires an application-side strategy.
• sessionsUsed is incremented application-side; there is no DB CHECK ensuring sessionsUsed <= sessionsLimit when limit is set.