Tariffe Sessioni
HandyCafe utilizza un motore di tariffazione basato su segmenti per calcolare i costi delle sessioni nel tuo internet cafe o gaming center. Anziche applicare un'unica tariffa fissa per l'intera sessione, il motore divide ogni sessione in segmenti, ognuno con il proprio contesto tariffario. Questo approccio garantisce una fatturazione accurata anche quando le sessioni attraversano piu fasce orarie, variazioni di prezzo, pause o disconnessioni.
Concetti Fondamentali
Prima di entrare nei dettagli, ecco i termini chiave:
| Termine | Definizione |
|---|---|
| Tariffa oraria base | Il prezzo all'ora prima dell'applicazione di qualsiasi moltiplicatore. Impostato in Impostazioni > Tariffe. |
| Fascia tariffaria | Un periodo temporale denominato con un moltiplicatore specifico. Ci sono 8 fasce, ognuna con codice colore. |
| Moltiplicatore | Un fattore applicato alla tariffa base. 1,0 = prezzo standard, 0,5 = meta prezzo, 2,0 = prezzo doppio. |
| Segmento | Un periodo continuo all'interno di una sessione dove il contesto tariffario (fascia, moltiplicatore, prezzo base) resta invariato. |
| Saldo | Il calcolo finale che determina quanto il cliente deve pagare al termine della sessione. |
Tariffa Oraria Base
La tariffa oraria base e il fondamento di tutti i calcoli tariffari. Viene impostata in Impostazioni > Tariffe e rappresenta il prezzo standard all'ora di utilizzo del PC.
Tutti i calcoli interni utilizzano unita minori di valuta (ad esempio centesimi per EUR). Se la tariffa base e 3,00 euro all'ora, il valore interno e 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 le tariffe internazionali differiscono da quelle locali:
- Valuta base. La valuta utilizzata per i calcoli tariffari interni.
- Valuta locale. La valuta visualizzata ai clienti e utilizzata per i pagamenti.
- Tasso FX. Il fattore di conversione tra valuta base e locale.
Se entrambe le valute sono uguali, il tasso FX viene trattato come 1,0 e non ha effetto.
Fasce Tariffarie
Ci sono 8 fasce tariffarie con codice colore, ognuna rappresentante un diverso livello tariffario:
| Fascia | Colore | Uso Tipico |
|---|---|---|
| Blu | Blu | Tariffa standard |
| Arancione | Arancione | Supplemento serale o weekend |
| Rosso | Rosso | Premium ore di punta |
| Verde | Verde | Sconto fuori punta |
| Teal | Teal | Tariffa studente o membro |
| Grigio | Grigio | Tariffa festivita o speciale |
| Ciano | Ciano | Tariffa notturna |
| Smeraldo | Smeraldo | Tariffa promozionale |
Ogni fascia ha tre proprieta:
- 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 (meta prezzo), 1,5 (supplemento 50%), 2,0 (prezzo doppio). Il moltiplicatore deve essere zero o positivo.
- Dati programmazione. Una rappresentazione interna che definisce in quali ore e giorni la fascia si applica. Gestita automaticamente tramite la griglia programmazione.
Le fasce possono essere abilitate o disabilitate individualmente. Le fasce disabilitate vengono ignorate dal motore di tariffazione.
La Griglia di Programmazione
La programmazione tariffe e una matrice 7 giorni per 24 ore (168 blocchi di un'ora in totale). Ogni blocco e assegnato a una fascia tariffaria. La programmazione determina quale moltiplicatore si applica in ogni momento.
La griglia viene configurata in Impostazioni > Programmazione Tariffe. I giorni vanno da lunedi a domenica e le ore da 00:00 a 23:00. Per assegnare una fascia a un blocco temporale, seleziona il blocco nella griglia e scegli il colore della fascia desiderata.
Come il Motore Legge la Programmazione
Internamente, ogni blocco orario si mappa a una posizione nei dati della programmazione. Il motore controlla i dati della programmazione di ogni fascia abilitata per determinare quale fascia e attiva per un dato giorno e ora.
Se nessuna fascia ha il suo bit impostato per una data ora, il motore ricade sulla tariffa base con un moltiplicatore di 1,0.
Quando la funzionalita di programmazione tariffe e completamente disabilitata (in Impostazioni > Tariffe), tutte le sessioni utilizzano la tariffa base con moltiplicatore 1,0 indipendentemente dall'ora.
Segmenti Tariffari
Un segmento e un periodo continuo all'interno di una sessione dove il contesto tariffario non cambia. Il motore di tariffazione crea un nuovo segmento ogni volta che si verifica uno dei seguenti eventi confine:
| Confine | Attivazione |
|---|---|
| session_start | Inizia una nuova sessione |
| session_stop | La sessione viene terminata |
| pause | Il cassiere mette in pausa la sessione |
| resume | Il cassiere riprende una sessione in pausa |
| tick | L'orologio attraversa un confine orario in una fascia tariffaria diversa |
| disconnect | Il PC client perde la connessione di rete |
| offline | Il PC client va offline |
| load_recovery | 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 di quando il segmento e iniziato |
| segment_end | Timestamp Unix di quando il segmento e terminato (nullo se ancora aperto) |
| pricing_slot_id | L'ID della fascia tariffaria attiva (ad esempio "blue", "red" o "base") |
| multiplier | Il valore del moltiplicatore dalla fascia tariffaria |
| base_price_snapshot | La tariffa oraria base catturata al momento dell'apertura del segmento |
| amount | Il costo calcolato per questo segmento (impostato alla chiusura del segmento) |
| boundary_reason | Perche questo segmento e stato creato |
Perche lo Snapshot del Prezzo Base?
Il base_price_snapshot cattura la tariffa oraria base all'esatto momento dell'apertura del segmento. Questo e fondamentale perche un amministratore potrebbe modificare la tariffa base durante una sessione. Con lo snapshot, ogni segmento utilizza la tariffa in vigore al momento della sua apertura, garantendo una fatturazione equa e verificabile.
Formula del Costo
Il costo di un singolo segmento viene calcolato come:
importo = ceil( (base_price_snapshot * moltiplicatore * durata_secondi) / 3600 )
Piu precisamente, il motore utilizza aritmetica intera scalata per evitare errori in virgola mobile:
- Il moltiplicatore viene scalato a un intero a virgola fissa (moltiplicato per 1.000.000).
- Il calcolo viene eseguito interamente in interi a 128 bit.
- Viene utilizzata la divisione con arrotondamento per eccesso. Il risultato arrotonda sempre all'unita minore successiva.
Calcolo per Minuti
Se l'opzione "calcola per minuti" e abilitata in Impostazioni > Tariffe, la formula cambia leggermente:
importo = ceil( (base_price_snapshot * moltiplicatore * minuti_utilizzati) / 60 )
Dove minuti_utilizzati = ceil(durata_secondi / 60). Questo significa che qualsiasi minuto parziale viene contato come minuto intero.
Calcolo del Totale Sessione
Il costo totale della sessione viene 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 viene 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 verso l'alto (per eccesso) per proteggere i ricavi. Il passo di arrotondamento e configurabile in Impostazioni > Tariffe.
Passaggio 3: Applicazione del Minimo Tariffa di Avvio
totale_finale = max(totale_arrotondato, tariffa_avvio)
La tariffa di avvio e l'addebito minimo per qualsiasi sessione, indipendentemente dalla durata. Se il totale arrotondato e inferiore alla tariffa di avvio, viene addebitata la tariffa di avvio.
Saldo
Il saldo e il processo di finalizzazione della fatturazione per una sessione. Ci sono due fasi di saldo:
Saldo Iniziale (Solo Prepagata)
Quando una sessione prepagata inizia, viene creato un record di saldo "inizio". Questo cattura:
- Costo calcolato. Il costo calcolato dal sistema per il tempo acquistato.
- Importo addebitato. L'importo che il cliente ha effettivamente pagato (di solito uguale al costo calcolato).
Per la modalita prepagata "Blocco all'Acquisto", questo importo bloccato determina il costo della sessione indipendentemente dalle variazioni tariffarie durante la sessione.
Saldo Finale
Quando qualsiasi sessione (prepagata o postpagata) viene terminata, viene creato un record di saldo "fine":
| Campo | Descrizione |
|---|---|
| Costo calcolato | Il totale calcolato dal sistema da tutti i segmenti tariffari |
| Importo addebitato | L'importo effettivamente addebitato (predefinito al costo calcolato) |
| Importo rettificato manualmente | Se il cassiere ha rettificato manualmente il prezzo, il costo calcolato originale viene conservato qui |
| Tasso 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 tariffario nella sessione |
Lo snapshot della timeline fornisce una traccia di controllo completa che mostra esattamente come il costo e stato calcolato, segmento per segmento.
Commissioni del Metodo di Pagamento
Ogni metodo di pagamento puo avere due tipi di commissioni:
Commissione (Punti Base)
Il tasso di commissione e espresso come percentuale. La commissione viene calcolata applicando questo tasso all'importo addebitato.
Tariffa Fissa
Una tariffa fissa detratta per transazione, indipendentemente dall'importo.
Entrambe le commissioni sono informative. Rappresentano il costo per l'attivita di accettare quel metodo di pagamento. Vengono registrate nel saldo ma non aggiunte al conto del cliente.
IVA (Imposta sul Valore Aggiunto)
L'IVA viene configurata come percentuale (0--100%) in Impostazioni > Tariffe. Viene applicata in aggiunta all'importo calcolato della sessione:
IVA = importo addebitato x (aliquota IVA / 100)
L'importo IVA viene visualizzato separatamente nella finestra di pagamento cosi il cassiere puo vedere il dettaglio fiscale.
Modalita Tariffarie Prepagata
Come descritto in Gestione Sessioni, le sessioni prepagate supportano due modalita tariffarie:
Blocco all'Acquisto
Quando una sessione prepagata inizia, il saldo "inizio" blocca l'importo addebitato. Per la durata della sessione:
- L'ora di fine della sessione e fissa in base ai minuti acquistati.
- Anche se la programmazione tariffe cambia, la sessione continua fino alla scadenza del tempo bloccato.
- Il saldo finale utilizza l'importo bloccato dal saldo iniziale.
Programmazione in Tempo Reale
Il tempo rimanente della sessione viene ricalcolato continuamente man mano che le fasce tariffarie cambiano:
- Se la sessione entra in una fascia piu economica, il tempo rimanente si estende (il cliente ottiene piu minuti per il suo denaro).
- Se la sessione entra in una fascia piu costosa, il tempo rimanente si contrae.
- Il saldo finale riflette le tariffe effettivamente applicate durante la sessione.
Cifre Decimali
Il numero di cifre decimali utilizzate per la visualizzazione della valuta e configurabile (2--4 cifre decimali). Questo influisce su come gli importi vengono visualizzati nell'interfaccia ma non cambia i calcoli interni in unita minori.
Passi Successivi
- Gestione Sessioni: Scopri il ciclo di vita completo delle sessioni
- Impostazioni: Tariffe: Configura la tariffa base, l'arrotondamento e la tariffa di avvio
- Impostazioni: Programmazione Tariffe: Configura la griglia programmazione 7x24
- Metodi di Pagamento: Configura i metodi di pagamento con commissioni e tariffe