docs: define staff check-in flow

docs/booking-flow.md

@@ -79,19 +79,27 @@ The QR code must not contain:
 
 ## 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:
+1. Staff signs in with an account that has check-in permission.
+2. Staff opens a mobile-friendly web page for entrance check-in.
+3. Staff scans the visitor's QR code with the device camera or enters the QR token manually.
+4. The QR code provides only an opaque check-in token or verification URL.
+5. The frontend submits the token to the backend for a verification preview.
+6. 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.
+7. The backend returns a preview with only the minimum information needed for admission, such as performance, party size, and check-in state.
+8. Staff confirms check-in in the mobile web page.
+9. The backend validates the token again server-side.
+10. The backend creates a `CheckIn` record, or updates an existing incomplete check-in record for the same reservation.
+11. The backend stores the check-in timestamp and authenticated staff user.
+12. The backend returns a successful check-in response.
+13. Staff admits the visitor party.
+
+The token remains opaque throughout the flow. The QR code must not expose visitor name, email address, phone number, notes, or other personal data.
 
 ## Duplicate Check-In
 
@@ -103,6 +111,21 @@ If the same QR code is scanned again:
 
 The response should be clear enough for staff to understand that the reservation was already used.
 
+## Check-In Failure States
+
+Failed validation must return clear error states without creating a successful check-in.
+
+Expected check-in failures include:
+
+- missing or malformed token;
+- unknown token;
+- expired token;
+- staff user is not authenticated;
+- staff user does not have check-in permission;
+- reservation is not confirmed;
+- reservation was already checked in;
+- token is not valid for the selected performance or check-in window.
+
 ## Capacity Handling
 
 Capacity is calculated as: