docs: define staff check-in flow

docs/api-contract.md

@@ -243,13 +243,58 @@ Status codes:
 
 ## Check-In
 
-### Verify QR Code
+Check-in endpoints are for authenticated staff or admin users. Staff use a mobile-friendly Angular page to scan the QR code with a device camera or enter the token manually.
+
+The QR code must contain only an opaque verification token or a verification URL containing that token. The backend resolves and validates the token server-side.
+
+### QR Verification Preview
 
 ```http
-POST /api/check-ins/verify/
+POST /api/check-ins/preview/
 ```
 
-Validates a QR token and records check-in. This endpoint is for authenticated staff or an authenticated scanning interface.
+Validates a QR token and returns a preview before staff confirms entrance. This endpoint must not create a successful check-in.
+
+Request:
+
+```json
+{
+  "token": "opaque-check-in-token"
+}
+```
+
+Response `200 OK`:
+
+```json
+{
+  "status": "valid",
+  "reservation_id": 123,
+  "performance_id": 10,
+  "show_title": "The Open Stage",
+  "starts_at": "2026-05-15T20:30:00+02:00",
+  "party_size": 2
+}
+```
+
+Status codes:
+
+- `200 OK`: token is valid and reservation can be checked in;
+- `400 Bad Request`: token is missing or malformed;
+- `401 Unauthorized`: staff authentication is missing;
+- `403 Forbidden`: authenticated user cannot preview check-in;
+- `404 Not Found`: token is unknown;
+- `409 Conflict`: reservation is not confirmed or was already checked in;
+- `410 Gone`: token is expired.
+
+The preview response should include only the minimum information staff need to validate the party. It must not expose unnecessary reservation personal data.
+
+### Check-In Confirmation
+
+```http
+POST /api/check-ins/confirm/
+```
+
+Validates the token again and records successful entrance.
 
 Request:
 
@@ -267,7 +312,8 @@ Response `200 OK`:
   "reservation_id": 123,
   "performance_id": 10,
   "party_size": 2,
-  "checked_in_at": "2026-05-15T19:55:00+02:00"
+  "checked_in_at": "2026-05-15T19:55:00+02:00",
+  "checked_in_by": 7
 }
 ```
 
@@ -276,12 +322,32 @@ Status codes:
 - `200 OK`: reservation checked in;
 - `400 Bad Request`: token is missing or malformed;
 - `401 Unauthorized`: staff authentication is missing;
-- `403 Forbidden`: authenticated user cannot perform check-in;
+- `403 Forbidden`: authenticated user cannot confirm check-in;
 - `404 Not Found`: token is unknown;
 - `409 Conflict`: reservation is not confirmed or was already checked in;
 - `410 Gone`: token is expired.
 
-The response should include only the minimum information staff need to admit the party.
+Successful confirmation creates a `CheckIn` record, or updates an existing incomplete check-in record for the reservation. A reservation cannot have two successful check-ins.
+
+Error responses should use clear machine-readable states so the staff interface can show simple messages.
+
+Example `409 Conflict` for duplicate check-in:
+
+```json
+{
+  "status": "already_checked_in",
+  "detail": "This reservation has already been checked in."
+}
+```
+
+Example `409 Conflict` for unconfirmed reservation:
+
+```json
+{
+  "status": "reservation_not_confirmed",
+  "detail": "This reservation is not confirmed."
+}
+```
 
 ## Administration