[TASK][Backend] Introduce reservation and availability APIs with slot conflict protection

[vugarsafarzada]

Source of Truth

• PRD: https://www.notion.so/3435ef9e213280eaa56ad864787cda02
• Repo: Reziphay/nodejs-app
• Task type: execution-ready backend task for AI/code agents
• Depends on: #9 for Service contracts and coordination with #7/#8 for brand-branch-team context
• Blocks: nextjs-app#11 and most of nextjs-app#12

Current Codebase Snapshot

• There is no Reservation or Availability domain exposed yet.
• The repo already has Brand/Branch/Team foundations and a notification feed foundation that reservation events can plug into later.
• The PRD makes reservation the main customer outcome, so this is a central domain task, not a side feature.

Goal

Implement the core reservation engine: provider availability, slot generation, booking requests, USO decision flows, status transitions, and hard conflict protection against double booking.

In Scope

• Prisma models for provider availability windows, blocked days, buffer time, reservations, and any status/audit data needed.
• Read APIs for available slots based on service duration, branch hours, and provider-level narrowing rules.
• Booking creation for UCR against a specific service/provider/branch context.
• USO actions for accept, reject, complete, cancel, and no-show flows.
• UCR actions for list/history and self-cancel where allowed.
• Reservation status lifecycle: PENDING, CONFIRMED, CANCELLED_BY_UCR, CANCELLED_BY_USO, COMPLETED, NO_SHOW.
• Event hooks/contracts so notifications/reminders can be wired by #12 without reworking reservation logic.

Suggested Implementation Order

1. Finalize the reservation/availability schema before writing controllers.
2. Implement slot calculation reads first so booking logic can share the same assumptions.
3. Add booking create/cancel endpoints and provider-facing decision endpoints.
4. Add status transition guards so invalid jumps are rejected centrally.
5. Add transaction-safe conflict protection.
6. Add tests for overlap, buffer handling, branch-hour restrictions, cancellation, and completion flows.

Important Constraints For Agents

• Conflict protection must be enforced in the backend, not left to frontend optimism.
• Use explicit timezone-safe date/time handling and document the chosen storage strategy.
• Keep slot calculation logic centralized so read-model and booking write-model do not diverge.
• Do not bury reminder scheduling logic inside reservation controllers; expose clear domain events/hooks instead.

Deliverables

• Prisma migration(s) and Reservation/Availability schema.
• Slot-read and booking/status-transition endpoints.
• Central reservation service with conflict protection.
• Tests covering overlap, race-risk scenarios, and lifecycle transitions.

Acceptance Criteria

• UCR can request a reservation against a real service/provider context.
• Confirmed reservations cannot double-book the same provider/time window.
• Slot reads respect branch hours, provider narrowing, blocked days, and buffer time.
• USO can accept/reject/complete/no-show reservations through explicit server-side transitions.
• UCR can list their reservations and cancel according to the allowed rules.
• Reservation events are exposed cleanly for later notification/review work.

Out of Scope

• Calendar sync with external providers.
• A real-time websocket layer unless the repo already has one.