From 5c7d4ad128ab6bcd9f0fca7e2ac6e9dcf6ed1ddc Mon Sep 17 00:00:00 2001 From: Schalli Date: Thu, 6 Aug 2026 14:10:53 +0200 Subject: [PATCH] docs(16): reassign PERM-02 to phase 16 with import semantics --- .planning/REQUIREMENTS.md | 6 +- .planning/ROADMAP.md | 2 +- .../16-PATTERNS.md | 715 ++++++++++++++++++ 3 files changed, 719 insertions(+), 4 deletions(-) create mode 100644 .planning/phases/16-ad-gruppen-synchronisation/16-PATTERNS.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index accc786..9b050c1 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -64,7 +64,7 @@ ### PERM — Modul-Berechtigungen - [x] **PERM-01**: Admin verwaltet Gruppen pro Mandant (anlegen, umbenennen, löschen) und weist Benutzer manuell zu oder entfernt sie. Beim Löschen einer belegten Gruppe warnt ein Dialog mit Mitglieder- und Freigabenanzahl, bevor Mitgliedschaften und Freigaben mitgelöscht werden. -- [ ] **PERM-02**: Eine Gruppe kann optional an einen AD-Gruppen-DN gebunden werden, ausgewählt aus der bestehenden LDAP-Gruppensuche. Der Benutzer-Sync liest `memberOf` mit und pflegt daraus die Mitgliedschaften; verlässt ein Benutzer die AD-Gruppe, fällt nur seine LDAP-Mitgliedschaft weg — manuell gesetzte bleiben bestehen. +- [ ] **PERM-02**: Ein Admin wählt im LDAP-Bereich einzelne AD-Gruppen aus und importiert sie; je ausgewählter Gruppe entsteht eine Tessera-Gruppe mit AD-Bindung, nicht ausgewählte werden nicht angelegt. Der bestehende Benutzer-Sync führt sie danach nach: Umbenennung im AD zieht in den Gruppennamen nach, Verschwinden aus dem AD löscht die Tessera-Gruppe samt Mitgliedschaften und Modulfreigaben, und `memberOf` pflegt die Mitgliedschaften — verlässt ein Benutzer die AD-Gruppe, fällt nur seine LDAP-Mitgliedschaft weg, manuell gesetzte bleiben bestehen. Lokal angelegte Gruppen ohne AD-Bindung bleiben vom Gruppen-Sync unberührt und können nicht nachträglich gebunden werden. *(Neu gefasst 2026-08-06 nach Phase-16-Entscheidungen D-01/D-05/D-07 — die frühere Fassung „lokale Gruppe an AD-DN binden" ist verworfen.)* - [x] **PERM-03**: Admin gibt ein mandantenweit aktives Modul gezielt für Gruppen und für einzelne Benutzer frei und entzieht Freigaben wieder. Gruppenfreigaben werden in einer Matrix Module × Gruppen gepflegt, Einzelfreigaben im Benutzer-Detail samt Anzeige der über Gruppen geerbten Rechte. - [x] **PERM-04**: Ohne Freigabe hat ein USER keinen Zugriff: das Modul fehlt in der Sidebar, die Modulseite antwortet mit einer 403-Seite samt Hinweis, und die Modul-API antwortet mit 403. Sidebar, Modulseite und API nutzen dieselbe Zugriffsauflösung. - [x] **PERM-05**: ADMIN und SUPER_ADMIN sehen und nutzen innerhalb ihres Mandanten alle aktiven Module ohne Freigabe. @@ -123,11 +123,11 @@ | UI-06 | Phase 14 | Complete | | PERM-01 | Phase 15 | Complete | -| PERM-02 | Phase 15 | Pending | +| PERM-02 | Phase 16 | Pending | | PERM-03 | Phase 15 | Complete | | PERM-04 | Phase 15 | Complete | | PERM-05 | Phase 15 | Pending | | PERM-06 | Phase 15 | Pending | | PERM-07 | Phase 15 | Complete | -**Coverage:** 29/29 v1.1 requirements mapped — no orphans. 7/7 v1.2 requirements mapped auf Phase 15. +**Coverage:** 29/29 v1.1 requirements mapped — no orphans. 7/7 v1.2 requirements mapped: PERM-01/03/04/05/06/07 auf Phase 15, PERM-02 auf Phase 16 (umgehängt 2026-08-06). diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b3e95f7..1944096 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -543,7 +543,7 @@ Plans: **Goal:** Ausgewählte AD-Gruppen werden als Tessera-Gruppen angelegt und dauerhaft nachgeführt, statt jede Gruppe von Hand anzulegen und zu binden. Der Admin wählt aus der AD-Gruppenliste aus, welche Gruppen übernommen werden; der bestehende Benutzer-Sync hält Bestand, Namen und Mitgliedschaften danach aktuell. **Depends on**: Phase 15 -**Requirements**: TBD (werden in /gsd-plan-phase 16 vergeben) +**Requirements**: PERM-02 **Success Criteria** (what must be TRUE): 1. Ein Admin wählt aus der AD-Gruppenliste einzelne Gruppen zur Übernahme aus; für jede ausgewählte Gruppe entsteht eine Tessera-Gruppe mit gesetzter AD-Bindung diff --git a/.planning/phases/16-ad-gruppen-synchronisation/16-PATTERNS.md b/.planning/phases/16-ad-gruppen-synchronisation/16-PATTERNS.md new file mode 100644 index 0000000..35454c4 --- /dev/null +++ b/.planning/phases/16-ad-gruppen-synchronisation/16-PATTERNS.md @@ -0,0 +1,715 @@ +# Phase 16: AD-Gruppen-Synchronisation - Pattern Map + +**Mapped:** 2026-08-06 +**Files analyzed:** 13 +**Analogs found:** 13 / 13 + +## File Classification + +| New/Modified File | Role | Data Flow | Closest Analog | Match Quality | +|--------------------|------|-----------|-----------------|----------------| +| `apps/api/prisma/schema.prisma` (`Group.internalName`, `Group.ldapObjectGuid`) | model | CRUD | `apps/api/prisma/schema.prisma:137-152` (`Group`-Modell selbst) | exact | +| `apps/api/prisma/migrations/_add_group_internal_name_and_object_guid/migration.sql` | migration | batch | `20260804130130_add_groups_and_module_grants/migration.sql` (Spalten/Index) + `20260804130918_groups_rls_policies/migration.sql` (RLS-Referenz, unverändert zu übernehmen) | exact | +| `apps/api/src/ldap/ldap.service.ts` — `importGroupsByDn()` | service | batch (LDAP → DB) | `importUsersByDn()` (Zeilen 447-547) | exact | +| `apps/api/src/ldap/ldap.service.ts` — `syncBoundGroupsForTenant()` | service | batch (LDAP → DB, reconciliation) | `syncGroupMembershipsForTenant()` (Zeilen 839-935) | exact | +| `apps/api/src/ldap/ldap.controller.ts` — `POST /ldap/groups/import` | controller | request-response | `POST /ldap/users/import` (`importUsers()`, Zeilen 215-245) | exact | +| `apps/api/src/ldap/dto/ldap-config.dto.ts` — `ImportGroupsDto` | model (DTO) | request-response | `ImportUsersDto` (Zeilen 109-114) | exact | +| `apps/api/src/groups/groups.service.ts` — `internalName`-Handling, Name-Lock, Default-Handoff | service | CRUD | `update()` (Zeilen 99-154), `findOwned()` (78-86), `ensureDefaultGroup()` (277-328) | exact | +| `apps/api/src/groups/module-grants.service.ts` (Zeilen ~249/264) | service | transform (Projektion) | dieselbe Datei, Zeilen 244-267 (`groupNamesByModule`/`groups`-Projektion) | exact | +| `apps/api/src/ldap/ldap.service.spec.ts` (neue `describe`-Blöcke) | test | batch | bestehende `describe`-Blöcke für `syncGroupMembershipsForTenant`/D-21 im selben File | exact | +| `apps/api/src/groups/groups.service.spec.ts` (Mock-Anpassung `findFirst`) | test | CRUD | bestehende Mock-Struktur für `GroupsService.update`/`findOwned` im selben File | exact | +| `apps/web/src/app/(portal)/admin/ldap/page.tsx` — Sektion "AD-Gruppen importieren" | component | request-response (discover + import) | Sektion 2.55 "Einzelbenutzer suchen & importieren" (Zeilen 808-909) + Sektion 2.5 (684-806) für das reine Auswahllisten-Markup | exact | +| `apps/web/src/app/(portal)/admin/groups/components/GroupFormModal.tsx` | component | request-response (form) | dieselbe Datei — bestehendes Namensfeld (136-145) und `saveError`-Banner (229-233) als Vorbild für den neuen, jetzt konsequent genutzten Fehlerzustand | exact | +| `apps/web/src/app/(portal)/admin/groups/page.tsx` (Namensspalte) | component | CRUD (Anzeige) | dieselbe Datei, Namens-/Badge-Zellen (Zeilen 179-190) | exact | +| `apps/web/src/app/(portal)/admin/modules/grants/page.tsx` (Zeilen ~206-213) | component | transform (Anzeige) | dieselbe Datei, `th`-Block (Zeilen 206-213) | exact | +| `apps/web/src/messages/de.json` / `en.json` | config | — | bestehende `admin.ldap.*`/`admin.groups.*`-Blöcke (de.json Zeilen 334-398) | exact | + +## Pattern Assignments + +### `apps/api/prisma/schema.prisma` — `Group.internalName`, `Group.ldapObjectGuid` (model, CRUD) + +**Analog:** das `Group`-Modell selbst, `apps/api/prisma/schema.prisma:137-152` + +```prisma +model Group { + id String @id @default(uuid()) + tenantId String + tenant Tenant @relation(fields: [tenantId], references: [id]) + name String + ldapDn String? // optionale AD-Bindung (D-05) + isDefault Boolean @default(false) // D-13 — genau eine pro Mandant, DB-erzwungen (Hand-SQL) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + memberships GroupMembership[] + grants ModuleGrant[] + + @@unique([tenantId, name]) // Gruppennamen sind pro Mandant eindeutig + @@unique([tenantId, ldapDn]) // NULL ist in Postgres je Zeile distinct — mehrere ungebundene Gruppen sind erlaubt + @@index([tenantId]) +} +``` + +Neue Spalten folgen exakt demselben Kommentar-/Nullable-Stil wie `ldapDn`: +```prisma + internalName String? // D-04: vom Sync nie berührt, überschreibt die Anzeige wenn gesetzt + ldapObjectGuid String? // D-03/SC-3: hex-kodierter objectGUID, rename-stabiler Sync-Match-Key (ldapDn bleibt Anzeige-/Debug-Feld) + + @@unique([tenantId, ldapObjectGuid]) // gleiches NULL-ist-distinct-Muster wie @@unique([tenantId, ldapDn]) +``` +`internalName` trägt bewusst **keinen** eigenen Unique-Index — zwei Gruppen dürfen denselben internen Namen tragen (keine Entscheidung dagegen in D-04). + +--- + +### `apps/api/prisma/migrations/_...` (migration, batch) + +**Analog 1 (Spalten/Index-Stil):** `apps/api/prisma/migrations/20260804130130_add_groups_and_module_grants/migration.sql`, Zeilen 1-46: +```sql +CREATE TABLE "Group" ( + "id" TEXT NOT NULL, + "tenantId" TEXT NOT NULL, + "name" TEXT NOT NULL, + "ldapDn" TEXT, + ... +); +CREATE UNIQUE INDEX "Group_tenantId_ldapDn_key" ON "Group"("tenantId", "ldapDn"); +``` +→ Analoges Muster für die neue Migration: `ALTER TABLE "Group" ADD COLUMN "internalName" TEXT, ADD COLUMN "ldapObjectGuid" TEXT;` + `CREATE UNIQUE INDEX "Group_tenantId_ldapObjectGuid_key" ON "Group"("tenantId", "ldapObjectGuid");` + +**Analog 2 (RLS-Referenz, NICHT erneut ausführen, nur als Kontext):** `apps/api/prisma/migrations/20260804130918_groups_rls_policies/migration.sql`, Zeilen 15-20 — bestätigt, dass `Group` bereits `FORCE ROW LEVEL SECURITY` trägt; die neue Migration braucht keine eigene RLS-Anweisung, die Policy greift automatisch auf die neuen Spalten mit. + +**Lokaler Migrationsbefehl** (aus RESEARCH.md, verifiziertes Muster): +```bash +docker start tessera-ctl-db-1 +DB_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' tessera-ctl-db-1) +cd apps/api && DATABASE_URL="postgresql://tessera:tessera_dev@${DB_IP}:5432/tessera" \ + pnpm exec prisma migrate dev --name add_group_internal_name_and_object_guid +``` + +--- + +### `apps/api/src/ldap/ldap.service.ts` — `importGroupsByDn()` (service, batch) + +**Analog:** `importUsersByDn()`, Zeilen 447-547 (vollständig gelesen) + +**Imports** (Datei-Kopf, Zeilen 1-5): +```typescript +import { Injectable, Logger } from '@nestjs/common'; +import { Client, Entry } from 'ldapts'; +import { PrismaService } from '../prisma/prisma.service'; +import { forTenant } from '../prisma/prisma-tenant.extension'; +import { UserService } from '../user/user.service'; +``` + +**Signatur- und Result-Muster:** +```typescript +async importUsersByDn( + config: LdapConfigData, + tenantId: string, + dns: string[], +): Promise { + const result: LdapUserImportResult = { created: 0, updated: 0, skipped: 0, errors: [] }; + const client = new Client(this.buildClientOptions(config.serverUrl, config.tlsRejectUnauthorized)); + try { + await this.bind(client, config.bindDn, config.bindPassword); + for (const dn of dns) { + try { + // Base-scoped lookup of exactly this DN. + const { searchEntries } = await client.search(dn, { filter: '(objectClass=person)', attributes, scope: 'base' }); + if (searchEntries.length === 0) { result.errors.push(`${dn}: not found`); continue; } + // ... map, dedup by existing ldapDn/username, create or skip ... + } catch (entryError: unknown) { + const msg = entryError instanceof Error ? entryError.message : 'Unknown error importing entry'; + result.errors.push(`${dn}: ${msg}`); + } + } + } finally { + try { await client.unbind(); } catch { /* Ignore unbind errors */ } + } + return result; +} +``` + +`importGroupsByDn()` folgt demselben Gerüst, aber mit `scope: 'base'`-Suche nach `(objectClass=group)`, Extraktion von `cn`+`objectGUID` (per `explicitBufferAttributes: ['objectGUID']`, siehe RESEARCH.md Pattern 2), und einem `prisma.group.create()`/`GroupsService`-Aufruf statt `userService.create()`. Für die Idempotenz-/Dedup-Prüfung ist `searchUsers()`s Existenz-Query das bessere Vorbild (siehe unten), nicht `importUsersByDn` selbst. + +**Idempotenz-/`alreadyImported`-Muster** (Analog: `searchUsers()`, Zeilen 404-430): +```typescript +const dns = entries.map((e) => e.dn); +const existing = await this.prisma.user.findMany({ + where: { tenantId, OR: [{ ldapDn: { in: dns } }, { username: { in: usernames } }] }, + select: { ldapDn: true, username: true }, +}); +const dnSet = new Set(existing.map((u) => u.ldapDn).filter((d): d is string => !!d)); +return entries.map((e) => ({ ...e, alreadyImported: dnSet.has(e.dn) || ... })); +``` +→ Gruppen-Äquivalent laut RESEARCH.md: `Group.findMany({ where: { tenantId, ldapObjectGuid: { in: guids } } })`. + +**Binäres Attribut lesen** (RESEARCH.md Pattern 2, Quelle: installierter `ldapts`-Bibliothekscode): +```typescript +const { searchEntries } = await client.search(baseDn, { + filter: '(objectClass=group)', + attributes: ['cn', 'dn', 'objectGUID'], + explicitBufferAttributes: ['objectGUID'], + scope: 'sub', +}); +const guidHex = (entry['objectGUID'] as Buffer).toString('hex'); +``` + +**Pro-Gruppe-Fehlersammlung ohne Lauf-Abbruch** (Analog: `syncGroupMembershipsForTenant`-Loop, Zeilen 860-934, siehe unten) — dasselbe try/catch-pro-Element-Muster gilt auch hier, insbesondere um eine `ConflictException` aus einer Namenskollision (Pitfall 4 in RESEARCH.md) in `result.errors` zu sammeln statt zu werfen. + +--- + +### `apps/api/src/ldap/ldap.service.ts` — `syncBoundGroupsForTenant()` (service, batch/reconciliation) + +**Analog:** `syncGroupMembershipsForTenant()`, Zeilen 839-935 (vollständig gelesen) — MUSS laut D-21-Reihenfolge **vor** diesem bestehenden Schritt in `syncUsersForTenant()` eingehängt werden (aktuell Aufruf bei Zeile 708-715). + +**Bestehender Aufrufpunkt in `syncUsersForTenant()`** (Zeilen 705-715): +```typescript +// 5b. D-21: reconcile GroupMembership rows for every AD-bound Group in +// this same run — no separate sync job, no second button. Runs behind +// the Base-DN no-op guard above, exactly like the rest of this method. +await this.syncGroupMembershipsForTenant( + client, config, sanitizedFilter, attributes, tenantId, result, +); +``` +→ Neuer Schritt `5a` unmittelbar davor einfügen: `await this.syncBoundGroupsForTenant(client, config, tenantId, result);` — Reihenfolge ist die zentrale Pitfall-1-Vorgabe aus RESEARCH.md. + +**Bound-Groups-Query + Pro-Gruppe-try/catch** (Zeilen 839-864, 927-934): +```typescript +private async syncGroupMembershipsForTenant( + client: Client, config: LdapConfigData, sanitizedFilter: string, + attributes: string[], tenantId: string, result: LdapSyncResult, +): Promise { + const tenantPrisma = forTenant(this.prisma, tenantId) as any; + const boundGroups: { id: string; name: string; ldapDn: string | null }[] = + await tenantPrisma.group.findMany({ + where: { tenantId, ldapDn: { not: null } }, + select: { id: true, name: true, ldapDn: true }, + }); + if (boundGroups.length === 0) { return; } + + for (const group of boundGroups) { + try { + // ... AD-Suche, Reconciliation ... + } catch (groupError: unknown) { + const msg = groupError instanceof Error ? groupError.message : 'Unknown error syncing group'; + result.errors.push(`Gruppe ${group.name}: ${msg}`); + } + } +} +``` +`syncBoundGroupsForTenant()` fragt stattdessen `where: { tenantId, ldapObjectGuid: { not: null } }` ab (Identität statt `ldapDn`, siehe Anti-Pattern in RESEARCH.md), sucht pro Gruppe per binärem `objectGUID`-Filter (RESEARCH.md Pattern 3), und verzweigt: Treffer mit geändertem `cn` → `Group.update({ name, ldapDn })`; kein Treffer → D-06-Handoff dann `group.delete()`. + +**Binärer Existenz-Sweep-Filter** (RESEARCH.md Pattern 3, `[ASSUMED]`, vor Prod-Schärfung gegen echtes AD zu prüfen): +```typescript +function escapeLdapFilterBuffer(buf: Buffer): string { + return Array.from(buf).map((b) => '\\' + b.toString(16).padStart(2, '0')).join(''); +} +const filter = `(objectGUID=${escapeLdapFilterBuffer(storedGuidBuffer)})`; +``` + +**Default-Marker-Handoff-Transaktion** (Analog: `GroupsService.update()`, `apps/api/src/groups/groups.service.ts:123-136`): +```typescript +if (data.isDefault === true) { + const [, updated] = await this.prisma.$transaction([ + this.prisma.group.updateMany({ where: { tenantId, isDefault: true }, data: { isDefault: false } }), + this.prisma.group.update({ where: { id }, data: { ...updateData, isDefault: true } }), + ]); + return updated; +} +``` +→ D-06-Handoff braucht eine NEUE Methode (z.B. `GroupsService.reassignDefaultBeforeDelete(tenantId, groupId)`), die die Zielgruppe selbst bestimmt (zuerst "Alle Benutzer" per `findFirst({ where: { tenantId, name: 'Alle Benutzer' } })`, sonst irgendeine andere per `findFirst({ where: { tenantId, id: { not: groupId } } })`), dann dieselbe Zwei-Schritt-Transaktionsform anwendet, BEVOR `group.delete()` läuft. Nach jeder Löschung `ensureDefaultGroup(tenantId)` als Fallback aufrufen (Pitfall 5), siehe `apps/api/src/groups/groups.service.ts:277-328`. + +**Escaping-Baustein** (bestehend, zwingend wiederverwenden für String-Filter, z.B. beim `cn`-Vergleich): +```typescript +static escapeLdapFilterValue(value: string): string { + return value + .replace(/\\/g, '\\5c') + .replace(/\*/g, '\\2a') + .replace(/\(/g, '\\28') + .replace(/\)/g, '\\29') + .replace(/\x00/g, '\\00'); +} +``` +(`apps/api/src/ldap/ldap.service.ts:977-984`) + +**Result-Interface wächst additiv** (Zeilen 10-20): +```typescript +export interface LdapSyncResult { + created: number; + updated: number; + deactivated: number; + groupMembershipsAdded: number; + groupMembershipsRemoved: number; + errors: string[]; +} +``` +→ neue Felder `groupsImported`, `groupsRenamed`, `groupsDeleted`, `defaultMarkerMoved` (alle `number`) additiv anhängen, exakt wie D-21 es bereits für `groupMembershipsAdded`/`groupMembershipsRemoved` getan hat. + +--- + +### `apps/api/src/ldap/ldap.controller.ts` — `POST /ldap/groups/import` (controller, request-response) + +**Analog:** `POST /ldap/users/import` (`importUsers()`), Zeilen 210-245: +```typescript +/** + * POST /ldap/users/import - Import specific AD users by DN (from the user + * search). Idempotent and non-deactivating: existing users are skipped, so + * a later department/group sync never creates a duplicate. + */ +@Post('users/import') +@Roles(Role.ADMIN, Role.SUPER_ADMIN) +async importUsers(@Req() req: any, @Body() dto: ImportUsersDto) { + const tenantId = req.tenantId; + if (!tenantId) { + throw new BadRequestException('No tenant context'); + } + + const config = await this.ldapConfigService.getConfig(tenantId); + if (!config) { + throw new NotFoundException('No LDAP config found for this tenant'); + } + + return this.ldapService.importUsersByDn( + { id: config.id, tenantId: config.tenantId, serverUrl: config.serverUrl, ... }, + tenantId, + dto.dns, + ); +} +``` +→ `POST 'groups/import'` mit `@Roles(Role.ADMIN, Role.SUPER_ADMIN)`, identischem `tenantId`/`config`-Guard-Präfix, ruft `ldapService.importGroupsByDn(config, tenantId, dto.dns)`. + +**Routen-Reihenfolge-Hinweis (Projektregel, siehe Memory `project_nest_route_order`):** Der bestehende `GET 'groups'`-Endpoint (Zeile 158) ist bereits eine statische Route ohne `:id`-Segment — die neue `POST 'groups/import'`-Route hat kein Kollisionsrisiko mit einer `:id`-Route, da dieser Controller (anders als z.B. `UsersController`) keine `@Get(':id')`-Route auf Gruppen-Ebene definiert. Trotzdem: neue statische Routen (`groups/import`) vor jeder eventuell später hinzugefügten `:id`-Route platzieren. + +--- + +### `apps/api/src/ldap/dto/ldap-config.dto.ts` — `ImportGroupsDto` (model/DTO, request-response) + +**Analog:** `ImportUsersDto`, Zeilen 109-114: +```typescript +/** + * DTO for POST /ldap/users/import — the DNs of AD users to import individually. + */ +export class ImportUsersDto { + @IsArray() + @ArrayNotEmpty() + @IsString({ each: true }) + dns!: string[]; +} +``` +→ `ImportGroupsDto` ist strukturell identisch (`dns!: string[]`), ggf. mit demselben Docblock-Stil, nur auf Gruppen umbenannt. + +--- + +### `apps/api/src/groups/groups.service.ts` — `internalName`, Name-Lock, Default-Handoff (service, CRUD) + +**Analog:** `update()` (Zeilen 99-154), `findOwned()` (78-86), `create()` (54-72), `ensureDefaultGroup()` (277-328) — alle vollständig gelesen. + +**Ownership-Check-Muster, zwingend für jeden neuen Codepfad mit `groupId`:** +```typescript +private async findOwned(tenantId: string, id: string) { + const group = await this.prisma.group.findFirst({ where: { id, tenantId } }); + if (!group) { + throw new NotFoundException(`Gruppe '${id}' nicht gefunden`); + } + return group; +} +``` + +**Name-Lock-Durchsetzung (RESEARCH.md Open Question 1 — muss serverseitig, nicht nur im UI, erzwungen werden):** in `update()` VOR dem bestehenden `if (data.name !== undefined)`-Block (Zeile 112) eine Prüfung einfügen, die `data.name` ablehnt, wenn die geladene Gruppe (`findOwned`) `ldapObjectGuid` gesetzt hat — Antwortform identisch zum bestehenden `BadRequestException`-Stil: +```typescript +if (data.name !== undefined) { + const trimmed = data.name.trim(); + if (!trimmed) { + throw new BadRequestException('Gruppenname darf nicht leer sein'); + } + updateData.name = trimmed; +} +``` +`internalName` läuft als eigenständiges, IMMER erlaubtes Feld daneben — keine Sperre, da D-04 es gerade unabhängig vom Sync hält. + +**P2002-Übersetzung (Namenskollision, für Sync UND für `internalName`-Kollisionsfreiheit falls gewünscht):** +```typescript +} catch (err: any) { + if (err?.code === 'P2002') { + throw new ConflictException( + `Eine Gruppe mit dem Namen '${updateData.name}' existiert bereits in diesem Mandanten`, + ); + } + throw err; +} +``` +Der neue Sync-Code darf diese Exception laut Pitfall 4 (RESEARCH.md) NICHT ungefangen durchreichen — eigenes try/catch pro Gruppe, Nachricht in `result.errors` sammeln (siehe `syncBoundGroupsForTenant`-Pattern oben). + +**Anzeige-Select `internalName ?? name`:** `listForTenant()` (Zeilen 28-45) projiziert aktuell `name: g.name` explizit — hier `internalName: g.internalName` ergänzen (rohes Feld ausliefern, Fallback-Entscheidung bleibt im Frontend bzw. wird analog zu `module-grants.service.ts` serverseitig aufgelöst, je nach Planungsentscheidung). + +**`ensureDefaultGroup()` als Fallback-Baustein für D-06/Pitfall 5:** +```typescript +async ensureDefaultGroup(tenantId: string) { + const existingCount = await this.prisma.group.count({ where: { tenantId } }); + if (existingCount > 0) { return null; } + try { + return await this.prisma.$transaction(async (tx) => { + const group = await tx.group.create({ data: { tenantId, name: 'Alle Benutzer', isDefault: true } }); + // ... Backfill Mitglieder + Grants ... + return group; + }); + } catch (err: any) { + if (err?.code === 'P2002') { return null; } + throw err; + } +} +``` +→ am Ende von `syncBoundGroupsForTenant()` (bzw. nach jeder Gruppen-Löschung) unbedingt aufrufen, damit ein Mandant nie ohne jede Gruppe dasteht. + +--- + +### `apps/api/src/groups/module-grants.service.ts` (Zeilen ~249/264) — `internalName ?? name` (service, transform) + +**Analog:** dieselbe Datei, `getUserAccess()`-Ausschnitt, Zeilen 244-267 (vollständig gelesen): +```typescript +const groupNamesByModule = new Map(); +for (const g of groupGrants as any[]) { + if (!g.group) continue; + const names = groupNamesByModule.get(g.moduleId) ?? []; + names.push(g.group.name); // Zeile 249 — zu ändern in g.group.internalName ?? g.group.name + groupNamesByModule.set(g.moduleId, names); +} +... +const groups = (memberships as any[]) + .filter((m) => m.group) + .map((m) => ({ + id: m.group.id as string, + name: m.group.name as string, // Zeile 264 — zu ändern in m.group.internalName ?? m.group.name + source: m.source as string, + })) + .sort((a, b) => a.name.localeCompare(b.name)); +``` +Beide `include: { group: ... }`-Queries (Zeilen 224-227, 238-241) müssen `internalName: true` mit selektieren, sonst ist das Feld zur Laufzeit `undefined`. + +--- + +### `apps/api/src/ldap/ldap.service.spec.ts` (test, batch) + +**Analog:** bestehende Mock-Struktur für `syncGroupMembershipsForTenant`/D-21 im selben File (nicht komplett gelesen, aber laut RESEARCH.md Test-Map bei Zeile ~665 als "ignores a Tessera group with no ldapDn"-Testmuster referenziert). Neue `describe`-Blöcke `importGroupsByDn`, `syncBoundGroupsForTenant` (Rename/Delete/Default-Handoff/Namenskollision) folgen demselben Mock-Prisma-Client-Aufbau wie die bestehenden D-21-Tests in dieser Datei — `prisma.group.findFirst`/`findMany` als `vi.fn()`-Mocks mit `mockResolvedValue`. + +### `apps/api/src/groups/groups.service.spec.ts` (test, CRUD) + +**Analog:** bestehende Tests für `GroupsService.update`/`findOwned` im selben File. **Wichtiger Hinweis aus dem Auftrag:** ein gemockter `findFirst()` muss in Gruppen-Queries einen optionalen ID-Parameter akzeptieren — beim Erweitern der Mocks für die neue Name-Lock-Logik darauf achten, dass `findOwned(tenantId, id)` weiterhin exakt EIN `findFirst`-Aufrufmuster erwartet (kein zweiter, versehentlich inkompatibler Mock-Aufruf für dieselbe Methode). + +--- + +### `apps/web/src/app/(portal)/admin/ldap/page.tsx` — Sektion "AD-Gruppen importieren" (component, request-response) + +**Analog:** Sektion 2.55 "Einzelbenutzer suchen & importieren", Zeilen 808-909 (vollständig gelesen) — 1:1-Vorbild für Suchfeld → Ergebnisliste mit Checkbox → Import-Button → Ergebniszeile. + +**Interfaces** (Zeilen 33-59, zu erweitern): +```typescript +interface LdapDirectoryEntry { + dn: string; + name: string; + type: 'group' | 'ou'; +} + +interface UserImportResult { + created: number; + updated: number; + skipped: number; + errors: string[]; +} + +interface SyncResult { + created: number; + updated: number; + deactivated: number; + errors: string[]; +} +``` +→ neu: `LdapGroupSearchResult extends LdapDirectoryEntry` (oder eigenständig) mit `alreadyImported: boolean`; `GroupImportResult` analog zu `UserImportResult`; `SyncResult` additiv um `groupMembershipsAdded`, `groupMembershipsRemoved`, `groupsImported`, `groupsRenamed`, `groupsDeleted`, `defaultMarkerMoved` erweitern (Pitfall 3 aus RESEARCH.md — diese Lücke besteht bereits für D-21 und muss in derselben Änderung geschlossen werden). + +**Ergebnislisten-Markup mit `alreadyImported`-Badge** (Zeilen 841-877): +```tsx +{userSearchResults && userSearchResults.length > 0 && ( +
+ {userSearchResults.map((u) => ( + + ))} +
+)} +``` + +**Import-Button + Ergebniszeile** (Zeilen 885-908): +```tsx +{userSearchResults && userSearchResults.length > 0 && ( + +)} +{userImportResult && ( +

+ {userImportResult.created} {t('userSearch.created')},{' '} + {userImportResult.skipped} {t('userSearch.skipped')} + {userImportResult.errors.length > 0 && ( + <>, {userImportResult.errors.length} {t('userSearch.errors')} + )} +

+)} +``` + +**Handler-Grundform, ABER mit sichtbarem Fehlerzustand (Owner-Entscheidung 2026-08-06 — NICHT das bestehende stumme `catch {}` kopieren):** +```typescript +// Bestehendes (zu vermeidendes) Muster, z.B. handleDiscoverGroups (Zeilen 286-301): +const handleDiscoverGroups = async () => { + setDiscovering(true); + try { + const res = await fetch(`${API_URL}/ldap/groups`, { credentials: 'include' }); + if (res.ok) { + const data = await res.json(); + setDiscovered(data); + } + } catch { + // silently fail <-- NICHT für die neuen Gruppen-Import-Handler übernehmen + } finally { + setDiscovering(false); + } +}; +``` +→ Für die neuen Handler (`handleDiscoverGroupsToImport`, `handleImportGroups`) stattdessen: bei `!res.ok` UND im `catch`-Zweig einen `text-sm text-destructive`-Fehlerstate setzen (`admin.ldap.groupImport.discoverError` bzw. `.importError`), analog zum Fehlerbanner-Vorbild aus `groups/page.tsx:135-139` (siehe unten). `handleSync` (Zeilen 231-249) liefert bereits das Vorbild für "Fehler setzt ein Result-Objekt statt zu schweigen": +```typescript +const handleSync = async () => { + setSyncing(true); + setSyncResult(null); + try { + const res = await fetch(`${API_URL}/ldap/sync`, { method: 'POST', credentials: 'include' }); + if (res.ok) { + const data = await res.json(); + setSyncResult(data); + await fetchConfig(); + } + } catch { + setSyncResult({ created: 0, updated: 0, deactivated: 0, errors: ['Network error'] }); + } finally { + setSyncing(false); + } +}; +``` +Für den Sync-Request-Fehler (`admin.ldap.sync.requestError`) reicht laut UI-SPEC ein separater sichtbarer `text-sm text-destructive`-Zustand anstelle des Berichts-Containers — nicht zwingend über `syncResult.errors`. + +**Sync-Bericht-Container, additiv um weitere `

`-Zeilen zu erweitern** (Zeilen 1069-1088): +```tsx +{syncResult && ( +

+

+ {t('sync.result', { created: syncResult.created, updated: syncResult.updated, deactivated: syncResult.deactivated })} +

+ {syncResult.errors.length > 0 && ( +
+ {syncResult.errors.map((err, i) => ( +

{err}

+ ))} +
+ )} +
+)} +``` +→ zusätzliche `

`-Zeilen für Gruppenmitgliedschaften/Gruppen/Default-Marker-Handoff exakt wie in UI-SPEC Surface Contract 2 spezifiziert, gleicher Container. + +--- + +### `apps/web/src/app/(portal)/admin/groups/components/GroupFormModal.tsx` — Entfernung Radio-Block, Name-Lock, interner Name (component, request-response) + +**Zu entfernender Block:** Zeilen 9-13 (`LdapDirectoryEntry`-Interface, nur für diesen Zweck importiert), 37-40 (Discovery-State), 42-67 (`fetchLdapGroups` + Effekt), 147-227 (kompletter AD-Bindungs-Block im JSX) sowie der zweistufige Create-Flow in `handleSubmit` (Zeilen 93-119, insbesondere der `bindRes`-PATCH-Zweig Zeilen 107-118). + +**Bestehendes Namensfeld als Analog für sowohl das freie Create-Feld als auch das Grundgerüst des gesperrten Edit-Felds** (Zeilen 136-145): +```tsx +

+ + setName(e.target.value)} + className="flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm" + /> +
+``` +→ für Zustand (c) (importierte Gruppe) `disabled` ergänzen (`disabled` + bestehende `disabled:opacity-50`-Konvention, siehe UI-SPEC Surface Contract 4) und `value={group?.name ?? ''}` beibehalten, ohne `onChange`-Wirkung auf ein zu sendendes Feld. + +**`saveError`-Banner ist BEREITS das gesuchte Fehler-Vorbild — hier schon vorhanden, nur konsequent auf JEDEN Fehlerfall auszuweiten** (Zeilen 122-124, 229-233): +```typescript +} catch { + setSaveError(t('saveError')); +} finally { + setSaving(false); +} +``` +```tsx +{saveError && ( +
+ {saveError} +
+)} +``` +Dieses Muster bleibt unverändert bestehen und wird nach D-07 einfacher (kein `discoverError`-Sonderfall mehr, da der gesamte AD-Discovery-Codepfad in diesem Modal entfällt). Bei Namenskollision zusätzlich `admin.groups.saveErrorNameTaken` statt `saveError` an derselben Stelle rendern (UI-SPEC Copywriting Contract). + +**Neues Feld "Interner Name" für Zustand (c):** identisches Input-Markup wie das Namensfeld oben, aber editierbar, mit `internalName`-State und `PATCH`-Payload `{ internalName }` statt `{ name, ldapDn }` (bestehende Payload-Zeile 87 als Vorbild für die PATCH-Aufrufform): +```typescript +const res = await fetch(`${API_URL}/groups/${group.id}`, { + method: 'PATCH', + headers: { 'Content-Type': 'application/json' }, + credentials: 'include', + body: JSON.stringify({ name, ldapDn }), // → wird für importierte Gruppen zu { internalName } +}); +``` + +**Neuer Hinweis-Link im Create-Zustand** (Analog für `text-primary hover:underline`-Link-Stil: `apps/web/src/app/(portal)/admin/modules/grants/page.tsx:184-189`): +```tsx + + {t('emptyModulesLink')} + +``` + +--- + +### `apps/web/src/app/(portal)/admin/groups/page.tsx` — Namensspalte + Fehlerbanner (component, CRUD-Anzeige) + +**Analog:** dieselbe Datei, Namens-/Badge-Zellen, Zeilen 179-190 (vollständig gelesen): +```tsx +{group.name} + + + {group.ldapDn ? t('boundBadge') : t('manualBadge')} + + +``` +→ Namenszelle wird zu `{group.internalName ?? group.name}` mit zusätzlichem `title={group.name}` auf dem umschließenden `` (UI-SPEC Surface Contract 3). Badge-Zelle bleibt unverändert — sie ist nach D-07 der alleinige "importiert"-Marker. + +**Fehlerbanner-Vorbild, das die UI-SPEC ausdrücklich als Analog für die neuen `ldap/page.tsx`-Fehlerzustände benennt** (Zeilen 135-139): +```tsx +{error && ( +
+ {error} +
+)} +``` +Dieses `rounded-md border border-destructive/50 bg-destructive/10 p-3 text-sm text-destructive`-Muster ist die Ziel-Klassenkombination für `admin.ldap.groupImport.discoverError`, `.importError` und `admin.ldap.sync.requestError` — siehe Shared Patterns unten. + +--- + +### `apps/web/src/app/(portal)/admin/modules/grants/page.tsx` (Zeilen ~206-213) — Spaltenkopf-Namensanzeige (component, transform) + +**Analog:** dieselbe Datei, `th`-Block, Zeilen 206-213 (vollständig gelesen): +```tsx +{filteredGroups.map((g) => ( + + {g.name} + +))} +``` +→ `title={g.name}` und `{g.name}` werden zu `title={g.internalName ?? g.name}` und `{g.internalName ?? g.name}` — reiner Textwert-Wechsel, keine Klassenänderung. + +--- + +## Shared Patterns + +### LDAP-Client-Verbindungsauf-/-abbau +**Source:** `apps/api/src/ldap/ldap.service.ts:372-374, 431-437` (u.v.a. — dasselbe try/finally-Muster an jeder Client-Nutzung in dieser Datei) +**Apply to:** `importGroupsByDn()`, `syncBoundGroupsForTenant()` +```typescript +const client = new Client(this.buildClientOptions(config.serverUrl, config.tlsRejectUnauthorized)); +try { + await this.bind(client, config.bindDn, config.bindPassword); + // ... +} finally { + try { + await client.unbind(); + } catch { + // Ignore unbind errors + } +} +``` + +### LDAP-Filter-Escaping (String) +**Source:** `apps/api/src/ldap/ldap.service.ts:977-984` (`static escapeLdapFilterValue`) +**Apply to:** jede neue Filter-Interpolation mit String-Werten (z.B. `cn`-Vergleich beim Rename-Check) + +### LDAP-Filter-Escaping (binär, `objectGUID`) +**Source:** RESEARCH.md Pattern 3 (`[ASSUMED]`, vor Prod-Schärfung gegen echtes AD zu verifizieren) +**Apply to:** `syncBoundGroupsForTenant()`-Existenz-Sweep + +### Mandantenscoping bei Schreibzugriffen im Sync +**Source:** `apps/api/src/ldap/ldap.service.ts:596, 847` (`forTenant(this.prisma, tenantId) as any`) +**Apply to:** `importGroupsByDn()`, `syncBoundGroupsForTenant()` — jeder DB-Schreibzugriff im Sync-Kontext + +### Ownership-Check bei jeder `groupId`-Route +**Source:** `apps/api/src/groups/groups.service.ts:78-86` (`findOwned`) +**Apply to:** jede neue `GroupsService`-Methode, die eine `groupId` entgegennimmt + +### Pro-Element-try/catch mit gesammelten Fehlern statt Lauf-Abbruch +**Source:** `apps/api/src/ldap/ldap.service.ts:860-934` (Loop in `syncGroupMembershipsForTenant`) +**Apply to:** `importGroupsByDn()`, `syncBoundGroupsForTenant()` — inkl. Abfangen einer `ConflictException` aus `GroupsService.create()`/`update()` bei Namenskollision (Pitfall 4) + +### Sichtbarer Fehlerzustand statt stummem `catch {}` (Owner-Entscheidung 2026-08-06, NUR für die neuen Codepfade) +**Source (Ziel-Optik):** `apps/web/src/app/(portal)/admin/groups/page.tsx:135-139` (Fehlerbanner) und `apps/web/src/app/(portal)/admin/groups/components/GroupFormModal.tsx:229-233` (`saveError`) +**Source (zu vermeidende Altlast, NICHT für neue Handler kopieren):** die zahlreichen `catch { /* silently fail */ }`-Blöcke in `apps/web/src/app/(portal)/admin/ldap/page.tsx` (Zeilen 267-269, 281-283, 296-297, 332-333, 365-366, 396-397, 415-417) +**Apply to:** `handleDiscoverGroupsToImport`, `handleImportGroups` (neue Handler in `ldap/page.tsx`), sowie — laut UI-SPEC-Owner-Entscheidung — auch `handleSync`s Request-Fehlerpfad (separat vom bestehenden `syncResult.errors`-Netzwerkfehler-Fallback) und `GroupFormModal`s `handleSubmit` (bereits vorhanden, nur konsequent für alle drei Zustände a/b/c beizubehalten) +```tsx +
+ {error} +
+``` + +### Additive Sync-Report-Felder statt zweitem Report-Typ +**Source:** `apps/api/src/ldap/ldap.service.ts:10-20` (`LdapSyncResult`), gespiegelt im Frontend-`SyncResult`-Interface `apps/web/src/app/(portal)/admin/ldap/page.tsx:54-59` +**Apply to:** Backend `LdapSyncResult` UND Frontend `SyncResult` — beide müssen im selben Schritt um dieselben Feldnamen wachsen, sonst wiederholt sich Pitfall 3 (Frontend kennt neue Backend-Felder nicht) + +### `internalName ?? name`-Fallback-Projektion +**Source:** noch kein bestehendes Beispiel im Repo (neues Muster dieser Phase) — konsistent an drei Stellen zu implementieren: +- Backend: `apps/api/src/groups/module-grants.service.ts:249, 264` (`g.group.internalName ?? g.group.name`) +- Frontend: `apps/web/src/app/(portal)/admin/groups/page.tsx` Namenszelle, `apps/web/src/app/(portal)/admin/modules/grants/page.tsx` Spaltenkopf +**Apply to:** jede Anzeige-Stelle, die heute `group.name`/`g.name` direkt rendert + +## No Analog Found + +| File | Role | Data Flow | Reason | +|------|------|-----------|--------| +| — | — | — | Alle 14 Zielflächen dieser Phase haben einen direkten, strukturell passenden Analog im Repo — Phase 16 ist laut RESEARCH.md zu über 90% Erweiterung bestehender Muster, kein neues Fundament. | + +## Metadata + +**Analog search scope:** `apps/api/src/ldap/`, `apps/api/src/groups/`, `apps/api/prisma/`, `apps/web/src/app/(portal)/admin/{ldap,groups,modules/grants}/`, `apps/web/src/messages/` +**Files scanned:** `ldap.service.ts` (985 Zeilen, vollständig), `ldap.controller.ts` (320 Zeilen, vollständig), `dto/ldap-config.dto.ts` (114 Zeilen, vollständig), `groups.service.ts` (350 Zeilen, vollständig), `module-grants.service.ts` (Zeilen 220-278), `schema.prisma` (Group-Modell + Migrationen), `admin/ldap/page.tsx` (Zeilen 1-65, 231-421, 680-909, 1040-1093), `GroupFormModal.tsx` (255 Zeilen, vollständig), `admin/groups/page.tsx` (Zeilen 120-219), `admin/modules/grants/page.tsx` (Zeilen 175-225) +**Pattern extraction date:** 2026-08-06