Consultation Module - Feature List

1. Overview

Consultation module provides consultation slot management and booking capabilities.

• Admin manages slot availability and booking follow-up status.
• Customers can discover open slots and submit booking requests.
• Booking notifications are queued to the notifications runtime.

2. Exposed Routes

3. Core Features

Data integrity guardrails:

• Slot deletion restricted when a booking exists (ON DELETE RESTRICT + service guard).
• Slot time check enforced (start_time < end_time).
• Booking contacted-state check enforced by DB constraint.

4. Admin Features

• list/detail consultation slots
• create consultation slots in bulk from day-pattern + interval
• update/delete consultation slots
• toggle slot active/inactive status
• list/detail bookings
• update booking status to contacted

5. Customer Features

• view available consultation slots (GET /consultations/slots)
• book a consultation slot as guest or logged-in user (POST /consultations/book)
• view own booking history when authenticated (GET /consultations/bookings)

6. State Models

6.1 Slot lifecycle state

6.2 Booking state model

6.3 Customer booking journey

7. Queue/Worker Features

7.1 Notification Jobs

Queued on booking success:

Payload includes slot date/time summary for email templates.

8. Cache Features

• Keys are built with CacheKeyUtil.build(...).
• Slot-write and booking-write paths invalidate consultation:customer:slots:list:*.
• Cache failures degrade gracefully (warn + DB fallback).

9. Rate Limiting

Redis-backed request limits protect:

• customer slot listing
• customer booking creation
• customer booking history
• admin slot and booking operations

Limit/rate-window values are sourced from environment configuration and fail-open on Redis errors with warning logs.

10. Environment Variables

• CONSULTATION_PUBLIC_BOOK_RATE_LIMIT (default 10)
• CONSULTATION_PUBLIC_BOOK_RATE_WINDOW_SECONDS (default 60)
• CONSULTATION_SLOTS_CACHE_TTL_SECONDS (default 300)

11. Error UX Mapping

12. Release/QA Checklist

• Verify admin slot CRUD operations resolve permissions correctly
• Verify bulk slot generation creates correct slots
• Verify booking flow blocks inactive/past/booked slots
• Verify booking status update to contacted works
• Verify slot cache invalidates on writes
• Verify notification jobs are enqueued
• Verify mobile routes resolve correctly
• Verify rate limiting returns 429 on breach
• Verify guest booking works without JWT

13. Data Flow

14. Integration Flows

14.1 Booking Flow

A customer books a consultation slot as guest or authenticated user.

1. Customer calls GET /api/consultations/slots (or GET /api/mobile/consultations/slots) to browse available slots.
2. System filters slots by date range and returns only active, future, unbooked slots.
3. Customer selects a slot and calls POST /api/consultations/book (or POST /api/mobile/consultations/book) with slot details.
4. System validates: slot exists, is active, is in the future, and is not already booked.
5. If customer is authenticated (JWT), system links customer_id to booking.
6. If guest, system stores guest contact fields (name, email, phone) without customer_id.
7. System creates consultation_booking with status pending.
8. System enqueues email notification job to send booking confirmation.
9. If customerId exists, system enqueues push notification job.
10. System invalidates slot list cache consultation:customer:slots:list:*.
11. Customer can view their bookings via GET /api/consultations/bookings (authenticated only).

14.2 Admin Slot Management Flow

An admin creates and manages consultation slots for booking.

1. Admin calls POST /api/admin/consultations/slots/bulk with date range, interval, and time constraints.
2. System parses weekday patterns and date range to generate slot time entries.
3. System validates no duplicate slots exist for each (date, start_time) pair.
4. System inserts multiple consultation_slot records with isActive = true.
5. Admin can view all slots via GET /api/admin/consultations/slots.
6. Admin can update a slot (e.g., deactivate) via PATCH /api/admin/consultations/slots/:id.
7. If slot has an existing booking, system blocks deletion (returns error).
8. Admin can view bookings via GET /api/admin/consultations/bookings.
9. Admin updates booking status to contacted via PATCH /api/admin/consultations/bookings/:id.

Time fields in this module are stored as timezone-aware values and should be handled as ISO-8601 instants by API consumers.

---

See Also

• API Reference: See Consultation - API & Integration Guide Section 7 (Endpoint Reference + Payload Cheatsheet) for complete request/response DTOs.
• Backend Reference: See Consultation - Backend Documentation Section 3 (Data Model) for schema details.