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: