From 4a564ad8f7392b19f69ab63c0e7b968406c9b2d1 Mon Sep 17 00:00:00 2001 From: Benjamin Admin Date: Thu, 5 Mar 2026 22:31:28 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20SDK=20Workflow=20Referenzseite=20?= =?UTF-8?q?=E2=80=94=20Seq-Nummern,=20visibleWhen,=20Navigation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Neue Übersichtsseite sdk-workflow.md mit vollständiger Referenz: - Alle 34 Steps mit seq-Nummern (100–4800) in Pakettabellen - Lücken-Konvention (100er innerhalb, 300er an Paket-Grenzen) - visibleWhen-Logik für import/dsfa/document-generator - Prerequisite-Ketten-Regeln und Ausnahmen - Alle Navigationsfunktionen (getNextStep, getVisibleSteps, etc.) - Anleitung zum Einfügen neuer Steps - Deprecated-Hinweis für getVisibleStepsForCustomerType Co-Authored-By: Claude Opus 4.6 --- docs-src/services/sdk-modules/sdk-workflow.md | 241 ++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 242 insertions(+) create mode 100644 docs-src/services/sdk-modules/sdk-workflow.md diff --git a/docs-src/services/sdk-modules/sdk-workflow.md b/docs-src/services/sdk-modules/sdk-workflow.md new file mode 100644 index 0000000..6425a9b --- /dev/null +++ b/docs-src/services/sdk-modules/sdk-workflow.md @@ -0,0 +1,241 @@ +# SDK Workflow — Sequenznummern & Navigation + +Vollständige Referenz für das SDK-Workflow-System: Sequenznummern, Pakete, bedingte Sichtbarkeit und Navigationsfunktionen. + +**Quelle:** `admin-compliance/lib/sdk/types.ts` + +--- + +## Konzept + +Jeder SDK-Schritt (Step) hat eine **globale Sequenznummer** (`seq`), die seine Position im gesamten Workflow eindeutig bestimmt — unabhängig vom Paket. + +### Warum seq statt order? + +Das alte `order`-Feld war paket-lokal (1, 2, 3 innerhalb eines Pakets). Das führte zu Problemen: + +- Paket-zu-Paket-Navigation war hardcoded (Phasen 1→2) +- Neue Steps konnten nicht einfach zwischen bestehende Steps eingefügt werden +- Bedingte Sichtbarkeit (DSFA nur bei L2+) war nicht systematisch + +Das `seq`-System löst alle drei Probleme: + +- Navigation basiert auf globalem `seq`-Sort → kein hardcoded Phasenwechsel +- 100er-Lücken zwischen Steps erlauben späteres Einfügen ohne Umnummerierung +- `visibleWhen`-Funktion pro Step steuert Sichtbarkeit state-abhängig + +--- + +## Lücken-Konvention + +``` +100er-Lücken: innerhalb eines Pakets (Platz für 9 neue Steps zwischen je zwei) +300er-Lücken: an Paket-Grenzen (700→1000, 1600→2000, 2400→3000, 3400→4000) +``` + +Beispiel — neuer Step zwischen `requirements` (1000) und `controls` (1100): +→ `seq: 1050` vergeben, `order` entsprechend setzen. + +**Ausnahme `email-templates` (seq 4350):** Nachträglich zwischen `consent-management` (4300) und `notfallplan` (4400) eingefügt — nutzt die Hälfte der Lücke. + +--- + +## Vollständige Step-Tabelle + +### Paket 1 — Vorbereitung + +| seq | id | Name | visibleWhen | isOptional | +|-----|----|------|-------------|-----------| +| 100 | `company-profile` | Unternehmensprofil | immer | nein | +| 200 | `compliance-scope` | Compliance Scope | immer | nein | +| 300 | `use-case-assessment` | Anwendungsfall-Erfassung | immer | nein | +| 400 | `import` | Dokument-Import | `customerType === 'existing'` | **ja** | +| 500 | `screening` | System Screening | immer | nein | +| 600 | `modules` | Compliance Modules | immer | nein | +| 700 | `source-policy` | Source Policy | immer | nein | + +### Paket 2 — Analyse + +| seq | id | Name | visibleWhen | isOptional | +|-----|----|------|-------------|-----------| +| 1000 | `requirements` | Requirements | immer | nein | +| 1100 | `controls` | Controls | immer | nein | +| 1200 | `evidence` | Evidence | immer | nein | +| 1300 | `risks` | Risk Matrix | immer | nein | +| 1400 | `ai-act` | AI Act Klassifizierung | immer | nein | +| 1500 | `audit-checklist` | Audit Checklist | immer | nein | +| 1600 | `audit-report` | Audit Report | immer | nein | + +### Paket 3 — Dokumentation + +| seq | id | Name | visibleWhen | isOptional | +|-----|----|------|-------------|-----------| +| 2000 | `obligations` | Pflichtübersicht | immer | nein | +| 2100 | `dsfa` | DSFA | Scope L2/L3/L4 oder `dsfaRequired`-Trigger | **ja** | +| 2200 | `tom` | TOMs | immer | nein | +| 2300 | `loeschfristen` | Löschfristen | immer | nein | +| 2400 | `vvt` | VVT | immer | nein | + +### Paket 4 — Rechtliche Texte + +| seq | id | Name | visibleWhen | isOptional | +|-----|----|------|-------------|-----------| +| 3000 | `einwilligungen` | Einwilligungen | immer | nein | +| 3100 | `consent` | Rechtliche Vorlagen | immer | nein | +| 3200 | `cookie-banner` | Cookie Banner | immer | nein | +| 3300 | `document-generator` | Dokumentengenerator | immer (→ `true`) | **ja** | +| 3400 | `workflow` | Document Workflow | immer | nein | + +### Paket 5 — Betrieb + +| seq | id | Name | visibleWhen | isOptional | +|-----|----|------|-------------|-----------| +| 4000 | `dsr` | DSR Portal | immer | nein | +| 4100 | `escalations` | Escalations | immer | nein | +| 4200 | `vendor-compliance` | Vendor Compliance | immer | nein | +| 4300 | `consent-management` | Consent Verwaltung | immer | nein | +| 4350 | `email-templates` | E-Mail-Templates | immer | nein | +| 4400 | `notfallplan` | Notfallplan & Breach Response | immer | nein | +| 4500 | `incidents` | Incident Management | immer | nein | +| 4600 | `whistleblower` | Hinweisgebersystem | immer | nein | +| 4700 | `academy` | Compliance Academy | immer | nein | +| 4800 | `training` | Training Engine | immer | nein | + +--- + +## Bedingte Sichtbarkeit (`visibleWhen`) + +Drei Steps haben eine `visibleWhen`-Funktion, die den `SDKState` auswertet: + +### `import` (seq 400) + +```typescript +visibleWhen: (state) => state.customerType === 'existing' +``` + +Nur sichtbar für **Bestandskunden**. Neukunden überspringen den Import-Schritt. + +### `dsfa` (seq 2100) + +```typescript +visibleWhen: (state) => { + const level = state.complianceScope?.decision?.determinedLevel + if (level && ['L2', 'L3', 'L4'].includes(level)) return true + const triggers = state.complianceScope?.decision?.triggeredHardTriggers || [] + return triggers.some(t => t.rule.dsfaRequired) +} +``` + +Sichtbar wenn: +- Compliance-Scope-Level **L2, L3 oder L4** ermittelt wurde, **oder** +- Ein Hard-Trigger mit `dsfaRequired: true` ausgelöst wurde (z.B. Gesundheitsdaten, Minderjährige, Hochrisiko-KI) + +Bei **L1-Kunden ohne DSFA-Trigger** ist der Schritt unsichtbar — TOM folgt direkt nach `obligations`. + +### `document-generator` (seq 3300) + +```typescript +visibleWhen: () => true +``` + +Immer sichtbar, aber `isOptional: true` — kann übersprungen werden. + +--- + +## Prerequisite-Kette + +Steps sind sequenziell verknüpft. Wichtige Besonderheiten: + +| Step | prerequisiteSteps | Hinweis | +|------|-------------------|---------| +| `dsfa` | `['obligations']` | Nicht von `audit-report` abhängig | +| `tom` | `['obligations']` | Nicht von `dsfa` abhängig (da optional) | +| `workflow` | `['cookie-banner']` | Nicht von `document-generator` abhängig (da optional) | + +**Regel:** Optionale Steps (`isOptional: true`) dürfen **keine** Pflicht-Steps als Voraussetzung haben. + +--- + +## Navigationsfunktionen + +Alle Funktionen in `admin-compliance/lib/sdk/types.ts`: + +```typescript +// Alle Steps global nach seq sortiert (privat) +function getAllStepsSorted(): SDKStep[] + +// Sichtbare Steps für aktuellen State +export function getVisibleSteps(state: SDKState): SDKStep[] + +// Nächster/vorheriger sichtbarer Step +export function getNextVisibleStep(currentStepId: string, state: SDKState): SDKStep | undefined +export function getPreviousVisibleStep(currentStepId: string, state: SDKState): SDKStep | undefined + +// Rückwärtskompatible Wrapper (state optional) +export function getNextStep(currentStepId: string, state?: SDKState): SDKStep | undefined +export function getPreviousStep(currentStepId: string, state?: SDKState): SDKStep | undefined + +// Package/Phase gefiltert, seq-sortiert +export function getStepsForPackage(packageId: SDKPackageId): SDKStep[] +export function getStepsForPhase(phase: SDKPhase): SDKStep[] +``` + +### Verhalten ohne `state` + +Wird kein State übergeben (Fallback), navigiert `getNextStep`/`getPreviousStep` seq-sortiert **ohne** `visibleWhen`-Filter. Das ist für Initialisierung und Tests nützlich. + +### Context-Integration + +`admin-compliance/lib/sdk/context.tsx` übergibt den State automatisch: + +```typescript +const goToNextStep = useCallback(() => { + const nextStep = getNextStep(state.currentStep, state) // state mitgeben! + if (nextStep) goToStep(nextStep.id) +}, [state, goToStep]) + +const canGoNext = useMemo(() => { + return getNextStep(state.currentStep, state) !== undefined +}, [state]) +``` + +--- + +## Neuen Step einfügen + +1. **seq wählen:** Freien Wert in der gewünschten Lücke wählen (z.B. 1050 zwischen 1000 und 1100) +2. **Step-Eintrag anlegen** in `SDK_STEPS` (types.ts): + +```typescript +{ + id: 'my-new-step', + seq: 1050, + phase: 1, + package: 'analyse', + order: 2, // Lokale Ordnung innerhalb des Pakets + name: 'Neuer Step', + nameShort: 'Neu', + description: 'Beschreibung', + url: '/sdk/my-new-step', + checkpointId: 'CP-NEW', + prerequisiteSteps: ['requirements'], + isOptional: false, + // optional: + visibleWhen: (state) => state.someFlag === true, +} +``` + +3. **Frontend-Seite** anlegen: `admin-compliance/app/sdk/my-new-step/page.tsx` +4. **Docs** erstellen: `docs-src/services/sdk-modules/my-new-step.md` +5. **mkdocs.yml** nav-Eintrag hinzufügen + +--- + +## Deprecated + +```typescript +/** @deprecated Use getVisibleSteps(state) instead */ +export function getVisibleStepsForCustomerType(customerType: CustomerType): SDKStep[] +``` + +Diese Funktion filtert nur den `import`-Step nach Kundentyp — nicht state-aware. Bitte `getVisibleSteps(state)` verwenden. diff --git a/mkdocs.yml b/mkdocs.yml index f8cb513..80a516e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -92,6 +92,7 @@ nav: - IACE (CE-Risikobeurteilung): services/sdk-modules/iace.md - Obligations v2 (CP-OBL): services/sdk-modules/obligations.md - Training Engine (CP-TRAIN): services/sdk-modules/training.md + - SDK Workflow & Seq-Nummern: services/sdk-modules/sdk-workflow.md - Entwicklung: - Testing: development/testing.md - Dokumentation: development/documentation.md