MobilityOps/docs/08-return-workflow.md

Vehicle-return workflow

Preview

POST /api/v1/bookings/{public_ref}/return-preview takes the same request body as the commit endpoint below and runs the identical evaluation (evaluate_return()) with no writes, no audit event and no outbox event — it exists so the UI's review step shows the server's actual answer instead of guessing the outcome client-side. It returns the canonical and submitted odometer readings, whether the submission is a regression, the resulting vehicle status with a human-readable reason, whether a quality issue would be created, and next-booking risk. register_vehicle_return (below) calls the same evaluate_return() function, so preview and commit cannot drift apart.

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; compare the submitted reading only with the vehicle's canonical odometer so a lower reading is recorded as evidence instead of rejected.
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.