HS-Codes (Zolltarif)

Zweck

HsCode modelliert das Harmonized System (HS) — eine internationale, hierarchische Klassifizierung von Produkten für Zoll, Statistik und Aussenhandel. Pro Code wird code (Roh-Code), formattedCode (mit Punkten/Trennern), name, level (Hierarchie-Tiefe), codeType und der parentCode-Verweis gepflegt.

Die meisten Felder sind disabled (read-only) — der Standard-HsCode-Stamm wird über den Setup-Wizard oder Sync-Job in die Mandanten-DB geladen. Eigene Codes koennen über isStandard = false ergaenzt werden; masterHsCodeId referenziert dann den Eintrag aus dem Master-Stamm, von dem abgeleitet wurde.

Voraussetzungen

- Berechtigung `view:HsCode`. Anlegen ueblicherweise nur für Sync-Jobs (`create:HsCode`). - Sub-Liste `/hscodes/:id/products` für Produkt-Zuordnung benötigt `view:Product`.

Berechtigungen (CASL)

Action	Subject	Wirkung	Keycloak-Rolle
view	FE_HsCode, HsCode	Liste/Detail aufrufbar	—
create/update/delete	HsCode	Pflegen (typisch durch System)	APP_SPEAMCORE_CREATE/UPDATE/DELETE_HS_CODE
view	Product	Produkt-Sub-Liste pro Code	APP_SPEAMCORE_VIEW_PRODUCT

Schritt-für-Schritt-Anleitung

Code suchen und Produkt zuordnen

1. HS-Codes (/hscodes) öffnen — DataGrid mit allen Standard-Codes.
2. Volltextsuche oder Filter auf level einsetzen, um den passenden Code zu finden.
3. Detail öffnen → Tab Produkte (/hscodes/:id/products) listet alle Produkte, die diesem Code zugeordnet sind.
4. Zuordnung erfolgt im Produkt-Detail (Feld hsCodeId).

Eigenen Code anlegen

1. + Neu — code, formattedCode, name, level, codeType pflegen.
2. isStandard = false setzen — masterHsCodeId zeigt auf den abgeleiteten Master-Code.

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)

Felder und Eingaben

Feldname	Pflicht	Datentyp	Wirkung beim Ausfuellen	Voraussetzung
code	ja	String	Roh-HS-Code (z. B. 841459).	—
formattedCode	ja	String	Formatierter Code (z. B. 8414.59).	—
name	ja	String	Bezeichnung des Codes.	—
level	ja	Integer	Hierarchie-Tiefe (Kapitel/Unterkapitel/...).	—
codeType	ja	String	Code-Typ (z. B. HS, KN).	—
parentCode	nein	String	Verweis auf Eltern-Code.	—
section	nein	String	Abschnitt im Zolltarif.	—
isStandard	ja (read-only für Standard)	Boolean	true: aus Master-Stamm. false: eigener Code.	—
masterHsCodeId	nein	UUID	Bei isStandard = false: Verweis auf Master-Code.	—

Wiederverwendbare Konzepte

• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Produkte — Product.hsCodeId referenziert einen Code. Sub-Liste /hscodes/:id/products.

Häufige Fehler und Lösungen

Fehler	Lösung
Code fehlt im Stamm	Standard-Stamm-Sync laufen lassen oder eigenen Code mit isStandard = false anlegen.
Hierarchie wirkt unvollstaendig	parentCode muss zu vorhandenen Codes verweisen.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/hs-codes	Liste	view HsCode
POST	/api/hs-codes	Anlegen	create HsCode
GET	/api/hs-codes/:id	Detail	view HsCode
PATCH	/api/hs-codes/:id	Ändern	update HsCode
DELETE	/api/hs-codes/:id	Soft-Delete	delete HsCode
GET	/api/products?filter[hsCodeId]	Produkt-Sub-Liste	view Product

Versionshinweise

• 2026-04-30: Initiale Veroeffentlichung.