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/app/api/routers/integrations.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from fastapi import APIRouter, Depends, Header
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_db
+from app.core.config import get_settings
+from app.core.errors import AppError
+from app.models.audit import AuditEvent
+from app.models.outbox import OutboxEvent
+from app.services.audit import record_audit_event
+
+router = APIRouter(prefix="/api/v1/integrations/n8n", tags=["integrations"])
+settings = get_settings()
+
+
+@router.post("/return-callback")
+def return_callback(
+    body: dict[str, Any],
+    idempotency_key: str = Header(..., alias="Idempotency-Key"),
+    service_token: str = Header(..., alias="X-Service-Token"),
+    db: Session = Depends(get_db),
+) -> dict:
+    if service_token != settings.n8n_callback_token:
+        raise AppError("UNAUTHORIZED_SERVICE", "Invalid service token.", status_code=401)
+
+    try:
+        event_id = uuid.UUID(idempotency_key)
+    except ValueError as exc:
+        raise AppError(
+            "INVALID_IDEMPOTENCY_KEY", "Idempotency-Key must be the event's UUID.", status_code=422
+        ) from exc
+
+    event = db.scalar(select(OutboxEvent).where(OutboxEvent.event_id == event_id))
+    if event is None:
+        raise AppError("EVENT_NOT_FOUND", "No outbox event matches this event ID.", status_code=404)
+
+    # Idempotent by event ID: n8n or our own dispatcher may redeliver the same event
+    # (e.g. a lost response after a timeout), so this callback must not double-record.
+    already_recorded = (
+        db.scalar(
+            select(AuditEvent.id).where(
+                AuditEvent.action == "n8n_return_followup_recorded",
+                AuditEvent.metadata_json["event_id"].astext == str(event_id),
+            )
+        )
+        is not None
+    )
+    if not already_recorded:
+        record_audit_event(
+            db,
+            actor_type="service",
+            actor_label="n8n",
+            action="n8n_return_followup_recorded",
+            entity_type="booking",
+            correlation_id=uuid.UUID(body.get("correlation_id"))
+            if body.get("correlation_id")
+            else None,
+            after={"follow_up": body.get("follow_up"), "summary": body.get("summary")},
+            metadata={"event_id": str(event_id)},
+        )
+        db.commit()
+
+    return {
+        "status": "recorded",
+        "event_id": str(event_id),
+        "occurred_at": datetime.now(UTC).isoformat(),
+    }

backend/app/api/routers/workflows.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_db, require_operations_manager
+from app.core.errors import AppError
+from app.models.outbox import OutboxEvent
+from app.schemas import AutomationRunOut, CurrentUser
+from app.services.audit import record_audit_event
+
+router = APIRouter(prefix="/api/v1/workflows", tags=["workflows"])
+
+
+def _to_out(event: OutboxEvent) -> AutomationRunOut:
+    return AutomationRunOut(
+        event_id=str(event.event_id),
+        event_type=event.event_type,
+        aggregate_ref=event.payload_json.get("aggregate_ref", ""),
+        status=event.delivery_status,
+        attempts=event.attempts,
+        last_error=event.last_error,
+        occurred_at=event.occurred_at,
+    )
+
+
+@router.get("", response_model=list[AutomationRunOut])
+def list_workflows(
+    status: str | None = Query(default=None),
+    db: Session = Depends(get_db),
+    _user: CurrentUser = Depends(require_operations_manager),
+) -> list[AutomationRunOut]:
+    stmt = select(OutboxEvent).order_by(OutboxEvent.occurred_at.desc())
+    if status:
+        stmt = stmt.where(OutboxEvent.delivery_status == status)
+    events = db.scalars(stmt).all()
+    return [_to_out(e) for e in events]
+
+
+@router.post("/{event_id}/retry", response_model=AutomationRunOut)
+def retry_workflow(
+    event_id: str,
+    db: Session = Depends(get_db),
+    user: CurrentUser = Depends(require_operations_manager),
+) -> AutomationRunOut:
+    try:
+        parsed_id = uuid.UUID(event_id)
+    except ValueError as exc:
+        raise AppError("INVALID_EVENT_ID", "event_id must be a UUID.", status_code=422) from exc
+
+    event = db.scalar(select(OutboxEvent).where(OutboxEvent.event_id == parsed_id))
+    if event is None:
+        raise AppError("EVENT_NOT_FOUND", "Workflow event not found.", status_code=404)
+    if event.delivery_status != "failed":
+        raise AppError(
+            "NOT_RETRYABLE",
+            f"Event is '{event.delivery_status}', not 'failed'; "
+            "only failed deliveries can be retried.",
+            status_code=409,
+        )
+
+    event.delivery_status = "pending"
+    event.next_attempt_at = None
+    record_audit_event(
+        db,
+        actor_type="user",
+        actor_label=user.display_name,
+        action="workflow_retry",
+        entity_type="outbox_event",
+        metadata={"event_id": event_id, "previous_attempts": event.attempts},
+    )
+    db.commit()
+    return _to_out(event)