HandyCafe Docs
owner

Sitzungsabrechnung

HandyCafe verwendet ein segmentbasiertes Preismodell, um die Kosten für Sitzungen in Ihrem Internetcafé oder Gaming Center zu berechnen. Anstatt einen einheitlichen Tarif für die gesamte Sitzung anzuwenden, teilt die Engine jede Sitzung in Segmente auf, die jeweils ihren eigenen Preiskontext haben. Dieser Ansatz gewährleistet eine genaue Abrechnung, selbst wenn Sitzungen mehrere Zeitfenster, Preisänderungen, Pausen oder Unterbrechungen umfassen.

Grundkonzepte

Bevor wir ins Detail gehen, hier die wichtigsten Begriffe:

Begriff Definition
Basisstundensatz Der Preis pro Stunde, bevor Multiplikatoren angewendet werden. Festgelegt unter Einstellungen > Preise.
Preisslot Ein benannter Zeitraum mit einem spezifischen Multiplikator. Es gibt 8 Slots, die jeweils farbcodiert sind.
Multiplikator Ein Faktor, der auf den Basispreis angewendet wird. 1,0 = Standardpreis, 0,5 = halber Preis, 2,0 = doppelter Preis.
Segment Ein kontinuierlicher Zeitraum innerhalb einer Sitzung, in dem der Preiskontext (Slot, Multiplikator, Basispreis) unverändert bleibt.
Abrechnung Die endgültige Berechnung, die bestimmt, wie viel der Kunde bei Sitzungsende schuldet.

Basisstundensatz

Der Basisstundensatz ist die Grundlage aller Preisberechnungen. Er wird unter Einstellungen > Preise festgelegt und stellt den Standardpreis pro Stunde PC-Nutzung dar.

Alle internen Berechnungen verwenden kleinere Währungseinheiten (zum Beispiel Cent für USD, Kurus für TRY). Wenn Ihr Basispreis 3,00 $ pro Stunde beträgt, ist der interne Wert 300. Dies eliminiert Rundungsfehler bei Gleitkommazahlen.

Unterstützung für zwei Währungen

HandyCafe unterstützt eine Basiswährung und eine lokale Währung mit einem Wechselkurs (FX). Wenn Sie in einem Land tätig sind, in dem sich internationale Preise von lokalen Preisen unterscheiden:

  • Basiswährung. Die Währung, die für interne Preisberechnungen verwendet wird.
  • Lokale Währung. Die Währung, die den Kunden angezeigt wird und für Zahlungen verwendet wird.
  • FX-Kurs. Der Umrechnungsfaktor zwischen Basis- und Lokalwährung.

Wenn beide Währungen gleich sind, wird der FX-Kurs als 1,0 behandelt und hat keine Auswirkungen.

Preisslots

Es gibt 8 farbcodierte Preisslots, die jeweils eine andere Preiskategorie darstellen:

Slot Farbe Typische Verwendung
Blau Blau Standardtarif
Orange Orange Abend- oder Wochenendzuschlag
Rot Rot Spitzenzeitenaufschlag
Grün Grün Rabatt außerhalb der Spitzenzeiten
Türkis Türkis Studenten- oder Mitgliedertarif
Grau Grau Feiertags- oder Sonderpreise
Cyan Cyan Nachttarif
Smaragd Smaragd Aktionspreis

Jeder Slot hat drei Eigenschaften:

  1. Name. Ein beschreibendes Label (zum Beispiel "Spitzenzeiten" oder "Nachtrabatt").
  2. Multiplikator. Ein Dezimalwert, der den Basispreis modifiziert. Übliche Werte sind 1,0 (Standard), 0,5 (halber Preis), 1,5 (50% Zuschlag), 2,0 (doppelter Preis). Der Multiplikator muss null oder positiv sein.
  3. Zeitplandaten. Eine interne Darstellung, die definiert, zu welchen Stunden an welchen Tagen der Slot gilt. Dies wird automatisch über das Zeitplanraster verwaltet.

Slots können individuell aktiviert oder deaktiviert werden. Deaktivierte Slots werden von der Preis-Engine ignoriert.

Das Zeitplanraster

Der Preiszeitplan ist eine 7-Tage-zu-24-Stunden-Matrix (insgesamt 168 einstündige Blöcke). Jeder Block ist einem Preisslot zugeordnet. Der Zeitplan bestimmt, welcher Multiplikator zu einem bestimmten Zeitpunkt gilt.

Das Raster wird unter Einstellungen > Preiszeitplan konfiguriert. Die Tage laufen von Montag bis Sonntag und die Stunden von 00:00 bis 23:00. Um einem Zeitblock einen Slot zuzuweisen, wählen Sie den Block im Raster aus und wählen Sie die gewünschte Slotfarbe.

Wie die Engine den Zeitplan liest

Intern wird jeder Stundenblock einer Position in den Zeitplandaten zugeordnet. Die Engine überprüft die Zeitplandaten jedes aktivierten Slots, um festzustellen, welcher Slot an einem bestimmten Tag und zu einer bestimmten Stunde aktiv ist.

Wenn kein Slot für eine bestimmte Stunde gesetzt ist, fällt die Engine auf den Basispreis mit einem Multiplikator von 1,0 zurück.

Wenn die Preiszeitplanfunktion vollständig deaktiviert ist (unter Einstellungen > Preise), verwenden alle Sitzungen den Basispreis mit einem Multiplikator von 1,0, unabhängig von der Zeit.

Preissegmente

Ein Segment ist ein kontinuierlicher Zeitraum innerhalb einer Sitzung, in dem sich der Preiskontext nicht ändert. Die Preis-Engine erstellt ein neues Segment, wann immer eines dieser Grenzereignisse auftritt:

Grenze Auslöser
session_start Eine neue Sitzung beginnt
session_stop Die Sitzung wird gestoppt
pause Der Kassierer pausiert die Sitzung
resume Der Kassierer setzt eine pausierte Sitzung fort
tick Die Uhr überschreitet eine Stundenmarke in einen anderen Preisslot
disconnect Der Client-PC verliert seine Netzwerkverbindung
offline Der Client-PC geht offline
load_recovery Der Server startet neu und stellt eine laufende Sitzung wieder her

Jedes Segment zeichnet auf:

Feld Beschreibung
session_id Die Sitzung, zu der dieses Segment gehört
segment_start Unix-Zeitstempel, wann das Segment begann
segment_end Unix-Zeitstempel, wann das Segment endete (null, wenn noch offen)
pricing_slot_id Die ID des aktiven Preisslots (zum Beispiel "blau", "rot" oder "basis")
multiplier Der Multiplikatorwert aus dem Preisslot
base_price_snapshot Der Basisstundensatz, der im Moment der Segmenteröffnung erfasst wurde
amount Die berechneten Kosten für dieses Segment (festgelegt, wenn das Segment geschlossen wird)
boundary_reason Warum dieses Segment erstellt wurde

Warum den Basispreis erfassen?

Der base_price_snapshot erfasst den Basisstundensatz genau in dem Moment, in dem das Segment öffnet. Dies ist entscheidend, da ein Administrator den Basispreis während einer Sitzung ändern könnte. Durch die Erfassung verwendet jedes Segment den Preis, der zu Beginn galt, was eine faire und nachvollziehbare Abrechnung sicherstellt.

Kostenformel

Die Kosten eines einzelnen Segments werden wie folgt berechnet:

amount = ceil( (base_price_snapshot * multiplier * duration_seconds) / 3600 )

Genauer gesagt verwendet die Engine skalierte Ganzzahlarithmetik, um Gleitkommafehler zu vermeiden:

  1. Der Multiplikator wird auf eine Festkommazahl skaliert (multipliziert mit 1.000.000).
  2. Die Berechnung erfolgt vollständig in 128-Bit-Ganzzahlen.
  3. Es wird eine Aufwärtsrundung verwendet. Das Ergebnis wird immer auf die nächste kleinere Einheit aufgerundet.

Berechnung nach Minuten

Wenn die Option "Berechnung nach Minuten" unter Einstellungen > Preise aktiviert ist, ändert sich die Formel leicht:

amount = ceil( (base_price_snapshot * multiplier * used_minutes) / 60 )

Wobei used_minutes = ceil(duration_seconds / 60). Das bedeutet, dass jede angefangene Minute als volle Minute gezählt wird.

Gesamtkostenberechnung der Sitzung

Die Gesamtkosten einer Sitzung werden in drei Schritten berechnet:

Schritt 1: Alle Segmente summieren

raw_total = Summe aller geschlossenen Segmentbeträge + offener Segmentteilbetrag

Der offene Segmentteilbetrag wird in Echtzeit mit der obigen Formel berechnet, wobei der aktuelle Zeitstempel als Segmentende verwendet wird.

Schritt 2: Rundung anwenden

rounded_total = round_up(raw_total, rounding_step)

Die Rundung erfolgt immer aufwärts (Ceiling), um den Umsatz zu schützen. Der Rundungsschritt ist unter Einstellungen > Preise konfigurierbar. Zum Beispiel, wenn der Rundungsschritt 50 beträgt (was 0,50 $ in einer Währung mit 2 Dezimalstellen entspricht), wird ein Rohbetrag von 3,27 $ auf 3,50 $ aufgerundet.

Schritt 3: Mindeststartgebühr anwenden

final_total = max(rounded_total, startup_fee)

Die Startgebühr ist die Mindestgebühr für jede Sitzung, unabhängig von der Dauer. Wenn der gerundete Gesamtbetrag unter der Startgebühr liegt, wird stattdessen die Startgebühr berechnet.

Abrechnung

Die Abrechnung ist der Prozess der endgültigen Abrechnung einer Sitzung. Es gibt zwei Abrechnungsstufen:

Startabrechnung (nur Prepaid)

Wenn eine Prepaid-Sitzung beginnt, wird ein "Start"-Abrechnungsdatensatz erstellt. Dieser erfasst:

  • Berechnete Kosten. Die systemberechneten Kosten für die gekaufte Zeit.
  • Berechneter Betrag. Der Betrag, den der Kunde tatsächlich bezahlt hat (normalerweise derselbe wie die berechneten Kosten).

Für den Prepaid-Modus "Sperren beim Kauf" bestimmt dieser gesperrte Betrag die Kosten der Sitzung, unabhängig von Preisänderungen während der Sitzung.

Stop-Abrechnung

Wenn eine Sitzung (Prepaid oder Postpaid) gestoppt wird, wird ein "Stop"-Abrechnungsdatensatz erstellt:

Feld Beschreibung
Berechnete Kosten Der systemberechnete Gesamtbetrag aus allen Preissegmenten
Berechneter Betrag Der tatsächlich berechnete Betrag (standardmäßig die berechneten Kosten)
Manuell angepasster Betrag Wenn der Kassierer den Preis manuell angepasst hat, wird hier der ursprüngliche berechnete Betrag gespeichert
Provisionssatz Provisionssatz der Zahlungsmethode (als Prozentsatz)
commission_fee Der berechnete Provisionsbetrag
fixed_fee Feste Gebühr der Zahlungsmethode
computed_timeline_snapshot Ein JSON-Datensatz jedes Preissegments in der Sitzung

Der Timeline-Snapshot bietet eine vollständige Prüfspur, die genau zeigt, wie die Kosten segmentweise berechnet wurden.

Gebühren für Zahlungsmethoden

Jede Zahlungsmethode kann zwei Arten von Gebühren haben:

Provision (Basispunkte)

Der Provisionssatz wird als Prozentsatz ausgedrückt. Die Provisionsgebühr wird berechnet, indem dieser Satz auf den berechneten Betrag angewendet wird.

Beispiel: Wenn der berechnete Betrag 10,00 $ (1000 kleinere Einheiten) beträgt und die Zahlungsmethode einen Provisionssatz von 2,5 % hat, beträgt die Provisionsgebühr 0,25 $ (25 kleinere Einheiten).

Feste Gebühr

Eine feste Gebühr, die pro Transaktion abgezogen wird, unabhängig vom Betrag. Zum Beispiel eine Kreditkartengebühr von 0,30 $.

Beide Gebühren sind informativ. Sie stellen die Kosten für das Unternehmen dar, diese Zahlungsmethode zu akzeptieren. Sie werden in der Abrechnung erfasst, aber nicht auf die Rechnung des Kunden aufgeschlagen.

Mehrwertsteuer (MwSt.)

Die Mehrwertsteuer wird als Prozentsatz (0–100 %) unter Einstellungen > Preise konfiguriert. Sie wird auf den berechneten Sitzungsbetrag aufgeschlagen:

MwSt. = berechneter Betrag x (MwSt.-Satz / 100)

Der Mehrwertsteuerbetrag wird im Zahlungsdialog separat angezeigt, damit der Kassierer die Steueraufteilung sehen kann.

Prepaid-Preismodi

Wie in Sitzungsverwaltung beschrieben, unterstützen Prepaid-Sitzungen zwei Preismodi:

Sperren beim Kauf

Wenn eine Prepaid-Sitzung beginnt, sperrt die "Start"-Abrechnung den berechneten Betrag. Für die Dauer der Sitzung:

  • Die Sitzungsendzeit ist basierend auf den gekauften Minuten festgelegt.
  • Selbst wenn sich der Preiszeitplan ändert, läuft die Sitzung bis zum Ablauf der gesperrten Zeit weiter.
  • Die Stop-Abrechnung verwendet den gesperrten Betrag aus der Startabrechnung.

Live-Zeitplan

Die verbleibende Zeit der Sitzung wird kontinuierlich neu berechnet, wenn sich Preisslots ändern:

  • Wenn die Sitzung in einen günstigeren Slot wechselt, verlängert sich die verbleibende Zeit (der Kunde erhält mehr Minuten für sein Geld).
  • Wenn die Sitzung in einen teureren Slot wechselt, verkürzt sich die verbleibende Zeit.
  • Die Stop-Abrechnung spiegelt die tatsächlich während der Sitzung angewendeten Preise wider.

Dezimalstellen

Die Anzahl der Dezimalstellen, die für die Währungsanzeige verwendet werden, ist konfigurierbar (2–4 Dezimalstellen). Dies beeinflusst, wie Beträge in der Benutzeroberfläche angezeigt werden, ändert jedoch nicht die internen Berechnungen in kleineren Einheiten.

Beispiel: Mit 2 Dezimalstellen wird 3,50 $ als "3,50" angezeigt. Mit 3 Dezimalstellen würde es als "3,500" angezeigt.

Praktische Beispiele

Beispiel 1: Einfache Postpaid-Sitzung

  • Basispreis: 3,00 $/Stunde (300 kleinere Einheiten)
  • Zeitplan: Standardslot (Multiplikator 1,0) den ganzen Tag
  • Sitzung: 10:00 bis 11:30 Uhr (90 Minuten)
  • Startgebühr: 0,50 $

Berechnung:

Segment 1: (300 * 1,0 * 5400) / 3600 = 450 kleinere Einheiten (4,50 $)
Gesamt: max(4,50 $, 0,50 $) = 4,50 $

Beispiel 2: Sitzung über zwei Slots

  • Basispreis: 4,00 $/Stunde (400 kleinere Einheiten)
  • Zeitplan: Standard (1,0) von 10:00–12:00, Happy Hour (0,5) von 12:00–14:00
  • Sitzung: 11:00 bis 13:00 Uhr (120 Minuten)
  • Startgebühr: 1,00 $

Berechnung:

Segment 1 (11:00-12:00, Standard): (400 * 1,0 * 3600) / 3600 = 400 (4,00 $)
Segment 2 (12:00-13:00, Happy Hour): (400 * 0,5 * 3600) / 3600 = 200 (2,00 $)
Gesamt: 4,00 $ + 2,00 $ = 6,00 $
Endbetrag: max(6,00 $, 1,00 $) = 6,00 $

Beispiel 3: Sitzung mit Pause

  • Basispreis: 2,00 $/Stunde (200 kleinere Einheiten)
  • Zeitplan: Standardslot (Multiplikator 1,0) den ganzen Tag
  • Sitzung: Start 10:00, Pause 10:30, Fortsetzen 11:00, Stop 11:45
  • Startgebühr: 0,50 $

Berechnung:

Segment 1 (10:00-10:30, aktiv): (200 * 1,0 * 1800) / 3600 = 100 (1,00 $)
Pausenzeitraum (10:30-11:00): keine Berechnung
Segment 2 (11:00-11:45, aktiv): (200 * 1,0 * 2700) / 3600 = 150 (1,50 $)
Gesamt: 1,00 $ + 1,50 $ = 2,50 $
Endbetrag: max(2,50 $, 0,50 $) = 2,50 $

Nächste Schritte