Precios de sesiones
HandyCafe usa un motor de precios basado en segmentos para calcular los costos de sesion en su cibercafe o centro de gaming. En lugar de aplicar una tarifa plana unica para toda la sesion, el motor divide cada sesion en segmentos, cada uno con su propio contexto de precios. Este enfoque garantiza una facturacion precisa incluso cuando las sesiones abarcan multiples franjas horarias, cambios de precios, pausas o desconexiones.
Conceptos fundamentales
Antes de entrar en detalles, estos son los terminos clave:
| Termino | Definicion |
|---|---|
| Tarifa por hora base | El precio por hora antes de aplicar multiplicadores. Se establece en Configuracion > Precios. |
| Franja de precios | Un periodo de tiempo con un multiplicador especifico. Hay 8 franjas, cada una con codigo de color. |
| Multiplicador | Un factor aplicado a la tarifa base. 1.0 = precio estandar, 0.5 = mitad de precio, 2.0 = doble precio. |
| Segmento | Un periodo continuo dentro de una sesion donde el contexto de precios (franja, multiplicador, precio base) permanece sin cambios. |
| Liquidacion | El calculo final que determina cuanto debe el cliente cuando una sesion termina. |
Tarifa por hora base
La tarifa por hora base es la base de todos los calculos de precios. Se establece en Configuracion > Precios y representa el precio estandar por hora de uso de PC.
Todos los calculos internos usan unidades menores de moneda (por ejemplo, centavos para USD). Si su tarifa base es $3.00 por hora, el valor interno es 300. Esto elimina problemas de redondeo de punto flotante.
Soporte de doble moneda
HandyCafe admite una moneda base y una moneda local con un tipo de cambio (FX). Si opera en un pais donde los precios internacionales difieren de los precios locales:
- Moneda base. La moneda usada para los calculos internos de precios.
- Moneda local. La moneda mostrada a los clientes y usada para pagos.
- Tipo de cambio FX. El factor de conversion entre las monedas base y local.
Si ambas monedas son la misma, el tipo de cambio se trata como 1.0 y no tiene efecto.
Franjas de precios
Hay 8 franjas de precios con codigo de color, cada una representando un nivel de precios diferente:
| Franja | Color | Uso tipico |
|---|---|---|
| Azul | Azul | Tarifa estandar |
| Naranja | Naranja | Recargo de tarde o fin de semana |
| Rojo | Rojo | Prima de horas pico |
| Verde | Verde | Descuento fuera de pico |
| Verde azulado | Verde azulado | Tarifa para estudiantes o miembros |
| Gris | Gris | Precios de festivos o especiales |
| Cian | Cian | Tarifa nocturna |
| Esmeralda | Esmeralda | Tarifa promocional |
Cada franja tiene tres propiedades:
- Nombre. Una etiqueta descriptiva (por ejemplo, "Horas pico" o "Descuento nocturno").
- Multiplicador. Un valor decimal que modifica la tarifa base. Los valores comunes incluyen 1.0 (estandar), 0.5 (mitad de precio), 1.5 (recargo del 50%), 2.0 (doble precio). El multiplicador debe ser cero o positivo.
- Datos del horario. Una representacion interna que define que horas de que dias aplica la franja. Esto se gestiona automaticamente a traves de la cuadricula del horario.
Las franjas pueden habilitarse o deshabilitarse individualmente. Las franjas deshabilitadas son ignoradas por el motor de precios.
La cuadricula del horario
El horario de precios es una matriz de 7 dias por 24 horas (168 bloques de una hora en total). Cada bloque se asigna a una franja de precios. El horario determina que multiplicador aplica en cualquier momento dado.
La cuadricula se configura en Configuracion > Horario de precios. Los dias van de lunes a domingo y las horas de 00:00 a 23:00. Para asignar una franja a un bloque de tiempo, seleccione el bloque en la cuadricula y elija el color de franja deseado.
Como el motor lee el horario
Internamente, cada bloque de hora se mapea a una posicion en los datos del horario. El motor verifica los datos del horario de cada franja habilitada para determinar que franja esta activa para cualquier dia y hora dada.
Si ninguna franja tiene su bit activado para una hora dada, el motor usa la tarifa base con un multiplicador de 1.0.
Cuando la funcion de horario de precios esta completamente deshabilitada (en Configuracion > Precios), todas las sesiones usan la tarifa base con un multiplicador de 1.0 sin importar la hora.
Segmentos de precios
Un segmento es un periodo de tiempo continuo dentro de una sesion donde el contexto de precios no cambia. El motor de precios crea un nuevo segmento cada vez que ocurre uno de estos eventos limite:
| Limite | Activador |
|---|---|
| session_start | Comienza una nueva sesion |
| session_stop | La sesion se detiene |
| pause | El cajero pausa la sesion |
| resume | El cajero reanuda una sesion pausada |
| tick | El reloj cruza un limite de hora hacia una franja de precios diferente |
| disconnect | El PC cliente pierde su conexion de red |
| offline | El PC cliente se desconecta |
| load_recovery | El servidor se reinicia y recupera una sesion en ejecucion |
Cada segmento registra:
| Campo | Descripcion |
|---|---|
| session_id | La sesion a la que pertenece este segmento |
| segment_start | Marca de tiempo Unix cuando comenzo el segmento |
| segment_end | Marca de tiempo Unix cuando termino el segmento (nulo si aun esta abierto) |
| pricing_slot_id | El ID de la franja de precios activa (por ejemplo, "blue", "red" o "base") |
| multiplier | El valor del multiplicador de la franja de precios |
| base_price_snapshot | La tarifa por hora base capturada en el momento en que se abrio el segmento |
| amount | El costo calculado para este segmento (se establece cuando el segmento se cierra) |
| boundary_reason | Por que se creo este segmento |
Por que capturar el precio base
El base_price_snapshot captura la tarifa por hora base en el momento exacto en que se abre el segmento. Esto es critico porque un administrador podria cambiar la tarifa base durante una sesion. Al capturarlo, cada segmento usa la tarifa que estaba vigente cuando comenzo, asegurando una facturacion justa y auditable.
Formula de costo
El costo de un solo segmento se calcula como:
amount = ceil( (base_price_snapshot * multiplier * duration_seconds) / 3600 )
De forma mas precisa, el motor usa aritmetica de enteros escalados para evitar errores de punto flotante:
- El multiplicador se escala a un entero de punto fijo (multiplicado por 1,000,000).
- El calculo se realiza completamente en enteros de 128 bits.
- Se usa division con techo. El resultado siempre se redondea hacia arriba a la siguiente unidad menor.
Calculo por minutos
Si la opcion "calcular por minutos" esta habilitada en Configuracion > Precios, la formula cambia ligeramente:
amount = ceil( (base_price_snapshot * multiplier * used_minutes) / 60 )
Donde used_minutes = ceil(duration_seconds / 60). Esto significa que cualquier minuto parcial se cuenta como un minuto completo.
Calculo del total de la sesion
El costo total de la sesion se calcula en tres pasos:
Paso 1: Sumar todos los segmentos
total_bruto = suma de todos los montos de segmentos cerrados + monto parcial del segmento abierto
El monto parcial del segmento abierto se calcula en tiempo real usando la formula anterior con la marca de tiempo actual como fin del segmento.
Paso 2: Aplicar redondeo
total_redondeado = redondear_arriba(total_bruto, paso_de_redondeo)
El redondeo siempre va hacia arriba (techo) para proteger los ingresos. El paso de redondeo es configurable en Configuracion > Precios. Por ejemplo, si el paso de redondeo es 50 (representando $0.50 en una moneda con 2 digitos fraccionarios), un total bruto de $3.27 se redondea a $3.50.
Paso 3: Aplicar tarifa de inicio minima
total_final = max(total_redondeado, tarifa_de_inicio)
La tarifa de inicio es el cargo minimo para cualquier sesion, sin importar la duracion. Si el total redondeado es menor que la tarifa de inicio, se cobra la tarifa de inicio en su lugar.
Liquidacion
La liquidacion es el proceso de finalizar la facturacion de una sesion. Hay dos etapas de liquidacion:
Liquidacion de inicio (Solo prepago)
Cuando comienza una sesion prepago, se crea un registro de liquidacion de "inicio". Esto captura:
- Costo calculado. El costo calculado por el sistema para el tiempo comprado.
- Monto cobrado. El monto que el cliente realmente pago (usualmente el mismo que el costo calculado).
Para el modo prepago "Bloquear al comprar", este monto bloqueado determina el costo de la sesion sin importar los cambios de precios durante la sesion.
Liquidacion de fin
Cuando cualquier sesion (prepago o pospago) se detiene, se crea un registro de liquidacion de "fin":
| Campo | Descripcion |
|---|---|
| Costo calculado | El total calculado por el sistema de todos los segmentos de precios |
| Monto cobrado | El monto realmente cobrado (por defecto es el costo calculado) |
| Monto ajustado manualmente | Si el cajero ajusto manualmente el precio, el costo calculado original se preserva aqui |
| Tasa de comision | Tasa de comision del metodo de pago (como porcentaje) |
| commission_fee | El monto de comision calculado |
| fixed_fee | Tarifa fija del metodo de pago |
| computed_timeline_snapshot | Un registro JSON de cada segmento de precios en la sesion |
La instantanea de la linea de tiempo proporciona una pista de auditoria completa mostrando exactamente como se calculo el costo, segmento por segmento.
Tarifas del metodo de pago
Cada metodo de pago puede tener dos tipos de tarifas:
Comision (Puntos base)
La tasa de comision se expresa como un porcentaje. La tarifa de comision se calcula aplicando esta tasa al monto cobrado.
Ejemplo: Si el monto cobrado es $10.00 (1000 unidades menores) y el metodo de pago tiene una tasa de comision del 2.5%, la tarifa de comision es $0.25 (25 unidades menores).
Tarifa fija
Una tarifa plana deducida por transaccion, sin importar el monto. Por ejemplo, una tarifa de procesamiento de tarjeta de credito de $0.30.
Ambas tarifas son informativas. Representan el costo para el negocio de aceptar ese metodo de pago. Se registran en la liquidacion pero no se agregan a la cuenta del cliente.
IVA (Impuesto al Valor Agregado)
El IVA se configura como un porcentaje (0--100%) en Configuracion > Precios. Se aplica sobre el monto calculado de la sesion:
IVA = monto cobrado x (tasa de IVA / 100)
El monto del IVA se muestra por separado en el dialogo de pago para que el cajero pueda ver el desglose de impuestos.
Modos de precios prepago
Como se describe en Gestion de sesiones, las sesiones prepago admiten dos modos de precios:
Bloquear al comprar
Cuando comienza una sesion prepago, la liquidacion de "inicio" bloquea el monto cobrado. Durante la duracion de la sesion:
- La hora de fin de la sesion se fija basandose en los minutos comprados.
- Aunque el horario de precios cambie, la sesion continua hasta que el tiempo bloqueado expire.
- La liquidacion de fin usa el monto bloqueado de la liquidacion de inicio.
Horario en vivo
El tiempo restante de la sesion se recalcula continuamente a medida que cambian las franjas de precios:
- Si la sesion entra en una franja mas barata, el tiempo restante se extiende (el cliente obtiene mas minutos por su dinero).
- Si la sesion entra en una franja mas cara, el tiempo restante se contrae.
- La liquidacion de fin refleja los precios reales aplicados durante toda la sesion.
Digitos fraccionarios
La cantidad de decimales usados para la visualizacion de moneda es configurable (2--4 digitos fraccionarios). Esto afecta como se muestran los montos en la interfaz pero no cambia los calculos internos en unidades menores.
Ejemplo: Con 2 digitos fraccionarios, $3.50 se muestra como "3.50". Con 3 digitos fraccionarios, se mostraria como "3.500".
Ejemplos practicos
Ejemplo 1: Sesion pospago simple
- Tarifa base: $3.00/hora (300 unidades menores)
- Horario: Franja estandar (multiplicador 1.0) todo el dia
- Sesion: 10:00 AM a 11:30 AM (90 minutos)
- Tarifa de inicio: $0.50
Calculo:
Segmento 1: (300 * 1.0 * 5400) / 3600 = 450 unidades menores ($4.50)
Total: max($4.50, $0.50) = $4.50
Ejemplo 2: Sesion que abarca dos franjas
- Tarifa base: $4.00/hora (400 unidades menores)
- Horario: Estandar (1.0) de 10:00 a 12:00, Happy Hour (0.5) de 12:00 a 14:00
- Sesion: 11:00 AM a 1:00 PM (120 minutos)
- Tarifa de inicio: $1.00
Calculo:
Segmento 1 (11:00-12:00, estandar): (400 * 1.0 * 3600) / 3600 = 400 ($4.00)
Segmento 2 (12:00-13:00, happy hour): (400 * 0.5 * 3600) / 3600 = 200 ($2.00)
Total: $4.00 + $2.00 = $6.00
Final: max($6.00, $1.00) = $6.00
Ejemplo 3: Sesion con pausa
- Tarifa base: $2.00/hora (200 unidades menores)
- Horario: Franja estandar (multiplicador 1.0) todo el dia
- Sesion: Inicio 10:00, Pausa 10:30, Reanudacion 11:00, Fin 11:45
- Tarifa de inicio: $0.50
Calculo:
Segmento 1 (10:00-10:30, activo): (200 * 1.0 * 1800) / 3600 = 100 ($1.00)
Periodo en pausa (10:30-11:00): sin cargo
Segmento 2 (11:00-11:45, activo): (200 * 1.0 * 2700) / 3600 = 150 ($1.50)
Total: $1.00 + $1.50 = $2.50
Final: max($2.50, $0.50) = $2.50
Siguientes pasos
- Gestion de sesiones: Conozca el ciclo de vida completo de las sesiones
- Configuracion: Precios: Configure la tarifa base, redondeo y tarifa de inicio
- Configuracion: Horario de precios: Configure la cuadricula de horarios 7x24
- Metodos de pago: Configure metodos de pago con comision y tarifas