feat(verzeichnis): LDAP-Abgleich, Zeitplan, CSV-Import und Log (#30)

docs/architektur.md

@@ -276,6 +276,61 @@ 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.
+
 ## 6. Betrieb: zwei Wege, eine Regel
 
 Die Datenbank ist auf beiden Wegen von außen nicht erreichbar:

docs/devlog.md

@@ -18,11 +18,12 @@ als Unterpunkte mit Aufgabe und Dauer.
 | #013 | M8 – Läufe: Service und Abarbeitung | 3 h 05 min |
 | #014 | M9 – QR-Tags, Geräteseite, Etiketten, Scanner | 3 h 35 min |
 | #015 | M10 – Dashboard und Archiv | 2 h 20 min |
-| | **Summe** | **22 h 45 min** |
+| #016 | M11 – Verzeichnis und LDAP-Abgleich | 3 h 25 min |
+| | **Summe** | **26 h 10 min** |
 
 | Meilenstein | Tatsächlich | Status |
 |---|---|---|
-| v0.1.0 | 22 h 45 min | in Arbeit |
+| v0.1.0 | 26 h 10 min | in Arbeit |
 
 ---
 
@@ -680,3 +681,74 @@ als Unterpunkte mit Aufgabe und Dauer.
 
 - #016 Verzeichnis und LDAP-Abgleich — der größte verbleibende Brocken: `ldapts`, Attribut-Mapping,
   Zeitplan, verschlüsseltes Bind-Passwort und ein Integrationstest gegen einen OpenLDAP-Container.
+
+---
+
+## 2026-09-26 · Sitzung 12 · 23:05–02:30
+
+**Issue:** #016 (M11)
+**Version:** 0.1.0
+
+### Erledigt
+
+- **Vier Teile parallel**: LDAP-Schicht und Abgleich (Sub-Agent), Oberfläche Admin → Verzeichnis
+  (Sub-Agent), CSV-Import und Abteilungsvorschläge (Sub-Agent), Zeitplan und Server Actions (selbst)
+- `ldapts` mit `ldaps://`, `ldap+starttls://` und `ldap://`, eigenem CA-Zertifikat, TLS ab 1.2 und
+  `searchPaginated` in 1000er-Seiten — Eintrag für Eintrag verarbeitet, nicht erst gesammelt
+- `objectGUID` als Puffer gelesen und gemischt-endian zur GUID umsortiert; ein Puffer, der keine
+  GUID ist, wird nur dann als Text genommen, wenn dabei lesbarer Text herauskommt
+- Abgleich mit Anlegen, Aktualisieren, Übernehmen und Deaktivieren, Vorgesetzten-Auflösung in einem
+  zweiten Durchgang und Ergebnis in `Verzeichnisquelle` **und** `Protokoll`
+- Zeitplan mit `node-cron` im selben Prozess, gestartet aus `src/instrumentation.ts`, Sperre in der
+  Datenbank; „Jetzt abgleichen“ nimmt denselben Dienst
+- Admin → Verzeichnis mit Quelle anlegen und bearbeiten, Verbindungstest samt gemappter Felder,
+  bearbeitbarer Attributzuordnung, CA-Zertifikat und Abgleich-Log
+- Personen aus CSV einlesen, Abteilungsvorschläge aus den `department`-Werten
+- Unabhängiger Review: **ein Blocker**, acht Befunde, sieben Anmerkungen — alle abgearbeitet
+- **1098 Tests** (vorher 980) und **71 Ende-zu-Ende-Tests** (vorher 67) grün, Screenshots in
+  `docs/screenshots/m11/`
+
+### Entscheidungen
+
+- **Der Zeitplan nimmt keine eigene Sperre.** Der Dienst sperrt selbst, in der Datenbank. Eine
+  zweite Sperre im Zeitplan trüge einen anderen Schlüssel, liefe an der ersten vorbei — und ein von
+  Hand angestoßener Abgleich sähe für den Zeitplan wie ein unerwarteter Fehler aus.
+- **Übersprungene Einträge sind ein Hinweis, kein Fehler.** `letzterAbgleichFehler` soll heißen,
+  dass etwas schiefging, und nicht „ein Konto war krumm“. Der Hinweis steht in der Erfolgsmeldung
+  und im Log; der Lauf gilt als gelungen.
+- **Von Hand angelegte Personen werden übernommen, nicht verdoppelt.** Beim Onboarding entsteht die
+  Person hier und das AD-Konto danach. Gesucht wird über `upn`, dann `sam`, ohne Rücksicht auf
+  Groß- und Kleinschreibung — und nur unter Zeilen ohne Quelle: wer schon einer anderen Quelle
+  gehört, wandert nicht zwischen zwei Verzeichnissen hin und her.
+- **Attributzuordnung und Intervallgrenzen liegen in `src/lib/verzeichnis.ts`.** Das Formular
+  braucht dieselbe Liste wie der Dienst, und eine Client-Komponente importiert nichts aus
+  `src/server/*`.
+
+### Probleme
+
+- **Der Blocker hätte die ganze Firma gekostet.** Steht in der Attributzuordnung ein
+  Kennungsattribut, das es am Server nicht gibt, wird **jeder** Eintrag übersprungen: das Lesen
+  klappt, niemand wird wiedergesehen, und die Abschaltung trifft die gesamte Belegschaft — mit
+  Status `ERFOLG`. Das Abgleich-Log hat den Fall danach selbst dokumentiert: der Lauf um 01:20 zeigt
+  „4 gelesen, 0 angelegt, 3 deaktiviert, 4 übersprungen“, die Läufe danach nie wieder.
+- **Der Code versprach mehr als die Oberfläche hielt.** Ein Kommentar sagte „wer ein OpenLDAP
+  anbindet, ändert einzelne Zeilen“ — über die Oberfläche ging genau das nicht. Achter Meilenstein
+  in Folge mit einer Zusage ohne Deckung; diesmal war es die Zusage einer Bedienbarkeit.
+- **Ein hinterlegtes CA-Zertifikat war unsichtbar und unlöschbar.** Das Feld stand beim Bearbeiten
+  leer da, der Hinweis darunter behauptete „ohne Eintrag gelten die Systemwurzeln“ — und ein
+  leeres Feld hieß „unverändert“. Das Zertifikat entschied also unsichtbar weiter mit.
+- **Ein Test, der sich selbst aus dem Weg ging:** die Zusicherung im Nebenläufigkeitstest der
+  Vorlagen stand in einem `if`. Gewann das Speichern das Rennen, lief der Test durch, ohne etwas zu
+  belegen. Jetzt werden beide Ausgänge geprüft.
+- **Eine Stunde gegen einen alten Server geprüft.** Der gebaute Stand lief, sah richtig aus und
+  zeigte trotzdem keine der neuen Funktionen — auf Port 3300 hing noch ein `next start` aus einer
+  früheren Sitzung, und der neue Start scheiterte still an `EADDRINUSE`. Seitdem: erst
+  nachsehen, wer auf dem Port sitzt, dann glauben, was die Seite zeigt.
+- **Das Screenshot-Skript hat bei jedem Lauf zwei PNG-Dateien angefasst.** `kachelnErzeugen`
+  schrieb `public/icon-*.png` immer neu; `git status` zeigte Änderungen, die niemand gemacht hatte.
+  Jetzt wird verglichen und nur bei echtem Unterschied geschrieben.
+
+### Nächster Schritt
+
+- #017 Seed der sieben Vorlagen — alle sieben wortgetreu als veröffentlichte Version 1, dazu die
+  Beispieldaten und der Modus `DIENSTLEISTUNG` mit „Musterfirma GmbH“ und „Bäckerei Reiter“.

docs/issues/016-verzeichnis-ldap.md

@@ -1,9 +1,9 @@
 # #016 M11 – Verzeichnis und LDAP-Abgleich
 
-**Status:** offen
+**Status:** erledigt
 **Meilenstein:** v0.1.0
 **Labels:** phase-1, backend, frontend, security
-**Geschätzt:** 12 h   **Tatsächlich:** –
+**Geschätzt:** 12 h   **Tatsächlich:** 3 h 25 min
 
 ## Ziel
 
@@ -11,29 +11,61 @@ Die Mitarbeiter der eigenen Firma kommen aus dem Active Directory, damit beim St
 
 ## Aufgaben
 
-- [ ] `ldapts` 9.x: `ldaps` bevorzugt, StartTLS optional, eigenes CA-Zertifikat hinterlegbar (`caCertPem`), `minVersion: TLSv1.2`
-- [ ] `searchPaginated` mit `pageSize: 1000` — **nicht** `search` mit `paged`, das puffert alles im Speicher
-- [ ] `explicitBufferAttributes: ['objectGUID']` und korrekte Umsortierung der gemischt-endianen Bytes zur GUID-Zeichenkette als `externeId`
-- [ ] Standardfilter `(&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))`
-- [ ] Attribut-Mapping mit AD-Vorgaben: `givenName`, `sn`, `displayName`, `mail`, `userPrincipalName` → `upn`, `sAMAccountName` → `sam`, `department`, `title`, `manager` → `vorgesetzterExterneId`, `distinguishedName` → `dn`
-- [ ] „Verbindung testen“: zeigt die ersten 10 Treffer mit gemappten Feldern, ohne etwas zu schreiben
-- [ ] `abgleichService`: anlegen, aktualisieren, verschwundene oder deaktivierte Konten auf `aktiv = false` — **nie löschen**; Ergebnis (angelegt/aktualisiert/deaktiviert/Fehler) in `letzterAbgleichStatus`, `letzterAbgleichFehler`, `letzterAbgleichAm` und im `Protokoll`
-- [ ] Zeitplan mit `node-cron` im selben Prozess, Intervall je Quelle (Standard 60 min), Sperre über `AbgleichSperre` in der Datenbank, damit nur eine Instanz läuft; zusätzlich „Jetzt abgleichen“
-- [ ] Bind-Passwort verschlüsselt über `src/lib/geheimnisse.ts`, Serializer entfernt `bindPasswortVerschluesselt` aus jeder Antwort
-- [ ] Admin → Verzeichnis: Quelle anlegen und bearbeiten, Verbindung testen, Abgleich-Status und -Log, „Jetzt abgleichen“
-- [ ] Manuelle Mitarbeiter und CSV-Import (`givenName`, `sn`, `displayName`, `mail`, `upn`, `sam`, `department`, `title`)
-- [ ] Abteilungsvorschläge aus den `department`-Werten des Abgleichs, vom Admin in `Abteilung`-Einträge übernehmbar
-- [ ] Nur die gemappten Attribute speichern: keine Passwörter, keine Gruppenmitgliedschaften des Mitarbeiters
-- [ ] `docker-compose.test.yml` um OpenLDAP erweitern, mit AD-ähnlichem Fixture-Schema (`sAMAccountName`, `userPrincipalName`, binäres `objectGUID`) — aus #005 hierher verschoben, weil der Dienst erst hier benutzt wird
-- [ ] Screenshots Verzeichnis, Verbindungstest, Abgleich-Log, CSV-Import in `docs/screenshots/m11/`
+- [x] `ldapts` 9.x: `ldaps` bevorzugt, StartTLS optional, eigenes CA-Zertifikat hinterlegbar (`caCertPem`), `minVersion: TLSv1.2`
+- [x] `searchPaginated` mit `pageSize: 1000` — **nicht** `search` mit `paged`, das puffert alles im Speicher
+- [x] `explicitBufferAttributes: ['objectGUID']` und korrekte Umsortierung der gemischt-endianen Bytes zur GUID-Zeichenkette als `externeId`
+- [x] Standardfilter `(&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))`
+- [x] Attribut-Mapping mit AD-Vorgaben: `givenName`, `sn`, `displayName`, `mail`, `userPrincipalName` → `upn`, `sAMAccountName` → `sam`, `department`, `title`, `manager` → `vorgesetzterExterneId`, `distinguishedName` → `dn`
+- [x] „Verbindung testen“: zeigt die ersten 10 Treffer mit gemappten Feldern, ohne etwas zu schreiben
+- [x] `abgleichService`: anlegen, aktualisieren, verschwundene oder deaktivierte Konten auf `aktiv = false` — **nie löschen**; Ergebnis (angelegt/aktualisiert/deaktiviert/Fehler) in `letzterAbgleichStatus`, `letzterAbgleichFehler`, `letzterAbgleichAm` und im `Protokoll`
+- [x] Zeitplan mit `node-cron` im selben Prozess, Intervall je Quelle (Standard 60 min), Sperre über `AbgleichSperre` in der Datenbank, damit nur eine Instanz läuft; zusätzlich „Jetzt abgleichen“
+- [x] Bind-Passwort verschlüsselt über `src/lib/geheimnisse.ts`, Serializer entfernt `bindPasswortVerschluesselt` aus jeder Antwort
+- [x] Admin → Verzeichnis: Quelle anlegen und bearbeiten, Verbindung testen, Abgleich-Status und -Log, „Jetzt abgleichen“
+- [x] Manuelle Mitarbeiter und CSV-Import (`givenName`, `sn`, `displayName`, `mail`, `upn`, `sam`, `department`, `title`)
+- [x] Abteilungsvorschläge aus den `department`-Werten des Abgleichs, vom Admin in `Abteilung`-Einträge übernehmbar
+- [x] Nur die gemappten Attribute speichern: keine Passwörter, keine Gruppenmitgliedschaften des Mitarbeiters
+- [x] `docker-compose.test.yml` um OpenLDAP erweitern, mit AD-ähnlichem Fixture-Schema (`sAMAccountName`, `userPrincipalName`, binäres `objectGUID`) — aus #005 hierher verschoben, weil der Dienst erst hier benutzt wird
+- [x] Screenshots Verzeichnis, Verbindungstest, Abgleich-Log, CSV-Import in `docs/screenshots/m11/`
 
 ## Akzeptanzkriterien
 
-- [ ] Integrationstest gegen den Container: erster Lauf legt Mitarbeiter an, zweiter Lauf aktualisiert sie ohne Duplikate
-- [ ] Integrationstest: ein aus dem Verzeichnis entferntes Konto wird `aktiv = false` und bleibt in der Datenbank
-- [ ] Integrationstest: ein per `userAccountControl` deaktiviertes Konto wird `aktiv = false`
-- [ ] Test: `{{ou}}` wird korrekt aus dem `dn` abgeleitet
-- [ ] Test: `objectGUID` als Buffer ergibt reproduzierbar dieselbe GUID-Zeichenkette (bekannter Byte-Vektor als Fixture)
-- [ ] Test: keine API-Antwort und kein Server-Log enthält das Bind-Passwort im Klartext
-- [ ] Test: zwei gleichzeitig gestartete Abgleiche derselben Quelle — der zweite wird von der Sperre abgewiesen
-- [ ] Im Modus `DIENSTLEISTUNG` ist Admin → Verzeichnis nicht erreichbar
+- [x] Integrationstest gegen den Container: erster Lauf legt Mitarbeiter an, zweiter Lauf aktualisiert sie ohne Duplikate
+- [x] Integrationstest: ein aus dem Verzeichnis entferntes Konto wird `aktiv = false` und bleibt in der Datenbank
+- [x] Integrationstest: ein per `userAccountControl` deaktiviertes Konto wird `aktiv = false`
+- [x] Test: `{{ou}}` wird korrekt aus dem `dn` abgeleitet
+- [x] Test: `objectGUID` als Buffer ergibt reproduzierbar dieselbe GUID-Zeichenkette (bekannter Byte-Vektor als Fixture)
+- [x] Test: keine API-Antwort und kein Server-Log enthält das Bind-Passwort im Klartext
+- [x] Test: zwei gleichzeitig gestartete Abgleiche derselben Quelle — der zweite wird von der Sperre abgewiesen
+- [x] Im Modus `DIENSTLEISTUNG` ist Admin → Verzeichnis nicht erreichbar
+
+## Ergebnis
+
+Erledigt am 2026-09-26. **1098 Tests** (vorher 980) und **71 Ende-zu-Ende-Tests** (vorher 67) grün,
+Screenshots in `docs/screenshots/m11/`.
+
+Über die Vorgabe hinaus entstanden drei Dinge, die der Review verlangt hat und die zum Kern der
+Sache gehören:
+
+- **Eine Notbremse gegen den teuersten Fehler.** Lässt sich kein einziger gelesener Eintrag
+  zuordnen, wird niemand deaktiviert — der Lauf meldet einen Fehler mit Namen. Ein Tippfehler im
+  Kennungsattribut hätte sonst die gesamte Belegschaft abgeschaltet und dabei `ERFOLG` gemeldet.
+- **Die Attributzuordnung ist in der Oberfläche bearbeitbar.** Vorher stand sie nur in der
+  Datenbank, obwohl Code und Hilfetext etwas anderes versprachen.
+- **Ein Abgleich-Log je Quelle** mit den letzten zehn Läufen: gelesen, angelegt, übernommen,
+  aktualisiert, deaktiviert, übersprungen — und wer sie angestoßen hat, Mensch oder Zeitplan.
+
+### Der unabhängige Review
+
+Ein Blocker, acht Befunde, sieben Anmerkungen:
+
+- **Blocker: Abgleich ohne zuordenbare Einträge schaltete alle ab.** Siehe oben. Das Log hat den
+  Fall danach selbst dokumentiert — der Lauf um 01:20 zeigt „3 deaktiviert, 4 übersprungen“.
+- Übersprungene Einträge wurden mitdeaktiviert, obwohl sie im Ergebnis standen.
+- `VerbindungsFehler` erbte nicht von `VerzeichnisFehler`: falsches Passwort, falscher Basis-DN und
+  ein toter Server sahen in der Oberfläche identisch aus.
+- Ergebniscodes wie `0x31` standen roh in der Meldung.
+- Bei einem Abbruch mitten im Lesen stand „angelegt: 1500, gelesen: 0“.
+- `faelligeQuellen` fragte ohne Mandantengrenze.
+- Eine von Hand angelegte Person mit demselben `sam` wurde vom Abgleich verdoppelt.
+- Ein hinterlegtes CA-Zertifikat war unsichtbar und nicht entfernbar.
+- Die Intervallgrenzen liefen auseinander: 1440 Minuten in der Oberfläche, 10080 im Dienst.

docs/issues/README.md

@@ -20,8 +20,8 @@ Diese Dateien sind die Quelle; `pnpm issues:sync` spiegelt sie in den Gitea-Trac
 | #013 | [M8 – Läufe: Service und Abarbeitung](013-laeufe-abarbeitung.md) | erledigt | v0.1.0 | 14 h | 3 h 05 min |
 | #014 | [M9 – QR-Tags, Geräteseite, Etiketten, Scanner](014-qr-tags-geraeteseite.md) | erledigt | v0.1.0 | 12 h | 3 h 35 min |
 | #015 | [M10 – Dashboard und Archiv](015-dashboard-archiv.md) | erledigt | v0.1.0 | 8 h | 2 h 20 min |
-| #016 | [M11 – Verzeichnis und LDAP-Abgleich](016-verzeichnis-ldap.md) | offen | v0.1.0 | 12 h | – |
+| #016 | [M11 – Verzeichnis und LDAP-Abgleich](016-verzeichnis-ldap.md) | erledigt | v0.1.0 | 12 h | 3 h 25 min |
 | #017 | [M12 – Seed der sieben Vorlagen](017-seed-sieben-vorlagen.md) | offen | v0.1.0 | 8 h | – |
 | #018 | [M13 – E2E-Tests, Anleitung, PDF](018-e2e-anleitung-pdf.md) | offen | v0.1.0 | 14 h | – |
 | #019 | [M14 – Betriebswege und Release v0.1.0](019-betrieb-release.md) | offen | v0.1.0 | 10 h | – |
-| | **Summe** | | | **136 h** | **22 h 45 min** |
+| | **Summe** | | | **136 h** | **26 h 10 min** |