Textbausteine

Zweck

Textbausteine (TextBlock) sind wiederverwendbare HTML-Textfragmente, die auf Verkaufs- und Bestellbelegen erscheinen — z. B. Rechnungsfusstext, Pflichtangaben (Kleinunternehmer §19 UStG), AGB-Abschnitte, Lieferbedingungen. Pro Textbaustein koennen Sie über den Tab Defaults (TextBlockDefault) Kunden- oder Standort-spezifische Overrides anlegen.

Voraussetzungen

- Berechtigung `create:TextBlock`. - Für Defaults zusaetzlich `view:TextBlockDefault`.

Berechtigungen (CASL)

Action	Subject	Wirkung	Keycloak-Rolle
view	FE_TextBlock, TextBlock	Liste/Details aufrufbar	—
create/update/delete	TextBlock	Pflegen	APP_SPEAMCORE_CREATE/UPDATE/DELETE_TEXT_BLOCK
view	TextBlockDefault	Tab Defaults sichtbar	APP_SPEAMCORE_VIEW_TEXT_BLOCK_DEFAULT

Schritt-für-Schritt-Anleitung

Textbaustein anlegen

1. Textbausteine (/text-blocks) → + Neu.
2. Name vergeben (z. B. „Rechnungsfusstext", „Pflichtangaben Kleinunternehmer").
3. Im HTML-Editor den Inhalt formatieren — Listen, Hervorhebungen, Links erlaubt.
4. Änderungen werden automatisch gespeichert.

Kunden-spezifischen Default anlegen

1. Tab Defaults öffnen (/text-blocks/:id/defaults).
2. Default für einen Kunden oder Standort hinterlegen — der Override-Text wird statt des Standard-Textes auf Belegen dieses Kunden eingesetzt.

**HTML-Inhalt wird im aktuellen Code nicht serverseitig sanitiert.** Pflegen Sie nur vertrauenswuerdige Quellen ein und vermeiden Sie eingefuegtes Markup aus externen Editoren.

E-Mail-Vorlagen (neu, Juni 2026)

Textbausteine gibt es seit Juni 2026 in zwei Kategorien (category):

• standard — die bisherigen Belegtexte (Fusstext, Pflichtangaben), die beim Druck eines Belegs eingefügt werden.
• emailTemplate — E-Mail-Vorlagen, die beim Versand eines Belegs oder Protokolls per Mail den Betreff und den Nachrichtentext vorausfüllen.

Eine E-Mail-Vorlage hat zwei Felder: subject (Betreffzeile) und text (HTML-Body). Beide dürfen Platzhalter enthalten.

Platzhalter (Variablen)

Platzhalter haben die Form {{bereich.feld}} und werden beim Öffnen des Versand-Dialogs durch die echten Werte ersetzt (nicht gefundene Platzhalter werden leer ersetzt — keine {{…}}-Reste). Verfügbar sind:

Platzhalter	Inhalt
{{customer.name}}	Kundenname
{{customer.street}} / {{customer.zip}} / {{customer.city}}	Kunden-Adresse
{{location.name}}	Standortname
{{location.street}} / {{location.zip}} / {{location.city}}	Standort-Adresse
{{workorder.number}}	Auftragsnummer
{{salesDocument.number}}	Belegnummer

Im Vorlagen-Editor (Betreff und Body) gibt es einen Variablen-Picker, der den gewählten Platzhalter an der Cursor-Position einfügt.

Welche Vorlage wird genommen? (Matching)

Beim Klick auf Per Mail senden an einem Beleg/Protokoll wählt SpeamCore die passende Vorlage zweistufig:

1. Spezifisch: Vorlage, die genau auf den Beleg-Typ passt (z. B. Verkaufsbeleg-Typ invoice, offer, depositInvoice, … oder Auftrags-Protokoll TechnicalReport, ProofOfPerformance, …).
2. Fallback: Wenn keine spezifische Vorlage existiert, eine allgemeine Vorlage nach E-Mail-Kategorie (z. B. invoice, documentation, general).

Die Zuordnung erfolgt über TextBlockDefault mit textBlockType = 'emailTemplate'. Anders als die automatischen Belegtexte haben E-Mail-Vorlagen das Verhalten optional — sie werden nie automatisch an einen Beleg gehängt, sondern nur beim Mailversand herangezogen.

Empfänger-Vorbelegung

Der Versand-Dialog schlägt zusätzlich die Empfänger-Adresse vor. Sie wird aus den Kontakt-Attributen von Standort bzw. Kunde gezogen — zuerst die zur E-Mail-Kategorie passende Adresse (z. B. „Email (Invoice)", „Email (Documentation)"), sonst die allgemeine Adresse „Email (General)". Sie können den Vorschlag im Dialog vor dem Senden ändern.

Betreff, Text und Empfänger sind nur **Vorbelegungen** — der Versand-Dialog öffnet sich mit dem vollwertigen Mail-Editor, in dem Sie alles vor dem Senden prüfen und anpassen können. Nichts wird automatisch verschickt.

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

Button: „+ Neu"

Listenseite. Erzeugt leeren Datensatz, navigiert auf Details.

Komponente: HTML-Editor

WYSIWYG-Editor für das text-Feld. Unterstützt Listen, Tabellen, Bold/Italic, Links.

Tab: „Defaults"

Sub-Liste der TextBlockDefault-Einträge für diesen Textbaustein. Pro Eintrag: parentId + parentType (Customer / Location) und ein eigener Override-text.

Felder und Eingaben

Feldname	Pflicht	Datentyp	Beschreibung	Wirkung beim Ausfuellen	Voraussetzung
name	ja	String	Bezeichnung des Bausteins (intern).	Erscheint in Auswahl-Selects auf Beleg-Detailseiten und in der Liste.	—
category	nein	standard / emailTemplate	Art des Bausteins. standard = Belegtext (Druck), emailTemplate = E-Mail-Vorlage (Versand).	Steuert, wo der Baustein verwendet wird.	—
subject	nur bei emailTemplate	String	Betreffzeile der E-Mail-Vorlage, darf Platzhalter enthalten.	Füllt den Betreff im Versand-Dialog vor.	nur relevant bei category = emailTemplate.
text	ja	HTML	Eigentlicher Textbaustein-Inhalt.	Bei standard beim Druck eingefügt; bei emailTemplate als Mail-Body vorausgefüllt. Kunden-Override (TextBlockDefault) ueberschreibt diesen Wert pro Beleg-Empfaenger.	HTML; serverseitig nicht sanitiert.

Workflows und Zustaende

Kein Status-Feld. Soft-Delete via paranoid.

Wiederverwendbare Konzepte

• Polymorpher Parent-Pattern — TextBlockParent verknuepft Textbausteine mit Belegen; TextBlockDefault wiederum mit Kunden/Standorten.
• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Verkaufsbelege — TextBlockParent.parentType = 'SalesDocument' haengt einen Textbaustein an einen konkreten Beleg.
• Bestellbelege — analog parentType = 'PurchaseDocument'.
• Setup-Wizard Schritt 10 — Standard-Set wird dort angelegt (Rechnungsfusstext, Pflichtangaben).
• TextBlockDefault — Kunden-/Standort-spezifische Override-Texte.

Häufige Fehler und Lösungen

Fehler	Lösung
Override wirkt nicht auf Beleg	TextBlockDefault.parentType muss zum Beleg-Empfaenger passen (Customer vs. Location).
HTML wird nicht korrekt gerendert	Externer Editor fuegt unzulaessige Tags ein — direkt im SpeamCore-Editor formatieren.
Textbaustein erscheint doppelt	An mehreren Stellen über TextBlockParent verknuepft. Beleg-Detailseite prüfen.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/text-blocks	Liste	view TextBlock
GET	/api/text-blocks/:id	Detail	view TextBlock
POST	/api/text-blocks	Anlegen	create TextBlock
PUT	/api/text-blocks/:id	Ändern	update TextBlock
DELETE	/api/text-blocks/:id	Soft-Delete	delete TextBlock
GET	/api/text-block-defaults?textBlockId=:id	Customer/Location-Overrides	view TextBlockDefault

Versionshinweise

• 2026-06-02: E-Mail-Vorlagen ergänzt — neue Kategorie emailTemplate mit subject-Feld, {{bereich.feld}}-Platzhaltern (10 Variablen), Variablen-Picker, zweistufigem Vorlagen-Matching (spezifisch → Kategorie-Fallback) und Empfänger-Vorbelegung. Quelle: FE fillTemplateVariables.ts, emailTemplateVariables.ts, useSendByMail.ts; BE mailTemplateSeeder.service.ts.
• 2026-04-29: Initiale Veroeffentlichung mit FE-Tiefen-Standard.