Refund request

Purpose

TBD by human

Identity & key fields

• Primary key: id (uuid, default gen_random_uuid()).
• bookingId (uuid, NOT NULL, UNIQUE, FK → bookings.bookings.id, on-delete cascade) — one refund request per booking.
• walletId (uuid, NOT NULL, FK → wallet.wallet.id, on-delete cascade).
• amount (decimal 10,2, NOT NULL).
• status (enum refund_request_status: PENDING, APPROVED, REJECTED, default PENDING).
• resolvedBy (nullable uuid, FK → users.users.id, on-delete set null) — coach or manager who approved/rejected.
• resolvedAt (nullable timestamp).
• note (nullable text).

business meaning: TBD by human

Invariants

• bookingId is UNIQUE — at most one refund-request row per booking (enforced in tktspace-backend/libs/shared/data-access-db/src/lib/schema/wallet.schema.ts).
• bookingId, walletId ON DELETE CASCADE; resolvedBy ON DELETE SET NULL (enforced in tktspace-backend/libs/shared/data-access-db/src/lib/schema/wallet.schema.ts).
• amount, status NOT NULL; status defaults to PENDING (enforced in tktspace-backend/libs/shared/data-access-db/src/lib/schema/wallet.schema.ts).

business invariants: TBD by human

Lifecycle

Status enum values: PENDING, APPROVED, REJECTED.

transitions: TBD by human

Relationships

• Booking (ENT-003) — bookingId → bookings.bookings.id, UNIQUE, on-delete cascade. 1:1.
• Wallet (ENT-040) — walletId → wallet.wallet.id, on-delete cascade. N:1.
• User (resolver) (ENT-021) — resolvedBy → users.users.id, on-delete set null. N:1, optional.

API surfaces

Surface	Exposed	Notes
client	inferred yes — referenced via AutoRefundDto and the REFUND_* notification family (NotificationDto); no dedicated /refund-requests endpoint visible in audit-time client OpenAPI extract	Swagger UI
business	inferred yes — coach/manager resolves via business panel; managed in libs/features/wallet/src/lib/wallet-admin.module.ts	Swagger UI
super-admin	no	—

Known gotchas / open questions

• UNIQUE on bookingId enforces “one refund request per booking” — re-requesting after rejection requires application-side handling (delete + recreate, or repurpose the existing row).
• Auto-refund flows (e.g. cancellation inside the activity’s cancellation window) bypass this table and write directly to wallet transactions — see Wallet transaction.