generated from bisco/codex-bootstrap
137 lines
4.5 KiB
Markdown
137 lines
4.5 KiB
Markdown
# Booking Flow
|
|
|
|
This document describes the full public booking, confirmation, QR generation, and entrance check-in flow.
|
|
|
|
## 1. Public Discovery
|
|
|
|
1. A visitor opens the public website.
|
|
2. The Angular frontend requests published shows and upcoming performances from the backend.
|
|
3. The visitor opens a show detail page.
|
|
4. The frontend displays upcoming public performances and availability returned by the backend.
|
|
|
|
Availability shown to visitors is informational. The backend recalculates availability when reservation state changes.
|
|
|
|
## 2. Booking Submission
|
|
|
|
1. The visitor selects a performance.
|
|
2. The frontend displays the booking form for that performance.
|
|
3. The visitor enters contact details and party size.
|
|
4. The frontend submits the booking request to the backend.
|
|
5. The backend validates:
|
|
- required fields;
|
|
- email format;
|
|
- positive party size;
|
|
- performance exists and booking is open;
|
|
- requested seats do not exceed currently available seats.
|
|
6. The backend creates a `pending` reservation.
|
|
7. The backend creates a random opaque confirmation token.
|
|
8. The backend sends an email with a confirmation link.
|
|
9. The frontend tells the visitor to check their email.
|
|
|
|
The reservation is not confirmed at this stage.
|
|
|
|
## 3. Email Confirmation
|
|
|
|
1. The visitor opens the confirmation link from the email.
|
|
2. The frontend or backend submits the confirmation token to the confirmation endpoint.
|
|
3. The backend validates that the token:
|
|
- exists;
|
|
- has the `confirmation` purpose;
|
|
- belongs to a pending reservation;
|
|
- has not expired;
|
|
- has not already been used.
|
|
4. The backend starts a database transaction.
|
|
5. The backend locks the related performance row.
|
|
6. The backend recalculates confirmed reservations for the performance.
|
|
7. The backend confirms the reservation only if enough seats remain.
|
|
8. The backend marks the confirmation token as used.
|
|
9. The backend creates a QR verification token.
|
|
10. The backend generates a QR code containing the opaque QR token or a verification URL.
|
|
11. The backend returns or sends the QR code to the visitor.
|
|
|
|
If there is no longer enough capacity, the backend must not confirm the reservation.
|
|
|
|
## 4. QR Code Delivery
|
|
|
|
After confirmation, the visitor receives access to a QR code.
|
|
|
|
The QR code may be delivered as:
|
|
|
|
- an image displayed on the confirmation page;
|
|
- an image or link in a confirmation email;
|
|
- a printable page linked from the confirmation result.
|
|
|
|
The QR code must be usable from a smartphone screen or printed copy.
|
|
|
|
The QR code must contain:
|
|
|
|
- an opaque check-in token; or
|
|
- a verification URL containing an opaque token.
|
|
|
|
The QR code must not contain:
|
|
|
|
- visitor name;
|
|
- email address;
|
|
- phone number;
|
|
- notes;
|
|
- party size if avoidable;
|
|
- any other personal data.
|
|
|
|
## 5. Entrance Check-In
|
|
|
|
1. Staff opens the authenticated check-in interface.
|
|
2. Staff scans the visitor's QR code.
|
|
3. The frontend submits the scanned token to the backend.
|
|
4. The backend validates:
|
|
- staff authentication and permission;
|
|
- token exists and has the `check_in` purpose;
|
|
- reservation exists;
|
|
- reservation is confirmed;
|
|
- token is valid for the performance check-in window if such a window is configured;
|
|
- reservation has not already been checked in.
|
|
5. The backend creates a `CheckIn` record.
|
|
6. The backend returns a successful check-in response.
|
|
7. Staff admits the visitor party.
|
|
|
|
## Duplicate Check-In
|
|
|
|
If the same QR code is scanned again:
|
|
|
|
1. The backend detects an existing check-in for the reservation.
|
|
2. The backend returns `409 Conflict`.
|
|
3. The backend does not create a second check-in.
|
|
|
|
The response should be clear enough for staff to understand that the reservation was already used.
|
|
|
|
## Capacity Handling
|
|
|
|
Capacity is calculated as:
|
|
|
|
```text
|
|
room capacity + additional seats - manually occupied seats - confirmed reservations
|
|
```
|
|
|
|
Only confirmed reservations consume capacity. Pending reservations represent interest, not a guaranteed seat.
|
|
|
|
To avoid overbooking, final confirmation must be transactional:
|
|
|
|
1. lock the performance;
|
|
2. recalculate confirmed seats;
|
|
3. compare availability with requested party size;
|
|
4. confirm only when seats are available.
|
|
|
|
## Failure States
|
|
|
|
Expected failure states include:
|
|
|
|
- invalid booking input;
|
|
- booking disabled for the performance;
|
|
- no capacity remaining;
|
|
- confirmation token expired;
|
|
- confirmation token already used;
|
|
- QR token invalid;
|
|
- reservation not confirmed;
|
|
- reservation already checked in.
|
|
|
|
Each failure should return a clear status code and a concise user-facing message.
|