Initial MobilityOps build pack (docs, contracts, scaffold)

2026-08-01 20:34:43 +02:00
commit 24188d9b10
71 changed files with 3412 additions and 0 deletions
@@ -0,0 +1,42 @@
+# 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.