schulsync 0.1.0__py3-none-any.whl

schulsync/planner.py

@@ -0,0 +1,172 @@
+"""Der Planner: Soll/Ist-Vergleich nach dem Terraform-Prinzip.
+
+Eingaben:
+  * Soll-Zustand  – Personen aus dem Schulverwaltungs-Export
+  * Ist-Zustand   – von SchulSync verwaltete Konten aus dem AD
+
+Ausgabe: ein :class:`~schulsync.models.Plan` mit fünf Aktionsarten.
+Der Planner **verändert nichts** – er rechnet nur. Erst ``apply``
+führt den Plan aus. Dadurch ist jeder Lauf per Diff-Report
+nachvollziehbar und revisionssicher dokumentierbar.
+
+Sicherheitsnetz: Wenn der Export auffällig leer ist (würde mehr als
+``max_deaktivierungs_anteil`` der aktiven Konten deaktivieren), wird
+der Plan als Konflikt blockiert. Ein halber Export – falsche
+Berichtsvorlage, abgebrochener Download – soll nicht still eine
+halbe Schule deaktivieren.
+"""
+
+from __future__ import annotations
+
+from datetime import date, timedelta
+
+from .models import (
+    Anlegen,
+    Deaktivieren,
+    IstKonto,
+    Konflikt,
+    Loeschen,
+    Plan,
+    Reaktivieren,
+    SollPerson,
+    Umbenennen,
+    Verschieben,
+)
+from .usernames import erzeuge_benutzername
+
+MAX_DEAKTIVIERUNGS_ANTEIL = 0.5  # Notbremse gegen unvollständige Exporte
+
+
+def berechne_plan(
+    soll: list[SollPerson],
+    ist: list[IstKonto],
+    vergebene_benutzernamen: set[str],
+    benutzername_schema: str = "{vorname}.{nachname}",
+    notbremse: bool = True,
+) -> Plan:
+    """Berechnet den Plan. Deterministisch: gleiche Eingaben ⇒ gleicher Plan."""
+    plan = Plan()
+    ist_nach_id: dict[str, IstKonto] = {}
+
+    for konto in ist:
+        if not konto.quell_id:
+            plan.konflikte.append(
+                Konflikt(
+                    betrifft=konto.benutzername,
+                    grund=(
+                        "Konto liegt im SchulSync-Bereich, hat aber keine Quell-ID "
+                        "(employeeNumber). Manuell zuordnen oder herausverschieben."
+                    ),
+                )
+            )
+            continue
+        if konto.quell_id in ist_nach_id:
+            plan.konflikte.append(
+                Konflikt(
+                    betrifft=f"{konto.benutzername} / {ist_nach_id[konto.quell_id].benutzername}",
+                    grund=f"Quell-ID {konto.quell_id} ist im AD doppelt vergeben.",
+                )
+            )
+            continue
+        ist_nach_id[konto.quell_id] = konto
+
+    # Namen, die dieser Plan selbst vergibt, zählen sofort als belegt:
+    belegt = {b.lower() for b in vergebene_benutzernamen}
+    soll_ids: set[str] = set()
+
+    for person in sorted(soll, key=lambda p: (p.klasse or "", p.nachname, p.vorname, p.quell_id)):
+        soll_ids.add(person.quell_id)
+        konto = ist_nach_id.get(person.quell_id)
+
+        if konto is None:
+            # ---------------------------------------------------- ANLEGEN
+            try:
+                benutzername = erzeuge_benutzername(
+                    person.vorname, person.nachname, benutzername_schema, belegt
+                )
+            except ValueError as e:
+                plan.konflikte.append(Konflikt(betrifft=person.anzeigename, grund=str(e)))
+                continue
+            belegt.add(benutzername.lower())
+            plan.anlegen.append(Anlegen(person=person, benutzername=benutzername))
+            continue
+
+        veraendert = False
+
+        # ------------------------------------------------- REAKTIVIEREN
+        if not konto.aktiv:
+            plan.reaktivieren.append(Reaktivieren(konto=konto, nach_klasse=person.klasse))
+            veraendert = True
+        # -------------------------------------------------- VERSCHIEBEN
+        elif person.klasse != konto.klasse:
+            plan.verschieben.append(
+                Verschieben(konto=konto, von_klasse=konto.klasse, nach_klasse=person.klasse or "")
+            )
+            veraendert = True
+
+        # --------------------------------------------------- UMBENENNEN
+        if (person.vorname, person.nachname) != (konto.vorname, konto.nachname):
+            plan.umbenennen.append(
+                Umbenennen(
+                    konto=konto,
+                    neuer_vorname=person.vorname,
+                    neuer_nachname=person.nachname,
+                )
+            )
+            veraendert = True
+
+        if not veraendert:
+            plan.unveraendert += 1
+
+    # ------------------------------------------------------ DEAKTIVIEREN
+    aktive = [k for k in ist_nach_id.values() if k.aktiv]
+    abgaenger = sorted(
+        (k for k in aktive if k.quell_id not in soll_ids),
+        key=lambda k: (k.klasse or "", k.nachname, k.vorname),
+    )
+    plan.deaktivieren.extend(Deaktivieren(konto=k) for k in abgaenger)
+
+    # Notbremse: unvollständiger Export?
+    if (
+        notbremse
+        and aktive
+        and len(abgaenger) / len(aktive) > MAX_DEAKTIVIERUNGS_ANTEIL
+        and len(abgaenger) > 5
+    ):
+        plan.konflikte.append(
+            Konflikt(
+                betrifft=f"{len(abgaenger)} von {len(aktive)} aktiven Konten",
+                grund=(
+                    "Der Export würde mehr als die Hälfte aller aktiven Konten "
+                    "deaktivieren. Das deutet auf einen unvollständigen Export hin "
+                    "(falsche Berichtsvorlage? nur eine Klasse exportiert?). "
+                    "Bitte Export prüfen. Wenn es wirklich stimmt: --ohne-notbremse."
+                ),
+            )
+        )
+
+    return plan
+
+
+def berechne_cleanup(
+    ist: list[IstKonto],
+    heute: date,
+    frist_tage: int,
+) -> tuple[list[Loeschen], list[IstKonto]]:
+    """Findet Abgänger-Konten, deren Aufbewahrungsfrist abgelaufen ist.
+
+    Rückgabe: (endgültig zu löschen, noch in der Frist).
+    Konten ohne lesbaren Deaktivierungs-Stempel werden **nie** gelöscht.
+    """
+    loeschen: list[Loeschen] = []
+    wartend: list[IstKonto] = []
+    for konto in sorted(ist, key=lambda k: (k.nachname, k.vorname)):
+        if konto.aktiv or konto.deaktiviert_am is None:
+            continue
+        if heute >= konto.deaktiviert_am + timedelta(days=frist_tage):
+            loeschen.append(
+                Loeschen(konto=konto, deaktiviert_am=konto.deaktiviert_am, frist_tage=frist_tage)
+            )
+        else:
+            wartend.append(konto)
+    return loeschen, wartend

schulsync/report.py

@@ -0,0 +1,94 @@
+"""HTML-Diff-Report und Zugangsdaten-Briefe (Jinja2)."""
+
+from __future__ import annotations
+
+import csv
+from datetime import datetime
+from pathlib import Path
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+from . import __version__
+from .applier import NeuesKonto
+from .config import Config
+from .models import Plan, Rolle
+
+_env = Environment(
+    loader=PackageLoader("schulsync", "templates"),
+    autoescape=select_autoescape(["html"]),
+)
+
+
+def schreibe_report(
+    plan: Plan,
+    config: Config,
+    quelle: str,
+    pfad: Path,
+    zeitpunkt: datetime,
+    modus: str,
+) -> Path:
+    html = _env.get_template("report.html.j2").render(
+        plan=plan,
+        schule=config.schule.name,
+        quelle=quelle,
+        ziel=config.ldap.base_dn,
+        zeitpunkt=zeitpunkt.strftime("%d.%m.%Y %H:%M"),
+        modus=modus,
+        frist_tage=config.aufbewahrung.abgaenger_tage,
+        version=__version__,
+    )
+    pfad = Path(pfad)
+    pfad.write_text(html, encoding="utf-8")
+    return pfad
+
+
+def lese_zugangsdaten(pfad: Path) -> list[NeuesKonto]:
+    """Liest die von ``apply`` geschriebene Zugangsdaten-CSV wieder ein."""
+    zeilen = [
+        z for z in Path(pfad).read_text(encoding="utf-8").splitlines()
+        if z and not z.startswith("#")
+    ]
+    leser = csv.DictReader(zeilen, delimiter=";")
+    konten = []
+    for z in leser:
+        konten.append(
+            NeuesKonto(
+                benutzername=z["Benutzername"],
+                anzeigename=z["Name"],
+                klasse=z["Klasse"] or None,
+                rolle=Rolle(z["Rolle"]),
+                passwort=z["Initialpasswort"],
+            )
+        )
+    return konten
+
+
+def schreibe_briefe(
+    konten: list[NeuesKonto],
+    config: Config,
+    ziel_ordner: Path,
+    datum: str,
+) -> list[Path]:
+    """Erzeugt pro Klasse eine druckfertige HTML-Datei mit einem Brief
+    pro Konto (Seitenumbruch je Brief)."""
+    ziel_ordner = Path(ziel_ordner)
+    ziel_ordner.mkdir(parents=True, exist_ok=True)
+    vorlage = _env.get_template("briefe.html.j2")
+
+    nach_klasse: dict[str, list[NeuesKonto]] = {}
+    for k in sorted(konten, key=lambda k: (k.klasse or "", k.anzeigename)):
+        nach_klasse.setdefault(k.klasse or "ohne-Klasse", []).append(k)
+
+    dateien: list[Path] = []
+    for klasse, klassen_konten in nach_klasse.items():
+        html = vorlage.render(
+            konten=klassen_konten,
+            klasse=klasse,
+            schule=config.schule.name,
+            it_kontakt=config.schule.it_kontakt,
+            datum=datum,
+        )
+        datei = ziel_ordner / f"zugangsdaten-{klasse}.html"
+        datei.write_text(html, encoding="utf-8")
+        dateien.append(datei)
+    return dateien

schulsync/templates/briefe.html.j2

@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="de">
+<head>
+<meta charset="utf-8">
+<title>Zugangsdaten {{ klasse }} · {{ schule }}</title>
+<style>
+  * { box-sizing: border-box; }
+  body { font-family: "Segoe UI", system-ui, -apple-system, sans-serif;
+         color: #1a2332; margin: 0; line-height: 1.55; }
+  .brief { padding: 2.2cm 2cm; page-break-after: always; max-width: 21cm; margin: 0 auto; }
+  .brief:last-child { page-break-after: auto; }
+  .kopf { display: flex; justify-content: space-between; border-bottom: 2px solid #1a2332;
+          padding-bottom: .4rem; margin-bottom: 1.6rem; font-size: .9rem; color: #5c6675; }
+  h1 { font-size: 1.25rem; margin: 0 0 1rem; }
+  .zugang { border: 2px solid #1a2332; border-radius: .6rem; padding: 1rem 1.4rem;
+            margin: 1.2rem 0; display: grid; grid-template-columns: auto 1fr; gap: .35rem 1.5rem; }
+  .zugang dt { color: #5c6675; font-size: .85rem; align-self: center; }
+  .zugang dd { margin: 0; font-family: ui-monospace, Consolas, monospace;
+               font-size: 1.15rem; font-weight: 600; }
+  ol { padding-left: 1.2rem; } li { margin-bottom: .3rem; }
+  .fuss { margin-top: 1.6rem; font-size: .8rem; color: #5c6675;
+          border-top: 1px solid #e3e7ee; padding-top: .6rem; }
+  @media screen { .brief { border: 1px solid #e3e7ee; margin: 1rem auto; border-radius: .5rem; } }
+</style>
+</head>
+<body>
+{% for k in konten %}
+<div class="brief">
+  <div class="kopf">
+    <span><strong>{{ schule }}</strong> · IT</span>
+    <span>Klasse {{ k.klasse or "–" }} · {{ datum }}</span>
+  </div>
+  <h1>Dein Schul-Account, {{ k.anzeigename.split(" ")[0] }}!</h1>
+  <p>Hier sind deine Zugangsdaten für die Anmeldung an den Schulcomputern
+     und am WLAN. Bewahre dieses Blatt gut auf und zeige es niemandem.</p>
+  <dl class="zugang">
+    <dt>Name</dt><dd style="font-family: inherit; font-weight: 400;">{{ k.anzeigename }}</dd>
+    <dt>Benutzername</dt><dd>{{ k.benutzername }}</dd>
+    <dt>Startpasswort</dt><dd>{{ k.passwort }}</dd>
+  </dl>
+  <p><strong>Wichtig – deine ersten Schritte:</strong></p>
+  <ol>
+    <li>Melde dich mit Benutzername und Startpasswort an einem Schulcomputer an.</li>
+    <li>Du wirst sofort aufgefordert, ein <strong>eigenes neues Passwort</strong> zu wählen.
+        Das Startpasswort funktioniert danach nicht mehr.</li>
+    <li>Merke dir dein neues Passwort gut – bei Problemen hilft: {{ it_kontakt }}.</li>
+  </ol>
+  <div class="fuss">
+    Hinweis zum Datenschutz: Dein Konto wird automatisch aus den Daten der
+    Schulverwaltung erstellt und beim Verlassen der Schule wieder deaktiviert
+    und gelöscht. Fragen dazu beantwortet {{ it_kontakt }}.
+  </div>
+</div>
+{% endfor %}
+</body>
+</html>

schulsync/templates/report.html.j2

@@ -0,0 +1,206 @@
+<!DOCTYPE html>
+<html lang="de">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SchulSync-Plan · {{ schule }} · {{ zeitpunkt }}</title>
+<style>
+  :root {
+    --tinte: #1a2332; --grau: #5c6675; --linie: #e3e7ee; --papier: #f6f8fb;
+    --gruen: #1a7f4e; --gruen-bg: #e7f6ee;
+    --blau: #1f5fbf; --blau-bg: #e9f1fd;
+    --gelb: #9a6700; --gelb-bg: #fdf3d7;
+    --rot: #b3362c; --rot-bg: #fdecea;
+    --lila: #6f42c1; --lila-bg: #f1ebfb;
+  }
+  * { box-sizing: border-box; }
+  body {
+    font-family: "Segoe UI", system-ui, -apple-system, sans-serif;
+    color: var(--tinte); background: var(--papier);
+    margin: 0; padding: 2.5rem 1.5rem; line-height: 1.5;
+  }
+  .blatt { max-width: 60rem; margin: 0 auto; }
+  header { display: flex; justify-content: space-between; align-items: baseline;
+           flex-wrap: wrap; gap: .5rem; border-bottom: 3px solid var(--tinte);
+           padding-bottom: .75rem; margin-bottom: 1.5rem; }
+  h1 { font-size: 1.5rem; margin: 0; }
+  h1 small { color: var(--grau); font-weight: 400; }
+  .meta { color: var(--grau); font-size: .9rem; text-align: right; }
+  .karten { display: grid; grid-template-columns: repeat(auto-fit, minmax(9.5rem, 1fr));
+            gap: .75rem; margin-bottom: 2rem; }
+  .karte { background: #fff; border: 1px solid var(--linie); border-radius: .6rem;
+           padding: .9rem 1rem; }
+  .karte .zahl { font-size: 1.9rem; font-weight: 700; line-height: 1.1; }
+  .karte .label { font-size: .8rem; color: var(--grau); text-transform: uppercase;
+                  letter-spacing: .04em; }
+  .karte.gruen .zahl { color: var(--gruen); } .karte.blau .zahl { color: var(--blau); }
+  .karte.gelb .zahl { color: var(--gelb); }  .karte.rot .zahl { color: var(--rot); }
+  .karte.lila .zahl { color: var(--lila); }
+  section { background: #fff; border: 1px solid var(--linie); border-radius: .6rem;
+            margin-bottom: 1.25rem; overflow: hidden; }
+  section > h2 { font-size: 1rem; margin: 0; padding: .7rem 1rem; display: flex;
+                 align-items: center; gap: .5rem; }
+  .marke { display: inline-block; min-width: 1.6rem; text-align: center; padding: .1rem .45rem;
+           border-radius: 99px; font-size: .8rem; font-weight: 700; }
+  section.gruen > h2 { background: var(--gruen-bg); } section.gruen .marke { background: var(--gruen); color:#fff; }
+  section.blau  > h2 { background: var(--blau-bg); }  section.blau  .marke { background: var(--blau); color:#fff; }
+  section.gelb  > h2 { background: var(--gelb-bg); }  section.gelb  .marke { background: var(--gelb); color:#fff; }
+  section.rot   > h2 { background: var(--rot-bg); }   section.rot   .marke { background: var(--rot); color:#fff; }
+  section.lila  > h2 { background: var(--lila-bg); }  section.lila  .marke { background: var(--lila); color:#fff; }
+  table { width: 100%; border-collapse: collapse; font-size: .92rem; }
+  th { text-align: left; color: var(--grau); font-weight: 600; font-size: .8rem;
+       text-transform: uppercase; letter-spacing: .03em; }
+  th, td { padding: .5rem 1rem; border-top: 1px solid var(--linie); }
+  tbody tr:hover { background: var(--papier); }
+  code { background: var(--papier); border: 1px solid var(--linie); border-radius: .3rem;
+         padding: .05rem .35rem; font-size: .88em; }
+  .pfeil { color: var(--grau); padding: 0 .3rem; }
+  .hinweis { background: #fff; border: 1px dashed var(--linie); border-radius: .6rem;
+             padding: .8rem 1rem; color: var(--grau); font-size: .88rem; }
+  .konflikt td:last-child { color: var(--rot); }
+  footer { margin-top: 2rem; color: var(--grau); font-size: .8rem;
+           border-top: 1px solid var(--linie); padding-top: .75rem; }
+  @media print {
+    body { background: #fff; padding: 0; }
+    section, .karte { border-color: #bbb; break-inside: avoid; }
+  }
+</style>
+</head>
+<body>
+<div class="blatt">
+  <header>
+    <h1>SchulSync-Plan <small>· {{ schule }}</small></h1>
+    <div class="meta">
+      {{ zeitpunkt }}<br>
+      Quelle: <code>{{ quelle }}</code> · Ziel: <code>{{ ziel }}</code><br>
+      Modus: <strong>{{ modus }}</strong>
+    </div>
+  </header>
+
+  <div class="karten">
+    <div class="karte gruen"><div class="zahl">{{ plan.anlegen | length }}</div><div class="label">Anlegen</div></div>
+    <div class="karte blau"><div class="zahl">{{ plan.verschieben | length }}</div><div class="label">Klassenwechsel</div></div>
+    <div class="karte gelb"><div class="zahl">{{ plan.umbenennen | length }}</div><div class="label">Umbenennen</div></div>
+    <div class="karte lila"><div class="zahl">{{ plan.reaktivieren | length }}</div><div class="label">Reaktivieren</div></div>
+    <div class="karte rot"><div class="zahl">{{ plan.deaktivieren | length }}</div><div class="label">Deaktivieren</div></div>
+    <div class="karte"><div class="zahl">{{ plan.unveraendert }}</div><div class="label">Unverändert</div></div>
+  </div>
+
+  {% if plan.konflikte %}
+  <section class="rot">
+    <h2><span class="marke">{{ plan.konflikte | length }}</span> Konflikte – bitte zuerst klären</h2>
+    <table>
+      <thead><tr><th>Betrifft</th><th>Grund</th></tr></thead>
+      <tbody>
+      {% for k in plan.konflikte %}
+        <tr class="konflikt"><td>{{ k.betrifft }}</td><td>{{ k.grund }}</td></tr>
+      {% endfor %}
+      </tbody>
+    </table>
+  </section>
+  {% endif %}
+
+  {% if plan.anlegen %}
+  <section class="gruen">
+    <h2><span class="marke">＋</span> Anlegen ({{ plan.anlegen | length }})</h2>
+    <table>
+      <thead><tr><th>Name</th><th>Klasse</th><th>Benutzername</th><th>Rolle</th></tr></thead>
+      <tbody>
+      {% for a in plan.anlegen %}
+        <tr>
+          <td>{{ a.person.anzeigename }}</td>
+          <td>{{ a.person.klasse or "–" }}</td>
+          <td><code>{{ a.benutzername }}</code></td>
+          <td>{{ "Lehrkraft" if a.person.rolle.value == "lehrkraft" else "Schüler:in" }}</td>
+        </tr>
+      {% endfor %}
+      </tbody>
+    </table>
+  </section>
+  {% endif %}
+
+  {% if plan.verschieben %}
+  <section class="blau">
+    <h2><span class="marke">⇄</span> Klassenwechsel ({{ plan.verschieben | length }})</h2>
+    <table>
+      <thead><tr><th>Name</th><th>Benutzername</th><th>Wechsel</th></tr></thead>
+      <tbody>
+      {% for v in plan.verschieben %}
+        <tr>
+          <td>{{ v.konto.anzeigename }}</td>
+          <td><code>{{ v.konto.benutzername }}</code></td>
+          <td>{{ v.von_klasse or "–" }}<span class="pfeil">→</span><strong>{{ v.nach_klasse }}</strong></td>
+        </tr>
+      {% endfor %}
+      </tbody>
+    </table>
+  </section>
+  {% endif %}
+
+  {% if plan.umbenennen %}
+  <section class="gelb">
+    <h2><span class="marke">✎</span> Umbenennen ({{ plan.umbenennen | length }})</h2>
+    <table>
+      <thead><tr><th>Benutzername</th><th>Bisher</th><th>Neu</th></tr></thead>
+      <tbody>
+      {% for u in plan.umbenennen %}
+        <tr>
+          <td><code>{{ u.konto.benutzername }}</code></td>
+          <td>{{ u.konto.anzeigename }}</td>
+          <td><strong>{{ u.neuer_vorname }} {{ u.neuer_nachname }}</strong></td>
+        </tr>
+      {% endfor %}
+      </tbody>
+    </table>
+  </section>
+  {% endif %}
+
+  {% if plan.reaktivieren %}
+  <section class="lila">
+    <h2><span class="marke">↻</span> Reaktivieren – Rückkehrer ({{ plan.reaktivieren | length }})</h2>
+    <table>
+      <thead><tr><th>Name</th><th>Benutzername</th><th>Neue Klasse</th></tr></thead>
+      <tbody>
+      {% for r in plan.reaktivieren %}
+        <tr>
+          <td>{{ r.konto.anzeigename }}</td>
+          <td><code>{{ r.konto.benutzername }}</code></td>
+          <td><strong>{{ r.nach_klasse or "–" }}</strong></td>
+        </tr>
+      {% endfor %}
+      </tbody>
+    </table>
+  </section>
+  {% endif %}
+
+  {% if plan.deaktivieren %}
+  <section class="rot">
+    <h2><span class="marke">⏻</span> Deaktivieren – Abgänger ({{ plan.deaktivieren | length }})</h2>
+    <table>
+      <thead><tr><th>Name</th><th>Benutzername</th><th>Bisherige Klasse</th><th>Weiteres Vorgehen</th></tr></thead>
+      <tbody>
+      {% for d in plan.deaktivieren %}
+        <tr>
+          <td>{{ d.konto.anzeigename }}</td>
+          <td><code>{{ d.konto.benutzername }}</code></td>
+          <td>{{ d.konto.klasse or "–" }}</td>
+          <td>Abgänger-OU, Löschung nach {{ frist_tage }} Tagen (<code>schulsync cleanup</code>)</td>
+        </tr>
+      {% endfor %}
+      </tbody>
+    </table>
+  </section>
+  {% endif %}
+
+  {% if plan.leer and not plan.konflikte %}
+  <p class="hinweis">✔ Keine Abweichungen – Active Directory und Schulverwaltung sind synchron.</p>
+  {% endif %}
+
+  <footer>
+    Erzeugt von <strong>SchulSync {{ version }}</strong> am {{ zeitpunkt }}.
+    Dieses Dokument enthält personenbezogene Daten – vertraulich behandeln und
+    nach Gebrauch löschen (Art. 5 Abs. 1 lit. e DSGVO).
+  </footer>
+</div>
+</body>
+</html>

schulsync/usernames.py

@@ -0,0 +1,91 @@
+"""Benutzernamen-Erzeugung.
+
+Regeln, die sich im Schulbetrieb bewährt haben:
+
+* Schema konfigurierbar (Standard ``vorname.nachname``), alles klein.
+* Umlaute & Co. werden AD-tauglich transliteriert: ``Müller`` → ``mueller``,
+  ``Yılmaz`` → ``yilmaz``, ``Đorđević`` → ``dordevic``. Schulen sind
+  vielfältig – die Benutzernamen müssen es aushalten.
+* ``sAMAccountName`` ist historisch auf **20 Zeichen** begrenzt – wird
+  gekürzt, bevor das AD einen kryptischen Fehler wirft.
+* Kollisionen (zweite ``lena.schmidt``) bekommen einen Zähler: ``lena.schmidt2``.
+* Deterministisch: gleicher Input ⇒ gleicher Benutzername.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+SAM_MAX = 20  # historisches NetBIOS-Limit für sAMAccountName
+
+# Gezielte Ersetzungen, die NFKD nicht (oder falsch) erledigt:
+_ERSETZUNGEN = str.maketrans(
+    {
+        "ä": "ae", "ö": "oe", "ü": "ue", "ß": "ss",
+        "Ä": "ae", "Ö": "oe", "Ü": "ue", "ẞ": "ss",
+        "ı": "i", "İ": "i",          # Türkisch
+        "ð": "d", "Ð": "d",
+        "đ": "d", "Đ": "d",          # Südslawisch
+        "ø": "oe", "Ø": "oe",
+        "æ": "ae", "Æ": "ae",
+        "œ": "oe", "Œ": "oe",
+        "þ": "th", "Þ": "th",
+        "ł": "l", "Ł": "l",          # Polnisch
+    }
+)
+
+
+def transliteriere(text: str) -> str:
+    """Wandelt einen Namen in reines ASCII-Kleinbuchstaben-Format um."""
+    text = text.translate(_ERSETZUNGEN)
+    # NFKD zerlegt z. B. é in e + Akzent; die Akzente werden verworfen.
+    text = unicodedata.normalize("NFKD", text)
+    text = "".join(c for c in text if not unicodedata.combining(c))
+    text = text.lower()
+    text = re.sub(r"[\s']+", "-", text.strip())  # Leerzeichen/Apostroph → Bindestrich
+    text = re.sub(r"[^a-z0-9-]", "", text)  # Rest raus (AD-sicher)
+    text = re.sub(r"-{2,}", "-", text).strip("-")
+    return text
+
+
+def _kuerze(basis: str, max_len: int) -> str:
+    return basis[:max_len].rstrip(".-")
+
+
+def erzeuge_benutzername(
+    vorname: str,
+    nachname: str,
+    schema: str = "{vorname}.{nachname}",
+    vergeben: set[str] | None = None,
+) -> str:
+    """Erzeugt einen eindeutigen, AD-tauglichen Benutzernamen.
+
+    ``vergeben`` enthält alle bereits existierenden sAMAccountNames der
+    Domäne (nicht nur die von SchulSync verwalteten!) – sonst kollidiert
+    die neue Schülerin irgendwann mit dem Hausmeister-Konto.
+    """
+    vergeben = {v.lower() for v in (vergeben or set())}
+    # Bei mehrteiligen Vornamen zählt der Rufname (erster Teil):
+    erster_vorname = vorname.strip().split()[0] if vorname.strip() else vorname
+    basis = schema.format(
+        vorname=transliteriere(erster_vorname),
+        nachname=transliteriere(nachname),
+    )
+    basis = re.sub(r"\.{2,}", ".", basis).strip(".")
+    if not basis.replace(".", "").replace("-", ""):
+        raise ValueError(
+            f"Aus '{vorname} {nachname}' lässt sich kein Benutzername bilden – "
+            "bitte Datensatz in der Schulverwaltung prüfen."
+        )
+
+    kandidat = _kuerze(basis, SAM_MAX)
+    if kandidat.lower() not in vergeben:
+        return kandidat
+
+    for zaehler in range(2, 1000):
+        suffix = str(zaehler)
+        kandidat = _kuerze(basis, SAM_MAX - len(suffix)) + suffix
+        if kandidat.lower() not in vergeben:
+            return kandidat
+    raise ValueError(f"Kein freier Benutzername für '{vorname} {nachname}' gefunden.")