Verkaufsbeleg-Positionen (SalesDocumentItems)

Zweck

/sales-document-items ist eine globale Cross-Beleg-Sicht auf alle Positionen (SalesDocumentItem) aus allen Verkaufsbelegen. Diese Liste eignet sich für Auswertungen über Belege hinweg — etwa „welche Produkte wurden in den letzten 30 Tagen verkauft" oder „wo lag der Margen-Schnitt im Q1".

Die Liste ist read-only (kein POST/PATCH/DELETE auf der Cross-Liste); Pflege erfolgt im Beleg-Kontext über /sales-documents/:id/items.

Voraussetzungen

- Berechtigung `view:SalesDocumentItem`. - Für Drill-Down ins Belegdetail: `view:SalesDocument`.

Berechtigungen (CASL)

Action	Subject	Wirkung	Keycloak-Rolle
view	FE_SalesDocumentItem, SalesDocumentItem	Cross-Liste aufrufbar	—
view	SalesDocument	Drill-Down zum Beleg	APP_SPEAMCORE_VIEW_SALES_DOCUMENT

Schritt-für-Schritt-Anleitung

1. Verkaufsbeleg-Positionen (/sales-document-items) — DataGrid mit allen Positionen.
2. Filter und Sortierung pro Spalte (Beleg-Nummer, Produkt, Datum, Preis, Marge, ...).
3. Klick auf Position → Drill-Down zum jeweiligen Beleg /sales-documents/:salesDocumentId.

Felder und Eingaben (lesend)

Auswahl der wichtigsten Felder aus dem Modell SalesDocumentItem:

Feldname	Datentyp	Bedeutung
salesDocumentId	UUID	Verweis auf den Beleg.
position	String	Positionsnummer (z. B. 1, 1.1).
type	String	Positions-Typ: Product, Text oder Discount (Rabatt-Position, neu Mai 2026).
discount	Decimal	Rabatt-Wert. Nur bei discountType/Rabatt relevant.
discountType	String	percentage (Prozent, Default) oder fixed (fester Betrag).
productId	UUID	Verweis auf Produkt (optional).
productNo	String	Produkt-Nummer zum Zeitpunkt der Erfassung.
productTitle / productDescription	String / TEXT	Anzeige-Texte.
quantity	Decimal	Menge.
price	Decimal	Verkaufspreis (netto).
purchasePrice	Decimal	Einkaufspreis (bereits rabattierter EK, für Marge).
productSupplier	Lookup	Produkt-Lieferant — Quelle des Einkaufspreises, wenn kein expliziter purchasePrice gesetzt ist.
hsCode/hsCodeName	String	Zolltarif.
optional / alternative	Boolean	Position als Optional bzw. Alternative gekennzeichnet.
productUnit / productUnitId	String / UUID	Einheit (Snapshot + Verweis).
productGroupId	UUID	Produkt-Gruppe.
accountId	UUID	Buchhaltungskonto.

Gewinn-Spalte (Marge)

Die Liste zeigt pro Position eine Gewinn-Spalte im Format Betrag (Prozent), z. B. 368,60 € (38,00 %). Berechnung:

• Gewinn = (rabattierter Verkaufspreis − Einkaufspreis) × Menge.
• Marge (%) = Gewinn ÷ Verkaufs-Summe × 100.

Sonderfälle:

Anzeige	Bedeutung
„Produkt hat keinen Lieferanten"	Es ist weder ein Produkt-Lieferant noch ein Einkaufspreis (purchasePrice) hinterlegt — ohne EK lässt sich keine Marge berechnen. Lösung: am Produkt einen Lieferanten/Einkaufspreis pflegen.
leer / keine Anzeige	Bei Positions-Typ ≠ Product (z. B. Text- oder Rabatt-Zeilen) sowie bei Korrekturrechnung und Gutschrift wird kein Gewinn ausgewiesen.

Die Gewinn-/Margen-Spalte ist eine **interne** Auswertungshilfe in der Cross-Beleg-Liste. Sie erscheint **nicht** auf dem gedruckten Kundenbeleg.

Rabatt-Positionen (neu, Mai 2026)

SpeamCore kennt seit Mai 2026 einen eigenen Positions-Typ Discount — eine Rabatt-Zeile, die wie eine normale Position im Beleg steht, aber die Summe reduziert statt erhöht.

Zwei Ebenen, nicht verwechseln:

Ebene	Wo	Wirkung
Positions-Rabatt	Felder discount + discountType direkt an einer Produkt-Position	Reduziert nur diese eine Position. fixed = fester Betrag pro Stück (× Menge), percentage = Prozent vom Zeilen-Betrag. Netto wird nie negativ.
Beleg-Rabatt	eigene Position vom Typ Discount	Reduziert das Gesamt-Netto des Belegs. Die Umsatzsteuer wird auf dem reduzierten Netto neu berechnet, anteilig pro Steuersatz.

So legen Sie eine Beleg-Rabatt-Position an (im Beleg-Detail /sales-documents/:id/items):

1. + Position hinzufügen → Rabatt wählen.
2. Rabatt-Art wählen: Prozent (percentage) oder fester Betrag (fixed).
3. Wert eingeben (z. B. 10 für 10 % oder 50 für 50,00 €).

In der Liste erscheint die Rabatt-Zeile mit negativem Summen-Betrag; in der Summen-Box sehen Sie „Netto nach Rabatt" und die darauf neu berechnete USt.

Beleg-Rabatte werden in der E-Rechnung normkonform als **Allowance auf Dokument-Ebene** (EN 16931, Gruppe BG-20) ausgegeben — mit `ChargeIndicator=false`, optionalem Rabatt-Grund und je Steuerkategorie ausgewiesenem Betrag. Der steuerpflichtige Betrag (`TaxExclusiveAmount`) wird entsprechend gemindert. Sie müssen dafür nichts extra tun — die Rabatt-Position fließt automatisch korrekt in die E-Rechnung ein (siehe [Glossar: E-Rechnung / XRechnung](/grundlagen/glossar#e)).

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)

Wiederverwendbare Konzepte

• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Verkaufsbelege — Eltern-Entitaet. Pflege erfolgt im Beleg-Detail.
• Produkte — productId-Verweis.
• Konten — accountId-Verweis für Buchungs-Logik.
• Geschaefts-Analyse — verwandte Auswertung mit Aggregations-Tabs.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/sales-document-items	Cross-Liste	view SalesDocumentItem
GET	/api/sales-document-items/:id	Detail	view SalesDocumentItem

Versionshinweise

• 2026-05-29: Rabatt-Position (Discount-Typ) + Felder discount/discountType dokumentiert; EN-16931-Allowance in E-Rechnung erläutert.
• 2026-04-30: Initiale Veroeffentlichung.