UC03 – Fachentscheidungen Version 0.4¶
Stand: 01.08.2026 14:55
Branch: docs/einheitliche-kopfbereiche
Status: ✅ Eingearbeitet – Entscheide sind in uc03-spezifikation.md (Abschnitt 5) übernommen. Dieses Dokument dient als Entscheidungsnachweis mit Begründungen.
| Datum, Uhrzeit | Version | Änderung | Autor |
|---|---|---|---|
| 01.08.2026 14:55 | 0.4 | Kopfbereich vereinheitlicht | David Mittig |
| Mai 2026 | 0.4 | Fachentscheidungen zu Rechtematrix, Nitrox, Punkteverbrauch, Ledger, Offline-Konflikten, Preislogik und UI-Begriffen dokumentiert | David Mittig |
Ergänzungsdokument zur Spezifikation:
docs/developer/uc03/uc03-spezifikation.md
UC: UC03 – Füll-Abo & Füllkarten-Verwaltung
1. Ziel dieses Dokuments¶
Dieses Dokument hält die bestätigten Fachentscheidungen zu UC03 fest, die aus dem Feedback zur Spezifikation Version 0.3 entstanden sind.
Die Inhalte sind verbindlich für die weitere Ausarbeitung von UC03 und sollen bei der nächsten konsolidierten Überarbeitung in uc03-spezifikation.md übernommen werden.
2. Rechtematrix V1¶
2.1 Entscheidungen¶
| ID | Frage | Entscheidung |
|---|---|---|
| RR1 | Darf ein mitarbeiter ein neues Füllkonto anlegen? |
Ja |
| RR2 | Darf ein mitarbeiter eine Buchung stornieren? |
Ja, mit Stornierungsgrund, Datum/Zeit und User-Stempel |
| RR3 | Muss eine Korrektur durch tenant_admin freigegeben werden? |
Nein |
| RR4 | Gibt es später eine Rolle fill_manager? |
Nicht in V1; für V3 als mögliche Erweiterung für grössere Tauchbasen vormerken |
2.2 Verbindliche Ergänzung¶
Mitarbeiter dürfen Füllkonten anlegen und Buchungen stornieren.
Storno und Korrektur müssen immer auditierbar sein.
Jede Stornierung benötigt einen Pflichtgrund sowie Datum/Zeit und Benutzerstempel.
Eine Freigabe durch tenant_admin ist in V1 nicht erforderlich.
2.3 Angepasste Rechtematrix¶
| 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 Umsetzung final entscheiden |
| Bonus vergeben | Nein | Ja | wirtschaftlich relevante Aktion |
| Guthaben aufladen | Ja / 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 |
| negatives Guthaben erlauben | Nein | Ausnahme mit Pflichtgrund | Standard: nicht erlaubt |
| Export / Bericht anzeigen | Ja / offen | Ja | Datenschutzprüfung bei Kundendaten |
3. Nitrox-Gasarten und Zusatzfelder¶
3.1 Entscheidung¶
Nitrox ist Bestandteil von UC03 V1. Es müssen unterschiedliche Nitrox-Varianten verwaltet werden können, insbesondere:
| Gasart / Variante | FO₂ |
|---|---|
| Luft | 21 % |
| Nitrox 32 | 32 % |
| Nitrox 36 | 36 % |
| Nitrox 40 | 40 % |
Weitere tenant-spezifische Nitrox-Varianten sollen später möglich sein.
3.2 FO₂ und ppO₂¶
FO₂ ist nicht dasselbe wie ppO₂.
| Begriff | Bedeutung |
|---|---|
| FO₂ | Sauerstoffanteil im Atemgas, z. B. 0,32 = 32 % Sauerstoff |
| ppO₂ / PPO₂ | Sauerstoffpartialdruck, abhängig von FO₂ und Tiefe / Umgebungsdruck |
Beispiel:
Nitrox 32 hat FO₂ = 0,32.
Bei 30 m Tiefe beträgt der Umgebungsdruck ca. 4 bar.
ppO₂ = 0,32 × 4 bar = 1,28 bar.
Für UC03 ist primär FO₂ relevant. ppO₂ ist eher für Tauchgangsplanung, MOD-Berechnung oder Sicherheitsprüfung relevant.
3.3 Sinnvolle Nitrox-Zusatzfelder¶
| Feld | Zweck | Empfehlung |
|---|---|---|
gas_type |
Luft / Nitrox | Pflicht |
fo2_percent |
z. B. 32, 36, 40 | bei Nitrox sinnvoll |
nitrox_variant_name |
z. B. Nitrox 32 | sinnvoll |
analysis_performed |
Analyse wurde durchgeführt ja/nein | optional |
analysis_by_role |
Mitarbeiter oder Kunde | wenn analysiert wurde |
analysis_by_name |
Name der analysierenden Person | wenn analysiert wurde |
analysis_at |
Analysezeitpunkt | wenn analysiert wurde |
customer_reanalysis_performed |
Kunde hat zusätzlich selbst analysiert | optional |
customer_analysis_at |
Zeitpunkt der Kundenanalyse | optional |
analysis_note |
optionale Bemerkung | optional |
points_cost |
tenant-spezifischer Punkteverbrauch | erforderlich für Punktekarte |
3.4 Analyse durch Mitarbeiter und Kunde¶
Es muss nachvollziehbar sein, ob ein Mitarbeiter oder der Kunde die Analyse durchgeführt hat. In beiden Fällen müssen Name der Person und Analysezeitpunkt nachvollziehbar sein, wenn analysiert wurde.
Es kann vorkommen, dass zuerst der Mitarbeiter analysiert und später der Kunde bei Abholung nochmals selbst analysiert. Diese Mehrfachanalyse muss fachlich vorbereitet werden.
4. Verantwortungsbestätigung bei Nitrox¶
4.1 Entscheidung für V1¶
Analyseinformationen sind optional erfassbar. Wenn eine Analyse erfasst wird, müssen Person, Rolle und Zeitpunkt nachvollziehbar sein.
Eine separate Verantwortungsbestätigung ist in V1 optional, aber nicht verpflichtend.
Analyseinformationen sind optional erfassbar.
Wenn eine Analyse erfasst wird, müssen Person, Rolle und Zeitpunkt nachvollziehbar sein.
Eine separate Verantwortungsbestätigung ist in V1 optional, aber nicht verpflichtend.
4.2 Spätere Prüfung¶
Bei kundeninitiiertem Nitrox-Abruf oder echtem Self-Service kann später eine optionale Bestätigung eingeblendet werden.
Bei kundeninitiiertem Nitrox-Abruf kann eine optionale Bestätigung eingeblendet werden.
5. Punkteverbrauch pro Gasart oder Produktvorlage¶
5.1 Entscheidung¶
| Version | Regel |
|---|---|
| V1 | Punkteverbrauch pro Gasart / Nitrox-Variante |
| V2 / V3 | optionale Abweichung pro Produktvorlage |
5.2 V1-Beispiel¶
| Gasart / Variante | Beispiel-Punkteverbrauch | Status |
|---|---|---|
| Luft 21 % | Standardwert | konkreter Wert noch festzulegen |
| Nitrox 32 | tenant-spezifisch | konkreter Wert noch festzulegen |
| Nitrox 36 | tenant-spezifisch | konkreter Wert noch festzulegen |
| Nitrox 40 | tenant-spezifisch | konkreter Wert noch festzulegen |
5.3 Spätere Produktvorlagen-Abweichung¶
In V2 oder V3 kann eine Produktvorlage eigene Punktewerte überschreiben.
Beispiel:
| Produktvorlage | Luft | Nitrox 32 | Nitrox 36 | Nitrox 40 |
|---|---|---|---|---|
| Standard-Punktekarte | 1 | 2 | 3 | 4 |
| Premium-Punktekarte | 1 | 1 | 2 | 3 |
| Vereinskarte | 1 | 2 | 2 | 3 |
6. Manuelle Übersteuerung des Punkteverbrauchs¶
6.1 Entscheidungen¶
| ID | Frage | Entscheidung |
|---|---|---|
| PV1 | Sind Punktewerte tenant-spezifisch konfigurierbar? | Ja |
| PV2 | Gibt es System-Standardwerte für Luft und Nitrox? | Luft hat Standardwert; Nitrox je FO₂-Wert / Variante |
| PV3 | Darf der Punkteverbrauch pro Füllung manuell übersteuert werden? | Ja, aber nur durch Mitarbeiter, nicht durch Kunden |
| PV4 | Ist bei manueller Übersteuerung ein Pflichtgrund erforderlich? | Ja, mit Begründung, Datum/Zeit und User-Stempel |
| PV5 | Gibt es Punkteverbrauch nur pro Gasart oder auch pro Produktvorlage? | V1 pro Gasart / Nitrox-Variante; V2/V3 optional pro Produktvorlage |
7. Datenbank-Transaktionsstrategie gegen Doppelbuchungen¶
7.1 Entscheidung für UC03 V1¶
Online-Buchungen: Datenbank-Transaktion mit Row Lock.
Offline-Buchungen: Vormerkung mit pending_sync und Konfliktprüfung beim Sync.
7.2 Online-Buchung mit Row Lock¶
Ablauf:
1. Füllkonto-Zeile sperren
2. aktuellen Saldo prüfen
3. Ledger-Eintrag schreiben
4. current_balance aktualisieren
5. Transaktion committen
| Vorteil | Wirkung |
|---|---|
| zuverlässig | verhindert parallele Doppelbuchungen |
| gut nachvollziehbar | klare Transaktionslogik |
| V1-tauglich | fachlich robust und technisch üblich |
| Nachteil | Wirkung |
|---|---|
| etwas komplexer | Transaktionslogik muss sauber implementiert werden |
| kurze Sperren möglich | bei parallelen Buchungen wartet eine Buchung kurz |
7.3 Offline-Buchung¶
Offline-Buchungen werden vorgemerkt und erhalten pending_sync. Beim Sync wird geprüft, ob das Guthaben unter Berücksichtigung aller Vormerkungen ausreicht.
8. Bonuskarten-Prüfung initial_balance = paid_units + bonus_units¶
8.1 Entscheidung für V1¶
Die Anwendung prüft initial_balance = paid_units + bonus_units.
Eine harte Datenbank-Constraint wird geprüft, aber nicht zwingend sofort umgesetzt.
8.2 Praktische Bedeutung¶
| Beispiel | paid_units |
bonus_units |
initial_balance |
Ergebnis |
|---|---|---|---|---|
| gültig | 10 | 3 | 13 | korrekt |
| ungültig | 10 | 3 | 12 | muss blockiert oder korrigiert werden |
9. Korrektur fehlerhafter synchronisierter Ledger-Einträge¶
9.1 Entscheidung¶
Bereits synchronisierte Ledger-Einträge werden nicht verändert.
Fehler werden über reverse oder correction mit Pflichtgrund, Datum/Zeit und User-Stempel korrigiert.
9.2 Beispiel¶
| Vorgang | Ledger |
|---|---|
| falsche Luftfüllung gebucht | consume -1 |
| Fehler erkannt | reverse +1 mit Bezug auf Ursprungsbuchung |
| richtige Nitroxfüllung buchen | consume -2 |
10. Konflikte und Gegenbuchung¶
10.1 Entscheidung für V1¶
Keine automatische Gegenbuchung ohne Benutzerentscheidung.
Das System darf eine Korrektur vorschlagen, aber Mitarbeiter oder tenant_admin müssen bestätigen.
10.2 Beispiel Offline-Doppelverbrauch¶
| Zustand | Wert |
|---|---|
| Restguthaben online | 1 |
| Gerät A offline bucht Luftfüllung | -1 |
| Gerät B offline bucht Luftfüllung | -1 |
Beim Sync erkennt das System den Konflikt. Eine Buchung kann übernommen werden, die zweite wird als Konflikt markiert. Das System darf eine Korrektur vorschlagen, darf diese aber nicht ohne Benutzerentscheidung buchen.
11. Offline-Regeln¶
11.1 Entscheidungen¶
| ID | Frage | Entscheidung |
|---|---|---|
| OQ1 | Darf offline gebucht werden, wenn Restguthaben nur noch 1 Einheit beträgt? | Ja, wenn diese Einheit inklusive bereits vorgemerkter Offline-Verbräuche verfügbar ist |
| OQ2 | Wird offline Verbrauch direkt abgezogen oder nur vorgemerkt? | Vorgemerkt; direkter Abzug nur bei Online-Abgleich, Berechnung und Prüfung |
| OQ3 | Wer darf Sync-Konflikte lösen? | Mitarbeiter und/oder tenant_admin |
| OQ4 | Wird bei Konflikt automatisch eine Gegenbuchung vorgeschlagen? | Vorschlag ja, automatische Buchung nein |
| OQ5 | Muss bei pending_sync im UI immer ein Warnhinweis erscheinen? |
Ja |
| OQ6 | Wird Korrektur / Storno offline erlaubt? | In V1 gesperrt; ggf. V2/V3 prüfen |
11.2 UI-Regel bei pending_sync¶
Neue Abbuchungen darf der Kunde nur dann vornehmen, wenn keine nicht synchronisierten Offline-Buchungen vorhanden sind.
Kunde darf neue Abbuchungen nur vornehmen, wenn keine nicht synchronisierten Offline-Buchungen vorhanden sind.
12. Preislogik und Zahlungsinformation¶
12.1 Entscheidung für UC03 V1¶
Preise werden in UC03 V1 nur informativ vorbereitet.
Keine vollständige Preis-, Zahlungs-, Steuer- oder Rechnungslogik in V1.
12.2 Optionale Zahlungsinformation¶
Trotz informativ vorbereiteter Preise soll gekennzeichnet werden können, ob eine Karte oder ein Abo bezahlt wurde.
| Feld | Zweck |
|---|---|
payment_status |
z. B. unknown, unpaid, paid, partially_paid |
paid_at |
Zeitpunkt der Zahlungsbestätigung |
payment_method_note |
freie Info, z. B. Bar, Karte, Überweisung, externes Kassensystem |
payment_confirmed_by |
Benutzer, der Zahlung bestätigt hat |
payment_note |
optionale Bemerkung |
Diese Felder ersetzen keine vollständige Rechnungsstellung und keine Kassenlogik.
13. UI-Begriff¶
Der primäre UI-Titel lautet:
Füllkarten & Abos
Technisch bleibt das Modell intern ein fill_account.
14. Produktvorlagen V1¶
14.1 Entscheidung¶
| Produktvorlage | V1 |
|---|---|
| 10er-Karte Luft | Ja |
| 10+3 Bonuskarte Luft | Ja |
| Einzel-Füllung Luft | Ja |
| Punktekarte gemischt | noch offen |
| Saisonabo mit Kontingent | noch offen |
| Nitrox-Karte | fachlich vorbereitet, konkrete Produktvorlage noch offen |
14.2 Tenant-spezifische Anpassung¶
Produktvorlagen sind tenant-spezifisch anpassbar.
14.3 Eigene Kartenmodelle¶
Ein Tenant soll neben Vorlagen auch eigene Kartenmodelle erstellen können. Dies wird fachlich vorgesehen, aber die Umsetzung kann in V2 oder V3 erfolgen.
14.4 Bonusmodell¶
Die 10+3-Bonuskarte wird nicht hart als Sonderfall eingebaut. Stattdessen wird ein allgemeines Bonusmodell vorbereitet.
| Modell | Bezahlte Einheiten | Bonus-Einheiten | Startguthaben |
|---|---|---|---|
| 10+2 | 10 | 2 | 12 |
| 10+3 | 10 | 3 | 13 |
| 10+4 | 10 | 4 | 14 |
15. Aktualisierung offener Restpunkte aus Kapitel 18.2¶
| ID | Frage | Neuer Status |
|---|---|---|
| OE01 | Welche Produktvorlagen werden im ersten Release aktiv angeboten? | beantwortet: 10er-Karte Luft, 10+3 Bonuskarte Luft, Einzel-Füllung Luft |
| OE02 | Wird Punktekarte in V1 vollständig umgesetzt oder nur vorbereitet? | weiterhin offen |
| OE03 | Welche Punktewerte gelten für Luft und Nitrox? | teilweise beantwortet: Luft Standardwert, Nitrox je FO₂-Wert; konkrete Werte offen |
| OE04 | Sind Punktewerte tenant-spezifisch konfigurierbar? | beantwortet: ja |
| OE05 | Muss bei Nitrox FO₂ erfasst werden? | beantwortet: optional |
| OE06 | Muss bei Nitrox eine Analysebestätigung gespeichert werden? | beantwortet: optional |
| OE07 | Darf ein mitarbeiter Füllkonten anlegen? |
beantwortet: ja |
| OE08 | Darf ein mitarbeiter Stornos durchführen? |
beantwortet: ja, mit Grund und Auditdaten |
| OE09 | Darf Guthaben in Ausnahmefällen negativ werden? | weiterhin Empfehlung: nein; Ausnahme nur tenant_admin mit Pflichtgrund |
| OE10 | Wie werden Offline-Doppelbuchungen final gelöst? | teilweise beantwortet: Vormerkung, Sync-Prüfung, Konfliktlösung durch Mitarbeiter/Admin |
| OE11 | Wird QR-Code für Füllkarte / Füllkonto in V1 vorbereitet? | weiterhin offen, aber aus Self-Service-Kontext naheliegend |
| OE12 | Werden Preise nur informativ vorbereitet oder gepflegt? | beantwortet: nur informativ vorbereitet |
| OE13 | Wird Korrektur / Storno offline erlaubt? | beantwortet: in V1 gesperrt, ggf. V2/V3 |