Erst-Einrichtung (Setup-Wizard)

Bis April 2026 war der Setup-Wizard ein **Modal** auf der Login-/Home-Seite (Frontmatter-Endpoint war `/setup-required-modal`). Seit Mai 2026 ist `/setup-wizard` eine **eigenständige Route** mit eigener Page (FE-Tag v1.71.0). Hintergrund: bessere UX — der Admin kann den Wizard jederzeit aufrufen, um Schritte nachträglich zu erledigen oder zu überspringen.

Begleitende BE-Änderungen (v1.64.0):

• feat(setup-wizard): backend support — country revision heal + step status cleanup
• chore(setup-wizard): drop redundant FE_SetupWizard CASL subject
• fix(setup-wizard): finish/skip now actually removes the realm role
• Tasks-Folder tasks/2026-04-28_initial-setup-assistant/ mit strukturierten DECISIONS / PROGRESS / NEXT_STEPS

Der „Erst-Einrichtung erforderlich"-Realm-Role in Keycloak wird nach Abschluss/Skip korrekt entfernt — der Wizard erscheint nicht mehr als verpflichtender Block beim Login. FE_SetupWizard-CASL-Subject wurde entfernt — die Route prüft auf die regulären Setup-Permissions.

Der **Wizard-Redirect** im `SecurityLayout` läuft über den neuen Hook `useSetupWizardRoleDirect`, der `GET /api/setup/role-direct` aufruft. Der Endpoint nutzt einen Keycloak-Service-Account, um zu prüfen, ob die Rolle `APP_SPEAMCORE_DO_SETUP_WIZARD` dem aktuellen User **direkt** zugewiesen ist (nicht über eine Keycloak-Gruppe vererbt).

Hintergrund: POST /api/setup/finish versucht beim Abschluss, die Rolle direkt vom User zu entfernen. Wäre sie nur über eine Gruppe geerbt, würde der Cleanup fehlschlagen und der User würde nach jedem Login wieder im Wizard landen.

Logik:

• isDirect === true → Wizard zeigen, beim Finish/Skip läuft der Cleanup sauber.
• isDirect === false → Rolle ist nur per Gruppe vererbt → Wizard überspringen (User wäre sonst gefangen).
• API-Fehler oder Loading-Status → trotzdem Wizard zeigen (Fix bd444294), damit der User keine leere Seite sieht.

CASL-Gate des Endpoints: do:SetupWizard. Implementation: api.speamcore.com/src/controllers/setup.controller.ts (checkRoleDirect).

Zweck

SpeamCore liefert nach der Mandanten-Anlage einen One-Click-Setup-Pfad für die deutsche Buchhaltung. Solange dieser nicht durchlaufen wurde (oder bewusst uebersprungen), erscheint beim ersten Besuch von /accounts oder /tax-rates ein SetupRequiredModal mit zwei Pfaden:

1. Standards (DE) laden — empfohlen. Backend-Endpoint POST /api/setup/de-defaults legt idempotent in einer Transaktion an:
   • SKR03 als ChartOfAccountFramework plus alle 10 Klassen.
   • Standard-TaxRates mit historischen Validitaeten (z. B. 19 % / 16 % / 7 %).
   • ~250 SKR03-Konten als Account-Sätze, mit Verknuepfung zur Steuer-Logik.
   • AccountLinks für Skonto / Bonus / Rabatt.
2. Selbst einrichten — Anwender bestätigt per Checkbox, dass das Setup manuell durchgeführt wird, und das Modal erscheint nicht mehr (Settings.accountingSetupSkipped = true). Die Markierung kann später über /settings zurueckgenommen werden.

Seit Mai 2026 ist der Setup-Wizard ein **geführter Mehr-Schritte-Flow** auf der Route `/setup-wizard` (`SetupWizardPage` rendert die Liste aus `config/setupSteps.ts`). Jeder Schritt hat eine **Anforderungs-Stufe**: `mandatory` (Pflicht), `recommended` (empfohlen), `optional` oder `review` (nur prüfen).

Daneben existiert weiterhin das alte SetupRequiredModal (One-Click-„Standards (DE) laden") — es erscheint situativ auf den Konten-/Steuer-Seiten und läuft über denselben de-defaults-Endpoint, den der Wizard-Schritt Buchhaltung (SKR03) intern aufruft (SetupService.seedDeDefaults()).

Die Schritte im Überblick

#	Schritt	Stufe	Inhalt
1	Firmen-Stammdaten	Pflicht	Firmenname, Adresse, Kontakt.
2	Sprache & Region	Pflicht	Locale/Zeitzone (Default de-DE).
3	Branding	optional	Logo + Farben (/customization/general).
4	Buchhaltung (SKR03)	empfohlen	Lädt SKR03 + Steuersätze + Konten über de-defaults (idempotent).
5	DATEV	optional	DATEV-Export-Vorgaben.
6	Bankkonto	optional	Erstes Bankkonto hinterlegen.
7	Master-Sync (Stammdaten)	empfohlen	Einheiten + HS-Codes von einem zentralen Master laden — siehe unten.
8	Zahlungsziele	empfohlen	Standard-Zahlungsziele.
9	Arbeitszeitmodelle	empfohlen	Arbeitszeit-Modelle.
10	Textbausteine	empfohlen	Standard-Textbausteine.
11	Nummernkreise	prüfen	Nummernkreise kontrollieren.
12	Postfach	optional	Erstes Mail-Postfach verbinden.

Schritte sind überspringbar; der Wizard merkt sich den Fortschritt und ist jederzeit über /setup-wizard erneut aufrufbar.

Schritt 7 — Master-Sync (Stammdaten von zentralem Master)

Der Schritt Master-Sync lädt zentral gepflegte Stammdaten — Einheiten (Unit, z. B. Stück, Meter, Stunde) und HS-Codes (Zolltarif-Nummern) — von einem übergeordneten Speam-Master in Ihren Mandanten. So müssen diese Standard-Listen nicht pro Mandant von Hand gepflegt werden.

Pro Datentyp (Einheiten / HS-Codes) sehen Sie eine Zeile mit Status und Aktion:

Status	Bedeutung	Aktion
„noch nicht synchronisiert"	Lokal sind keine Datensätze vorhanden.	Synchronisieren klicken.
„synchronisiert (N)" ✓	Alle N Datensätze sind geladen und aktuell.	Optional erneut laden (Refresh-Icon).
„X von Y" (orange)	Es sind weniger lokale als Master-Datensätze vorhanden — Teil-Stand.	Synchronisieren klicken, um zu vervollständigen.
„wird synchronisiert…"	Der Hintergrund-Abgleich läuft (Status aktualisiert sich automatisch alle ~3 s).	warten.
„Master nicht erreichbar" (rot)	Der zentrale Master ist gerade nicht erreichbar.	später erneut versuchen.

Der Abgleich läuft als Hintergrund-Job — Sie können im Wizard weiterarbeiten; die Zeile aktualisiert sich selbst, wenn der Sync fertig ist.

Der hier sichtbare Teil (Einheiten + HS-Codes im Setup-Wizard, plus Refresh-Buttons auf den Listen [/units](/units) und [/hscodes](/hscodes)) ist alles, was Endanwender vom Master-Sync sehen. Die dahinterliegende Mechanik (zentrale Berechtigungs-Steuerung, `masterId`-Verknüpfung, laufender bidirektionaler Abgleich weiterer Datentypen) ist reine Infrastruktur und wird vom Speam-Team verwaltet — technische Details siehe interne Notiz `_internal/feature-notes/admin-master-sync.md`.

Voraussetzungen

- Anwender hat Berechtigungen `create:Account`, `create:TaxRate`, `create:ChartOfAccountFramework`/`ChartOfAccountClass`, `create:AccountLink`, `update:Settings`. - Mandant ist im Keycloak-Realm angelegt (siehe [Mandanten-Konzept](/konzepte/mandanten)). - Anwender hat noch keine SKR03-Konten gepflegt (sonst kein Trigger).

Berechtigungen (CASL)

Action	Subject	Wirkung	Keycloak-Rolle
create	Account	SKR03-Konten anlegen	APP_SPEAMCORE_CREATE_ACCOUNT
create	TaxRate	Steuersätze anlegen	APP_SPEAMCORE_CREATE_TAX_RATE
create	ChartOfAccountFramework, ChartOfAccountClass	Kontenrahmen + Klassen	APP_SPEAMCORE_CREATE_CHART_OF_ACCOUNT_FRAMEWORK, CHART_OF_ACCOUNT_CLASS
create	AccountLink	Skonto-/Bonus-/Rabatt-Verknuepfungen	APP_SPEAMCORE_CREATE_ACCOUNT_LINK
update	Settings	Skipped-Flag setzen	APP_SPEAMCORE_UPDATE_SETTINGS

Schritt-für-Schritt-Anleitung

1. Anmelden mit dem ersten Mandanten-Admin (Keycloak-Realm).
2. Auf der Startseite oder direkt über Konten (/accounts) — der SetupRequiredModal öffnet sich.
3. Optionen:
   • „Standards (DE) laden" klicken → Backend laeuft idempotent durch, Toast „Setup erfolgreich" mit Counter (Anzahl Konten / TaxRates / AccountLinks).
   • Alternativ Checkbox „Selbst einrichten" aktivieren und Bestaetigen — Modal erscheint nicht mehr.
4. Danach durch die regulären Modul-Seiten konfigurieren — Niederlassungen, Mitarbeiter, Anpassungs-Settings etc.

**Re-Run:** Der Endpoint ist idempotent — bei wiederholtem Aufruf werden vorhandene Konten/Steuern erkannt und nur fehlende ergaenzt. Der Modal selbst kann über das `Settings.accountingSetupSkipped`-Flag erneut erzwungen werden, falls das Setup ungewollt ueberlebt wurde.

Toolbar (Detail-Seite)

Schlanke Toolbar oben rechts:

Icon	Aktion (aria-label)	CASL	Wirkung
←	Zurückgehen	—	Zurück zur Liste.
🏠	Zur Startseite gehen	—	Springt auf das Dashboard / /.
⏮/◀/▶/⏭	Pagination	—	Navigation durch die gefilterte Liste — Massen-Bearbeitung ohne Liste-Sprung.

Globale Floating-Drawer (links)

Wie auf jeder Detail-Seite verfuegbar — siehe Floating-Quickbar:

• KAL. (Mini-Kalender)
• ZEIT (Persoenliche Wochen-Arbeitszeit)
• ARBEIT (Eigene bevorstehende Aufträge)

UI-Elemente

Komponente: SetupRequiredModal

speamcore.com/src/components/SetupRequiredModal/SetupRequiredModal.tsx — wird in AccountListPage und TaxRateListPage über den Hook useSetupRequired() getriggert.

Hook: useSetupRequired

Steuert den Modal: prueft ob accountingSetupSkipped-Flag gesetzt ist und ob bereits Konten existieren; bietet runSetup() und markAsSkipped().

Wiederverwendbare Konzepte

• Buchhaltungskonten — was SKR03 in SpeamCore bedeutet.
• Mandanten — Multi-Tenant-Architektur.
• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Konten — Setup legt ~250 SKR03-Konten an.
• Steuersaetze — Setup legt Default-TaxRates (19 % / 7 % / 0 %) plus historische Validitaeten an.
• Kontenrahmen — SKR03 als ChartOfAccountFramework.
• Kategorien — Setup legt typische Kategorien an.
• Anpassung — Branding-Werte (Logo, Farben) werden separat über PublicAttribute gepflegt.
• Settings — accountingSetupSkipped-Flag steuert das Modal.

Häufige Fehler und Lösungen

Fehler	Lösung
Modal erscheint dauerhaft trotz erfolgreichem Setup	Settings.accountingSetupSkipped prüfen und ggf. setzen.
Setup laeuft mit Fehler ab	Backend-Logs prüfen — meist Berechtigungs- oder DB-Constraint-Probleme.
„Selbst einrichten" gewählt, jetzt fehlen die SKR03-Konten	accountingSetupSkipped zuruecksetzen, Modal wird wieder angezeigt, „Standards (DE) laden" klicken.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
POST	/api/setup/de-defaults	Idempotent SKR03 + TaxRates + Konten + AccountLinks anlegen	create Account, create TaxRate, create ChartOfAccountFramework, create ChartOfAccountClass, create AccountLink
GET	/api/admin-sync/:entityType/info	Sync-Status eines Datentyps (Master-/Lokal-Anzahl, letzter Sync)	Keycloak-geschützt
POST	/api/admin-sync/:entityType/trigger	Master-Sync als Hintergrund-Job starten (Body {forceReset?})	Keycloak-geschützt

Der Master-Sync-Schritt nutzt /admin-sync/:entityType/info + /trigger für die Datentypen Unit und HsCode.

Response (Auszug):

{
  "framework": { "id": "...", "name": "SKR03" },
  "classes": { "created": 10, "updated": 0 },
  "taxRates": { "created": 8, "updated": 0 },
  "taxRateValidities": { "created": 12, "updated": 0 },
  "accounts": { "created": 246, "updated": 0 },
  "taxAccountsLinked": 8,
  "accountLinks": { "created": 24, "skipped": 0 }
}

Versionshinweise

• 2026-05-31: Drift-Korrektur — das FE hat seit Mai 2026 wieder einen echten geführten 12-Schritte-Wizard (config/setupSteps.ts, gerendert von SetupWizardPage), mit Anforderungs-Stufen pro Schritt. Schritt-Tabelle ergänzt; neuer Schritt Master-Sync (Einheiten + HS-Codes vom zentralen Master) dokumentiert. Das SetupRequiredModal existiert weiterhin parallel und nutzt denselben de-defaults-Endpoint wie der SKR03-Schritt.
• 2026-04-30: Doku auf den damaligen Code-Stand korrigiert — zu diesem Zeitpunkt nur SetupRequiredModal mit One-Click-Setup über /api/setup/de-defaults (der mehrstufige Wizard war vorübergehend nicht aktiv). Siehe Korrektur 2026-05-31.