craftvia/docs/wizard-uebergabe/01_Planung/Wizard-Entwickler-Backlog.md

# Onboarding-Wizard — Entwickler-Backlog (2 Full-Stack-Lanes, parallel auf `dev`)

Grundlage: `Onboarding_Wizard_Fahrplan_Detail.md` (Berater), `STAND-dev-branch.md` (Ist-Stand `dev`, 2026-07-24), `Onboarding-Wizard-Machbarkeitsanalyse.md`.
Aufbau: **2 Entwickler**, je **vertikaler Feature-Slice** (BE+FE+Migration) auf eigenem **Feature-Branch unter `dev`**. Umfang: **kompletter Wizard**. Manueller Richtlinien-Upload: **UI/Modell jetzt, Datei-Speicher später** (Storage-Adapter gestubbt).

> Fachliche Zulieferungen (SME/Berater) sind je Epic mit **🧩 SME** markiert und in `Berater-Anweisung-Fachcontent.md` als Arbeitspakete C1–C9 ausformuliert.

---

## 0. Arbeitsmodell, Branching & Definition of Done

**Branching**
- Basis-Branch: **`dev`** (nicht `main`). Alle Feature-Branches zweigen von `dev` ab, PR-Ziel ist `dev`.
- Namensschema: **`dev/<lane><n>-<slug>`** — z. B. `dev/a1-wizard-shell`, `dev/b2-regel-engine`.
- **Dev A = Lane A** („Flow, Governance & Bewertung"), **Dev B = Lane B** („Engines, Inhalte & Ausgabe").
- Häufig auf `dev` rebasen (mind. täglich), kleine PRs je Epic, Review durch die jeweils andere Person.

**Definition of Done (jede Story)**
- `npx tsc --noEmit` → `npm run lint` → `npm run build` grün (der `prebuild`-Guard-Check läuft mit).
- Neue Server-Action-Datei ist in **`scripts/check-module-guards.ts`** eingetragen (Modul-Key oder `EXEMPT`).
- Neues tenant-gebundenes Modell in **`TENANT_MODELS`** (`src/server/db.ts`) **und** RLS-Policy in der Migration.
- Migration erstellt (Prisma-7-Flow) inkl. manuell angehängtem **RLS-DO-Block**; läuft via `migrate deploy`.
- Wenn Seed/Vorlagenpaket berührt: `python3 seed/isms-vorlagenpaket-v2/_verify.py` → **OK**.
- Browser-Verifikation der Kern-Flows; Demo-Daten/Seed weiterhin lauffähig.

**Geteilte „Hot Files" — nur koordiniert anfassen (Konflikt-Risiko):**
`prisma/schema.prisma` · Migrationsreihenfolge · `src/lib/modules.ts` · `scripts/check-module-guards.ts` · `src/server/db.ts` (`TENANT_MODELS`) · das Wizard-Shell-Step-Registry (Lane A liefert, Lane B registriert Steps).
→ Migrationen **nie gleichzeitig** ohne Absprache erzeugen; jede Lane hält ihre Migration isoliert und rebased vor dem Erstellen.

---

## 1. Zuerst festzurren — Foundation-Contracts (gemeinsam, VOR den Lanes)

Ein kurzer gemeinsamer Branch **`dev/foundation-contracts`** (1 Person federführend, andere reviewt), **zuerst nach `dev` gemergt**. Legt die vier Verträge fest, die alles andere determinieren:

1. **Aufgaben-Objekt-Schema** — Erweiterung des bestehenden `Task`/`TaskComment` (heute Typ `policy_approval`) um: `type` (`document_create` / `evidence_provide` / `technical` / `organizational` / `validation`), `owner`, `dueDate`, `priority`, `status`, **`resources` (JSON: tool/budget/personnel/time)**, **`origin` (auslösender Schritt)**, polymorphe Verknüpfung (`control` / `risk` / `document` / `asset`). RLS wie gehabt.
2. **Objekt-Validierungs-Status** — einheitliches Enum `offen → in_bearbeitung → zur_validierung → validiert | zurueckgewiesen(+Kommentar)` als wiederverwendbares Feld/Mixin über Objekttypen; Rolle **`external_validator`** (externer Berater).
3. **Regel-/Mapping-DSL** — Vertrag: `Bedingung(Antwort/Scope/Flag) → Wirkung(Klausel ein/aus · Control relevant/irrelevant · Risiko/Asset-Bezug · Aufgabe)`. JSON-basiert, testbar; baut auf vorhandenen Handlebars-Flags + Lieferanten-Anforderungs-Engine auf.
4. **Assessment-Readiness-Export-Format** — Datenschema des vorausgefüllten VDA-ISA-Katalogs (Control → Teilanforderungen → Reifegrad/Belege/offene Punkte/Status „bestätigt|unbestätigt").

**Aufwand:** M (Schema-/Typ-Definitionen + Migration `tasks`-Erweiterung). **DoD:** Typen/Interfaces + Task-Migration gemergt, damit beide Lanes darauf bauen.

---

## 2. Lane A — Dev A: „Flow, Governance & Bewertung"

| Epic | Branch | Hängt ab von | Aufwand | 🧩 SME |
|---|---|---|---|:--:|
| **A1 Wizard-Shell & Navigation** | `dev/a1-wizard-shell` | Foundation | M–L | – |
| **A2 Scoping + AL2/AL3 zentral (Adminportal) + Scope-Filter** | `dev/a2-scoping-admin-al` | A1 | M | 🧩 C1 |
| **A3 Validierungs-Workflow generalisieren** | `dev/a3-validation-workflow` | Foundation, B1 | M | – |
| **A4 ISMS-Rollen & Funktionstrennung (Schritt 3)** | `dev/a4-isms-rollen` | A1, A3 | M | 🧩 C7 |
| **A5 Asset-Anbindung Wizard (Schritt 5, Reuse)** | `dev/a5-assets-step` | A1 | S | – |
| **A6 Risiko-Katalog & Anbindung (Schritt 6)** | `dev/a6-risiko-katalog` | A1, B2 | M–L | 🧩 C4 |
| **A7 Control-Assessment & Reifegrad/Gap (Schritt 7, SoA)** | `dev/a7-control-assessment` | A2, B1, B2, B5 | L | 🧩 C5, C6 |
| **A8 Gap-Konsolidierung (Schritt 8)** | `dev/a8-gap-konsolidierung` | A6, A7, B1 | M | 🧩 C8 |

**A1 — Wizard-Shell & Navigation.** Neuer Bereich `src/app/(app)/onboarding/**` + `src/server/actions/onboarding.ts` (in `check-module-guards.ts` registrieren; neues Modul `onboarding` in `src/lib/modules.ts`). Multi-Step-State-Machine mit Fortschritt, **Gates** (Schritt „validiert" bevor weiter), **Wiederaufnahme**, und einem **Step-Registry**, in das Lane B ihre Schritt-Komponenten einklinkt (klare Datei-Trennung je Schritt). Persistenter Wizard-Fortschritt je Mandant. *Akzeptanz:* Flow ist resumierbar; Gates blockieren korrekt; Schritte sind als eigenständige Module registrierbar.

**A2 — Scoping + AL2/AL3 zentral im Adminportal.** (Explizite Anforderung.) Der **AL2/AL3-Schalter wird zentral im Superadmin-/Adminportal** gesetzt (`src/app/(platform)/admin/**` + `src/server/actions/admin.ts`/`platform.ts`) als Teil der Mandanten-Kern-Config — **einzige Quelle der Wahrheit**. Schritt 1 (Scoping) liest ihn **read-only** (nur Superadmin ändert), plus Prüfziele/Standorte/Geltungsbereich/Ausschlüsse → **Scope-Objekt**. Scope filtert nachgelagert Control-/Template-/Risiko-Sets (an vorhandene Coverage-Filter-Logik nach Assessment-Level andocken). *Akzeptanz:* AL nur im Adminportal änderbar; Änderung propagiert in Coverage/Zusatzanforderungen; nicht relevante Controls/Templates ausgeblendet. **🧩 C1** (AL2/AL3-Kennzeichnung + Prüfziel-Zuordnung je Control).

**A3 — Validierungs-Workflow generalisieren.** Den bestehenden Vier-Augen-Freigabe-/Task-Mechanismus (`policy_approval`) zu einem **generischen Objekt-Review** über alle Typen ausbauen (Modul/Richtlinie/Risiko/Control-Bewertung): Status-Feld (Foundation #2), Reviewer-Zuweisung inkl. **externer Berater**, Kommentare, „unbestätigt zählt nicht" in Auswertungen. Wiederverwendet `src/server/actions/tasks.ts` + `submitForApproval`. *Akzeptanz:* jedes Objekt trägt Review-Status; nur „validiert" zählt als bestätigt; externer Validierer-Rolle testbar.

**A4 — ISMS-Rollen & Funktionstrennung (Schritt 3).** ISMS-Rollenmodell (GF/ISB/DSB/IT) auf Basis vorhandener RBAC/RACI; **Funktionstrennungs-Prüfung** (z. B. ISB ≠ IT); Rollen-Platzhalter in Dokumente (ISB-Bestellung aus Vorlage). Konflikt → Hinweis/Aufgabe (A3/B1). *Akzeptanz:* Funktionstrennungs-Konflikt wird erkannt und als Aufgabe ausgewiesen. **🧩 C7**.

**A5 — Asset-Anbindung Wizard (Schritt 5).** Dünne Wizard-Schicht auf das bestehende Assets/BIA-Modul (C/I/A, Schutzbedarf, Eigentümer, Abhängigkeiten sind vorhanden). Trigger „Inventar unvollständig / kein Eigentümer" → Aufgabe (B1). *Akzeptanz:* Wizard nutzt Bestands-Assets; Trigger erzeugt Aufgabe.

**A6 — Risiko-Katalog & Anbindung (Schritt 6).** Bewertungs-/Register-Kern existiert (5×5, Behandlung, Control-Verknüpfung). Neu: **kuratierter Standard-/VDA-Risiko-Katalog** (Auswahl + eigene Ergänzung), Verknüpfung Asset/Control, Maßnahme→Aufgabe (B1). *Akzeptanz:* VDA-geforderte Risiken auswählbar; inakzeptables Risiko hat Behandlung; Maßnahmen erzeugen Aufgaben. **🧩 C4** (Kataloginhalt + Standardmaßnahmen).

**A7 — Control-Assessment & Reifegrad/Gap (Schritt 7, SoA).** Größter Block: baut die bislang fehlende **SoA-/Control-Oberfläche**. Je Control: Beleg-Verknüpfung (Dok/Risiko/Asset), **Reifegrad-Selbsteinschätzung** mit regelbasiertem Vorschlag (aus Belegen) **+ Pflichtbestätigung** (Muster: Lieferanten-Reifegrad-Freigabe), Markierung offener Teilanforderungen; unter Ziel → Aufgabe. Nutzt Coverage-Daten + Foundation-Export-Schema. *Akzeptanz:* jede relevante Teilanforderung adressiert; Reifegradvorschlag nachvollziehbar an Belege gekoppelt. **🧩 C5** (Reifegrad-Logik), **🧩 C6** (Umsetzungshinweis-Content, via B5).

**A8 — Gap-Konsolidierung (Schritt 8).** Aggregation/Dedup/Priorisierung (Muss/AL3 = hoch) aus Schritt 6+7 zu einer konsolidierten Gap-/Maßnahmenliste, abgeglichen mit Aufgaben (B1). *Akzeptanz:* keine Dopplungen; jeder offene Punkt hat Priorität + ggf. Aufgabe. **🧩 C8** (Priorisierungslogik/Quick-Wins).

---

## 3. Lane B — Dev B: „Engines, Inhalte & Ausgabe"

| Epic | Branch | Hängt ab von | Aufwand | 🧩 SME |
|---|---|---|---|:--:|
| **B1 Aufgaben-Modul erweitern** | `dev/b1-tasks-erweiterung` | Foundation | M | – |
| **B2 Regel-/Mapping-Layer** | `dev/b2-regel-engine` | Foundation | L | 🧩 C2 |
| **B3 Fragebogen/Fakten (Schritt 2)** | `dev/b3-fragebogen` | A1, B2 | M | 🧩 C2 |
| **B4 Richtlinien: Import-bei-Aktivierung + manueller Upload + Control-Mapping (Schritt 4 + Menü)** | `dev/b4-richtlinien-import-upload` | Foundation | M–L | 🧩 C3 |
| **B5 Umsetzungshinweise (Content-Modell + Inline-Panel)** | `dev/b5-umsetzungshinweise` | A1 | S (Code) | 🧩 C6 |
| **B6 Versionierung/Propagation** | `dev/b6-versionierung` | B4 | M–L | – |
| **B7 Assessment-Readiness & Export (Schritt 9)** | `dev/b7-readiness-export` | A7, A8 | L | 🧩 C9 |

**B1 — Aufgaben-Modul erweitern.** Das generische `Task`-Modell (heute `policy_approval`) um die Foundation-Felder erweitern; **Auto-Generierung** aus Triggern (Schritt 3/4/6/7/8, Zurückweisung) als **Vorschlag mit Bestätigung**; Ressourcenfelder editierbar; Verknüpfungen Control/Risiko/Dok/Asset; Anzeige/Filter im bestehenden Modul „Aufgaben" (`src/app/(app)/tasks/`). *Akzeptanz:* Trigger erzeugt Aufgabenvorschlag mit korrekten Verknüpfungen/Ressourcen; Bestätigung übernimmt.

**B2 — Regel-/Mapping-Layer.** Umsetzung der DSL (Foundation #3) als testbare Engine `src/lib/rules/**`: Antwort/Scope/Flag → Klausel-Ein/Ausblendung (Handlebars-Flags erweitern), betroffene Controls/Assets/Risiken, Aufgaben-Trigger. Isoliert + unit-getestet. *Akzeptanz:* Regelauswertung deterministisch, mit Testfällen belegt; Änderung einer Antwort propagiert sichtbar. **🧩 C2** (Antwort→Wirkung-Mapping).

**B3 — Fragebogen/Fakten (Schritt 2).** Dynamischer, **bedingter Fragebogen**; Antworten als **wiederverwendbare Faktenobjekte** (an vorhandene zentrale Variablen/Stammdaten andocken, ohne die Sperre der zentralen Variablen zu verletzen). Bedingte Sichtbarkeit über B2. *Akzeptanz:* Antworten wiederverwendbar; Änderung propagiert in abhängige Objekte/Platzhalter. **🧩 C2** (Fragenkatalog).

**B4 — Richtlinien: Import-bei-Aktivierung + manueller Upload + Control-Mapping.** (Explizite Anforderung.) Zwei Wege:
- **(a) Vorlagen-Import bei Modul-Aktivierung:** Wird das **Richtlinien-Modul im Superadmin/Adminportal aktiviert**, wird das Vorlagenpaket **mandantenweit importiert** — die vorhandene **nicht-destruktive** Logik (`prisma/import-policies.ts`, Diff/Upsert/`archivedAt`) als **serverseitig auslösbare Aktion/Job** kapseln (statt nur CLI/Seed). Zusätzlich Button „Vorlagen importieren/aktualisieren" (Admin bzw. `/policies`). Idempotent, Änderungsreport.
- **(b) Manueller Upload eigener Richtlinien direkt im Menü `/policies`:** Einstiegspunkt + Metadaten-/Block-Modell + **Control-Zuordnung** jetzt bauen; **Datei-Persistenz über einen Storage-Adapter-Interface stubben** (echtes Storage-Backend = Folge-Epic **S1**, außerhalb dieses Batches). Upload erfasst Datei-Referenz/Platzhalter + Control-Mapping in die Nachweislage. *Akzeptanz:* Modul-Aktivierung importiert Vorlagen nicht-destruktiv; unter `/policies` existiert „Eigene Richtlinie hochladen" mit Control-Zuordnung; Storage-Adapter ist gekapselt und später ohne UI-Änderung verdrahtbar. **🧩 C3** (regelfähige Vorlagen-Auszeichnung).

**B5 — Umsetzungshinweise (Content-Modell + Inline-Panel).** Strukturiertes Hinweis-Modell (org/tech/Nachweise/Vorlagen-Verweis/**Ressourcenindikation**), Scope-/Antwort-Filter (B2), kontextsensitives Inline-Panel an Teilanforderungen/Risiken/Templates. Code klein — **Inhalt ist der Aufwand**. *Akzeptanz:* passende Hinweise werden nach Scope/Antworten gefiltert eingeblendet; führen bei Maßnahme zu Aufgabe (B1). **🧩 C6**.

**B6 — Versionierung/Propagation.** Versionierung von Katalog/Templates/Risiko-Katalog + **Instanz-Referenz auf genutzte Version** + **Diff & gesteuerte Übernahme** bei Updates (löst zugleich den heute noch offenen Richtlinien-Diff und flankiert den nicht-destruktiven Re-Import). *Akzeptanz:* laufende Kundeninstanz bekommt bei Update einen Diff und übernimmt kontrolliert; nichts wird still überschrieben.

**B7 — Assessment-Readiness & Export (Schritt 9).** Reifegrad-Dashboard je Kapitel/gesamt, vorausgefüllte **VDA-ISA-Katalogsicht**, Maßnahmenplan; „bestätigt vs. unbestätigt" nach Validierungsstatus (A3); **Export** (koppelt an den offenen DOCX/PDF-Export). *Akzeptanz:* Kennzahlen stimmen mit Einzelbewertungen; Export vollständig/nachvollziehbar. **🧩 C9** (Auswertungs-/Interpretationstexte, Export-Layout).

---

## 4. Sequenz / Meilensteine (2 Lanes im Takt)

| Takt | Dev A (Lane A) | Dev B (Lane B) | Gate |
|---|---|---|---|
| **M0** | Foundation-Contracts (gemeinsam) | Foundation-Contracts (gemeinsam) | Contracts + `tasks`-Migration auf `dev` |
| **M1** | A1 Wizard-Shell | B1 Tasks-Erweiterung · B2 Regel-Engine (Kern) | Shell + Task-API stehen |
| **M2** | A2 Scoping/Admin-AL | B4 Richtlinien-Import/Upload · B3 Fragebogen | AL zentral · Import läuft |
| **M3** | A3 Validierung · A4 Rollen | B5 Umsetzungshinweise | Review generisch |
| **M4** | A5 Assets · A6 Risiko-Katalog | B6 Versionierung | Katalog/Risiko nutzbar |
| **M5** | A7 Control-Assessment (SoA) | (Puffer/Review A7) · Start B7 | Kern-Bewertung steht |
| **M6** | A8 Gap-Konsolidierung | B7 Readiness & Export | North-Star: Readiness-Export |

**Kürzester Pfad zur Assessment-Readiness:** M0→M1→M2→…→M6. Governance (A3/B1/B5/B6) läuft bewusst mit, nicht am Ende.

---

## 5. Explizite Anforderungen (Kurz-Referenz)
- **AL2/AL3 zentral im Adminportal:** → **A2** (einzige Quelle im Superadmin/Admin; Scoping liest read-only; treibt Coverage/AL3-Zusatzanforderungen).
- **Richtlinien-Vorlagen-Import bei Modul-Aktivierung + manueller Upload im Menü:** → **B4** (Import nicht-destruktiv on-enable; manueller Upload jetzt als UI/Modell/Control-Mapping, Datei-Speicher via Storage-Adapter später = Folge-Epic **S1**).

## 6. Außerhalb dieses Batches (Folge-Epics)
- **S1 Storage-Backend** (Coolify-Volume/MinIO) — schaltet echten Datei-Upload (B4b, Netzplan REG-NET, Nachweis-Upload) scharf.
- **Paket 4** (SMTP/Einladung), **NIS2-Modul**, **Admin Phase 2** (Impersonation/Plan-Limits) — unverändert im Backlog.

---

## 7. Nächster Schritt
Foundation-Contracts (Abschnitt 1) gemeinsam finalisieren und mergen → dann Lanes starten. Fachliche Zulieferung C1–C9 parallel anstoßen (siehe `Berater-Anweisung-Fachcontent.md`), sonst werden C2/C3/C4/C5/C6 zum kritischen Pfad für A2/A6/A7 und B2/B3/B4/B5.