Zum Inhalt

UC03 Ergänzung – Self-Service-Füllabruf durch Kunden

Stand: 12.10.2026 11:23 Branch: main Status: Ergänzung für UC03 V1

Änderungshistorie anzeigen

Ergänzungsdokument zur Spezifikation: docs/developer/uc03/uc03-spezifikation.md
UC: UC03 – Füll-Abo & Füllkarten-Verwaltung

1. Ziel der Ergänzung

Ein Füll-Abo oder eine Füllkarte ist für Kunden vor allem dann wertvoll, wenn der Kunde dieses Guthaben beim Füllen selbst abrufen oder zumindest kundeninitiiert vorzeigen kann.

UC03 V1 soll daher nicht nur einen mitarbeitergeführten Verbrauch buchen, sondern auch einen Self-Service- bzw. kundeninitiierten Füllabruf unterstützen.

Das bedeutet:

Kunde besitzt Füll-Abo / Füllkarte
→ Kunde identifiziert sich oder sein Füllkonto
→ Kunde löst den Abruf der Füllung aus oder zeigt ihn vor
→ Verbrauch wird gegen sein Füllkonto gebucht
→ Restguthaben und Historie werden aktualisiert

2. Fachliche Entscheidung für V1

Thema Entscheidung
Self-Service-Füllabruf Bestandteil von UC03 V1
Kundeninitiierter Abruf Bestandteil von UC03 V1
Verbrauch auf Füllkonto Bestandteil von UC03 V1
Kundenportal-Anzeige für V1 vorbereiten, in Verbindung mit UC06
QR-Code / digitale Karte für V1 vorbereiten, konkrete Umsetzung noch offen
Flaschen-Tracking weiterhin nicht Bestandteil von UC03 V1
UC01-/UC02-Sperrprüfung weiterhin nicht Bestandteil von UC03 V1

3. Begriffe

Begriff Bedeutung
Self-Service-Füllabruf Kunde kann sein Füll-Abo oder seine Füllkarte selbst zum Verbrauch abrufen
kundeninitiierter Abruf Kunde startet den Prozess, ein Mitarbeiter bestätigt oder schliesst die Buchung ab
digitale Füllkarte digitale Darstellung eines Füllkontos, z. B. im Kundenportal oder per QR-Code
Abruf-Code QR-Code oder Token, der ein Füllkonto identifiziert
Verbrauchsbestätigung Bestätigung, dass eine Einheit oder Punkte vom Füllkonto abgezogen werden

4. Varianten des Self-Service-Prozesses

4.1 Variante A – Mitarbeitergeführt

Der Mitarbeiter sucht Kunde oder Füllkonto und bucht den Verbrauch.

Mitarbeiter sucht Kunde
→ Mitarbeiter wählt Füllkonto
→ Mitarbeiter erfasst Gasart / Verbrauch
→ Mitarbeiter bucht Verbrauch

Diese Variante ist bereits in der UC03-Spezifikation enthalten.

4.2 Variante B – Kundeninitiierter Abruf mit Mitarbeiterbestätigung

Der Kunde zeigt sein Füllkonto, z. B. über QR-Code oder digitale Karte. Der Mitarbeiter prüft und bestätigt die Buchung.

Kunde zeigt QR-Code / digitale Füllkarte
→ System öffnet Füllkonto
→ Mitarbeiter sieht Restguthaben und Verbrauchsvorschlag
→ Mitarbeiter bestätigt Verbrauch
→ System bucht Verbrauch im Ledger

Diese Variante ist für V1 besonders sinnvoll, weil sie Self-Service vorbereitet, aber die Kontrolle bei der Tauchschule belässt.

4.3 Variante C – echter Self-Service durch Kunde

Der Kunde meldet sich an oder nutzt einen Abruf-Code und löst den Verbrauch selbst aus.

Kunde öffnet Kundenportal oder scannt digitalen Abruf
→ Kunde sieht Füllkonto und Restguthaben
→ Kunde wählt Füllung / Gasart
→ Kunde bestätigt Verbrauch
→ System bucht Verbrauch oder setzt Buchung zur Prüfung

Diese Variante ist für V1 gewünscht, benötigt aber zusätzliche Sicherheits- und Missbrauchsregeln.

5. V1-Empfehlung

Für UC03 V1 wird empfohlen, zwei Stufen umzusetzen:

Stufe Umsetzung V1-Empfehlung
Stufe 1 kundeninitiierter Abruf mit Mitarbeiterbestätigung Ja
Stufe 2 echter Self-Service durch Kunde Ja, wenn technisch und sicherheitlich vertretbar

Die Mindestanforderung für V1 sollte sein:

Kunde kann sein Füllkonto digital vorzeigen oder abrufen.
Die Verbrauchsbuchung kann durch den Kunden ausgelöst werden, muss aber je nach Tenant-Einstellung durch einen Mitarbeiter bestätigt werden können.

6. Fachlicher Ablauf – Kundeninitiierter Abruf

1. Kunde öffnet digitale Füllkarte oder zeigt QR-Code.
2. System identifiziert Kunde und Füllkonto.
3. System zeigt Restguthaben, Modell und Status.
4. System prüft, ob Füllkonto aktiv, nicht abgelaufen und nicht leer ist.
5. Kunde oder Mitarbeiter wählt Gasart / Verbrauchsart.
6. System zeigt den geplanten Verbrauch.
7. Kunde oder Mitarbeiter bestätigt den Abruf.
8. System erzeugt Verbrauchsbuchung im Ledger.
9. System aktualisiert Restguthaben.
10. Kunde und Tauchschule sehen den aktualisierten Stand.

6.1 BPMN-nahe Prozessdarstellung – Kundeninitiierter Abruf

Hinweis: Die folgende Mermaid-Darstellung ist eine GitHub-kompatible, BPMN-nahe Visualisierung. Sie nutzt Swimlanes, Tasks, Start-/Endereignisse und Entscheidungspunkte, ist aber keine formal vollständige native BPMN-2.0-Datei.

flowchart TD
    %% BPMN-nahe Mermaid-Darstellung mit Swimlanes

    subgraph K["Kunde"]
        K1([Start])
        K2["Digitale Füllkarte öffnen<br/>oder QR-Code zeigen"]
        K3["Gasart / Verbrauchsart wählen"]
        K4["Abruf bestätigen"]
        K5([Ende])
    end

    subgraph S["System"]
        S1["Kunde und Füllkonto identifizieren"]
        S2["Restguthaben, Modell und Status anzeigen"]
        S3{"Füllkonto aktiv,<br/>nicht abgelaufen<br/>und nicht leer?"}
        S4["Verbrauchsvorschau anzeigen"]
        S5["Verbrauchsbuchung im Ledger erzeugen"]
        S6["Restguthaben aktualisieren"]
        S7["Blockierung anzeigen"]
    end

    subgraph M["Mitarbeiter"]
        M1["Abruf prüfen"]
        M2["Verbrauch bestätigen"]
    end

    K1 --> K2 --> S1 --> S2 --> S3
    S3 -- Ja --> K3 --> S4 --> M1 --> M2 --> K4 --> S5 --> S6 --> K5
    S3 -- Nein --> S7 --> K5

7. Fachlicher Ablauf – echter Self-Service

1. Kunde authentifiziert sich im Kundenportal oder über freigegebenen Abruf-Code.
2. Kunde öffnet aktives Füll-Abo oder aktive Füllkarte.
3. System zeigt Restguthaben, Gültigkeit und mögliche Verbrauchsarten.
4. Kunde wählt Füllung, z. B. Luftfüllung oder Nitroxfüllung.
5. System zeigt Verbrauch, Restguthaben vorher und Restguthaben nachher.
6. Kunde bestätigt den Verbrauch.
7. System prüft tenant-spezifische Regel: sofort buchen oder Mitarbeiterfreigabe erforderlich.
8. System bucht Verbrauch oder erzeugt `pending_confirmation`.
9. Kunde erhält Bestätigung.
10. Verbrauch erscheint in Füllhistorie je Kunde und Füllkonto.

7.1 BPMN-nahe Prozessdarstellung – echter Self-Service

Hinweis: Die folgende Mermaid-Darstellung ist eine GitHub-kompatible, BPMN-nahe Visualisierung. Sie bildet den Ablauf mit Entscheidungspunkt zur Mitarbeiterbestätigung ab, ersetzt aber keine formal vollständige BPMN-2.0-Datei.

flowchart TD
    %% BPMN-nahe Mermaid-Darstellung mit Swimlanes

    subgraph K["Kunde"]
        K1([Start])
        K2["Im Kundenportal anmelden<br/>oder Abruf-Code verwenden"]
        K3["Aktives Füll-Abo / Füllkarte öffnen"]
        K4["Füllung wählen<br/>(z. B. Luft / Nitrox)"]
        K5["Verbrauch bestätigen"]
        K6([Ende])
    end

    subgraph S["System"]
        S1["Restguthaben, Gültigkeit<br/>und Verbrauchsarten anzeigen"]
        S2["Verbrauchsvorschau anzeigen"]
        S3{"Mitarbeiterbestätigung<br/>erforderlich?"}
        S4["Buchung als<br/>pending_confirmation anlegen"]
        S5["Verbrauch direkt<br/>im Ledger buchen"]
        S6["Bestätigung anzeigen"]
        S7["Restguthaben aktualisieren"]
    end

    subgraph M["Mitarbeiter"]
        M1["Offenen Abruf prüfen"]
        M2{"Abruf freigeben?"}
        M3["Freigeben"]
        M4["Ablehnen"]
    end

    K1 --> K2 --> K3 --> S1 --> K4 --> S2 --> K5 --> S3
    S3 -- Nein --> S5 --> S7 --> S6 --> K6
    S3 -- Ja --> S4 --> M1 --> M2
    M2 -- Ja --> M3 --> S5
    M2 -- Nein --> M4 --> S6 --> K6
    S5 --> S7 --> S6 --> K6

Fachliche Lesart

Swimlane Bedeutung
Kunde startet den Abruf über digitale Füllkarte oder QR-Code
System identifiziert Kunde und Füllkonto, prüft Status und bucht Verbrauch
Mitarbeiter prüft und bestätigt den kundeninitiierten Abruf

In dieser Variante startet der Kunde den Prozess, die eigentliche Verbrauchsbuchung wird jedoch durch den Mitarbeiter bestätigt. Diese Variante ist für V1 besonders geeignet, weil sie Self-Service ermöglicht, aber die operative Kontrolle bei der Tauchschule belässt.

Fachliche Lesart

Entscheidungspunkt Bedeutung
Mitarbeiterbestätigung erforderlich? Tenant-spezifische Einstellung, ob der Kunde direkt buchen darf oder ob ein Mitarbeiter bestätigen muss
Abruf freigeben? Mitarbeiter entscheidet, ob der kundeninitiierte Verbrauch tatsächlich gebucht wird

Für V1 wird empfohlen, den kundeninitiierten Abruf mit Mitarbeiterbestätigung als sicheren Standardmodus vorzusehen. Direkter Self-Service ohne Mitarbeiterbestätigung sollte nur optional und tenant-spezifisch aktivierbar sein.

8. Status-Erweiterung für Self-Service

Für Self-Service wird empfohlen, den Status des Füllvorgangs zu erweitern.

Status Bedeutung
draft vorbereitet, noch nicht gebucht
pending_confirmation Kunde hat Abruf ausgelöst, Mitarbeiterbestätigung steht aus
booked Verbrauch ist gebucht
cancelled Vorgang wurde abgebrochen / storniert
blocked Abruf wurde wegen Regelverletzung blockiert
conflict Konflikt, z. B. durch Offline- oder Parallelbuchung

9. Sicherheits- und Missbrauchsaspekte

Risiko Gegenmassnahme / offene Entscheidung
QR-Code wird weitergegeben QR-Code darf nur Füllkonto öffnen, nicht zwingend automatisch buchen
fremder Kunde nutzt Karte Authentifizierung oder Mitarbeiterbestätigung prüfen
mehrfacher Abruf Ledger- und Transaktionsschutz erforderlich
Offline-Doppelbuchung Konfliktregel aus UC03 anwenden
Kunde bucht falsche Gasart Verbrauchsvorschau und Bestätigung anzeigen
Guthaben wird negativ Standardmässig blockieren
Self-Service ohne Kontrolle tenant-spezifische Einstellung: sofort buchen oder Bestätigung erforderlich

10. Rollen und Rechte

Aktion kunde mitarbeiter tenant_admin
eigenes Füllkonto anzeigen Ja Ja Ja
eigenes Restguthaben anzeigen Ja Ja Ja
Füllabruf starten Ja Ja Ja
Verbrauch direkt buchen offen Ja Ja
Verbrauch nach Kundenabruf bestätigen Nein Ja Ja
Füllkonto sperren Nein Nein / offen Ja
Storno / Korrektur Nein eingeschränkt / offen Ja
Bonus vergeben Nein Nein Ja

11. Datenmodell-Ergänzungen

Folgende Felder oder Konzepte sollten für V1 vorbereitet werden:

Feld / Konzept Zweck
self_service_enabled Tenant- oder Produktregel, ob Self-Service erlaubt ist
requires_staff_confirmation Verbrauch muss durch Mitarbeiter bestätigt werden
customer_initiated Verbrauch wurde durch Kunde ausgelöst
initiated_by_customer_id Kunde, der Abruf gestartet hat
confirmed_by_user_id Mitarbeiter, der Abruf bestätigt hat
confirmation_status not_required, pending, confirmed, rejected
access_token_hash technischer Schutz für digitale Abrufcodes
access_token_expires_at Ablaufzeit für temporären Abrufcode
last_self_service_at letzter Self-Service-Abruf

12. Auswirkungen auf Screen-Flow FA-01 bis FA-10

Screen Auswirkung
FA-01 Übersicht sollte Self-Service-fähige Füllkonten anzeigen können
FA-02 Beim Anlegen eines Abos sollte Self-Service optional aktivierbar sein
FA-03 Füllkarte sollte digitale Karte / QR-Code / Abrufstatus anzeigen
FA-04 Füllvorgang kann durch Kunde oder Mitarbeiter gestartet sein
FA-05 Kunde / Füllkonto auswählen wird um QR-Code / Abruf-Link erweitert
FA-06 Gasart und Verbrauchsdaten müssen für Kunde verständlich sein
FA-07 Verbrauch / Guthaben buchen muss Bestätigung oder Mitarbeiterfreigabe unterstützen
FA-08 Füllhistorie je Kunde zeigt auch kundeninitiierte Abrufe
FA-09 Füllhistorie je Füllkonto zeigt Self-Service-Status und Bestätigung
FA-10 Korrektur / Storno muss Self-Service-Buchungen berücksichtigen

13. Offene Fragen KA1 bis KA8

ID Frage Status
KA1 Darf der Kunde sein Füllkonto nur anzeigen oder auch aktiv eine Füllung auslösen? offen; V1-Ziel: aktives Auslösen ermöglichen
KA2 Erfolgt der Abruf per QR-Code, Kundenkarte, Login, Name/Suche oder manuelle Auswahl durch Mitarbeiter? offen; QR-Code und Kundenportal vorbereiten
KA3 Muss ein Mitarbeiter die Buchung immer bestätigen? offen; Empfehlung: tenant-spezifisch konfigurierbar
KA4 Darf Self-Service in V1 vorbereitet oder bereits umgesetzt werden? entschieden: soll in V1 umgesetzt werden
KA5 Wie wird Missbrauch verhindert, wenn ein QR-Code weitergegeben wird? offen; Zugriffsschutz und/oder Mitarbeiterbestätigung erforderlich
KA6 Wird eine Buchung im Kundenportal sichtbar? offen; Empfehlung: ja, mindestens Füllhistorie und Restguthaben
KA7 Wird der Kunde bei niedrigem Guthaben oder ablaufendem Abo benachrichtigt? offen; Bezug zu UC07
KA8 Wird eine digitale Füllkarte im Kundenportal angezeigt? offen; Empfehlung: ja, für V1 vorbereiten

14. Neue fachliche Regeln für UC03-Spezifikation

Diese Regeln sollten in die Hauptspezifikation übernommen werden:

ID Regel
SSR01 UC03 V1 unterstützt kundeninitiierten Abruf von Füll-Abo und Füllkarte
SSR02 Ein Kunde darf nur eigene Füllkonten sehen und abrufen
SSR03 Self-Service-Verbrauch muss über Ledger gebucht werden
SSR04 Ein Self-Service-Abruf darf kein Guthaben unbemerkt negativ machen
SSR05 Tenant kann festlegen, ob Mitarbeiterbestätigung erforderlich ist
SSR06 QR-Code / Abrufcode darf nicht ohne Schutz zu unkontrollierter Buchung führen
SSR07 Kundeninitiierte Abrufe müssen in der Füllhistorie sichtbar sein
SSR08 Self-Service-Buchungen müssen auditierbar sein

15. Akzeptanzkriterien für Self-Service V1

ID Kriterium
SS-AC01 Kunde kann sein aktives Füllkonto digital abrufen oder vorzeigen
SS-AC02 System zeigt Restguthaben, Modell und Gültigkeit verständlich an
SS-AC03 Kunde kann einen Füllabruf starten, wenn das Füllkonto aktiv ist
SS-AC04 System zeigt Verbrauch vor der Buchung an
SS-AC05 Verbrauch wird über Ledger gebucht
SS-AC06 Guthaben wird nach Abruf aktualisiert
SS-AC07 Kundeninitiierte Abrufe erscheinen in der Historie
SS-AC08 Tenant kann Mitarbeiterbestätigung verlangen
SS-AC09 QR-Code / digitaler Abruf ist gegen Missbrauch zu schützen
SS-AC10 Kunde sieht nur eigene Füllkonten

Änderungshistorie

Datum, Uhrzeit Version Änderung Autor
12.10.2026 11:23 0.7 Leere Überschrift «16. Änderungshistorie» aus der Zeit vor dem einheitlichen Dokumentaufbau entfernt Claude
12.10.2026 11:01 0.6 Versionsnummern der Änderungshistorie chronologisch durchgehend nummeriert (4 Einträge angepasst; Datum, Änderung und Autor unverändert) Claude
12.10.2026 10:19 0.5 Datum und Uhrzeit von 1 älteren Historieneinträgen aus der Git-Historie ergänzt (Zeitpunkt des Commits, der den Eintrag eingeführt hat) Claude
12.10.2026 09:58 0.4 Änderungshistorie ans Dokumentende verschoben und Sprunglink «Änderungshistorie anzeigen» unter dem Kopf ergänzt (einheitlicher Dokumentaufbau gemäss AGENTS.md) Claude
12.10.2026 09:08 0.3 Branch-Angabe im Kopfbereich auf main korrigiert Claude
01.08.2026 14:55 0.2 Kopfbereich vereinheitlicht David Mittig
06.05.2026 14:07 0.1 Self-Service-Füllabruf als UC03-V1-Ergänzung dokumentiert; Varianten, Abläufe, Rollen, Datenmodellfelder, KA1 bis KA8 und Akzeptanzkriterien ergänzt David Mittig