Laufzettel/docs/architektur.md

Architektur und Entscheidungen

Ergänzt CLAUDE.md, das die verbindlichen Konventionen enthält. Hier steht das Warum.

1. Zwei Betriebsmodi, ein Codepfad

Einstellung.modus ist INTERN oder DIENSTLEISTUNG und liegt in der Datenbank, nicht in der Umgebung — der Admin schaltet ohne Neustart um.

Der Kern der Entscheidung: jede kundenbezogene Zeile trägt immer eine kundeId, auch im Modus INTERN. Dort ist es die eine Organisation mit isteigeneOrganisation = true, die in keiner Liste, keinem Filter, keinem Formular und auf keinem Etikett erscheint. Dadurch ist der Wechsel nach DIENSTLEISTUNG eine Datenänderung (die eigene Organisation wird zum ersten Kunden) und keine Migration.

Es gibt daher nicht zwei Codepfade für Geräte oder Läufe, sondern ein- und ausgeblendete Felder und Filter. Zwei Funktionen tragen das:

• betriebsmodus() — gecachter Zugriff, den alle Listen und Formulare fragen
• kundeErmitteln(eingabe) — liefert im Modus INTERN immer die eigene Organisation und verwirft eine mitgeschickte kundeId. Das ist eine Sicherheitsgrenze, kein Komfort.

2. Schichtung

Server Component ──► queries/*  ──► prisma
Server Action    ──► services/* ──► prisma
                     └─ rechtErforderlich(), Zod, Regeln, Protokoll

services/* hält die Regeln und wirft eigene …Fehler-Klassen. queries/* hält Lesemodelle und wendet Rollen- und Mandantensicht selbst an, damit kein Aufrufer sie vergessen kann. actions/* sind Dreizeiler: Recht prüfen, Schema anwenden, Service rufen.

Der Grund für die Trennung von Action und Service: die Regeln sollen ohne Next.js testbar sein. Vitest ruft den Service direkt.

3. Anmeldung: kein Auth.js

Der Auftrag nannte Auth.js. Beim Prüfen der Lage am 2026-09-24:

• next-auth v5 steht auf 5.0.0-beta.32, seit Jahren ohne GA
• authjs.dev führt das Projekt im Wartungsmodus („The Auth.js project is now part of Better Auth"), die Maintainer schreiben „no immediate plans for v5“
• @auth/prisma-adapter deklariert @prisma/client nur bis >=6 — wir fahren Prisma 7

Entschieden wurde deshalb der Eigenbau mit stabilen Bausteinen, wie in ProxLedger:

• openid-client 6.x für generisches OIDC mit Discovery (Ziel: authentik)
• jose für ein signiertes Sitzungs-Cookie (HS256 aus APP_SECRET)
• @node-rs/argon2 für den lokalen Notfallzugang

Rolle und Aktiv-Status werden pro Anfrage aus der Datenbank gelesen, nicht aus dem Token. Eine Rollenänderung greift damit sofort, und ein deaktivierter Benutzer wird auch mit gültigem Cookie abgewiesen.

4. Versionierung und Archiv

Zwei Regeln tragen die Nachvollziehbarkeit:

1. Eine veröffentlichte VorlagenVersion wird nie verändert. „Bearbeiten“ erzeugt eine tiefe Kopie als Entwurf. Ein Lauf auf Version 1 zeigt für immer die Schritte aus Version 1, auch wenn längst Version 5 veröffentlicht ist.
2. Ein archivierter Lauf ist schreibgeschützt. Die Sperre sitzt in genau einer Funktion, laufMussVeraenderbarSein(lauf), die vor jeder Änderung an Kopfdaten, Schrittergebnis und Kommentar gerufen wird. Nur ADMIN holt einen Lauf zurück, mit Protokoll-Eintrag.

Beides ist durch Tests abgedeckt, nicht durch Disziplin.

Abgeschlossen ist nicht archiviert, und der Unterschied ist Absicht. „Abgeschlossen“ ist ein Arbeitszustand: fertig für jetzt. Eine nachgetragene Notiz, ein Kommentar mit dem, was beim Nachfassen herauskam, eine korrigierte Seriennummer — das passiert danach, und zwar oft. Würde schon der Abschluss sperren, bräuchte jede Kleinigkeit einen Administrator, und die Technikerin würde Läufe schlicht nicht mehr abschließen; das Archiv wäre danach nicht genauer, sondern leerer. Unveränderlich wird ein Lauf durch das Archivieren, eine ausdrückliche zweite Handlung. Damit „abgeschlossen“ trotzdem nicht lügt, nimmt der Abschluss sich selbst zurück, sobald eine Änderung einen Pflichtschritt wieder offen lässt.

Der Aufbau einer Version wird als Ganzes gespeichert, nicht Schritt für Schritt: der Editor hält den Baum im Speicher und sortiert per Drag & Drop, ein Teil-Update wäre dort ständig mit dem Sortieren im Streit. Dasselbe Zod-Schema (src/lib/vorlagen-format.ts) beschreibt den Entwurf im Editor, den JSON-Export und den Import — drei getrennte Schemata würden auseinanderlaufen, und der Import wäre der Ort, an dem das erst auffiele. Das Format ist in docs/vorlagen-format.md beschrieben.

Die eingebauten Platzhalter stehen als Liste in src/lib/platzhalter.ts — Daten, kein Code. Der Editor zeigt sie als Hilfe, die Warnung vor unbekannten Platzhaltern vergleicht dagegen, und die Auflösung in #012 baut darauf auf. Eine zweite Aufzählung an anderer Stelle würde unweigerlich auseinanderlaufen: ein Platzhalter, der in der Hilfe steht, aber nicht aufgelöst wird, bliebe im fertigen PowerShell-Befehl als {{…}} stehen.

Die Warnung ist ausdrücklich keine Ablehnung. Ein Tippfehler soll im Editor auffallen und nicht erst dem Techniker im Lauf; es kann aber gute Gründe geben, einen Platzhalter stehen zu lassen — etwa weil die Variable gleich noch kommt. Speichern und Veröffentlichen bleiben deshalb erlaubt.

5. Der Weg zu Phase 4 (Aktionen)

Die in den Vorlagen vorbereiteten PowerShell-Befehle sind bewusst die Vorstufe ausführbarer Schritte. Damit der Schritt dorthin keine Migration braucht:

• VorlagenSchritt.typ ist ein Enum, dem AKTION hinzugefügt wird; konfig (Json) trägt dann Connector und Parameter
• Schrittergebnis.wert ist ein Json, das ein Aktionsergebnis mit Log, IDs und Zeitstempeln aufnimmt
• kein Codepfad nimmt an, dass ein Schritt nur von einem Menschen erledigt wird
• das Krypto-Modul für das LDAP-Bind-Passwort ist schon der Platz für Connector-Geheimnisse

5a. Was in der Datenbank steht und warum

Die Service-Schicht ist der richtige Ort für Regeln mit verständlichen Meldungen. Sie ist aber nicht der einzige Weg, auf dem Daten entstehen: Migrationen, psql, Skripte und ab Phase 4 die Connectoren schreiben an ihr vorbei. Was stillschweigend falsch werden könnte, steht deshalb zusätzlich in der Datenbank:

Regel	Form
Höchstens eine eigene Organisation	partieller Eindeutigkeitsindex
Höchstens ein Entwurf je Vorlage	partieller Eindeutigkeitsindex
Kundenkürzel, tagCode-Form, verschlüsseltes Bind-Passwort	CHECK auf die Form
Registriertes Gerät braucht Hostname oder Bezeichnung	CHECK, greift erst ab registriertAm
Mitarbeiter aus dem Verzeichnis oder Freitextname	CHECK
Status und Zeitstempel laufen nicht auseinander	vier CHECKs
NICHT_ZUTREFFEND und FEHLGESCHLAGEN brauchen eine Notiz	CHECK
Einstellung ist eine einzelne Zeile	CHECK auf die feste Kennung
Mandantengrenze	vier zusammengesetzte Fremdschlüssel

Die Mandantengrenze verdient die Erklärung: Lauf verweist mit ("geraetId", "kundeId") auf Geraet("id", "kundeId"), analog für Person und Abteilung, und Geraet ebenso auf den Besitzer. Damit ist ein Lauf, der ein Gerät eines fremden Kunden zieht, nicht mehr bloß ein Fehler im Service, sondern strukturell unmöglich. MATCH SIMPLE sorgt dafür, dass ein Lauf ohne Gerät weiterhin erlaubt ist.

Zwei Dinge sind bewusst nicht kaskadierend: ein Lauf nimmt seine Schrittergebnisse und Kommentare nicht mit, und ein Protokoll-Eintrag verliert seinen Urheber nicht. Beides stünde gegen den Zweck eines Archivs. Der tagCode ist zusätzlich in TagCodeVergabe festgehalten, aus dem nie gelöscht wird — sonst würde ein Code nach dem Löschen eines Geräts wieder frei und ein alter Aufkleber zeigte auf ein fremdes Objekt.

5b. Warum ein Screenshot nichts über Bedienbarkeit sagt

In dieser Umgebung hydriert next dev nicht: die Seiten werden serverseitig gerendert und sehen vollständig richtig aus, aber React hängt sich nie an — kein Knopf, kein Formular, kein Sortieren tut etwas. Nachgewiesen in #010, und zwar auch ohne src/proxy.ts und ohne output: "standalone"; der HMR-WebSocket scheitert mit ERR_INVALID_HTTP_RESPONSE. Es liegt am Werkzeug, nicht an diesem Code — im gebauten Stand tragen 1281 von 1296 Elementen React-Knoten, im Entwicklungsmodus zwei.

Zwei Folgen, beide verbindlich:

1. Oberflächen werden gegen pnpm build && pnpm start abgenommen, nicht gegen pnpm dev — ebenso die Screenshots. Steht in CLAUDE.md.
2. Was nur mit angehängtem React gelingt, gehört in einen Playwright-Test. pnpm test:e2e klickt den Editor durch: anlegen, tippen, sortieren mit dem Finger bei 390 px, speichern, neu laden und nachsehen, ob es wirklich in der Datenbank steht.

Die Content-Security-Policy in src/proxy.ts ist deshalb zweigeteilt: im Entwicklungsmodus mit unsafe-eval und WebSocket, im ausgelieferten Stand ohne beides. Die Entscheidung fällt an process.env.NODE_ENV, und tests/sicherheitsrichtlinie.test.ts prüft sie am Proxy selbst — eine Prüfung der Funktion mit selbst gesetztem Argument hätte genau den Fehler durchgelassen, vor dem der Kommentar darüber warnt.

5c. Warum die Maskierung dort sitzt, wo sie sitzt

Aus einer Vorlage entsteht ein PowerShell-Befehl, den ein Techniker kopiert und auf einem Domänencontroller ausführt. Drei Entscheidungen tragen das (#012):

1. Maskiert wird der eingesetzte Wert, nicht der fertige Befehl. Sonst maskierte man die Anführungszeichen des Befehls gleich mit. platzhalterErsetzen bekommt die Maskierung deshalb als Funktion und wendet sie auf jeden Wert einzeln an.
2. Die Maskierung setzt keine Anführungszeichen dazu — die stehen in der Vorlage. Das ist eine Annahme, und sie wird geprüft: steht ein {{platzhalter}} in einem BEFEHL-Schritt nicht zwischen den erwarteten Anführungszeichen, wird der Schritt abgewiesen statt gefüllt. Ein halb maskierter Befehl zum Kopieren wäre die gefährlichste aller Antworten.
3. Was sich nicht sicher maskieren lässt, wird abgelehnt. Für Cmd gibt es keine Regel, die ein " in jedem Fall richtig behandelt — ein solcher Wert bekommt eine Fehlermeldung, keinen Befehl. PowerShell liest auch “, ” und „ als Begrenzer; die werden auf ihre ASCII-Form gebracht und dann maskiert, weil sie sich als Text ohnehin nicht durchreichen lassen.

Geprüft wird das ausgeführt, nicht gelesen: tests/shell.test.ts schickt bösartige Werte durch ein echtes bash -c und durch ein echtes PowerShell — und wenn auf der Maschine kein pwsh liegt, nimmt der Test das Container-Abbild. In CI bricht er ab, statt sich zu überspringen; ein stilles Überspringen sieht genauso grün aus wie ein bestandener Lauf.

Das generierte Passwort entsteht erst beim Ersetzen und wird nirgends zurückgegeben — es gibt keinen Weg, es außerhalb des fertigen Texts zu bekommen. Gäbe es ein Feld dafür, wäre die Versuchung groß, es „nur fürs Protokoll“ mitzuschreiben.

5d. Wie die Aktualisierung funktioniert – und warum sie keine Befehle mitliefert

Die Abarbeitungsansicht hält GET /api/laeufe/[id]/zustand als Ereignisstrom offen — zwei Techniker teilen sich ein Onboarding und sollen die Arbeit des anderen sehen, ohne die Seite neu zu laden. Diese Nutzlast trägt nur Status, Schrittzustände und die Zahl der Kommentare und Anhänge, ausdrücklich keine fertigen Befehle.

Der Grund ist {{generiertes_passwort}}: es entsteht bei jedem Auflösen neu. Lieferte die Aktualisierung Befehle mit, stünde nach jeder Änderung ein anderes Passwort auf dem Bildschirm als das, das der Techniker gerade in die Konsole geklebt hat. Die Befehle entstehen deshalb genau einmal je Seitenaufbau, und der Client lädt die Seite erst neu, wenn sich am Zustand wirklich etwas geändert hat. Bei verstecktem Tab wird der Strom geschlossen.

Der Route Handler prüft sein Recht selbst und gibt einen fremden Lauf als „nicht gefunden“ zurück — auch und gerade für den Strom, bevor das erste Ereignis fließt.

Warum die Datenbank das Ereignis schickt, nicht der Dienst

Bis #033 fragte die Seite alle zehn Sekunden. Das war richtig, aber zehn Sekunden sind lang, wenn zwei Leute dieselbe Liste abhaken, und zwanzig offene Laschen bedeuteten zwanzig Abfragen je zehn Sekunden. Seit #033 melden vier Trigger NOTIFY lauf_geaendert, '<laufId>', eine LISTEN-Verbindung je Prozess hört zu, und der Route Handler schiebt weiter.

In der Datenbank und nicht im Service, aus demselben Grund, aus dem auch die Regeln dort stehen: ein Ereignis, das der Service verschickt, entsteht nur auf dem Weg durch den Service. Ein Trigger sieht auch den Seed, eine Migration und die Reparatur per psql. Und NOTIFY geht an jede Verbindung mit LISTEN — also an jede Instanz der Anwendung, ohne einen zweiten Dienst.

Welche Tabellen melden, hängt an dem, was das Lesemodell liefert. Das Polling verglich den ganzen Stand und sah damit auch, was kein Trigger meldet; ein Strom sieht nur, was gemeldet wird. Fehlte Kommentar oder Anhang, wäre die Live-Aktualisierung gegenüber dem Polling ein Rückschritt — der Kommentar des Kollegen käme nie an. tests/datenbankregeln.test.ts zählt die vier Trigger namentlich auf, tests/zustand-route.test.ts die Schlüssel des Zustands.

Das Polling bleibt, als Rückfall an derselben Adresse. Wer kein EventSource hat oder hinter einem Proxy sitzt, der Ströme puffert, bekommt den alten Weg — dieselbe Rechteprüfung, dasselbe Lesemodell, dieselbe Nutzlast. Ein zweiter Endpunkt wäre eine zweite Stelle, an der jemand das Recht vergessen kann. Unterschieden wird allein am Accept-Kopf, den EventSource von sich aus schickt. Dieser Rückfall wird gefahren, nicht behauptet: tests/e2e/live.spec.ts nimmt dem Browser EventSource weg.

Eine Obergrenze (SSE_MAX_STROEME, Vorgabe 200) begrenzt die offenen Ströme je Instanz. Ist sie erreicht, antwortet der Handler gewöhnlich mit JSON; EventSource meldet darauf einen Fehler und versucht es nicht wieder, und der Client fällt von sich aus auf Polling zurück. Das braucht keinen Sonderfall und keinen eigenen Fehlercode. Die Hülle unter src/app/(app)/layout.tsx deckt src/app/api/ nicht ab.

Warum die Benachrichtigungen in einer Warteschlange liegen

Vier Anlässe gehen seit #034 hinaus: zugewiesen, überfällig, abgeschlossen, Abgleich fehlgeschlagen. Drei Entscheidungen prägen das.

Eingereiht wird im Anfrage-Pfad, gesendet wird es nicht. Ein hängender Mailserver darf kein Abhaken blockieren. Der Dienst schreibt eine Zeile in Zustellung — eine Einfügung in dieselbe Datenbank, die der Vorgang ohnehin anfasst —, und ein Zeitplan im selben Prozess schickt sie. Das Einreihen passiert nach der Transaktion und mit abgefangenem Fehler: ein Abhaken darf nicht daran scheitern, dass eine Benachrichtigung nicht eingereiht werden konnte.

Betreff und Rumpf stehen fertig in der Zeile. Das kostet Platz und ist es wert: eine Meldung sagt, was damals war. Baute der Zeitplan den Text erst beim Senden, stünde in einer Mail von heute der Stand von jetzt — und in einer aufgegebenen Zustellung von nächster Woche etwas völlig anderes.

In keiner Meldung steht ein Schrittinhalt. Darüber wacht src/lib/meldungen.ts: die Funktionen dort nehmen nur Kopfdaten, der Typ lässt nichts anderes zu. Eine Mail mit dem Lauf-Inhalt wäre genau die Lücke, die dieses Projekt an jeder anderen Stelle geschlossen hat — das erzeugte Passwort wird nirgends gespeichert, aber eine Mail liegt für immer in einem Postfach, oft auf einem Server, der nicht im Haus steht. tests/benachrichtigungen.test.ts prüft es zusätzlich über alle Rumpftexte, die wirklich verschickt wurden, so wie #012 es für die Druckansicht tat.

Zwei Dinge, die ohne Datenbank nicht gehalten hätten. Die Einmaligkeit der Überfälligkeitsmeldung liegt in einem partiellen eindeutigen Index: der Zeitplan sieht jede Minute nach, und ohne ihn bekäme der Zuständige für einen Lauf, der über das Wochenende steht, 2880 Mails — jede davon für sich korrekt, kein Test rot. Und die Sperre der Warteschlange liegt in derselben Tabelle wie die des Abgleichs: hinter einem Lastverteiler laufen zwei Instanzen, und ein let laeuft = false im Modul wüsste nichts von der zweiten.

Das Polling-Prinzip gilt auch hier nicht umgekehrt: ein Kommentar und ein angehängtes Foto lösen keine Mail aus. Beides sieht die Live-Aktualisierung sofort (Abschnitt 5d); eine Mail dafür wäre Lärm. Mehr Anlässe wären ein Benachrichtigungsbaukasten, und der ist eine Phase für sich.

5e. Der Aufkleber ist die Schnittstelle

Jedes Objekt traegt einen QR-Aufkleber mit einem tagCode, der nie geaendert und nie wiederverwendet wird — auch nicht, nachdem das Geraet geloescht wurde (TagCodeVergabe, #006). Der Aufkleber ist damit die einzige Angabe am Geraet, die Jahre haelt: Hostnamen aendern sich, Besitzer wechseln, Seriennummern werden abgeschrieben.

Im QR steht ausschliesslich {APP_URL}/t/{tagCode}. Kein Name, keine Seriennummer, kein Besitzer. Ein Aufkleber haengt sichtbar am Geraet und wird von jedem Telefon gelesen, auch von einem fremden; was darauf steht, ist veroeffentlicht. Die Adresse selbst verraet nichts — dahinter verlangt /t/[tagCode] eine Anmeldung und zeigt einem fremden Kunden dieselbe Antwort wie bei einem Code, den es nicht gibt.

Drei Dinge daran sind nicht mehr zu korrigieren, sobald gedruckt ist, und stehen deshalb fest:

1. Die Basisadresse kommt aus APP_URL, mit ihrem Pfad. Liegt die Anwendung unter https://firma.de/laufzettel, muss genau das im QR stehen; basisAdresse() in src/lib/adressen.ts haelt den Pfad fest, tagAdresse() haengt relativ an. Ohne gesetzte APP_URL warnt die Druckseite, statt still localhost zu drucken.
2. Der QR entsteht lokal (qrcode, Fehlerkorrektur M, Ruhezone 4). Eine externe API bekaeme mit jedem Aufruf den Bestand an Tag-Codes geliefert.
3. Die Masse sind geprueft, nicht behauptet. tests/e2e/etiketten.spec.ts misst die Seitengroesse an einem echten PDF (62 × 29 mm bzw. A4) und liest ein bei 300 dpi gerastertes Etikett mit demselben Decoder zurueck, den auch der Scanner benutzt.

Der Scanner laedt barcode-detector/polyfill: wo der Browser eine BarcodeDetector-API mitbringt, laeuft sie, sonst springt WebAssembly ein. Dessen .wasm kommt aus dem eigenen Haus (scripts/wasm-bereitstellen.mjs legt es unter public/zxing/), weil die Content-Security-Policy nur connect-src 'self' erlaubt und die Anwendung ohne Internet laufen soll; dafuer traegt script-src ein 'wasm-unsafe-eval' — die schmale Erlaubnis, WebAssembly zu uebersetzen, und nicht unsafe-eval. Laeuft die Kamera nicht oder faellt der Decoder aus, steht an derselben Stelle ein Feld fuer den abgetippten Code: der steht lesbar unter jedem QR, und ein Scanner, der nicht startet, darf keine Sackgasse sein.

5f. Archiv und Ausdruck: das Gedaechtnis

Die Archivsuche geht ueber drei Tabellen — Lauf.titel, Schrittergebnis.notiz, Schrittergebnis.wert und Kommentar.rumpf — und steht deshalb als eine SQL-Anweisung in src/server/queries/archiv.ts statt als vier Prisma-Abfragen. Zwei Gruende, beide handfest:

1. Schrittergebnis.wert ist ein Json. Nur ("wert")::text trifft den pg_trgm-GIN-Index aus #006; eine ganze Json-Spalte als Text zu durchsuchen kann Prisma nicht.
2. Die Fundstelle gehoert zum Treffer. Wer im Archiv sucht, will nicht wissen dass etwas passt, sondern wo — Titel, Notiz, Wert oder Kommentar, mit dem Ausschnitt drumherum. Vier getrennte Abfragen muessten das hinterher wieder zusammenlegen.

Jeder Wert geht als Parameter in die Anweisung (Prisma.sql), und %, _ und \ werden fuer ILIKE maskiert: die Suche nach „50 %“ trifft sonst „5099“. tsvector bleibt die spaetere Optimierung, so wie in §5a festgehalten.

Abgelegt heisst COALESCE(archiviertAm, abgeschlossenAm, erstelltAm) — derselbe Ausdruck fuer die Sortierung und den Zeitraumfilter. Zwei verschiedene Ausdruecke hiessen: ein Lauf steht ausserhalb des Zeitraums, den die Liste an seiner Position anzeigt.

Die Druckansicht (/drucken/lauf/<id>) ist ein eigenes Lesemodell und kein Schalter an laufZumAbarbeiten. Dort entsteht beim Fuellen der Befehle ein {{generiertes_passwort}}; auf einem Blatt, das jemand abheftet, darf keines stehen — dort erscheint [Passwort – nicht gespeichert], und erzeugt wird keines. Der Beweis dafuer ist ein Vergleich: zwei Ausdrucke desselben Laufs sind Zeichen fuer Zeichen gleich, ein erzeugtes Passwort waere bei jedem Aufbau ein anderes.

Vom Mitarbeiter holt dieses Lesemodell nur Name, UPN und Abteilung — nicht alles und dann gefiltert. Ein Ausdruck liegt herum, wird kopiert und weitergegeben; was darauf steht, ist aus der Hand gegeben.

5g. Der Verzeichnis-Abgleich: vier Schichten und eine Notbremse

Das LDAP-Modul liegt unter src/server/ldap/ und ist absichtlich in vier Dateien geteilt, von denen nur eine das Netz anfasst:

Datei	Was darin steht
fehler.ts	VerzeichnisFehler — die Basis, unterhalb der Dienstschicht, damit verbindung.ts von ihr erben kann, ohne die Schichtung umzudrehen
verbindung.ts	Adressformen (ldaps://, ldap+starttls://, ldap://), TLS-Optionen, mitVerbindung() und das Saeubern fremder Fehlermeldungen
zuordnung.ts	reine Funktionen: aus einem Entry wird ein Datensatz in unseren Feldern, DNs werden vergleichbar, Vorgesetzte aufgeloest
leser.ts	searchPaginated in 1000er-Seiten, Eintrag fuer Eintrag weitergegeben

Die Attributzuordnung und die Grenzen des Intervalls stehen in src/lib/verzeichnis.ts und nicht bei den LDAP-Modulen: das Formular braucht dieselbe Liste und dieselben Zahlen, und eine Client-Komponente importiert nichts aus src/server/*. Als beides zweimal geschrieben war, lief es auseinander — die Oberflaeche liess hoechstens 1440 Minuten zu, der Dienst 10080.

Der Abgleich laeuft nicht in einer Transaktion. Das ist eine Entscheidung mit Folgen: bricht er in der Mitte ab, bleiben die bis dahin geschriebenen Personen stehen. Eine Transaktion ueber das gesamte Verzeichnis haette die Tabelle so lange gesperrt, wie das Lesen dauert. Deaktiviert wird dagegen nur nach einem vollstaendigen Durchlauf — sonst haette ein Netzwerkfehler nach der halben Liste die andere Haelfte der Firma abgeschaltet.

Darum herum liegen drei Regeln, die alle denselben Fehler verhindern — dass eine kaputte Eingabe wie „alle sind gegangen“ aussieht:

1. Kein einziger Eintrag zuordenbar ⇒ Fehler, kein Abschalten. Steht in der Zuordnung ein Kennungsattribut, das es am Server nicht gibt, wird jeder Eintrag uebersprungen: das Lesen hat geklappt, niemand wurde wiedergesehen, und die Abschaltung traefe die gesamte Belegschaft — mit Status ERFOLG. Danach sucht niemand mehr nach dem Grund.
2. Uebersprungene Eintraege sind nicht verschwunden. Sie werden am dn erkannt und aus der Abschaltung herausgenommen.
3. Von Hand angelegte Personen werden uebernommen, nicht verdoppelt. Beim Onboarding entsteht die Person hier und das AD-Konto danach; der Abgleich findet sie ueber upn oder sam (ohne Rucksicht auf Gross- und Kleinschreibung) und haengt Quelle und Kennung an dieselbe Zeile. Eine Person, die schon eine andere Quelle fuehrt, wird nie uebernommen.

Uebersprungene Eintraege kommen als hinweis zurueck und nicht als fehler: Verzeichnisquelle.letzterAbgleichFehler soll heissen, dass etwas schiefging, und nicht „ein Konto war krumm“.

Der Zeitplan ist node-cron im selben Prozess wie die Anwendung, gestartet aus src/instrumentation.ts — nur in der Node-Laufzeit und nur, wenn ZEITPLAN_AKTIV nicht false ist. Zwei Gruende fuer „im selben Prozess“: der nativ ausgerollte LXC braucht keine zweite systemd-Unit, und der Abgleich benutzt denselben Dienst wie „Jetzt abgleichen“, also gibt es keinen zweiten Weg mit eigenen Regeln. Die Sperre liegt in der Datenbank (AbgleichSperre) und nicht im Prozess: zwei Instanzen hinter einem Reverse Proxy kommen sich sonst in die Quere. Der Zeitplan nimmt ausdruecklich keine eigene Sperre — sie traege einen anderen Schluessel und liefe an der des Dienstes vorbei.

5h. Der Seed: einrichten, nicht aufraeumen

Die sieben Vorlagen stehen als JSON im Austauschformat unter prisma/seed-daten/vorlagen/ und nicht als TypeScript-Literale. Damit prueft sie dasselbe Zod-Schema, das auch Import, Export und Editor benutzen: eine Seed-Vorlage ist genau das, was ein Redakteur einspielen koennte, und ein Fehler faellt beim Einrichten auf statt im ersten Lauf.

Angelegt werden sie nicht ueber vorlageImportieren. Der Import erzeugt absichtlich einen Entwurf und schreibt einen Protokolleintrag mit dem handelnden Menschen; der Seed hat keinen Menschen und braucht veroeffentlichte Versionen, weil sich sonst kein Lauf starten liesse. Er geht trotzdem denselben Weg wie ein Redakteur — erst Entwurf, dann veroeffentlichen: die Trigger aus #010 verbieten jedes Schreiben an Abschnitten, Variablen und Schritten einer veroeffentlichten Version. Eine Version gleich als VEROEFFENTLICHT anzulegen und danach zu fuellen scheitert an der Datenbank, und das ist richtig so.

Der Seed richtet ein, er raeumt nicht auf. Jede Zeile hat einen sprechenden Schluessel — die Vorlage ihren Namen, die Abteilung (kundeId, name), die Person ihren UPN, das Geraet seinen tagCode —, und was es schon gibt, bleibt unberuehrt. Kein upsert mit gefuelltem update: eine im Betrieb geaenderte Ziel-OU, eine bearbeitete Vorlage und ein umgeschalteter Betriebsmodus ueberstehen jeden weiteren Lauf. Zweimal hintereinander aufgerufen aendert der zweite Lauf nichts, und tests/seed.test.ts haelt das fest.

Im Modus DIENSTLEISTUNG haengt der Beispielbestand an der Musterfirma und nicht an der eigenen Organisation: der Auftrag verlangt, dass LZ-7K3F9Q dort auf MUS-PC-001 fuehrt. Ein Tag-Code gehoert genau einem Geraet, beides zugleich ginge also ohnehin nicht — „erzeugt stattdessen“.

Die Tag-Codes der Beispielgeraete sind fest und nicht gezogen. Ein Seed, der jedes Mal fuenf neue Codes zieht, waere nicht idempotent: beim dritten Lauf laegen fuenfzehn Aufkleber im Stapel. Weil ein tagCode global eindeutig ist und nie wiederverwendet wird, bekommt jeder Demo-Kunde seinen eigenen Satz.

6. Betrieb: zwei Wege, eine Regel

Die Datenbank ist auf beiden Wegen von außen nicht erreichbar:

Weg	Wie
Docker Compose	postgres ohne ports:, nur im Netz intern mit internal: true (kein Gateway)
Nativ im LXC	PostgreSQL mit listen_addresses = '' — nur Unix-Socket

Festgehalten in tests/betriebsstand.test.ts, damit ein ports:-Mapping nicht versehentlich zurückkommt.

7. Werkzeug-Obergrenzen

Zwei Abhängigkeiten dürfen nicht angehoben werden, beides empirisch festgestellt:

• eslint bleibt auf 9.x. eslint-config-next bringt eslint-plugin-react@7.37.5 mit, das eslint nur bis ^9.7 unterstützt. Mit eslint 10 bricht das Regelwerk beim Laden ab (contextOrFilename.getFilename is not a function). Eine neuere Fassung des Plugins gibt es nicht — die letzte stammt von April 2025.
• typescript bleibt auf ~6.0.3. typescript-eslint@8 erlaubt nur >=4.8.4 <6.1.0. TypeScript 7.0.2 ist zwar latest, aber noch nicht unterstützt.

Dazu ein Pinning: prisma und @prisma/client exakt auf 7.10.0. Der latest-Tag von prisma zeigt auf einen 8.0-RC, der von @prisma/client nicht — ein unbedachtes pnpm add prisma würde beide auseinanderlaufen lassen.