Precios de sesiones
HandyCafe usa un motor de precios basado en segmentos para calcular los costos de sesión en su cibercafé o centro de gaming. En lugar de aplicar una tarifa plana única para toda la sesión, el motor divide cada sesión en segmentos, cada uno con su propio contexto de precios. Este enfoque garantiza una facturación precisa incluso cuando las sesiones abarcan múltiples franjas horarias, cambios de precios, pausas o desconexiones.
Conceptos fundamentales
Antes de entrar en detalles, estos son los términos clave:
| Término | Definición |
|---|---|
| Tarifa por hora base | El precio por hora antes de aplicar multiplicadores. Se establece en Configuración > Precios. |
| Franja de precios | Un período de tiempo con un multiplicador específico. Hay 8 franjas, cada una con código de color. |
| Multiplicador | Un factor aplicado a la tarifa base. 1.0 = precio estándar, 0.5 = mitad de precio, 2.0 = doble precio. |
| Segmento | Un período continuo dentro de una sesión donde el contexto de precios (franja, multiplicador, precio base) permanece sin cambios. |
| Liquidación | El cálculo final que determina cuánto debe el cliente cuando una sesión termina. |
Tarifa por hora base
La tarifa por hora base es la base de todos los cálculos de precios. Se establece en Configuración > Precios y representa el precio estándar por hora de uso de PC.
Todos los cálculos 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 país donde los precios internacionales difieren de los precios locales:
- Moneda base. La moneda usada para los cálculos internos de precios.
- Moneda local. La moneda mostrada a los clientes y usada para pagos.
- Tipo de cambio FX. El factor de conversión 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 código de color, cada una representando un nivel de precios diferente:
| Franja | Color | Uso típico |
|---|---|---|
| Azul | Azul | Tarifa estándar |
| 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 (estándar), 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 representación interna que define qué horas de qué días aplica la franja. Esto se gestiona automáticamente a través de la cuadrícula del horario.
Las franjas pueden habilitarse o deshabilitarse individualmente. Las franjas deshabilitadas son ignoradas por el motor de precios.
La cuadrícula del horario
El horario de precios es una matriz de 7 días por 24 horas (168 bloques de una hora en total). Cada bloque se asigna a una franja de precios. El horario determina qué multiplicador aplica en cualquier momento dado.
La cuadrícula se configura en Configuración > Horario de precios. Los días 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 cuadrícula y elija el color de franja deseado.
Cómo el motor lee el horario
Internamente, cada bloque de hora se mapea a una posición en los datos del horario. El motor verifica los datos del horario de cada franja habilitada para determinar qué franja está activa para cualquier día 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 función de horario de precios está completamente deshabilitada (en Configuración > 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 período de tiempo continuo dentro de una sesión donde el contexto de precios no cambia. El motor de precios crea un nuevo segmento cada vez que ocurre uno de estos eventos límite:
| Límite | Activador |
|---|---|
| session_start | Comienza una nueva sesión |
| session_stop | La sesión se detiene |
| pause | El cajero pausa la sesión |
| resume | El cajero reanuda una sesión pausada |
| tick | El reloj cruza un límite de hora hacia una franja de precios diferente |
| disconnect | El PC cliente pierde su conexión de red |
| offline | El PC cliente se desconecta |
| load_recovery | El servidor se reinicia y recupera una sesión en ejecución |
Cada segmento registra:
| Campo | Descripción |
|---|---|
| session_id | La sesión a la que pertenece este segmento |
| segment_start | Marca de tiempo Unix cuando comenzó el segmento |
| segment_end | Marca de tiempo Unix cuando terminó el segmento (nulo si aún está 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 abrió el segmento |
| amount | El costo calculado para este segmento (se establece cuando el segmento se cierra) |
| boundary_reason | Por qué se creó este segmento |
Por qué 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 crítico porque un administrador podría cambiar la tarifa base durante una sesión. Al capturarlo, cada segmento usa la tarifa que estaba vigente cuando comenzó, asegurando una facturación justa y auditable.
Fórmula de costo
El costo de un solo segmento se calcula como:
amount = ceil( (base_price_snapshot * multiplier * duration_seconds) / 3600 )
De forma más precisa, el motor usa aritmética 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 cálculo se realiza completamente en enteros de 128 bits.
- Se usa división con techo. El resultado siempre se redondea hacia arriba a la siguiente unidad menor.
Cálculo por minutos
Si la opción "calcular por minutos" está habilitada en Configuración > Precios, la fórmula 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.
Cálculo del total de la sesión
El costo total de la sesión 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 fórmula 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 Configuración > Precios. Por ejemplo, si el paso de redondeo es 50 (representando $0.50 en una moneda con 2 dígitos fraccionarios), un total bruto de $3.27 se redondea a $3.50.
Paso 3: Aplicar tarifa de inicio mínima
total_final = max(total_redondeado, tarifa_de_inicio)
La tarifa de inicio es el cargo mínimo para cualquier sesión, sin importar la duración. Si el total redondeado es menor que la tarifa de inicio, se cobra la tarifa de inicio en su lugar.
Liquidación
La liquidación es el proceso de finalizar la facturación de una sesión. Hay dos etapas de liquidación:
Liquidación de inicio (Solo prepago)
Cuando comienza una sesión prepago, se crea un registro de liquidación de "inicio". Esto captura:
- Costo calculado. El costo calculado por el sistema para el tiempo comprado.
- Monto cobrado. El monto que el cliente realmente pagó (usualmente el mismo que el costo calculado).
Para el modo prepago "Bloquear al comprar", este monto bloqueado determina el costo de la sesión sin importar los cambios de precios durante la sesión.
Liquidación de fin
Cuando cualquier sesión (prepago o pospago) se detiene, se crea un registro de liquidación de "fin":
| Campo | Descripción |
|---|---|
| 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 ajustó manualmente el precio, el costo calculado original se preserva aquí |
| Tasa de comisión | Tasa de comisión del método de pago (como porcentaje) |
| commission_fee | El monto de comisión calculado |
| fixed_fee | Tarifa fija del método de pago |
| computed_timeline_snapshot | Un registro JSON de cada segmento de precios en la sesión |
La instantánea de la línea de tiempo proporciona una pista de auditoría completa mostrando exactamente cómo se calculó el costo, segmento por segmento.
Tarifas del método de pago
Cada método de pago puede tener dos tipos de tarifas:
Comisión (Puntos base)
La tasa de comisión se expresa como un porcentaje. La tarifa de comisión se calcula aplicando esta tasa al monto cobrado.
Ejemplo: Si el monto cobrado es $10.00 (1000 unidades menores) y el método de pago tiene una tasa de comisión del 2.5%, la tarifa de comisión es $0.25 (25 unidades menores).
Tarifa fija
Una tarifa plana deducida por transacción, sin importar el monto. Por ejemplo, una tarifa de procesamiento de tarjeta de crédito de $0.30.
Ambas tarifas son informativas. Representan el costo para el negocio de aceptar ese método de pago. Se registran en la liquidación pero no se agregan a la cuenta del cliente.
IVA (Impuesto al Valor Agregado)
El IVA se configura como un porcentaje (0--100%) en Configuración > Precios. Se aplica sobre el monto calculado de la sesión:
IVA = monto cobrado x (tasa de IVA / 100)
El monto del IVA se muestra por separado en el diálogo de pago para que el cajero pueda ver el desglose de impuestos.
Modos de precios prepago
Como se describe en Gestión de sesiones, las sesiones prepago admiten dos modos de precios:
Bloquear al comprar
Cuando comienza una sesión prepago, la liquidación de "inicio" bloquea el monto cobrado. Durante la duración de la sesión:
- La hora de fin de la sesión se fija basándose en los minutos comprados.
- Aunque el horario de precios cambie, la sesión continúa hasta que el tiempo bloqueado expire.
- La liquidación de fin usa el monto bloqueado de la liquidación de inicio.
Horario en vivo
El tiempo restante de la sesión se recalcula continuamente a medida que cambian las franjas de precios:
- Si la sesión entra en una franja más barata, el tiempo restante se extiende (el cliente obtiene más minutos por su dinero).
- Si la sesión entra en una franja más cara, el tiempo restante se contrae.
- La liquidación de fin refleja los precios reales aplicados durante toda la sesión.
Dígitos fraccionarios
La cantidad de decimales usados para la visualización de moneda es configurable (2--4 dígitos fraccionarios). Esto afecta cómo se muestran los montos en la interfaz pero no cambia los cálculos internos en unidades menores.
Ejemplo: Con 2 dígitos fraccionarios, $3.50 se muestra como "3.50". Con 3 dígitos fraccionarios, se mostraría como "3.500".
Ejemplos prácticos
Ejemplo 1: Sesión pospago simple
- Tarifa base: $3.00/hora (300 unidades menores)
- Horario: Franja estándar (multiplicador 1.0) todo el día
- Sesión: 10:00 AM a 11:30 AM (90 minutos)
- Tarifa de inicio: $0.50
Cálculo:
Segmento 1: (300 * 1.0 * 5400) / 3600 = 450 unidades menores ($4.50)
Total: max($4.50, $0.50) = $4.50
Ejemplo 2: Sesión que abarca dos franjas
- Tarifa base: $4.00/hora (400 unidades menores)
- Horario: Estándar (1.0) de 10:00 a 12:00, Happy Hour (0.5) de 12:00 a 14:00
- Sesión: 11:00 AM a 1:00 PM (120 minutos)
- Tarifa de inicio: $1.00
Cálculo:
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: Sesión con pausa
- Tarifa base: $2.00/hora (200 unidades menores)
- Horario: Franja estándar (multiplicador 1.0) todo el día
- Sesión: Inicio 10:00, Pausa 10:30, Reanudación 11:00, Fin 11:45
- Tarifa de inicio: $0.50
Cálculo:
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
- Gestión de sesiones: Conozca el ciclo de vida completo de las sesiones
- Configuración: Precios: Configure la tarifa base, redondeo y tarifa de inicio
- Configuración: Horario de precios: Configure la cuadrícula de horarios 7x24
- Métodos de pago: Configure métodos de pago con comisión y tarifas