Niederlassungen

Zweck

Niederlassungen (Branch) sind die Mandanten-eigenen Standorte des Errichters — z. B. „Stuttgart" und „Berlin" eines Brandschutzbetriebes. Sie sind klar zu unterscheiden von Standorten (Location), die zu Kunden gehören. Pro Niederlassung pflegen Sie:

• vollständige Adresse,
• Kostenstelle,
• Primaer- und Sekundaer-Bank für Belegausgang,
• Kontaktdaten (E-Mail, Telefon, Fax, Webseite),
• steuerliche Identifikation (USt-IdNr., Steuernummer, Handelsregisternummer),
• Geschaeftsfuehrer(in).

Zusaetzlich koennen Sie über Neues Attributfeld strukturierte Custom-Felder ergaenzen — siehe Standardwerte und Attributfelder.

Voraussetzungen

- Mindestens eine Kostenstelle in den Stammdaten. - Optional: hinterlegte Bankkonten ([Bankkonten und Zuweisungen](/konzepte/bankkonten-und-zuweisungen)). - Berechtigung `create:Branch`.

Berechtigungen (CASL)

Frontend-Page-Guard:

Action	Subject	Keycloak-Rolle
view	FE_Branch	—
view	Branch	APP_SPEAMCORE_VIEW_BRANCH

API-Datenzugriff:

Action	Subject	Endpoint	Keycloak-Rolle
view	Branch	GET /api/branches, GET /api/branches/:id	APP_SPEAMCORE_VIEW_BRANCH
create	Branch	POST /api/branches	APP_SPEAMCORE_CREATE_BRANCH
update	Branch	PATCH /api/branches/:id	APP_SPEAMCORE_UPDATE_BRANCH
delete	Branch	DELETE /api/branches/:id	APP_SPEAMCORE_DELETE_BRANCH

Schritt-für-Schritt-Anleitung

Niederlassung anlegen

1. Niederlassungen (/branches) → + Neu.
2. Name vergeben (z. B. „Stuttgart", „Berlin").
3. Adresse pflegen — entweder Adressfelder direkt oder über das Suchfeld Adresse suchen (z. B. „Hauptstrasse 15, 70771 Stuttgart") für eine Adress-Autovervollstaendigung.
4. Kostenstelle auswählen — bestimmt die Kostenrechnung der Niederlassung.
5. Primaere Bank und optional Sekundaere Bank zuordnen — diese werden im Beleg-Footer als Zahlungsverbindung gedruckt.
6. Optional Kontaktdaten und steuerliche Felder ergaenzen. Bleiben diese leer, zieht das System die Werte aus den Mandanten-Haupteinstellungen (siehe Standardwerte und Attributfelder).
7. Speichern.

Bestehende Niederlassung pflegen

Änderungen werden automatisch gespeichert. Im Footer der Detailseite sehen Sie „zuletzt aktualisiert von … am …".

Custom-Felder ergaenzen

Am unteren Rand der Detailseite stehen zwei Buttons:

• Neues Attributfeld — fuegt ein strukturiertes Custom-Feld hinzu (Typ, Name, Default-Wert).
• Neues Feld — generisches Freitextfeld.

Details siehe Standardwerte und Attributfelder.

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

Tab: „Allgemeine Daten"

Aktuell der einzige standardmaessige Tab auf der Detailseite. Custom-Tabs koennen über Attributfelder entstehen.

Eingabe: Adress-Suche

Ein Suchfeld unter „Adresse" mit Placeholder Adresse suchen (z.B. Hauptstrasse 15, 70771 Stuttgart). Beim Auswählen eines Vorschlags werden Strasse, PLZ, Stadt, Land automatisch befuellt.

Auswahl: „Primaere Bank" / „Sekundaere Bank"

Dropdown-Auswahl aus den Mandanten-Bankkonten (BankAccount). Primaer wird im Belegfooter zuerst angezeigt; Sekundaer optional als Alternativ-Verbindung.

Button: „Neues Attributfeld"

Fuegt ein strukturiertes Custom-Feld hinzu. Siehe Standardwerte und Attributfelder.

Button: „Neues Feld"

Fuegt ein generisches Custom-Feld hinzu (freier Name + Wert). Siehe Standardwerte und Attributfelder.

Hauptniederlassung (Source of Truth)

Seit Juni 2026 ist eine Niederlassung pro Mandant die Hauptniederlassung (Feld isMainBranch = true). Sie ist die firmenweite Quelle für:

• Druck — Belegkopf/-footer und Briefkopf (Letterhead) ziehen Adresse, Bank und Pflichtangaben aus der Hauptniederlassung, wenn kein anderer Niederlassungs-Bezug vorliegt.
• Adresse der Firma.
• Bankverbindung (primäres/sekundäres Buchhaltungskonto).
• USt-IdNr., Steuernummer, Handelsregisternummer sowie Kontakt-Attribute (E-Mail, Telefon, Fax, Website, Geschäftsführer).

Diese Firmen-Stammdaten lagen früher in den Einstellungen unter /settings/company. Mit dem Umbau wurden sie per idempotenter, nicht-destruktiver Migration an die Hauptniederlassung übertragen; nur der Firmenname ist als Setting geblieben.

Regeln:

• Es gibt genau eine Hauptniederlassung. Setzen Sie den Schalter isMainBranch an einer anderen Niederlassung, wird die bisherige automatisch entmarkiert (erzwungen über einen beforeCreate/beforeUpdate-Hook).
• Ist (noch) keine Hauptniederlassung markiert, greift als Fallback die älteste Niederlassung.
• Lässt eine andere Niederlassung ein Kontakt-/Identifikationsfeld leer, erbt sie den Wert von der Hauptniederlassung (statt wie früher aus den Mandanten-Einstellungen).

Felder und Eingaben

Identifikation

Feldname	Pflicht	Datentyp	Beschreibung	Wirkung beim Ausfuellen	Voraussetzung
name	ja	String	Bezeichnung der Niederlassung.	Wird in Auswahllisten (Auftrag, Beleg, Mitarbeiter-Vertrag) und im Beleg-Footer als Niederlassungs-Name angezeigt.	—
isMainBranch	nein	Boolean (Switch, Default false)	Markiert diese Niederlassung als Hauptniederlassung.	Macht die Niederlassung zur firmenweiten Quelle für Druck, Adresse, Bank und USt-ID. Beim Aktivieren werden alle anderen Niederlassungen automatisch entmarkiert (genau eine Hauptniederlassung pro Mandant). Siehe Hauptniederlassung.	—
costCenterId	ja	UUID	Kostenstelle.	Bestimmt, auf welche Kostenstelle Buchungen aus dieser Niederlassung gehen. Reports werden danach gruppiert.	Kostenstelle muss in den Stammdaten existieren (CostCenter:view).
primaryBankAccountId	nein	UUID	Hauptkonto für Belegausgang.	Wird im Belegfooter zuerst als Zahlungsverbindung gedruckt.	Mindestens ein BankAccount mit IBAN/BIC angelegt.
secondaryBankAccountId	nein	UUID	Zweitkonto.	Optional als Alternativ-Bankverbindung im Belegfooter.	Wie primaere Bank.

Adresse

Feldname	Pflicht	Datentyp	Beschreibung	Wirkung beim Ausfuellen	Voraussetzung
street	nein	String	Strasse + Hausnummer.	Wird auf Belegen, Briefen und Mahnungen als Anschrift gedruckt.	—
zip	nein	String	Postleitzahl.	Wie Strasse. Beeinflusst Sortierungen nach Region.	—
city	nein	String	Stadt.	Wie Strasse.	—
countryId	nein	UUID	Land.	Bestimmt USt-Logik (innergemeinschaftlich vs. inland) und Belegformatierung.	Country:view. Land muss als Stammdatum existieren.

Adresse kann über das Adress-Suchfeld über dem name-Feld automatisch befuellt werden — beim Auswählen eines Vorschlags werden Strasse, PLZ, Stadt, Land in einem Schritt gesetzt.

Kontakt und Identifikation

Diese Felder werden im Belegfooter, in E-Mail-Signaturen und Reports verwendet. Lässt eine Nicht-Hauptniederlassung ein Feld leer, erbt sie den Wert von der Hauptniederlassung.

Feldname	Pflicht	Datentyp	Beschreibung	Wirkung beim Ausfuellen	Voraussetzung
email	nein	E-Mail	E-Mail (Allgemein).	Erscheint im Belegfooter; ueberschreibt den Mandanten-Default. Wird beim Versand „Antwort an" verwendet.	—
phone	nein	String + Laenderprefix	Telefon (Default +49).	Erscheint im Belegfooter und in Signaturen.	—
fax	nein	String	Fax.	Erscheint im Belegfooter, falls gepflegt.	—
website	nein	URL	Webseite.	Erscheint im Belegfooter und in Signaturen.	URL-Format.
managingDirector	nein	String	Geschaeftsfuehrer(in).	Erscheint im Belegfooter (Pflichtangabe nach §35a HGB).	—
vatId	nein	String	USt-IdNr.	Loest bei innergemeinschaftlichen Belegen Reverse-Charge-Logik aus.	Format [ISO-Code][Ziffern]. Wird automatisch normalisiert (UPPERCASE, ohne Leerzeichen/Bindestriche).
taxNumber	nein	String	Steuernummer.	Erscheint auf Rechnungen (Pflicht für deutsche Geschaeftskunden ohne USt-IdNr.).	—
commercialRegisterNumber	nein	String	Handelsregisternummer inkl. Registergericht.	Erscheint im Belegfooter (Pflichtangabe §35a HGB).	—

Bleibt ein Feld an einer Nicht-Hauptniederlassung leer, faellt das System bei Belegen und Reports auf den Wert der Hauptniederlassung zurück — siehe Standardwerte und Attributfelder.

Custom-Felder (am unteren Rand der Detailseite)

Button	Wirkung beim Klicken	Voraussetzung
Neues Attributfeld	Öffnet ein Dialog zum Anlegen eines strukturierten Attributs. Wird über AttributeParent (polymorph) am Branch verknuepft.	create:AttributeParent
Neues Feld	Fuegt ein generisches Schlüssel-Wert-Feld hinzu.	wie oben

Leere Kontakt-/Identifikationsfelder werden im Beleg-Druck automatisch durch den Wert der **Hauptniederlassung** ersetzt. Erklaeren Sie das aktiv, wenn Anwender fragen, wieso ein Wert auf der Rechnung erscheint, obwohl er an der Niederlassung nicht gepflegt ist.

Workflows und Zustaende

Niederlassungen haben kein Status-Feld — Aktivität erfolgt über Soft-Delete (paranoid).

Wiederverwendbare Konzepte

• Standardwerte und Attributfelder — wie „(Standardwert aus Haupteinstellungen, falls leer)" und Custom-Felder funktionieren.
• Bankkonten und Zuweisungen — BankAccount als Quelle für primary/secondary Bank.
• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Kostenstelle (CostCenter) — Pflicht-Referenz für Kostenrechnung.
• Bankkonten (BankAccount) — primaere/sekundaere Bank für Belegausgang.
• Mitarbeiter — EmployeeContract.branchId (Mitarbeiter-Vertrag verweist auf Branch).
• Aufträge — Workorder.branchId (Default aus Mitarbeiter-Vertrag).
• Einstellungen — hält nur noch den Firmennamen; die übrigen Firmen-Stammdaten liegen seit Juni 2026 an der Hauptniederlassung.

Häufige Fehler und Lösungen

Fehler	Lösung
Adresse wird beim Suchen nicht übernommen	Suchergebnis explizit anklicken — automatisches Anwenden erfolgt erst beim Klick.
Wert auf Beleg-Footer ohne Pflege	Wert kommt aus der Hauptniederlassung als Fallback. Wenn Sie ihn pro Niederlassung anders haben wollen, setzen Sie ihn hier explizit.
Falsche Firmen-Adresse/Bank im Druck	Prüfen, welche Niederlassung als Hauptniederlassung (isMainBranch) markiert ist — sie liefert die Druckdaten.
Bank-Auswahl leer	Noch kein BankAccount angelegt — siehe Setup-Wizard Schritt 6 oder direkt API.
Geaenderte Daten erscheinen nicht in alter Rechnung	Belege halten Adresse und Kontaktdaten als Snapshot. Änderung wirkt erst auf neue Belege.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/branches	Liste	view Branch
GET	/api/branches/:id	Detail	view Branch
POST	/api/branches	Anlegen	create Branch
PATCH	/api/branches/:id	Ändern	update Branch
DELETE	/api/branches/:id	Soft-Delete	delete Branch

Versionshinweise

• 2026-06-11: Hauptniederlassung (isMainBranch) als firmenweite Source-of-Truth für Druck/Adresse/Bank/USt-ID dokumentiert; Firmen-Stammdaten von /settings/company an die Hauptniederlassung migriert; Fallback für leere Felder von Mandanten-Einstellungen auf die Hauptniederlassung umgestellt. Verifiziert an branch.model.ts (isMainBranch, enforceSingleMainBranch), getMainBranch.ts, loadLetterheadConfig.ts und den Backfill-Migrationen.
• 2026-04-29: Inhaltliche Komplettierung nach IST-Vorlage (KFT-Beispiel) — Adressfelder, Kontakt-, Identifikations- und Custom-Field-Bereich vollständig dokumentiert.
• 2026-04-29: Initiale Veroeffentlichung.