Verkaufsbeleg — Textbausteine (Sub-Route)

Zweck

Sub-Route /sales-documents/:id/text-blocks zeigt alle Textbausteine, die am aktuellen Beleg gebunden sind — typisch Header-Text, Footer-Text, AGB-Hinweis, Liefer-/Garantiebedingungen. Verknuepfung erfolgt über das polymorphe TextBlockParent-Modell.

Detail-Sub-Route /sales-documents/:id/text-blocks/:textBlockParentId rendert den konkreten Eintrag mit Override-Texten.

Voraussetzungen

- Berechtigung `view:SalesDocument` und `view:TextBlockParent`/`view:TextBlock`. - Für Pflege: `create`/`update`/`delete:TextBlockParent`.

Berechtigungen (CASL)

Action	Subject	Wirkung	Keycloak-Rolle
view	FE_SalesDocument, SalesDocument	Detail aufrufbar	—
view	TextBlock	Baustein-Stamm	APP_SPEAMCORE_VIEW_TEXT_BLOCK
view/create/update/delete	TextBlockParent	Beleg-Verknuepfung	APP_SPEAMCORE_VIEW/CREATE/UPDATE/DELETE_TEXT_BLOCK_PARENT

Schritt-für-Schritt-Anleitung

1. Verkaufsbeleg (/sales-documents/:id) → Tab Textbloecke.
2. + Baustein wählt einen TextBlock aus dem Stamm. Eine TextBlockParent-Verknuepfung wird erzeugt mit parentType = SalesDocument, parentId = :id, position = naechste.
3. Position der Bausteine (Code-Lookup apply-text-block-defaults Endpoint) ist relevant für das PDF:
   • Vor den Positionen (position = 'before') — z. B. „Sehr geehrter Kunde, anbei unser Angebot..."
   • Nach den Positionen (position = 'after') — z. B. AGBs, Zahlungsbedingungen, Footer.
4. Override-Texte im Detail-Modal /sales-documents/:id/text-blocks/:textBlockParentId pflegen — Anwender ueberschreibt Stamm-Text für diesen einzelnen Beleg, ohne den Stamm zu touchieren. Original bleibt erhalten.
5. Reihenfolge innerhalb derselben Position per Drag-and-Drop.

Vorgegebene Defaults beim Beleg-Anlegen

Beim Anlegen eines neuen SalesDocument werden automatisch Default-Textbloecke verknuepft:

• Bausteine mit defaultForDocumentType = aktueller documentType
• Bausteine mit defaultForAll = true

Endpoint: POST /api/sales-documents/:id/apply-text-block-defaults — wird vom FE beim Beleg-Anlegen einmalig aufgerufen. Manuelles Re-Apply möglich, wenn der Stamm später erweitert wurde.

**Mandantenscope:** TextBloecke werden im Mandanten gepflegt ([/text-blocks](/text-blocks)) und sind nicht uebergreifend gültig. Änderungen am Baustein wirken nicht auf bereits verknuepfte Belege — bestehende `TextBlockParent`-Einträge haben den Stamm-Text als Snapshot. Wer aktuelle Texte will, muss "Override" setzen oder die Verknuepfung neu anlegen.

Wiederverwendbare Konzepte

• Polymorpher Parent-Pattern — TextBlockParent.
• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Verkaufsbelege — Eltern-Modul.
• Textbausteine — Stamm-Daten.
• Bestellbelege — eigene Textbaustein-Sub-Route mit identischem Pattern.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/text-block-parents?filter[parentType=SalesDocument]	Liste	view TextBlockParent
POST	/api/text-block-parents	Verknuepfen	create TextBlockParent
PATCH	/api/text-block-parents/:id	Override pflegen	update TextBlockParent
DELETE	/api/text-block-parents/:id	Verknuepfung entfernen	delete TextBlockParent

Versionshinweise

• 2026-04-30: Initiale Veroeffentlichung.