User Story
As a patient booking a healthcare appointment, I want the system to accurately reflect available time slots and prevent double-booking during the payment process so that I can reliably reserve a slot without conflicts, even when multiple users attempt to book concurrently.
Description
The backend will support FHIR-based scheduling by storing and managing only non-free (busy/busy-tentative) slots, rather than generating and maintaining a full set of free slots. This approach accounts for the fact that bookable healthcare services may have varying durations, making a fixed free-slot model impractical. Instead, the frontend will be responsible for computing available intervals by retrieving non-free slots from the backend and subtracting them from the practitioner role's available time windows, then partitioning the result according to the duration of the healthcare service selected by the user.
The backend must also handle race conditions that occur when multiple users attempt to book the same time slot simultaneously, ensuring data consistency and preventing double-booking.
Booking Flow:
- User selects a healthcare service.
- Frontend queries non-free slots from the backend and displays computed free slots to the user.
- User selects a desired slot.
- User proceeds to payment.
- While payment is being processed, the backend marks the selected slot as
busy-tentative.
- Upon successful payment completion, the backend marks the slot as
busy and appends an additional busy slot to represent a buffer window period.
- If payment is not completed within the allowed payment period, the backend removes the previously marked
busy-tentative slot, returning it to availability.
Reference
- FHIR Scheduling/Slot resource specification
- FHIR PractitionerRole available time windows
- FHIR HealthcareService duration configuration
Notes:
- Define and document the exact payment timeout period after which
busy-tentative slots are automatically released
- Implement a reliable mechanism (e.g., database-level locking, optimistic concurrency control, or atomic transactions) to prevent race conditions when concurrent users attempt to book overlapping slots
- Ensure the
busy-tentative to busy transition and the buffer slot creation occur atomically to avoid partial state during high-concurrency scenarios
- Clarify the buffer window duration and whether it is configurable per healthcare service or practitioner role
- Implement a scheduled job or event-driven mechanism to clean up expired
busy-tentative slots if not already covered by the payment timeout logic
- Add appropriate logging and monitoring for slot state transitions to support debugging and auditing
- Define API contract changes needed for the frontend to query non-free slots, including filtering by practitioner role and date range
- Add unit and integration tests covering concurrent booking attempts, payment timeout expiry, and successful booking completion
- Consider edge cases such as payment retries, partial payments, or users abandoning the booking flow after marking a slot as
busy-tentative
- Verify alignment with FHIR Slot resource status values (
free, busy, busy-unavailable, busy-tentative, entered-in-error)
User Story
As a patient booking a healthcare appointment, I want the system to accurately reflect available time slots and prevent double-booking during the payment process so that I can reliably reserve a slot without conflicts, even when multiple users attempt to book concurrently.
Description
The backend will support FHIR-based scheduling by storing and managing only non-free (
busy/busy-tentative) slots, rather than generating and maintaining a full set of free slots. This approach accounts for the fact that bookable healthcare services may have varying durations, making a fixed free-slot model impractical. Instead, the frontend will be responsible for computing available intervals by retrieving non-free slots from the backend and subtracting them from the practitioner role's available time windows, then partitioning the result according to the duration of the healthcare service selected by the user.The backend must also handle race conditions that occur when multiple users attempt to book the same time slot simultaneously, ensuring data consistency and preventing double-booking.
Booking Flow:
busy-tentative.busyand appends an additional busy slot to represent a buffer window period.busy-tentativeslot, returning it to availability.Reference
Notes:
busy-tentativeslots are automatically releasedbusy-tentativetobusytransition and the buffer slot creation occur atomically to avoid partial state during high-concurrency scenariosbusy-tentativeslots if not already covered by the payment timeout logicbusy-tentativefree,busy,busy-unavailable,busy-tentative,entered-in-error)