# n8n-Schnittstelle

Alle Fachdaten von EK-DOS-WEB liegen in n8n. Das Backend hält davon nichts vor
ausser einem kurzlebigen Cache.

## Adressen

Der n8n-Hauptdienst auf **Port 5678** ist ausschliesslich über
`https://n8n.elektro-krueger.eu` erreichbar. Jeder weitere n8n-Dienst auf einem
anderen Port ist nicht veröffentlicht und wird über **10.0.11.131** angesprochen.

In `backend/src/N8n/Endpoints.php`:

```php
$url->webhook('/offene-tickets');            // https://n8n.elektro-krueger.eu/webhook/ek-dos-web/offene-tickets
$url->internal(5679, '/webhook/irgendwas');  // http://10.0.11.131:5679/webhook/irgendwas
```

Neue Adressen gehören in diese Klasse, nicht verstreut in die Controller.

## Endpunkte

Alle unter `/webhook/ek-dos-web`. Die Spalte *Cache* nennt Gruppe sowie frische
und Rückfall-Haltbarkeit in Sekunden.

| Pfad                                | Verwendung                       | Cache                    |
| ----------------------------------- | -------------------------------- | ------------------------ |
| `/offene-tickets`                   | Ticketliste                      | `tickets` 15 / 600       |
| `/offene-tickets/kundenruecksprache`| Ergebnis speichern               | schreibend               |
| `/tickets/digitale-akte`            | PDF                              | –                        |
| `/tickets/servicebericht`           | PDF                              | –                        |
| `/angebote`                         | Angebotsliste                    | `offers` 30 / 600        |
| `/angebote/versendet` `/beauftragt` `/zuruecksetzen` `/loeschen` | Aktionen | schreibend |
| `/kundenstamm`                      | Kundenliste, Anlage, Änderung    | `customers` 120 / 1800   |
| `/kundenstamm/digitale-akte`        | PDF                              | –                        |
| `/rechnungen`                       | Rechnungen eines Kunden          | `invoices` 30 / 600      |
| `/rechnungen/alle`                  | Gesamtübersicht (geschützt)      | `invoices` 30 / 600      |
| `/rechnungen/zuordnen` `/sync`      | Zuordnung, Abgleich (geschützt)  | schreibend               |
| `/rechnungen/pdf`                   | PDF                              | –                        |
| `/rechnungen-anfertigen`            | Aufgabenliste                    | `invoices-create` 30/600 |
| `/rechnungen-anfertigen/erledigt`   | Aufgabe abschließen              | schreibend               |
| `/rechnungen-pruefen`               | Prüfliste                        | `invoices-review` 30/600 |
| `/rechnungen-versenden`             | Versandliste und -bestätigung    | `invoices-send` 30/600   |
| `/digitale-akte`                    | PDF als base64 im JSON           | –                        |
| `/interne-aufgaben` (+ `/erledigt` `/bearbeiten` `/loeschen`) | Aufgaben | `tasks` 20 / 600 |
| `/online-kaeufe` (+ `/erledigt` `/loeschen`) | Online-Käufe            | `purchases` 30 / 600     |
| `/stundennachweise`                 | Monatsreport                     | `hours` 300 / 3600       |

## Geteilte Geheimnisse

| Kopfzeile                  | aus                       | wofür                                                        |
| -------------------------- | ------------------------- | ------------------------------------------------------------ |
| `x-ekdos-invoice-sync`     | `N8N_INVOICE_SYNC_SECRET` | Rechnungsübersicht, Zuordnung, Abgleich, Kundenanlage, Angebot zurücksetzen |
| `X-EK-DOS-Customer-Key`    | `N8N_CUSTOMER_KEY`        | Lesen und Ändern im Kundenstamm                              |
| `x-ekdos-webhook-secret`   | `N8N_REFRESH_SECRET`      | n8n meldet EK-DOS eine Ticketänderung                        |

Fehlt eines davon, antworten die betroffenen Routen mit **503** und einer
Meldung, die genau das sagt -- sie schlagen nicht stumm fehl.

> Der Kundenschlüssel stand in der Next.js-Fassung als Literal im Quelltext
> (`app/api/customers/route.ts`). Er liegt jetzt in `.env`. **Er sollte in n8n
> gewechselt werden**, weil der alte Wert in der Versionsgeschichte steht.

## n8n meldet eine Ticketänderung

Der Workflow *Datenübergabe an EK-DOS-WEB* darf weiter auf seinen Endpunkt
zeigen, nur ohne Port:

```
POST https://schulung.elektro-krueger.local/api/tickets/refresh
x-ekdos-webhook-secret: <N8N_REFRESH_SECRET>
```

Anders als früher ist das kein Platzhalter mehr. In der Next.js-Fassung
antwortete die Route nur `{ok:true}` und tat sonst nichts; die Oberfläche sah
neue Tickets rein zufällig beim nächsten 20-Sekunden-Takt. Jetzt **verwirft der
Aufruf den Ticket-Cache**, sodass die nächste Abfrage die neuen Daten garantiert
sieht.

Ohne gesetztes `N8N_REFRESH_SECRET` verlangt die Route eine angemeldete Sitzung
und weist den Aufruf aus n8n mit 401 ab.

## Feldabbildung Tickets

Die einzige Stelle, an der das Backend n8n-Felder umbenennt
(`backend/src/Relay/TicketsController.php`):

| n8n                              | Oberfläche                     |
| -------------------------------- | ------------------------------ |
| `ticketnummer` / `id`            | `id`                           |
| `kunde` / `customer`             | `customer`                     |
| `liegenschaft` / `property`      | `property`                     |
| `letzter_servicebericht_status`  | `reportStatus`                 |
| `fortsetzung`                    | `continuation`                 |
| `entscheidung_code`              | `decisionCode`                 |
| `kundenruecksprache_ergebnis`    | `consultationResult`           |
| `kundenruecksprache_am` / `_von` | `consultationUpdatedAt` / `By` |

`requiresCustomerConsultation` wird abgeleitet: entweder
`entscheidung_code === "TEILERLEDIGUNG_RUECKSPRACHE_KUNDE"`, oder der
Fortsetzungstext enthält „nimmt mit Kunden für das weitere Vorgehen Kontakt auf".
Zeilen ohne Ticketnummer werden verworfen.

## Bekannte Kopplung

Interne Aufgaben kennen in n8n genau zwei Empfänger: `sascha` und `svenja`. Ein
drittes EK-DOS-Konto kann sich anmelden und alle Ansichten nutzen, aber noch
keine Aufgaben zugewiesen bekommen. Dafür müsste der n8n-Workflow *Interne
Aufgaben* einen freien Empfängerschlüssel annehmen.