M4: implement n8n automation

Outbox dispatcher (background thread, FOR UPDATE SKIP LOCKED claim, exponential backoff, no transaction held during HTTP I/O). n8n callback endpoint with shared-secret auth and idempotency by event ID. Automation nav + UI with manual retry. 49 backend tests passing, ruff clean. Fixed a crash-on-redelivery bug in seeded outbox payloads and made the dispatcher defensive against malformed payloads. Verified the full live round trip against a real n8n instance: return -> outbox -> dispatcher -> n8n workflow -> callback -> succeeded, including the S5 failed-retry demo scenario.

backend/tests/test_dispatcher.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from types import SimpleNamespace
+
+from sqlalchemy import select
+
+from app.core.config import get_settings
+from app.core.db import SessionLocal
+from app.models.booking import Booking
+from app.models.outbox import OutboxEvent
+from app.services import dispatcher
+
+
+def _make_pending_event(vehicle_ref: str) -> uuid.UUID:
+    db = SessionLocal()
+    try:
+        booking = db.scalar(select(Booking).where(Booking.status == "returned").limit(1))
+        event = OutboxEvent(
+            event_id=uuid.uuid4(),
+            event_type="vehicle.returned.v1",
+            aggregate_type="booking",
+            aggregate_id=booking.id,
+            payload_json={
+                "correlation_id": str(uuid.uuid4()),
+                "aggregate": {
+                    "type": "booking",
+                    "id": str(booking.id),
+                    "public_ref": booking.public_ref,
+                },
+                "data": {
+                    "vehicle_ref": vehicle_ref,
+                    "inspection_ref": "INSP-TEST",
+                    "resulting_vehicle_status": "cleaning",
+                    "attention_reasons": [],
+                },
+                "aggregate_ref": booking.public_ref,
+            },
+            occurred_at=datetime.now(UTC),
+            delivery_status="pending",
+            attempts=0,
+        )
+        db.add(event)
+        db.commit()
+        return event.event_id
+    finally:
+        db.close()
+
+
+def _get_event(event_id: uuid.UUID) -> OutboxEvent:
+    db = SessionLocal()
+    try:
+        return db.scalar(select(OutboxEvent).where(OutboxEvent.event_id == event_id))
+    finally:
+        db.close()
+
+
+def test_claim_marks_events_delivering():
+    event_id = _make_pending_event("MO-001")
+    claimed = dispatcher._claim_due_events()
+    assert event_id in claimed
+    assert _get_event(event_id).delivery_status == "delivering"
+
+
+def test_deliver_one_success(monkeypatch):
+    event_id = _make_pending_event("MO-002")
+    dispatcher._claim_due_events()
+
+    def fake_post(url, json, timeout):
+        return SimpleNamespace(
+            raise_for_status=lambda: None,
+            json=lambda: {"ok": True, "event_id": str(event_id), "result": {}},
+        )
+
+    monkeypatch.setattr(dispatcher.httpx, "post", fake_post)
+    dispatcher._deliver_one(event_id)
+
+    event = _get_event(event_id)
+    assert event.delivery_status == "succeeded"
+    assert event.attempts == 1
+    assert event.external_run_id == str(event_id)
+    assert event.last_error is None
+
+
+def test_deliver_one_failure_schedules_retry(monkeypatch):
+    event_id = _make_pending_event("MO-003")
+    dispatcher._claim_due_events()
+
+    def fake_post(url, json, timeout):
+        raise dispatcher.httpx.ConnectError("simulated connection failure")
+
+    monkeypatch.setattr(dispatcher.httpx, "post", fake_post)
+    dispatcher._deliver_one(event_id)
+
+    event = _get_event(event_id)
+    assert event.delivery_status == "pending"
+    assert event.attempts == 1
+    assert event.next_attempt_at is not None
+    assert "simulated connection failure" in event.last_error
+
+
+def test_deliver_one_exhausts_attempts_to_failed(monkeypatch):
+    event_id = _make_pending_event("MO-004")
+    settings = get_settings()
+
+    def fake_post(url, json, timeout):
+        raise dispatcher.httpx.ConnectError("still down")
+
+    monkeypatch.setattr(dispatcher.httpx, "post", fake_post)
+
+    for _ in range(settings.n8n_max_attempts):
+        dispatcher._claim_due_events()
+        db = SessionLocal()
+        try:
+            event = db.scalar(select(OutboxEvent).where(OutboxEvent.event_id == event_id))
+            event.next_attempt_at = None
+            db.commit()
+        finally:
+            db.close()
+        dispatcher._deliver_one(event_id)
+
+    event = _get_event(event_id)
+    assert event.delivery_status == "failed"
+    assert event.attempts == settings.n8n_max_attempts
+
+
+def test_deliver_one_handles_malformed_payload_without_getting_stuck(monkeypatch):
+    # Regression test: seeded/legacy outbox rows may lack the full event envelope. Delivery
+    # must resolve the claimed "delivering" row to pending/failed, never leave it stuck.
+    db = SessionLocal()
+    try:
+        booking = db.scalar(select(Booking).limit(1))
+        event = OutboxEvent(
+            event_id=uuid.uuid4(),
+            event_type="vehicle.returned.v1",
+            aggregate_type="booking",
+            aggregate_id=booking.id,
+            payload_json={"aggregate_ref": booking.public_ref},  # missing correlation_id/etc.
+            occurred_at=datetime.now(UTC),
+            delivery_status="pending",
+            attempts=0,
+        )
+        db.add(event)
+        db.commit()
+        event_id = event.event_id
+    finally:
+        db.close()
+
+    def fake_post(url, json, timeout):
+        raise AssertionError("must not attempt delivery with a malformed payload")
+
+    monkeypatch.setattr(dispatcher.httpx, "post", fake_post)
+
+    dispatcher._claim_due_events()
+    dispatcher._deliver_one(event_id)
+
+    event = _get_event(event_id)
+    assert event.delivery_status in ("pending", "failed")
+    assert event.attempts == 1
+    assert "Malformed outbox payload" in event.last_error
+
+
+def test_run_dispatch_cycle_end_to_end(monkeypatch):
+    event_id = _make_pending_event("MO-005")
+
+    def fake_post(url, json, timeout):
+        return SimpleNamespace(
+            raise_for_status=lambda: None,
+            json=lambda: {"ok": True, "event_id": str(event_id), "result": {}},
+        )
+
+    monkeypatch.setattr(dispatcher.httpx, "post", fake_post)
+    processed = dispatcher.run_dispatch_cycle()
+
+    assert processed >= 1
+    assert _get_event(event_id).delivery_status == "succeeded"