n8n: store cleaned workflow definitions as repo source of truth

Move the two live-validated workflows into n8n/workflows/ (credential- based auth referenced by name only, no secret values), add a manifest covering all 4 canonical workflows and a read-only drift-check script against n8n's Public API. Retire the pre-integration root-level starter files that still carried the literal-token pattern, and repoint the Unraid deploy scripts, Makefile targets and runbook at the new files. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-04 13:34:51 +02:00
parent 59cb4c062e
commit e0c107a94a
12 changed files with 410 additions and 165 deletions
@@ -993,7 +993,12 @@ below.
  via `de0bdea`, followed by evidence commit `f780557` on master. See the "Fleet Ops
  final localization" entry below for the next (small correction) round on top of this.

-## Fleet Ops final localization: remaining NL/FR gaps, API-error localization, greeting (2026-08-04) — IN PROGRESS on fix/fleet-ops-final-i18n-ux
+## Fleet Ops final localization: remaining NL/FR gaps, API-error localization, greeting (2026-08-04) — MERGED TO MASTER
+
+Merged to master via `5f0eaa5`; final evidence commit `c0995b7` added
+`artifacts/fleet-ops-final-localization/final-summary.md`. Master head at merge:
+`c0995b762e1cbf37172a08e03645baa6b66aa8d5`. Details below are the in-progress working log
+kept for reference.

 Branch `fix/fleet-ops-final-i18n-ux`, created from master's post-correction head
 (`f780557`) — the brief asked for `fix/fleet-ops-final-localization`, but the
@@ -1074,3 +1079,81 @@ product scope.
  `a7ac5ed` (docs), `7851e80` (11D/11F i18n tests), `cda2c32` (clean-checkout
  evidence), `2e4fb43` (evidence-summary localization fix, found live on Unraid).
  Deployed commit: `2e4fb43f093bfbdb04c4f74eed1e6c6d9a03c069`.
+
+## Live n8n + RAGcore integration (2026-08-04) — IN PROGRESS on feat/live-n8n-ragcore-integration
+
+Branch `feat/live-n8n-ragcore-integration`, from master `c0995b7`. Full brief: treat n8n
+(`https://n8n.itworx.tech`, existing shared instance) as a third integration layer
+alongside RAGcore and MCP Hub, owning process orchestration only — Fleet Ops keeps all
+business rules, authorization, transactions, audit and idempotency. Four canonical
+workflows required: (1) Vehicle Return Orchestration, (2) Scheduled Data Quality Scan —
+both pre-existing and now hardened; (3) RAGcore Procedure Sync, (4) Workflow Error
+Handler — both net-new, not yet built.
+
+- **Current-state audit**: `docs/live-ai-integration/n8n-current-state.md` documents the
+  live instance (reachable, production webhook base
+  `http://192.168.10.150:5678/webhook/mobilityops-return`), both existing workflows'
+  full node structure, and the findings that drove the security fixes below (webhook
+  Authentication was `None`; both HTTP nodes had `X-Service-Token` hardcoded as a literal
+  header value instead of a credential).
+- **Security fixes applied and live-validated** (commits `b79d485`, `59cb4c0`): webhook
+  trigger now requires Header Auth (credential `Fleet Ops Webhook Trigger Token`, a new
+  token generated this round — value stored in `.env`/Unraid `.env` only, never
+  printed); the outbound callback HTTP node now uses a `Fleet Ops Service Token` Header
+  Auth credential instead of a literal header value (existing secret copied
+  clipboard-to-clipboard, never typed/echoed). Backend: `X-Fleet-Ops-Trigger-Token`
+  header added to the outbox dispatcher's POST (`backend/app/services/dispatcher.py`),
+  plus a new `MOBILITYOPS_WEBHOOK_TRIGGER_TOKEN` setting/env var. Also hardened
+  `_deliver_one` to treat a 2xx response with a non-JSON-object body as a retryable
+  failure (`malformedResponse`) instead of an unhandled exception — a real failure mode
+  hit live when a workflow errors before its "Respond to Webhook" node runs; regression
+  test `test_deliver_one_treats_empty_2xx_body_as_failure` added. Live-validated: curl
+  probe without the header → `403`; with the header → pass-through; one real end-to-end
+  vehicle return produced one correct execution visible in both n8n and Fleet Ops
+  Audit/Automation. Both workflows explicitly `Publish`ed after the fixes (the editor
+  does not go live on save alone) and both canonical-renamed ("Fleet Ops — Vehicle
+  Return Orchestration", "Fleet Ops — Scheduled Data Quality Scan").
+- **RAGcore real contract discovered** (not the speculative one the adapter was built
+  against): OpenAPI at `/openapi.json`, health at `/health/live`/`/health/ready` (not
+  `/health`), ingestion via `POST /v1/uploads`, answers via `POST /v1/answers` with
+  `requested_space_ids`, control-plane endpoints require an `Idempotency-Key` header.
+  Bootstrapped a `fleet-ops` application + knowledge space + grant on the real server at
+  `http://192.168.10.150:1237`. **Blocked**: credential issuance for that application
+  failed identically via both the raw API and the admin UI ("authoritative
+  service-account state rejected issuance") — an apparent privilege boundary beyond the
+  interactive admin session. User chose to issue the credential themselves via another
+  mechanism and hand over the token; not yet received. `RAGcoreKnowledgeProvider`
+  (`backend/app/services/knowledge/ragcore.py`) still targets the old speculative
+  endpoints and needs fixing once that token arrives — approved, not started.
+- **Repository source of truth started** (task in progress): `n8n/workflows/` now holds
+  cleaned definitions for workflows 1-2 — `fleet-ops-vehicle-return.json` (sha256
+  `e13a3087269fc97019a7adf6c6a6a4ee4bd354c2dd7167d4966d4753a48e970e`),
+  `fleet-ops-data-quality-scan.json` (sha256
+  `cc30b28b07dad9f9908a6ea0c564ec4c2f362a3ed71b7e97a7b6894408bb7e2e`) — both credential
+  auth referenced by name only, no secret values. Reconstructed from direct verified
+  inspection of every live node, **not** a literal n8n export/download: the UI's "..."
+  menu has no Download option in this n8n version, and clipboard-based
+  copy/`navigator.clipboard.readText()` extraction timed out twice. Flagged as a known
+  limitation for the final evidence doc. `n8n/workflows/MANIFEST.md` records canonical
+  name/purpose/trigger/contract/credentials/live ID/active-status/checksum for all 4
+  workflows (3-4 marked not-yet-built). `n8n/workflows/check_drift.py` compares a repo
+  definition against the live workflow via n8n's Public API (`X-N8N-API-KEY`, read-only,
+  never auto-overwrites). The old root-level `n8n/mobilityops-return-processing.json`
+  and `n8n/mobilityops-scheduled-quality-scan.json` (pre-integration starters, still
+  carrying the literal-token pattern) are removed; `deploy/unraid/setup-existing-n8n.sh`,
+  `setup-scheduled-scan.sh`, `Makefile` (`n8n-setup`, `n8n-setup-scan`) and
+  `docs/17-runbook.md` updated to import from `n8n/workflows/` and to document the
+  now-required manual credential-creation step (credentials are never scripted or
+  committed).
+- **Explicitly deferred/forbidden this phase** (per brief): daily AI ops brief, email,
+  Slack, automatic vehicle-status changes, customer communication, billing, general
+  monitoring, autonomous MCP actions. An automatic demo-reset workflow may only be
+  prepared, not activated, once Fleet Ops goes public.
+- **Exact next action**: build workflow 4 (Workflow Error Handler) — does not depend on
+  the blocked RAGcore token, so it proceeds now. Workflow 3 (RAGcore Procedure Sync) and
+  the `RAGcoreKnowledgeProvider` adapter fix stay blocked until the user supplies a
+  working RAGcore application credential/token. After both new workflows exist: update
+  the Fleet Ops integration status page (task #88), run the full 4-workflow
+  testing/acceptance pass (task #90), and write
+  `artifacts/live-ai-integration/final-summary.md` (task #91, explicitly: no credentials
+  or secret values in that file).