# Vehicle-return workflow

## Input

- booking public reference;
- submitted end odometer;
- fuel level 0–100;
- cleanliness flag;
- damage flag;
- technical warning flag;
- notes;
- idempotency key.

## Transaction

1. Authorize Rental Employee or Operations Manager.
2. Lock booking and vehicle rows.
3. Reject cancelled/already-returned booking unless idempotency replay matches.
4. Validate required fields and submitted reading against booking start reading.
5. Create a return inspection.
6. Set booking to returned and store submitted end reading.
7. If submitted reading >= canonical odometer, update canonical odometer.
8. Otherwise create `odometer_regression`; keep canonical odometer unchanged.
9. Derive vehicle state:
   - damage or technical warning -> `blocked`;
   - service threshold reached -> `maintenance`;
   - otherwise -> `cleaning`.
10. Create quality issues for contradictions.
11. Create audit events.
12. Insert `vehicle.returned.v1` outbox event.
13. Commit once.

## Post-commit n8n behaviour

The event contains enough identifiers to retrieve current state, not an uncontrolled full database snapshot. n8n may create a cleaning/maintenance follow-up through a narrow callback API and return its run ID.

## Failure behaviour

- n8n unavailable: return succeeds; event stays pending.
- duplicate event delivery: n8n and callback are idempotent by event ID.
- callback fails: workflow appears failed and is retryable.
- concurrent return submissions: only one succeeds; same idempotency key replays the original response.