QR-Codes (QR-IDs)

Zweck

QR-IDs sind eindeutige Codes, die Vor-Ort-Identifikation ermoeglichen — z. B. ein Aufkleber an einer Anlage, der per Smartphone-Kamera gescannt wird und auf die zugehörige SpeamCore-Detailseite springt. Pro QR-ID wird eine NumberCircleAssignment (Nummernkreis-Eintrag) als Anker erzeugt; daraus generiert das System die Public-Route /qr/:id.

Voraussetzungen

- Eingerichteter Nummernkreis für QR-IDs (siehe Setup-Wizard Schritt 11). - Berechtigung `create:QrId`.

Berechtigungen (CASL)

Action	Subject	Wirkung	Keycloak-Rolle
view	FE_QrId, QrId	Liste/Details aufrufbar	—
create/update/delete	QrId	Pflegen	APP_SPEAMCORE_CREATE/UPDATE/DELETE_QR_ID
view	NumberCircleAssignment	Anzeige der Nummer + QR-Code	APP_SPEAMCORE_VIEW_NUMBER_CIRCLE_ASSIGNMENT

Die Public-Route /qr/:id ist ohne Login aufrufbar (siehe Frontend-Routen-Inventur in _internal/codebase-inventory.md im Doku-Repo) — sie zeigt nur die für Vor-Ort relevanten Stamm-Infos.

Schritt-für-Schritt-Anleitung

QR-ID anlegen

1. QR-IDs (/qr-ids) → + Neu.
2. Es wird eine leere QR-ID mit automatisch erzeugter NumberCircleAssignment angelegt.
3. Name vergeben — z. B. „Baustelle Hamburg Ost", „Heizungsraum E2".
4. Änderungen werden automatisch gespeichert.
5. Auf der Detailseite zeigt die QrCodeComponent rechts den fertigen QR-Code als PNG.
6. Den QR-Code drucken und am Objekt anbringen.

QR-ID scannen

Beim Scannen mit der Smartphone-Kamera wird die Public-URL https://app.speamcore.com/qr/<id> aufgerufen. Der QRDetailsPage-Component zeigt die Vor-Ort-relevanten Infos.

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

Komponente: QrCodeComponent

Rendert den QR-Code als PNG. Erscheint nur, wenn die NumberCircleAssignment bereits gesetzt ist.

Listen-Verhalten: Filter-Preservation

Beim Klick auf eine Zeile in der Listenseite wird der location.search-Querystring beibehalten (Filter-Zustand bleibt nach Detailansicht-Rueckkehr erhalten).

Felder und Eingaben

Feldname	Pflicht	Datentyp	Beschreibung	Wirkung beim Ausfuellen	Voraussetzung
qrIdNo	automatisch	NumberCircleAssignment	Aus Nummernkreis. Disabled im FE.	Identifiziert den QR-Code; bildet die ID in der Public-URL /qr/:id.	view:NumberCircleAssignment. Nummernkreis muss konfiguriert sein.
name	nein	String	Klartext-Bezeichnung der QR-Verknuepfung.	Erscheint in Listen, auf der Public-Detailseite und im Druck.	—

Workflows und Zustaende

Kein Status-Feld. Soft-Delete via paranoid.

Wiederverwendbare Konzepte

• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• NumberCircleAssignment — Pflicht-Anker pro QR-ID.
• Public-Route /qr/:id — wird beim Scannen aufgerufen, ist ohne Login zugaenglich.
• Betriebsmittel — OperatingEquipment nutzt ebenfalls QR-Codes über dieselbe Mechanik.
• Anlagen — Anlagen-spezifische QR-Codes als Beispiel-Verwendung.

Häufige Fehler und Lösungen

Fehler	Lösung
QR-Code wird nicht angezeigt	NumberCircleAssignment noch nicht erzeugt. Speichern und Seite neu laden.
Scan fuehrt zu 404	QR-ID wurde gelöscht (Soft-Delete) oder ist falsch gedruckt.
Filter-Zustand verloren bei Rueckkehr	Listen-Seite preserviert location.search nur bei direktem Klick — keine externen Links.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/qr-ids	Liste	view QrId
GET	/api/qr-ids/:id	Detail	view QrId
POST	/api/qr-ids	Anlegen	create QrId
PUT	/api/qr-ids/:id	Ändern	update QrId
DELETE	/api/qr-ids/:id	Soft-Delete	delete QrId

Public-Route /qr/:id (FE) ist ohne Authentifizierung aufrufbar — prüfen Sie bei sicherheitskritischen Anwendungen, welche Daten dort sichtbar sind.

Versionshinweise

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