Files

T

NuklearRabbit c981aad2a3 docs(release): update contracts and docs for functional-completion changes

Add the new endpoints to contracts/openapi.yaml and docs/05-api-contract.md
(return-preview, the four rule-specific data-quality resolution endpoints,
search, integration status, scheduled-scan), document the role matrix and
the audit before/after exposure in docs/12-security-and-audit.md, document
each rule type's actual resolution flow in docs/07-data-quality.md
(including the deliberate evidence-fingerprint simplification and the
reopened_from/previous_decision recurrence link), document the preview/
commit relationship in docs/08-return-workflow.md, and update README.md's
scope/integration-status/quality-gate sections to match what's actually
implemented and verified now. Also drops docs/05-api-contract.md's mention
of GET /api/v1/system/status, which was never implemented.

2026-08-02 07:10:37 +02:00

2.2 KiB

Raw Blame History

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

Authorize Rental Employee or Operations Manager.
Lock booking and vehicle rows.
Reject cancelled/already-returned booking unless idempotency replay matches.
Validate required fields and submitted reading against booking start reading.
Create a return inspection.
Set booking to returned and store submitted end reading.
If submitted reading >= canonical odometer, update canonical odometer.
Otherwise create odometer_regression; keep canonical odometer unchanged.
Derive vehicle state:
- damage or technical warning -> blocked;
- service threshold reached -> maintenance;
- otherwise -> cleaning.
Create quality issues for contradictions.
Create audit events.
Insert vehicle.returned.v1 outbox event.
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.

2.2 KiB Raw Blame History Unescape Escape