# Phase 16: AD-Gruppen-Synchronisation - Context
**Gathered:** 2026-08-05
**Status:** Ready for planning
## Phase Boundary
Ausgewählte AD-Gruppen werden als Tessera-Gruppen importiert und dauerhaft nachgeführt: Name, Bestand und Mitgliedschaften kommen aus dem Verzeichnis. Der Admin wählt im LDAP-Bereich aus, welche Gruppen übernommen werden.
Damit entstehen zwei klar getrennte Arten von Gruppen: lokal angelegte und aus dem AD importierte. Eine lokale Gruppe kann nicht nachträglich an eine AD-Gruppe geknüpft werden.
Nicht in dieser Phase: OU-weite Automatik, verschachtelte AD-Gruppen, Rechtestufen innerhalb von Modulen.
## Implementation Decisions
### Auswahl und Import
- **D-01:** Der Import sitzt im LDAP-Bereich (`/admin/ldap`), nicht in der Gruppenverwaltung: AD-Gruppe auswählen, importieren — dasselbe Muster wie der dort bereits vorhandene Benutzer-Import. Die vorhandene AD-Gruppensuche wird wiederverwendet, keine zweite Suchmechanik.
- **D-02:** Nur ausdrücklich ausgewählte Gruppen werden übernommen. Keine pauschale Übernahme einer OU oder eines Filters — **Reversibility:** reversible.
### Namen
- **D-03:** `Group.name` gehört dem AD. Wird die Gruppe dort umbenannt, zieht Tessera beim nächsten Sync nach. In Tessera ist das Feld für importierte Gruppen gesperrt, mit Hinweis auf die Herkunft.
- **D-04:** Dazu kommt eine neue Spalte für einen **internen Namen**, die der Sync niemals anfasst. Ist sie gesetzt, zeigt die Oberfläche diesen Namen — in der Gruppenliste, als Spaltenkopf der Freigabe-Matrix und in den Chips im Benutzer-Detail. Der AD-Name bleibt im Bearbeiten-Dialog sichtbar, damit die Herkunft nachvollziehbar bleibt. Löst den Zielkonflikt zwischen „AD ist die Wahrheit" und „wir wollen einen eigenen Namen", ohne dass der Sync ihn zurücksetzt — **Reversibility:** one-way — neue Spalte plus Migration; nach Vergabe echter interner Namen ist ein Rückbau Datenverlust.
### Löschen im AD
- **D-05:** Verschwindet eine importierte Gruppe aus dem AD, wird die Tessera-Gruppe entfernt — samt Mitgliedschaften und Modulfreigaben. Die betroffenen Benutzer verlieren den darüber vergebenen Zugriff, ohne den Warndialog aus Phase 15 D-17; der greift nur beim Löschen über die Tessera-Oberfläche. Bewusst akzeptiert.
- **D-06:** War die gelöschte Gruppe die markierte Standardgruppe, wandert die Markierung weiter statt zu verschwinden: bevorzugt auf die lokale Gruppe „Alle Benutzer", sonst auf eine andere vorhandene Gruppe. Es darf kein Zustand entstehen, in dem ein Mandant ohne Standardgruppe dasteht und neue Benutzer nirgends beitreten. Der Sync protokolliert den Wechsel.
### Verhältnis zu Phase 15
- **D-07:** Eine lokal angelegte Gruppe kann **nicht** an eine AD-Gruppe gebunden werden. Die in Plan 15-06 gebaute Radio-Auswahl im Anlegen- und Bearbeiten-Dialog wird wieder entfernt. Begründung: Mit dem internen Namen (D-04) entfällt ihr Hauptzweck, und zwei Wege zum selben Ergebnis sind eine Fehlerquelle. Bestehende Gruppen mit gesetztem `ldapDn` gelten als importiert und werden vom Sync verwaltet.
### Claude's Discretion
- Benennung und Typ der neuen Spalte für den internen Namen sowie die Migration
- Ob der Import einen Sync sofort auslöst oder erst der nächste turnusmäßige Lauf die Mitglieder füllt
- Form des Sync-Berichts: welche Zahlen zurückgemeldet werden (importiert, umbenannt, gelöscht, Markierung verschoben)
- Verhalten bei Namenskollision, wenn eine importierte AD-Gruppe genauso heißt wie eine bestehende lokale Gruppe — `@@unique([tenantId, name])` erzwingt hier eine Entscheidung
- Ob der Import-Dialog bereits importierte Gruppen als solche kennzeichnet oder ausblendet
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Projekt-Kontext
- `.planning/ROADMAP.md` — Abschnitt „### Phase 16" mit Goal und fünf Success Criteria
- `.planning/phases/15-modul-berechtigungen-gruppen-user-grants/15-CONTEXT.md` — D-05 (Gruppenmodell), D-13 (Standardgruppen-Markierung), D-17 (Löschdialog), D-19/D-20 (Mitgliedschafts-Herkunft)
### Bestehender Code, der das Verhalten definiert
- `apps/api/src/ldap/ldap.service.ts` — AD-Gruppensuche (bereits für Import-Filter und Phase-15-Bindung genutzt), Mitgliedschafts-Abgleich für gebundene Gruppen
- `apps/api/src/groups/groups.service.ts` — `ensureDefaultGroup`, `update` mit der Standardgruppen-Transaktion, `@@unique([tenantId, name])`
- `apps/web/src/app/(portal)/admin/ldap/page.tsx` — Benutzer-Import als Vorbild für den Gruppen-Import
- `apps/web/src/app/(portal)/admin/groups/components/GroupFormModal.tsx` — enthält die zu entfernende AD-Radio-Auswahl (D-07)
## Existing Code Insights
### Reusable Assets
- AD-Gruppensuche im LdapService: liefert Gruppen samt DN, wird bereits an zwei Stellen konsumiert — der Import braucht keine neue LDAP-Logik
- Mitgliedschafts-Abgleich aus Plan 15-04: pflegt für jede Gruppe mit gesetztem `ldapDn` die `LDAP`-Mitgliedschaften und lässt `MANUAL` unangetastet. Importierte Gruppen fallen automatisch in diesen Pfad
- `ensureDefaultGroup` (Quick-Task 260805-fok): garantiert, dass „Alle Benutzer" existiert — damit ist das Ziel für die Markierungs-Rückgabe aus D-06 immer vorhanden
### Integration Points
- LDAP-Sync-Durchlauf — hier entstehen und verschwinden importierte Gruppen
- Gruppenliste, Freigabe-Matrix und Benutzer-Detail — überall greift der interne Name aus D-04
- `GroupFormModal` — Radio-Auswahl entfernen, Namensfeld für importierte Gruppen sperren
## Specific Ideas
- Der interne Name kam vom User selbst, mit der Begründung, den Reset beim nächsten Import zu umgehen — das ist die tragende Idee dieser Phase, nicht ein Detail
- „Eine lokale Gruppe soll nicht mit einer AD verknüpft werden können. Das ist ja Quatsch" — wörtlich; die Trennung der beiden Gruppenarten ist gewollt und soll auch in der Oberfläche sichtbar sein
## Deferred Ideas
- **DÖE-Ausschreibungen verlinken auf die API statt auf die Bekanntmachungsseite** — vollständig diagnostiziert in `.planning/todos/pending/2026-08-05-ausschreibungsportal-falsche-url.md`. Der User will das ausdrücklich erst NACH dieser Phase angehen; der Todo trägt den entsprechenden Auslöser. Gehört nicht in Phase 16 und ist keine Lücke darin.
- Verschachtelte AD-Gruppen (indirekte Mitgliedschaft über Untergruppen) — seit Phase 15 bewusst außerhalb
- OU-weite oder filterbasierte Automatik statt Einzelauswahl — vom User verworfen
---
*Phase: 16-ad-gruppen-synchronisation*
*Context gathered: 2026-08-05*