Prezzi delle Sessioni
HandyCafe utilizza un motore di prezzi basato su segmenti per calcolare i costi delle sessioni nel tuo internet cafe o gaming center. Invece di applicare una tariffa unica per l'intera sessione, il motore divide ogni sessione in segmenti, ciascuno con il proprio contesto di prezzo. Questo approccio garantisce una fatturazione accurata anche quando le sessioni coprono più fasce orarie, cambi di prezzo, pause o disconnessioni.
Concetti Fondamentali
Prima di entrare nei dettagli, ecco i termini chiave:
| Termine | Definizione |
|---|---|
| Tariffa oraria base | Il prezzo per ora prima dell'applicazione di qualsiasi moltiplicatore. Impostato in Impostazioni > Prezzi. |
| Slot di prezzo | Un periodo di tempo denominato con un moltiplicatore specifico. Ci sono 8 slot, ciascuno codificato a colori. |
| Moltiplicatore | Un fattore applicato alla tariffa base. 1.0 = prezzo standard, 0.5 = metà prezzo, 2.0 = doppio prezzo. |
| Segmento | Un periodo continuo all'interno di una sessione in cui il contesto di prezzo (slot, moltiplicatore, prezzo base) rimane invariato. |
| Chiusura | Il calcolo finale che determina quanto il cliente deve pagare alla fine di una sessione. |
Tariffa Oraria Base
La tariffa oraria base è la base di tutti i calcoli di prezzo. È impostata in Impostazioni > Prezzi e rappresenta il prezzo standard per ora di utilizzo del PC.
Tutti i calcoli interni utilizzano unità monetarie minori (ad esempio, centesimi per USD, kurus per TRY). Se la tua tariffa base è di $3.00 all'ora, il valore interno è 300. Questo elimina i problemi di arrotondamento in virgola mobile.
Supporto Doppia Valuta
HandyCafe supporta una valuta base e una valuta locale con un tasso di cambio (FX). Se operi in un paese dove i prezzi internazionali differiscono da quelli locali:
- Valuta base. La valuta utilizzata per i calcoli interni dei prezzi.
- Valuta locale. La valuta mostrata ai clienti e utilizzata per i pagamenti.
- Tasso FX. Il fattore di conversione tra valuta base e locale.
Se entrambe le valute sono le stesse, il tasso FX è considerato 1.0 e non ha effetto.
Slot di Prezzo
Ci sono 8 slot di prezzo codificati a colori, ciascuno rappresentante un diverso livello di prezzo:
| Slot | Colore | Uso Tipico |
|---|---|---|
| Blu | Blu | Tariffa standard |
| Arancione | Arancione | Soprattassa serale o weekend |
| Rosso | Rosso | Premio per ore di punta |
| Verde | Verde | Sconto fuori orario |
| Teal | Teal | Tariffa per studenti o membri |
| Grigio | Grigio | Prezzi per festività o speciali |
| Ciano | Ciano | Tariffa notturna |
| Smeraldo | Smeraldo | Tariffa promozionale |
Ogni slot ha tre proprietà:
- Nome. Un'etichetta descrittiva (ad esempio, "Ore di Punta" o "Sconto Notturno").
- Moltiplicatore. Un valore decimale che modifica la tariffa base. Valori comuni includono 1.0 (standard), 0.5 (metà prezzo), 1.5 (soprattassa del 50%), 2.0 (doppio prezzo). Il moltiplicatore deve essere zero o positivo.
- Dati di programma. Una rappresentazione interna che definisce quali ore di quali giorni lo slot si applica. Questo è gestito automaticamente tramite la griglia del programma.
Gli slot possono essere attivati o disattivati individualmente. Gli slot disattivati sono ignorati dal motore di prezzi.
La Griglia del Programma
Il programma dei prezzi è una matrice di 7 giorni per 24 ore (168 blocchi di un'ora in totale). Ogni blocco è assegnato a uno slot di prezzo. Il programma determina quale moltiplicatore si applica in un dato momento.
La griglia è configurata in Impostazioni > Programma Prezzi. I giorni vanno da lunedì a domenica e le ore vanno da 00:00 a 23:00. Per assegnare uno slot a un blocco di tempo, seleziona il blocco nella griglia e scegli il colore dello slot desiderato.
Come il Motore Legge il Programma
Internamente, ogni blocco orario mappa a una posizione nei dati del programma. Il motore controlla i dati del programma di ciascuno slot attivato per determinare quale slot è attivo per un dato giorno e ora.
Se nessuno slot ha il suo bit impostato per un'ora data, il motore torna alla tariffa base con un moltiplicatore di 1.0.
Quando la funzione di programma dei prezzi è completamente disabilitata (in Impostazioni > Prezzi), tutte le sessioni utilizzano la tariffa base con un moltiplicatore di 1.0 indipendentemente dall'ora.
Segmenti di Prezzo
Un segmento è un periodo di tempo continuo all'interno di una sessione in cui il contesto di prezzo non cambia. Il motore di prezzi crea un nuovo segmento ogni volta che si verificano questi eventi di confine:
| Confine | Trigger |
|---|---|
| session_start | Inizia una nuova sessione |
| session_stop | La sessione viene fermata |
| pausa | Il cassiere mette in pausa la sessione |
| riprendi | Il cassiere riprende una sessione in pausa |
| tick | L'orologio attraversa un confine orario in uno slot di prezzo diverso |
| disconnessione | Il PC cliente perde la connessione di rete |
| offline | Il PC cliente va offline |
| recupero_carico | Il server si riavvia e recupera una sessione in corso |
Ogni segmento registra:
| Campo | Descrizione |
|---|---|
| session_id | La sessione a cui appartiene questo segmento |
| segment_start | Timestamp Unix quando il segmento è iniziato |
| segment_end | Timestamp Unix quando il segmento è terminato (null se ancora aperto) |
| pricing_slot_id | L'ID dello slot di prezzo attivo (ad esempio, "blu", "rosso" o "base") |
| moltiplicatore | Il valore del moltiplicatore dallo slot di prezzo |
| base_price_snapshot | La tariffa oraria base catturata al momento dell'apertura del segmento |
| importo | Il costo calcolato per questo segmento (impostato quando il segmento si chiude) |
| motivo_confine | Perché questo segmento è stato creato |
Perché Catturare la Tariffa Base?
Il base_price_snapshot cattura la tariffa oraria base nel momento esatto in cui il segmento si apre. Questo è fondamentale perché un amministratore potrebbe cambiare la tariffa base a sessione in corso. Catturando, ogni segmento utilizza la tariffa che era in vigore quando è iniziato, garantendo una fatturazione equa e verificabile.
Formula del Costo
Il costo di un singolo segmento è calcolato come:
importo = ceil( (base_price_snapshot * moltiplicatore * durata_secondi) / 3600 )
Più precisamente, il motore utilizza l'aritmetica intera scalata per evitare errori in virgola mobile:
- Il moltiplicatore è scalato a un intero a punto fisso (moltiplicato per 1.000.000).
- Il calcolo è eseguito interamente in interi a 128 bit.
- Viene utilizzata la divisione per eccesso. Il risultato arrotonda sempre all'unità minore successiva.
Calcolo per Minuti
Se l'opzione "calcola per minuti" è abilitata in Impostazioni > Prezzi, la formula cambia leggermente:
importo = ceil( (base_price_snapshot * moltiplicatore * minuti_usati) / 60 )
Dove minuti_usati = ceil(durata_secondi / 60). Questo significa che ogni minuto parziale è conteggiato come un minuto intero.
Calcolo Totale della Sessione
Il costo totale della sessione è calcolato in tre passaggi:
Passaggio 1: Somma di Tutti i Segmenti
totale_grezzo = somma di tutti gli importi dei segmenti chiusi + importo parziale del segmento aperto
L'importo parziale del segmento aperto è calcolato in tempo reale utilizzando la formula sopra con il timestamp corrente come fine del segmento.
Passaggio 2: Applicazione dell'Arrotondamento
totale_arrotondato = arrotonda_su(totale_grezzo, passo_arrotondamento)
L'arrotondamento va sempre su (per eccesso) per proteggere i ricavi. Il passo di arrotondamento è configurabile in Impostazioni > Prezzi. Ad esempio, se il passo di arrotondamento è 50 (rappresentando $0.50 in una valuta con 2 cifre decimali), un totale grezzo di $3.27 arrotonda a $3.50.
Passaggio 3: Applicazione della Tariffa Minima di Avvio
totale_finale = max(totale_arrotondato, tariffa_avvio)
La tariffa di avvio è il costo minimo per qualsiasi sessione, indipendentemente dalla durata. Se il totale arrotondato è inferiore alla tariffa di avvio, viene addebitata la tariffa di avvio.
Chiusura
La chiusura è il processo di finalizzazione della fatturazione per una sessione. Ci sono due fasi di chiusura:
Chiusura Iniziale (Solo Prepagato)
Quando inizia una sessione prepagata, viene creato un record di chiusura "iniziale". Questo cattura:
- Costo calcolato. Il costo calcolato dal sistema per il tempo acquistato.
- Importo addebitato. L'importo effettivamente pagato dal cliente (di solito lo stesso del costo calcolato).
Per la modalità prepagata "Blocco all'Acquisto", questo importo bloccato determina il costo della sessione indipendentemente dai cambiamenti di prezzo durante la sessione.
Chiusura Finale
Quando qualsiasi sessione (prepagata o postpagata) viene fermata, viene creato un record di chiusura "finale":
| Campo | Descrizione |
|---|---|
| Costo calcolato | Il totale calcolato dal sistema da tutti i segmenti di prezzo |
| Importo addebitato | L'importo effettivamente addebitato (predefinito al costo calcolato) |
| Importo regolato manualmente | Se il cassiere ha regolato manualmente il prezzo, il costo calcolato originale è conservato qui |
| Tasso di commissione | Tasso di commissione del metodo di pagamento (come percentuale) |
| commission_fee | L'importo della commissione calcolata |
| fixed_fee | Tariffa fissa del metodo di pagamento |
| computed_timeline_snapshot | Un record JSON di ogni segmento di prezzo nella sessione |
Lo snapshot della timeline fornisce una traccia di audit completa che mostra esattamente come è stato calcolato il costo, segmento per segmento.
Tariffe dei Metodi di Pagamento
Ogni metodo di pagamento può avere due tipi di tariffe:
Commissione (Punti Base)
Il tasso di commissione è espresso come percentuale. La commissione è calcolata applicando questo tasso all'importo addebitato.
Esempio: Se l'importo addebitato è $10.00 (1000 unità minori) e il metodo di pagamento ha un tasso di commissione del 2.5%, la commissione è $0.25 (25 unità minori).
Tariffa Fissa
Una tariffa fissa detratta per transazione, indipendentemente dall'importo. Ad esempio, una tariffa di elaborazione carta di credito di $0.30.
Entrambe le tariffe sono informative. Rappresentano il costo per l'azienda di accettare quel metodo di pagamento. Sono registrate nella chiusura ma non sono aggiunte al conto del cliente.
IVA (Imposta sul Valore Aggiunto)
L'IVA è configurata come percentuale (0--100%) in Impostazioni > Prezzi. È applicata sopra l'importo calcolato della sessione:
IVA = importo addebitato x (tasso IVA / 100)
L'importo dell'IVA è mostrato separatamente nella finestra di dialogo del pagamento in modo che il cassiere possa vedere il dettaglio delle tasse.
Modalità di Prezzo Prepagato
Come descritto in Gestione delle Sessioni, le sessioni prepagate supportano due modalità di prezzo:
Blocco all'Acquisto
Quando inizia una sessione prepagata, la chiusura "iniziale" blocca l'importo addebitato. Per la durata della sessione:
- L'orario di fine sessione è fissato in base ai minuti acquistati.
- Anche se il programma dei prezzi cambia, la sessione continua fino alla scadenza del tempo bloccato.
- La chiusura finale utilizza l'importo bloccato dalla chiusura iniziale.
Programma Live
Il tempo rimanente della sessione è ricalcolato continuamente mentre gli slot di prezzo cambiano:
- Se la sessione entra in uno slot più economico, il tempo rimanente si allunga (il cliente ottiene più minuti per il suo denaro).
- Se la sessione entra in uno slot più costoso, il tempo rimanente si contrae.
- La chiusura finale riflette il prezzo effettivamente applicato durante tutta la sessione.
Cifre Decimali
Il numero di cifre decimali utilizzate per la visualizzazione della valuta è configurabile (2--4 cifre decimali). Questo influisce su come gli importi sono visualizzati nell'interfaccia utente ma non cambia i calcoli interni delle unità minori.
Esempio: Con 2 cifre decimali, $3.50 è visualizzato come "3.50". Con 3 cifre decimali, sarebbe visualizzato come "3.500".
Esempi Pratici
Esempio 1: Sessione Postpagata Semplice
- Tariffa base: $3.00/ora (300 unità minori)
- Programma: Slot standard (moltiplicatore 1.0) tutto il giorno
- Sessione: 10:00 AM a 11:30 AM (90 minuti)
- Tariffa di avvio: $0.50
Calcolo:
Segmento 1: (300 * 1.0 * 5400) / 3600 = 450 unità minori ($4.50)
Totale: max($4.50, $0.50) = $4.50
Esempio 2: Sessione che Copre Due Slot
- Tariffa base: $4.00/ora (400 unità minori)
- Programma: Standard (1.0) dalle 10:00 alle 12:00, Happy Hour (0.5) dalle 12:00 alle 14:00
- Sessione: 11:00 AM a 1:00 PM (120 minuti)
- Tariffa di avvio: $1.00
Calcolo:
Segmento 1 (11:00-12:00, standard): (400 * 1.0 * 3600) / 3600 = 400 ($4.00)
Segmento 2 (12:00-13:00, happy hour): (400 * 0.5 * 3600) / 3600 = 200 ($2.00)
Totale: $4.00 + $2.00 = $6.00
Finale: max($6.00, $1.00) = $6.00
Esempio 3: Sessione con Pausa
- Tariffa base: $2.00/ora (200 unità minori)
- Programma: Slot standard (moltiplicatore 1.0) tutto il giorno
- Sessione: Inizio 10:00, Pausa 10:30, Riprendi 11:00, Stop 11:45
- Tariffa di avvio: $0.50
Calcolo:
Segmento 1 (10:00-10:30, attivo): (200 * 1.0 * 1800) / 3600 = 100 ($1.00)
Periodo in pausa (10:30-11:00): nessun addebito
Segmento 2 (11:00-11:45, attivo): (200 * 1.0 * 2700) / 3600 = 150 ($1.50)
Totale: $1.00 + $1.50 = $2.50
Finale: max($2.50, $0.50) = $2.50
Prossimi Passi
- Gestione delle Sessioni: Scopri il ciclo di vita completo delle sessioni
- Impostazioni: Prezzi: Configura la tariffa base, l'arrotondamento e la tariffa di avvio
- Impostazioni: Programma Prezzi: Imposta la griglia del programma 7x24
- Metodi di Pagamento: Configura i metodi di pagamento con commissioni e tariffe