UC03 – Füll-Abo & Füllkarten-Verwaltung
Stand: 01.08.2026 14:55
Branch: docs/einheitliche-kopfbereiche
Status: Spezifikation
| Datum, Uhrzeit |
Version |
Änderung |
Autor |
| 01.08.2026 14:55 |
0.3 |
Kopfbereich vereinheitlicht |
David Mittig |
| Mai 2026 |
0.1 |
Initiale Spezifikation für UC03 Füll-Abo & Füllkarten-Verwaltung erstellt |
David Mittig |
| Mai 2026 |
0.2 |
V1-Fokus auf Kunde / Füllkonto geschärft; Flaschen-Tracking und Sperrprüfung aus V1 entfernt; Anzahlkarte, Bonus-Füllkarte, Punktekarte, Kontingent-Abo und Einzel-Füllung ergänzt; Datenmodell um Füllkonto und Bonus-Einheiten erweitert |
David Mittig |
| Mai 2026 |
0.3 |
GEM-Review-Empfehlungen E01 bis E08 eingearbeitet; Ledger-, Salden-, Rollen-, Offline-, Punkte-, Nitrox-, UI- und Produktvorlagen-Details ergänzt; bestätigte Entscheide und offene Restpunkte neu strukturiert |
David Mittig |
Spezifikationsdatei – Leitdokument für Entwicklung, Testing und Abnahme
Review: GEM-Review 0.1 eingearbeitet
Status-Übersicht
| Schritt |
Bezeichnung |
Status |
Kommentar |
| 1 |
Steckbrief |
✅ Abgeschlossen |
Fachlicher Rahmen auf Kunde / Füllkonto fokussiert |
| 2 |
Scope & Abgrenzung |
✅ Abgeschlossen |
Flaschen-Tracking und UC01/UC02-Sperrprüfung nicht in V1 |
| 3 |
Füllmodelle |
✅ Abgeschlossen |
Anzahlkarte, Bonuskarte, Punktekarte, Kontingent-Abo und Einzel-Füllung aufgenommen |
| 4 |
Datenmodell |
🟡 In Bearbeitung |
Gemeinsames Füllkonto- und Ledger-Modell vorbereitet |
| 5 |
Ledger / Salden |
🟡 In Bearbeitung |
E01, E02, E03 eingearbeitet |
| 6 |
Offline / Konflikte |
🟡 In Bearbeitung |
E04 eingearbeitet, Detailfragen offen |
| 7 |
Punkte / Nitrox |
🟡 In Bearbeitung |
E05 und E07 als offene Restpunkte dokumentiert |
| 8 |
UI / Produktvorlagen |
🟡 In Bearbeitung |
E06 und E08 aufgenommen |
| 9 |
Screen-Vorgaben FA-01 bis FA-10 |
⬜ Offen |
nach fachlicher Detailklärung |
Legende: ✅ Abgeschlossen | 🟡 In Bearbeitung | 🔴 Blockiert | ⬜ Offen
1. Steckbrief
| Feld |
Inhalt |
| UC-ID |
UC03 |
| Name |
Füll-Abo & Füllkarten-Verwaltung |
| Version |
V1 |
| Zielgruppe |
Tauchschule |
| Primärakteur |
mitarbeiter |
| Sekundärakteur |
tenant_admin |
| Betroffener Akteur |
kunde |
| Reifegrad V1 |
Operativer MVP-Use-Case mit offenen Detailentscheidungen |
| Priorität |
Hoch |
1.1 Ziel
UC03 ermöglicht Tauchschulen, Füll-Abos, Füllkarten, Guthaben und einzelne Füllvorgänge auf Kundenebene zu verwalten. Dabei werden Kunden, Füllkonten, Gasarten, Verbrauchseinheiten und Buchungen nachvollziehbar dokumentiert.
UC03 V1 trackt Füllungen nicht auf konkrete Tauchflaschen. Eine Prüfung gegen Equipment-, Flaschen- oder TÜV-Status ist daher in UC03 V1 nicht relevant und wird nur als spätere Erweiterung vorbereitet.
2. Scope & Abgrenzung
2.1 Gehört zu UC03 V1
| Bereich |
Enthalten |
| Füllkonto anlegen und verwalten |
Ja |
| Füll-Abo anlegen und verwalten |
Ja |
| Füllkarte / Guthaben verwalten |
Ja |
| Bonus-Füllkarte, z. B. 10+3 |
Ja |
| Punktekarte |
Ja, Detailregeln offen |
| Einzelnen Füllvorgang erfassen |
Ja |
| Kunde zuordnen |
Ja |
| Gasart auswählen |
Ja |
| Verbrauch vom Füllkonto buchen |
Ja |
| Füllhistorie je Kunde anzeigen |
Ja |
| Füllhistorie je Füllkonto anzeigen |
Ja |
| Korrektur / Storno vorbereiten |
Ja |
| Auditierbare Buchungshistorie |
Ja |
2.2 Gehört nicht zu UC03 V1
| Bereich |
Hinweis |
| Tauchflasche zuordnen / scannen |
spätere Erweiterung, nicht V1 |
| Füllhistorie je Equipment |
spätere Erweiterung, nicht V1 |
| Sperrprüfung gegen UC01 / UC02 |
nicht V1, da keine Flasche getrackt wird |
| interne Füllung |
nicht V1 |
| Kurs-/Gruppenfüllung |
nicht V1 |
| vollständige Rechnungsstellung |
späterer eigener Umfang |
| komplexes Kassensystem |
nicht V1 |
| freie Export-/Berichtskonfiguration |
UC09 |
| Dokument-Upload |
UC13 |
| Gasblending-Detailberechnung |
später prüfen |
3. Begriffsabgrenzung
| Begriff |
Bedeutung |
| Füllkonto |
gemeinsames technisches Modell für Füll-Abo, Füllkarte, Bonuskarte oder Punktekarte |
| Füll-Abo |
Füllkonto mit Laufzeit und optionalem Kontingent |
| Füllkarte |
Füllkonto mit nutzbarem Guthaben / Kontingent |
| Bonus-Füllkarte |
Füllkarte mit bezahlten Einheiten plus Bonus-Einheiten, z. B. 10 bezahlt, 13 nutzbar |
| Punktekarte |
Füllkonto, bei dem Verbrauch in Punkten statt in Stück Füllungen gebucht wird |
| Füllvorgang |
einzelne konkrete Füllung, die als Verbrauch auf Kundenebene gebucht wird |
| Buchung |
Verbrauchs-, Aufladungs-, Bonus-, Korrektur- oder Stornobuchung auf einem Füllkonto |
| Ledger |
append-only Buchungshistorie eines Füllkontos |
| Gasart |
z. B. Luft, Nitrox, später ggf. weitere Gase |
| Einheit |
neutrale Verbrauchseinheit, z. B. Füllung oder Punkt |
4. V1-Füllmodelle
UC03 V1 verwendet ein gemeinsames Füllkonto-Modell. Dieses Füllkonto kann fachlich als Füll-Abo, Füllkarte, Bonus-Füllkarte oder Punktekarte verwendet werden.
| Variante |
In V1 |
Beschreibung |
| Anzahlkarte |
Ja |
Kunde erhält eine feste Anzahl nutzbarer Füllungen |
| Bonus-Füllkarte |
Ja |
Kunde bezahlt z. B. 10 Füllungen und erhält 13 nutzbare Füllungen |
| Punktekarte |
Ja |
Kunde erhält Punkte; Füllarten können unterschiedlich viele Punkte verbrauchen |
| Kontingent-Abo mit Laufzeit |
Ja |
Kunde erhält ein zeitlich gültiges Kontingent |
| Einzel-Füllung |
Ja |
einzelne Füllung ohne bestehendes Füllkonto wird dokumentiert |
| Wertguthaben |
nur vorbereiten |
später möglich, aber näher an Preis-/Kassenlogik |
| unbegrenztes Abo |
nicht V1 |
zu hohe fachliche und betriebswirtschaftliche Unschärfe für MVP |
4.1 Anzahlkarte
10er-Luftfüllkarte
Startguthaben: 10 Füllungen
Verbrauch pro Luftfüllung: 1 Einheit
| Feld |
Beispiel |
account_type |
card |
balance_type |
fills |
paid_units |
10 |
bonus_units |
0 |
initial_balance |
10 |
current_balance |
10 |
4.2 Bonus-Füllkarte
10+3 Luftfüllkarte
Kunde bezahlt 10 Füllungen
Kunde erhält 13 nutzbare Füllungen
| Feld |
Beispiel |
account_type |
bonus_card |
balance_type |
fills |
paid_units |
10 |
bonus_units |
3 |
initial_balance |
13 |
current_balance |
13 |
Wichtig:
Beim Verbrauch ist für den Benutzer nur das Restguthaben relevant. Für Auswertung und Nachvollziehbarkeit bleiben bezahlte Einheiten und Bonus-Einheiten separat gespeichert.
4.3 Punktekarte
20-Punktekarte
Luftfüllung = 1 Punkt
Nitroxfüllung = 2 Punkte
| Feld |
Beispiel |
account_type |
points_card |
balance_type |
points |
paid_units |
20 |
bonus_units |
0 |
initial_balance |
20 |
current_balance |
20 |
Der Punkteverbrauch je Gasart ist in V1 noch zu entscheiden.
4.4 Kontingent-Abo mit Laufzeit
Saisonabo Luft 2026
Gültig: 01.04.2026 bis 31.10.2026
Kontingent: 30 Füllungen
4.5 Einzel-Füllung
Einzel-Füllungen werden ohne vorheriges Füllkonto dokumentiert. Sie erzeugen eine Fülltransaktion und optional eine vorbereitete Buchungsreferenz, aber keine vollständige Rechnung.
Entscheid aus Review E02:
Eine Einzel-Füllung benötigt kein dauerhaftes fill_account.
| Feld |
Wert bei Einzel-Füllung |
fill_account_id |
null |
fill_model |
single |
fill_transaction |
Ja |
fill_ledger_entry |
nur falls später fachlich erforderlich |
| Historie |
über Kunde / Füllvorgang sichtbar |
5. Rollen und Rechte
| Rolle |
Rechte in UC03 |
tenant_admin |
Füllkonten anlegen, bearbeiten, korrigieren, stornieren, Berichte einsehen |
mitarbeiter |
Füllvorgänge erfassen, Guthaben verbuchen, stornieren, Historie einsehen |
kunde |
in V1 nur indirekt betroffen; spätere Anzeige im Kundenportal über UC06 möglich |
| System |
Kontingentprüfung, Buchungserstellung, Audit-Log |
Entscheide RR1–RR4 aus uc03-fachentscheidungen-v0.4.md eingearbeitet.
5.1 Rechtematrix V1
| Aktion |
mitarbeiter |
tenant_admin |
Hinweis |
| Füllung buchen |
Ja |
Ja |
Standardprozess |
| Füllkonto anzeigen |
Ja |
Ja |
nur eigener Tenant |
| Füllkonto anlegen |
Ja |
Ja |
Mitarbeiter darf neues Füllkonto anlegen |
| Füllkonto sperren |
Nein / offen |
Ja |
vor V1-Umsetzung final entscheiden |
| Bonus vergeben |
Nein |
Ja |
wirtschaftlich relevante Aktion |
| Guthaben aufladen |
offen |
Ja |
abhängig von späterer Preis-/Kassenlogik |
| Verbrauch buchen |
Ja |
Ja |
wenn Guthaben ausreichend |
| Guthaben korrigieren |
Ja, mit Pflichtgrund |
Ja, mit Pflichtgrund |
keine tenant_admin-Freigabe erforderlich |
| Storno durchführen |
Ja, mit Pflichtgrund |
Ja, mit Pflichtgrund |
immer über Gegenbuchung, Datum/Zeit und User-Stempel |
| negatives Guthaben erlauben |
Nein |
Ausnahme mit Pflichtgrund |
Standard: nicht erlaubt |
| Export / Bericht anzeigen |
Ja / offen |
Ja |
Datenschutzprüfung bei Kundendaten |
Noch offene Punkte: siehe uc03-offene-punkte.md (u. a. OP-RR4 fill_manager-Rolle für V3, OP-RR5–RR7 Self-Service-Rechte).
6. Vorbedingungen und Nachbedingungen
6.1 Vorbedingungen
| ID |
Vorbedingung |
| VB01 |
Tenant existiert und ist aktiv |
| VB02 |
Benutzer ist authentifiziert |
| VB03 |
Benutzer gehört zum Tenant |
| VB04 |
Benutzer hat Rolle tenant_admin oder mitarbeiter |
| VB05 |
Kunde existiert, falls kundenbezogener Verbrauch erfasst wird |
| VB06 |
Füllkonto existiert, falls Verbrauch gegen Abo oder Karte gebucht wird |
| VB07 |
Füllkonto ist aktiv und nicht abgelaufen, gesperrt oder verbraucht |
| VB08 |
Ausreichendes Guthaben / Kontingent ist vorhanden oder Ausnahme ist ausdrücklich erlaubt |
6.2 Nachbedingungen
| ID |
Nachbedingung |
| NB01 |
Füllvorgang ist gespeichert |
| NB02 |
Verbrauch wurde auf Abo, Füllkarte oder Einzelbuchung dokumentiert |
| NB03 |
Guthaben / Kontingent ist aktualisiert |
| NB04 |
Füllhistorie je Kunde ist aktualisiert |
| NB05 |
Füllhistorie je Füllkonto ist aktualisiert |
| NB06 |
Audit-Log enthält relevante Buchungen und Korrekturen |
7. Fachliche Ablaufbeschreibung
7.1 Füllvorgang mit Füllkarte
1. Benutzer öffnet Füll-Abo / Füllkarten-Übersicht.
2. Benutzer wählt Kunde oder Füllkonto.
3. System zeigt aktives Guthaben / Kontingent.
4. Benutzer erfasst Gasart und Verbrauchseinheiten.
5. System berechnet Verbrauch.
6. Benutzer bestätigt Buchung.
7. System erzeugt eine Verbrauchsbuchung im Ledger.
8. System aktualisiert das Restguthaben.
9. Füllvorgang erscheint in Kunde- und Füllkonto-Historie.
7.2 Bonus-Füllkarte nutzen
1. Benutzer wählt Kunde mit aktiver Bonus-Füllkarte.
2. System zeigt bezahlte Einheiten, Bonus-Einheiten und aktuelles Restguthaben.
3. Benutzer erfasst eine Füllung.
4. System erzeugt eine Verbrauchsbuchung.
5. System zieht die Verbrauchseinheit vom aktuellen Restguthaben ab.
6. Historie dokumentiert Verbrauch und Restguthaben.
7.3 Füll-Abo nutzen
1. Benutzer wählt Kunde mit aktivem Füll-Abo.
2. System prüft Abo-Status, Laufzeit und Restkontingent.
3. Benutzer erfasst Gasart und Verbrauchseinheiten.
4. Verbrauch wird gegen Abo-Kontingent oder Abo-Regel gebucht.
5. Füllhistorie wird aktualisiert.
7.4 Einzel-Füllung
1. Benutzer startet neuen Füllvorgang.
2. Benutzer wählt Kunde oder erfasst eine Füllung ohne bestehendes Füllkonto.
3. Benutzer erfasst Gasart und Verbrauchseinheiten.
4. System speichert Einzel-Füllung als fill_transaction.
5. Kein dauerhaftes fill_account ist erforderlich.
6. Optionale Abrechnung wird vorbereitet, aber nicht als vollständige Rechnung erzeugt.
8. Statusmodelle
8.1 Füllkonto-Status
| Status |
Bedeutung |
draft |
vorbereitet, noch nicht aktiv |
active |
nutzbar |
paused |
vorübergehend pausiert |
expired |
abgelaufen |
depleted |
Kontingent verbraucht |
blocked |
gesperrt |
cancelled |
storniert / beendet |
archived |
historisch archiviert |
8.2 Füllvorgang Status
| Status |
Bedeutung |
draft |
vorbereitet, noch nicht gebucht |
booked |
Füllung gebucht |
corrected |
korrigiert |
cancelled |
storniert |
blocked |
wegen Füllkonto- oder Guthabenregel nicht durchgeführt |
8.3 Buchungsstatus
| Status |
Bedeutung |
posted |
Buchung wirksam |
reversed |
storniert / rückgängig gemacht |
corrected |
durch Korrekturbuchung angepasst |
pending_sync |
offline erfasst, Sync ausstehend |
conflict |
Synchronisationskonflikt |
9. Fachliche Regeln
| ID |
Regel |
| R01 |
Nur Daten des eigenen Tenants dürfen verarbeitet werden |
| R02 |
Ein Füllvorgang wird in V1 auf Kunden- oder Füllkonto-Ebene gebucht |
| R03 |
Eine konkrete Tauchflasche wird in UC03 V1 nicht getrackt |
| R04 |
UC03 V1 führt keine Sperrprüfung gegen UC01 oder UC02 durch |
| R05 |
Verbrauchsbuchungen sind append-only zu modellieren; Korrekturen erfolgen über Gegenbuchung oder Korrekturbuchung |
| R06 |
Guthaben darf nicht unbemerkt negativ werden |
| R07 |
Negative Guthaben sind in V1 standardmässig nicht erlaubt |
| R08 |
Bonus-Einheiten werden separat gespeichert, aber dem nutzbaren Guthaben zugerechnet |
| R09 |
Bei Bonus-Füllkarten gilt: initial_balance = paid_units + bonus_units |
| R10 |
Gasart und Verbrauchseinheiten müssen nachvollziehbar gespeichert werden |
| R11 |
Nitrox-Füllungen benötigen ggf. zusätzliche fachliche Felder und Verantwortungsbestätigung |
| R12 |
Offline erfasste Füllungen erhalten pending_sync und müssen vor endgültiger Konfliktfreiheit geprüft werden |
| R13 |
Storno und Korrektur müssen auditierbar sein |
| R14 |
current_balance darf fachlich nur über Ledger-Buchungen verändert werden |
| R15 |
Historische Ledger-Einträge dürfen fachlich nicht überschrieben oder gelöscht werden |
| R16 |
Jede manuelle Korrektur benötigt einen Pflichtgrund |
| R17 |
Jeder Storno erfolgt über eine Gegenbuchung mit Bezug zur ursprünglichen Buchung |
| R18 |
Bonusvergabe ist eine wirtschaftlich relevante Aktion und benötigt Berechtigung sowie Nachvollziehbarkeit |
10. Gasarten, Verbrauchsdaten und Punktebewertung
10.1 Gasarten
| Gasart |
V1 |
Bemerkung |
| Luft |
Ja |
Standardfall |
| Nitrox |
Ja, wenn Tauchschule dies anbietet |
Zusatzfelder prüfen |
| Sauerstoff |
Nein / später |
fachlich und sicherheitstechnisch gesondert prüfen |
| Trimix |
Nein / später |
nicht V1 |
| Argon |
Nein / später |
nicht V1 |
10.2 Verbrauchsdaten
| Feld |
Pflicht |
Beschreibung |
| Gasart |
Ja |
Luft, Nitrox |
| Verbrauchseinheiten |
Ja |
z. B. 1 Füllung oder 2 Punkte |
| Füllmodell |
Ja |
Karte, Bonuskarte, Punktekarte, Abo, Einzel-Füllung |
| FO₂ |
Bei Nitrox, falls genutzt |
analysierter Sauerstoffanteil |
| Analyse bestätigt |
Bei Nitrox, falls genutzt |
Benutzer / Verantwortlicher bestätigt Analyse |
| Bemerkung |
Nein |
freie Notiz |
10.3 Punkteverbrauch je Gasart
| Leistung / Gasart |
Beispiel-Verbrauch |
Status |
| Luftfüllung |
1 Punkt |
Vorschlag |
| Nitroxfüllung |
2 Punkte |
Vorschlag, noch zu entscheiden |
| Sonderfüllung |
offen |
nicht V1 oder später konfigurieren |
| manuelle Übersteuerung |
offen |
Entscheidung erforderlich |
Offene Fragen:
| ID |
Frage |
| PV1 |
Sind Punktewerte tenant-spezifisch konfigurierbar? |
| PV2 |
Gibt es System-Standardwerte für Luft und Nitrox? |
| PV3 |
Darf der Punkteverbrauch pro Füllung manuell übersteuert werden? |
| PV4 |
Ist bei manueller Übersteuerung ein Pflichtgrund erforderlich? |
| PV5 |
Gibt es Punkteverbrauch nur pro Gasart oder auch pro Produktvorlage? |
10.4 Nitrox-Detailfragen
| Feld / Thema |
Offene Frage |
| FO₂ |
Pflichtfeld bei Nitrox ja/nein? |
| Analysebestätigung |
Pflicht bei Nitrox ja/nein? |
| Analyse durch |
Mitarbeiter, Kunde oder frei erfassbare Person? |
| Analysezeitpunkt |
muss Zeitpunkt gespeichert werden? |
| Verantwortungsbestätigung |
muss eine Bestätigung explizit gespeichert werden? |
| Punkteverbrauch |
fixer Wert oder tenant-spezifisch konfigurierbar? |
11. Datenmodell-Vorbereitung
Für V1 wird ein gemeinsames Füllkonto-Modell empfohlen. Abo und Karte müssen technisch nicht zwingend getrennte Tabellen sein.
| Tabelle |
Zweck |
fill_accounts |
gemeinsames Modell für Füll-Abos, Füllkarten, Bonuskarten und Punktekarten |
fill_transactions |
einzelne Füllvorgänge |
fill_ledger_entries |
Verbrauchs-, Auflade-, Korrektur- und Stornobuchungen |
fill_gas_types |
Gasarten je Tenant / Systemkatalog |
customers |
Kundenbezug |
audit_log |
Auditierbare Änderungen |
sync_queue |
Offline-Synchronisierung |
11.1 Beispielhafte Felder fill_accounts
| Feld |
Bedeutung |
id |
UUID |
tenant_id |
Tenant-Isolation |
customer_id |
Kunde |
account_type |
subscription, card, bonus_card, points_card |
balance_type |
fills, points, später ggf. value |
gas_scope |
air, nitrox, mixed |
paid_units |
bezahlte Einheiten, z. B. 10 |
bonus_units |
Bonus-Einheiten, z. B. 3 |
initial_balance |
Startguthaben, z. B. 13 |
current_balance |
aktuelles Restguthaben, denormalisierter Komfortwert |
valid_from |
gültig ab |
valid_until |
gültig bis |
status |
draft, active, paused, expired, depleted, blocked, cancelled, archived |
created_by |
Benutzer |
created_at |
Zeitpunkt |
Hinweis:
Einzel-Füllungen werden nicht als dauerhaftes fill_account gespeichert.
11.2 Beispielhafte Felder fill_transactions
| Feld |
Bedeutung |
id |
UUID |
tenant_id |
Tenant-Isolation |
customer_id |
Kunde, falls kundenbezogen |
fill_account_id |
Füllkonto, falls vorhanden; bei Einzel-Füllung null |
fill_model |
subscription, card, bonus_card, points_card, single |
gas_type |
air, nitrox |
consumption_units |
Verbrauchseinheiten |
fo2 |
Nitrox FO₂, falls relevant |
analysis_confirmed_by |
Analysebestätigung, falls Nitrox |
status |
draft, booked, corrected, cancelled, blocked |
sync_status |
local_only, pending_sync, synced, conflict |
created_by |
Benutzer |
created_at |
Zeitpunkt |
11.3 Beispielhafte Felder fill_ledger_entries
| Feld |
Bedeutung |
id |
UUID |
tenant_id |
Tenant-Isolation |
fill_account_id |
Bezug auf Füllkonto |
transaction_id |
Bezug auf Füllvorgang, falls vorhanden |
entry_type |
topup, bonus, consume, correction, reverse |
amount |
Menge / Punkte / Wert |
balance_before |
Stand vor Buchung |
balance_after |
Stand nach Buchung |
related_entry_id |
Bezug zur Ursprungsbuchung bei Storno / Korrektur |
reason |
Begründung, Pflicht bei Korrektur / Storno / Ausnahme |
sync_status |
local_only, pending_sync, synced, conflict |
created_by |
Benutzer |
created_at |
Zeitpunkt |
12. Ledger- und Saldenregeln
12.1 Grundsatz
Das Ledger ist die fachlich führende Wahrheit für Guthaben und Verbrauch.
current_balance ist ein gespeicherter Komfortwert für schnelle Anzeige und Abfragen. Der Wert muss jederzeit aus den Ledger-Einträgen rekonstruierbar sein.
12.2 Buchungstypen
entry_type |
Bedeutung |
Auswirkung |
topup |
Guthaben aufladen / Startguthaben setzen |
erhöht Guthaben |
bonus |
Bonus-Einheiten vergeben |
erhöht Guthaben, separat nachvollziehbar |
consume |
Verbrauch buchen |
reduziert Guthaben |
correction |
fachliche Korrektur |
erhöht oder reduziert Guthaben, Pflichtgrund |
reverse |
Storno / Gegenbuchung |
macht ursprüngliche Buchung fachlich rückgängig |
12.3 Verbindliche Regeln
| ID |
Regel |
| LR01 |
current_balance darf fachlich nur durch Ledger-Buchungen verändert werden |
| LR02 |
Historische Ledger-Einträge sind append-only und dürfen nicht überschrieben werden |
| LR03 |
Jede Buchung speichert balance_before und balance_after |
| LR04 |
Jede Korrektur benötigt einen Pflichtgrund |
| LR05 |
Jeder Storno benötigt Bezug zur Ursprungsbuchung über related_entry_id |
| LR06 |
Negative Guthaben sind standardmässig nicht erlaubt |
| LR07 |
Ausnahme von negativem Guthaben nur durch berechtigte Rolle und Pflichtgrund |
| LR08 |
Bonus-Einheiten müssen getrennt von bezahlten Einheiten nachvollziehbar bleiben |
| LR09 |
Bei Bonus-Füllkarten gilt fachlich: initial_balance = paid_units + bonus_units |
| LR10 |
Bei Konflikt zwischen Ledger und current_balance ist das Ledger massgeblich |
12.4 Offene technische Detailfragen
| ID |
Frage |
| LQ1 |
Wird current_balance bei jeder Buchung synchron aktualisiert oder periodisch rekonstruiert? |
| LQ2 |
Welche Datenbank-Transaktionsstrategie verhindert parallele Doppelbuchungen? |
| LQ3 |
Wird für Punkte und spätere Werte Decimal statt Integer verwendet? |
| LQ4 |
Wird initial_balance = paid_units + bonus_units technisch per Constraint geprüft? |
| LQ5 |
Wie wird ein fehlerhafter Ledger-Eintrag korrigiert, wenn er bereits synchronisiert wurde? |
13. Offline- und Konfliktregeln
Offline-Erfassung ist praxisnah, aber fachlich kritisch, weil mehrere Geräte dasselbe Füllkonto gleichzeitig verwenden können.
13.1 Grundregel
Offline-Buchungen dürfen nicht stillschweigend andere Buchungen überschreiben.
13.2 V1-Verhalten
| Situation |
Verhalten |
| Füllvorgang offline erfasst |
Transaktion erhält pending_sync |
| Guthaben ausreichend gemäss lokalem Stand |
Buchung lokal möglich, aber mit Sync-Hinweis |
| Guthaben niedrig oder unklar |
Warnung anzeigen |
| Sync erkennt parallelen Verbrauch |
Konflikt erzeugen, nicht automatisch überschreiben |
| Konflikt vorhanden |
Füllkonto erhält conflict oder Buchung erhält conflict |
| Konfliktlösung |
durch berechtigte Rolle mit Pflichtgrund |
13.3 Offene Fragen
| ID |
Frage |
| OQ1 |
Darf offline gebucht werden, wenn Restguthaben nur noch 1 Einheit beträgt? |
| OQ2 |
Wird offline Verbrauch direkt abgezogen oder nur vorgemerkt? |
| OQ3 |
Wer darf Sync-Konflikte lösen? |
| OQ4 |
Wird bei Konflikt automatisch eine Gegenbuchung vorgeschlagen? |
| OQ5 |
Muss bei pending_sync im UI immer ein Warnhinweis erscheinen? |
| OQ6 |
Wird Korrektur / Storno offline komplett gesperrt oder eingeschränkt erlaubt? |
14. Produktvorlagen V1
Für V1 werden Produktvorlagen empfohlen, damit Tauchschulen nicht sofort ein komplett freies Produktmodell konfigurieren müssen.
| Vorlage |
V1-Empfehlung |
Bemerkung |
| 10er-Karte Luft |
Standard |
einfachste Füllkarte |
| 10+3 Bonuskarte Luft |
Standard |
praxisnahe Bonusvariante |
| Einzel-Füllung Luft |
Standard |
ohne dauerhaftes Füllkonto |
| Punktekarte gemischt |
optional |
benötigt Punkteverbrauchsregeln |
| Saisonabo mit Kontingent |
optional |
Laufzeit + Kontingent |
| Nitrox-Karte |
offen |
abhängig von Nitrox-Detailentscheid |
| Wertguthaben |
nicht aktiv |
nur vorbereiten |
| unbegrenztes Abo |
nicht V1 |
bewusst ausgeschlossen |
Offene Fragen:
| ID |
Frage |
| PQ1 |
Welche Produktvorlagen werden beim ersten Release tatsächlich angeboten? |
| PQ2 |
Sind Produktvorlagen tenant-spezifisch anpassbar? |
| PQ3 |
Darf ein Tenant eigene Kartenmodelle erstellen oder nur Vorlagen nutzen? |
| PQ4 |
Wird die 10+3-Bonuskarte fest eingebaut oder als allgemeines Bonusmodell konfigurierbar? |
| PQ5 |
Werden Preise nur informativ vorbereitet oder vollständig gepflegt? |
15. UI-Begriffe und Darstellung
| Technischer Begriff |
Empfohlener UI-Begriff |
fill_account |
Karte / Abo |
account_type |
Modell |
balance_type |
Einheit |
paid_units |
bezahlt |
bonus_units |
Bonus |
initial_balance |
Startguthaben |
current_balance |
Restguthaben |
consume |
Verbrauch buchen |
topup |
Guthaben aufladen |
bonus |
Bonus gutschreiben |
correction |
Korrektur |
reverse |
Storno |
pending_sync |
noch nicht synchronisiert |
conflict |
Konflikt prüfen |
15.1 Bonuskarten-Anzeige
10 bezahlt + 3 Bonus = 13 Füllungen
Rest: 8 von 13
15.2 Punktekarte-Anzeige
Rest: 14 Punkte
Luftfüllung: 1 Punkt
Nitroxfüllung: 2 Punkte
Offene Fragen:
| ID |
Frage |
| UQ1 |
Wird im UI primär „Karte“, „Abo“ oder „Füllkonto“ angezeigt? |
| UQ2 |
Wie werden mehrere aktive Karten eines Kunden sortiert? |
| UQ3 |
Wird bei Punktekarte der konkrete Punkteverbrauch vor der Buchung immer angezeigt? |
| UQ4 |
Wie wird eine nicht synchronisierte Offline-Buchung im UI markiert? |
16. Screen-Flow & Wireframes
| Screen |
Bezeichnung |
Zweck |
Status |
| FA-01 |
Füll-Abo / Füllkarten-Übersicht |
Kunden, aktive Füllkonten, Karten und Guthaben anzeigen |
Offen |
| FA-02 |
Neues Füll-Abo anlegen |
Abo-Modell, Kunde, Laufzeit und Kontingent erfassen |
Offen |
| FA-03 |
Füllkarte / Guthaben verwalten |
Guthaben, Bonus, Aufladung, Sperre und Kartenstatus verwalten |
Offen |
| FA-04 |
Füllvorgang erfassen |
operativer Einstieg für einzelne Füllung |
Offen |
| FA-05 |
Kunde / Füllkonto auswählen |
Kunde und Füllkonto wählen oder suchen |
Offen |
| FA-06 |
Gasart und Verbrauchsdaten erfassen |
Luft / Nitrox und Verbrauchseinheiten dokumentieren |
Offen |
| FA-07 |
Verbrauch / Guthaben buchen |
Verbrauch berechnen, bestätigen und buchen |
Offen |
| FA-08 |
Füllhistorie je Kunde |
Historie und Guthabenverlauf eines Kunden anzeigen |
Offen |
| FA-09 |
Füllhistorie je Füllkonto |
Historie einer Karte / eines Abos anzeigen |
Offen |
| FA-10 |
Korrektur / Storno |
Buchung korrigieren oder stornieren |
Offen |
17. Beziehungen zu bestehenden Use Cases
| Use Case |
Beziehung |
| UC01 Equipment erfassen |
Keine direkte V1-Abhängigkeit; spätere Flaschenzuordnung möglich |
| UC02 TÜV-Inspektion einreichen |
Keine direkte V1-Abhängigkeit; spätere Sperrprüfung möglich |
| UC04 Inhouse-Service erfassen |
Keine direkte V1-Abhängigkeit |
| UC05 Fristen-Dashboard |
Für UC03 V1 nur indirekt relevant; spätere Konto-/Abo-Fristen möglich |
| UC06 Kunden einladen & Portal |
spätere Kundensicht auf Abo, Guthaben und Historie |
| UC07 Benachrichtigungen |
Guthaben niedrig, Abo läuft ab, Karte leer |
| UC08 Benutzerverwaltung |
Rollen und Berechtigungen |
| UC09 Berichte & Export |
Auswertung von Füllungen, Umsatzvorbereitung und Verbrauch |
| UC13 Dokument-Upload |
mögliche spätere Dokumente oder Nachweise |
| UC18 Equipment-Verleih |
Keine direkte V1-Abhängigkeit; spätere Kopplung möglich |
18. Entscheide / offene Restpunkte
18.1 Bestätigte Entscheide
| ID |
Entscheidung |
| ED01 |
UC03 V1 trackt keine konkrete Tauchflasche |
| ED02 |
UC03 V1 führt keine Sperrprüfung gegen UC01 / UC02 durch |
| ED03 |
Interne Füllungen sind nicht Bestandteil von UC03 V1 |
| ED04 |
Kurs-/Gruppenfüllungen sind nicht Bestandteil von UC03 V1 |
| ED05 |
Anzahlkarte ist Bestandteil von V1 |
| ED06 |
Bonus-Füllkarte, z. B. 10+3, ist Bestandteil von V1 |
| ED07 |
Kontingent-Abo mit Laufzeit ist Bestandteil von V1 |
| ED08 |
Einzel-Füllung ist Bestandteil von V1 |
| ED09 |
Wertguthaben wird nur vorbereitet, aber nicht aktiv umgesetzt |
| ED10 |
Unbegrenztes Abo ist nicht Bestandteil von V1 |
| ED11 |
Korrektur und Storno erfolgen über Ledger-Buchungen, nicht durch Überschreiben |
18.2 Offene Restpunkte
| ID |
Frage |
Status |
| OE01 |
Welche Produktvorlagen werden im ersten Release aktiv angeboten? |
offen |
| OE02 |
Wird Punktekarte in V1 vollständig umgesetzt oder nur vorbereitet? |
offen |
| OE03 |
Welche Punktewerte gelten für Luft und Nitrox? |
offen |
| OE04 |
Sind Punktewerte tenant-spezifisch konfigurierbar? |
offen |
| OE05 |
Muss bei Nitrox FO₂ erfasst werden? |
offen |
| OE06 |
Muss bei Nitrox eine Analysebestätigung gespeichert werden? |
offen |
| OE07 |
Darf ein mitarbeiter Füllkonten anlegen? |
offen |
| OE08 |
Darf ein mitarbeiter Stornos durchführen? |
offen |
| OE09 |
Darf Guthaben in Ausnahmefällen negativ werden? |
Empfehlung: nein, Ausnahme nur tenant_admin mit Pflichtgrund |
| OE10 |
Wie werden Offline-Doppelbuchungen final gelöst? |
offen |
| OE11 |
Wird QR-Code für Füllkarte / Füllkonto in V1 vorbereitet? |
offen |
| OE12 |
Werden Preise nur informativ vorbereitet oder gepflegt? |
offen |
| OE13 |
Wird Korrektur / Storno offline erlaubt? |
offen |
18.3 Spätere Erweiterungen
| Erweiterung |
Hinweis |
| Flaschen-Tracking |
spätere Kopplung an UC01 / UC02 möglich |
| Equipment-Sperrprüfung |
erst relevant, wenn Flasche getrackt wird |
| Wertguthaben |
später mit Preis-/Kassenlogik prüfen |
| vollständige Rechnung |
eigener späterer Umfang |
| Kundenportal-Anzeige |
UC06 |
| Export / Auswertung |
UC09 |
| Dokumente |
UC13 |
19. Akzeptanzkriterien
| ID |
Kriterium |
| AC01 |
Benutzer kann Füll-Abo und Füllkarte eines Kunden anzeigen |
| AC02 |
Benutzer kann Anzahlkarte, Bonus-Füllkarte, Punktekarte und Kontingent-Abo unterscheiden |
| AC03 |
Benutzer kann bezahlte Einheiten und Bonus-Einheiten einer Bonus-Füllkarte nachvollziehen |
| AC04 |
Benutzer kann einen Füllvorgang auf Kunden- oder Füllkonto-Ebene erfassen |
| AC05 |
Benutzer kann Kunde und Füllkonto zuordnen |
| AC06 |
Benutzer kann Gasart und Verbrauchseinheiten erfassen |
| AC07 |
Verbrauch wird gegen Abo oder Füllkarte gebucht |
| AC08 |
Guthaben / Kontingent wird aktualisiert |
| AC09 |
Füllhistorie je Kunde ist sichtbar |
| AC10 |
Füllhistorie je Füllkonto ist sichtbar |
| AC11 |
Korrekturen und Stornos sind auditierbar |
| AC12 |
Tenant-Isolation wird eingehalten |
| AC13 |
current_balance ist aus Ledger-Einträgen rekonstruierbar |
| AC14 |
Storno erzeugt eine Gegenbuchung und löscht keine historische Buchung |
| AC15 |
Korrektur benötigt einen Pflichtgrund |
| AC16 |
Offline-Konflikte werden sichtbar und nicht still überschrieben |
20. Übernommene GEM-Review-Empfehlungen
| ID |
Empfehlung |
Status in Version 0.3 |
| E01 |
current_balance darf nur über Ledger-Buchungen verändert werden |
übernommen in Kapitel 9 und 12 |
| E02 |
Einzel-Füllung braucht kein dauerhaftes Füllkonto |
übernommen in Kapitel 4.5 und 11 |
| E03 |
Rechte für Bonus, Korrektur, Storno und negatives Guthaben konkretisieren |
übernommen in Kapitel 5 und 18 |
| E04 |
Offline-Konfliktregel für parallele Buchungen präzisieren |
übernommen in Kapitel 13 und 18 |
| E05 |
Punkteverbrauch je Gasart als Konfigurationsfrage ergänzen |
übernommen in Kapitel 10 und 18 |
| E06 |
UI-Begriffe für technische Felder ergänzen |
übernommen in Kapitel 15 |
| E07 |
Nitrox-Detailentscheid FO₂ / Analyse offen lassen |
übernommen in Kapitel 10 und 18 |
| E08 |
Produktvorlagen für V1 ergänzen |
übernommen in Kapitel 14 und 18 |
21. Änderungshistorie