MobilityOps/docs/08-return-workflow.md

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.