Mengeneinheiten

Zweck

Mengeneinheiten (Unit) bilden die Mengen-Stammdaten (Stk, kg, m, h, l, m², m³, ... über 2 000 UN/ECE-Codes). Sie werden zentral von der Speam-Master-Datenbank synchronisiert — Mandanten koennen die Stammwerte nicht ändern, sondern nur das relevant-Flag setzen, um eigene Auswahl-Listen schlanker zu machen.

Voraussetzungen

- Master-Sync wurde mindestens einmal durchgeführt (siehe Setup-Wizard Schritt 7). - Berechtigung `view:Unit`. Für `relevant`-Flag ändern: `update:Unit`.

Berechtigungen (CASL)

Action	Subject	Wirkung	Keycloak-Rolle
view	FE_Unit, Unit	Liste/Details aufrufbar	—
update	Unit	relevant-Flag setzen	APP_SPEAMCORE_UPDATE_UNIT

Schritt-für-Schritt-Anleitung

Einheit als „relevant" markieren

1. Mengeneinheiten (/units).
2. Einheit anklicken.
3. Relevant-Switch aktivieren.
4. Wert wird automatisch gespeichert.

Master-Sync auslosen

1. Auf der Listen-Seite den Sync-Button klicken (oder über API POST /api/units/sync).
2. Das System fetcht die aktuellen Master-Werte und upsert sie lokal.

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

Switch: „Relevant"

Einziges editierbares Feld. Steuert, ob die Einheit in Auswahl-Listen (z. B. für Produkt-Mengeneinheit) angezeigt wird.

Button: „Sync" (administrativ)

Triggert POST /api/units/sync — fetcht die Master-Daten neu.

Felder und Eingaben

Feldname	Pflicht	Datentyp	Beschreibung	Wirkung beim Ausfuellen	Voraussetzung
code	—	String	UN/ECE-Code der Einheit (z. B. EA, KGM, MTR). Disabled im FE.	Wird beim Master-Sync gesetzt.	—
name	—	String	Klartext-Name (z. B. „Stueck", „Kilogramm"). Disabled.	Wie oben.	—
abbreviation	—	String	Kurzform (z. B. „Stk", „kg"). Disabled.	Wird auf Belegen angezeigt.	—
symbol	—	String	Symbol (z. B. „kg", „m²"). Disabled.	Erscheint neben Mengen in der UI.	—
relevant	nein	Boolean (Switch)	User-editierbar — markiert die Einheit als relevant für den Mandanten.	Wenn true: erscheint in der Mengen-Auswahl von Produkten und Belegen. Wenn false: bleibt versteckt.	update:Unit
masterUnitId	—	UUID	FK zur Master-Quelle.	Identifiziert die Quelle beim Sync.	—

Workflows und Zustaende

Master-Sync upsert die Master-Daten in regelmaessigen Abstaenden (Job-basiert). Mandanten-Änderungen am relevant-Flag bleiben dabei erhalten.

Im Code geprüft (siehe api.speamcore.com/src/services/unitSync.service.ts): Der Standard-Sync ueberschreibt das relevant-Flag nicht — Tenant-Edits bleiben erhalten. Nur wenn der Sync mit forceReset = true ausgeloest wird (administrativer Reset), werden auch lokale relevant-Werte aus dem Master übernommen.

Eine Race-Condition im engeren Sinne ist klein, aber nicht null: Der Sync laedt zuerst alle Master-Units in den Speicher (Snapshot), erzeugt dann update-Daten und schreibt in Batches von 100 Einträgen zurück. Wenn ein Anwender genau in dieser Spanne relevant umschaltet UND der Sync mit forceReset = true laeuft, wird der Toggle vom Master ueberschrieben. Beim Standard-Sync ist relevant nicht im updateData enthalten — kein Konflikt.

Empfehlung: forceReset nur ausführen, wenn man bewusst alle Tenant-Edits zuruecksetzen moechte (z. B. nach versehentlicher Massen-Deselektion).

Wiederverwendbare Konzepte

• Berechtigungen verstehen (CASL)
• Setup-Wizard Schritt 7 — Master-Sync.

Verknuepfungen zu anderen Modulen

• Produkte — Product.unitId referenziert diese Einheit.
• Verkaufs-/Bestellbelege — Positionen verwenden unitId aus dem Produkt-Stamm.
• HS-Codes — werden parallel synchronisiert (siehe Master-Sync).

Häufige Fehler und Lösungen

Fehler	Lösung
Einheit nicht in Produkt-Auswahl sichtbar	relevant = false setzen — markieren und neu laden.
Einheit fehlt komplett	Master-Sync laeuft (noch) nicht — siehe Setup-Wizard Schritt 7.
Änderung an code/name nicht möglich	Per Design — Stammdaten kommen vom Master. Korrektur dort vornehmen.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/units	Liste	view Unit
GET	/api/units/:id	Detail	view Unit
POST	/api/units	Anlegen (selten manuell genutzt)	create Unit
PUT	/api/units/:id	Ändern (i.d.R. nur relevant)	update Unit
DELETE	/api/units/:id	Löschen	delete Unit
POST	/api/units/sync	Master-Sync triggern	(admin)

Versionshinweise

• 2026-04-29: Initiale Veroeffentlichung mit FE-Tiefen-Standard.