Preços de Sessão

O HandyCafe utiliza um motor de preços baseado em segmentos para calcular os custos das sessões na sua lan house ou centro de jogos. Em vez de aplicar uma tarifa fixa única para toda a sessão, o motor divide cada sessão em segmentos, cada um com seu próprio contexto de preços. Esta abordagem garante cobrança precisa mesmo quando as sessões cruzam múltiplas faixas de horário, alterações de preços, pausas ou desconexões.

Conceitos Básicos

Antes de entrar nos detalhes, estes são os termos essenciais:

Termo	Definição
Tarifa base por hora	O preço por hora antes de qualquer multiplicador ser aplicado. Definido em Configurações > Preços.
Faixa de preços	Um período nomeado com um multiplicador específico. Existem 8 faixas, cada uma com uma cor.
Multiplicador	Um fator aplicado à tarifa base. 1,0 = preço padrão, 0,5 = meia tarifa, 2,0 = tarifa dobrada.
Segmento	Um período contínuo dentro de uma sessão onde o contexto de preços (faixa, multiplicador, preço base) permanece inalterado.
Liquidação	O cálculo final que determina quanto o cliente deve quando uma sessão termina.

Tarifa Base por Hora

A tarifa base por hora é a base de todos os cálculos de preços. Ela é definida em Configurações > Preços e representa o preço padrão por hora de uso de PC.

Todos os cálculos internos utilizam unidades menores de moeda (por exemplo, centavos para BRL). Se sua tarifa base é R$ 3,00 por hora, o valor interno é 300. Isso elimina problemas de arredondamento com ponto flutuante.

Suporte a Moeda Dupla

O HandyCafe suporta uma moeda base e uma moeda local com taxa de câmbio (FX). Se você opera em um país onde os preços internacionais diferem dos locais:

Moeda base. A moeda usada para cálculos internos de preços.
Moeda local. A moeda exibida aos clientes e usada para pagamentos.
Taxa FX. O fator de conversão entre as moedas base e local.

Se ambas as moedas forem iguais, a taxa FX é tratada como 1,0 e não tem efeito.

Faixas de Preços

Existem 8 faixas de preços codificadas por cor, cada uma representando um nível de preços diferente:

Faixa	Cor	Uso Típico
Azul	Azul	Tarifa padrão
Laranja	Laranja	Sobretaxa noturna ou de fim de semana
Vermelho	Vermelho	Premium de horário de pico
Verde	Verde	Desconto fora de pico
Teal	Teal	Tarifa para estudantes ou membros
Cinza	Cinza	Preços de feriado ou especiais
Ciano	Ciano	Tarifa noturna
Esmeralda	Esmeralda	Tarifa promocional

Cada faixa possui três propriedades:

Nome. Um rótulo descritivo (por exemplo, "Horário de Pico" ou "Desconto Noturno").
Multiplicador. Um valor decimal que modifica a tarifa base. Valores comuns incluem 1,0 (padrão), 0,5 (meia tarifa), 1,5 (sobretaxa de 50%), 2,0 (tarifa dobrada). O multiplicador deve ser zero ou positivo.
Dados da agenda. Uma representação interna que define em quais horas de quais dias a faixa se aplica. Isso é gerenciado automaticamente pela grade de agenda.

Faixas podem ser habilitadas ou desabilitadas individualmente. Faixas desabilitadas são ignoradas pelo motor de preços.

A Grade de Agenda

A agenda de preços é uma matriz de 7 dias por 24 horas (168 blocos de uma hora no total). Cada bloco é atribuído a uma faixa de preços. A agenda determina qual multiplicador se aplica em qualquer momento.

A grade é configurada em Configurações > Agenda de Preços. Os dias vão de segunda a domingo e as horas vão de 00:00 a 23:00. Para atribuir uma faixa a um bloco de horário, selecione o bloco na grade e escolha a cor da faixa desejada.

Como o Motor Lê a Agenda

Internamente, cada bloco de hora mapeia para uma posição nos dados da agenda. O motor verifica os dados de cada faixa habilitada para determinar qual faixa está ativa em qualquer dia e hora.

Se nenhuma faixa estiver definida para uma hora específica, o motor utiliza a tarifa base com multiplicador 1,0.

Quando o recurso de agenda de preços está completamente desabilitado (em Configurações > Preços), todas as sessões usam a tarifa base com multiplicador 1,0 independente do horário.

Segmentos de Preços

Um segmento é um período contínuo dentro de uma sessão onde o contexto de preços não muda. O motor de preços cria um novo segmento sempre que qualquer um destes eventos de limite ocorre:

Limite	Gatilho
session_start	Uma nova sessão começa
session_stop	A sessão é encerrada
pause	O operador pausa a sessão
resume	O operador retoma uma sessão pausada
tick	O relógio cruza um limite de hora para uma faixa de preços diferente
disconnect	O PC cliente perde a conexão de rede
off-line	O cliente PC fica offline
load_recovery	O servidor reinicia e recupera uma sessão em andamento

Cada segmento registra:

Campo	Descrição
session_id	A sessão à qual este segmento pertence
segment_start	Timestamp Unix de quando o segmento começou
segment_end	Timestamp Unix de quando o segmento terminou (nulo se ainda aberto)
pricing_slot_id	O ID da faixa de preços ativa (por exemplo, "blue", "red" ou "base")
multiplier	O valor do multiplicador da faixa de preços
base_price_snapshot	A tarifa base por hora capturada no momento em que o segmento foi aberto
amount	O custo calculado para este segmento (definido quando o segmento fecha)
boundary_reason	Por que este segmento foi criado

Por Que Registrar o Preço Base?

O base_price_snapshot captura a tarifa base por hora no exato momento em que o segmento é aberto. Isso é essencial porque um administrador poderia alterar a tarifa base durante uma sessão. Ao registrar, cada segmento usa a tarifa vigente quando começou, garantindo cobrança justa e auditável.

Fórmula de Custo

O custo de um único segmento é calculado como:

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

Mais precisamente, o motor usa aritmética de inteiros escalados para evitar erros de ponto flutuante:

O multiplicador é escalado para um inteiro de ponto fixo (multiplicado por 1.000.000).
O cálculo é realizado inteiramente em inteiros de 128 bits.
A divisão com arredondamento para cima é usada. O resultado sempre arredonda para a próxima unidade menor.

Cálculo por Minutos

Se a opção "calcular por minutos" estiver habilitada em Configurações > Preços, a fórmula muda levemente:

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

Onde used_minutes = ceil(duration_seconds / 60). Isso significa que qualquer minuto parcial é contado como um minuto completo.

Cálculo do Total da Sessão

O custo total da sessão é calculado em três etapas:

Etapa 1: Somar Todos os Segmentos

raw_total = soma de todos os valores dos segmentos fechados + valor parcial do segmento aberto

O valor parcial do segmento aberto é calculado em tempo real usando a fórmula acima com o timestamp atual como fim do segmento.

Etapa 2: Aplicar Arredondamento

rounded_total = round_up(raw_total, rounding_step)

O arredondamento sempre vai para cima (teto) para proteger a receita. O passo de arredondamento é configurável em Configurações > Preços. Por exemplo, se o passo de arredondamento é 50 (representando R$ 0,50 em uma moeda com 2 casas decimais), um total bruto de R$ 3,27 arredonda para R$ 3,50.

Etapa 3: Aplicar Mínimo da Taxa de Início

final_total = max(rounded_total, startup_fee)

A taxa de início é a cobrança mínima para qualquer sessão, independente da duração. Se o total arredondado for menor que a taxa de início, a taxa de início é cobrada.

Liquidação

Liquidação é o processo de finalizar a cobrança de uma sessão. Existem dois estágios de liquidação:

Liquidação de Início (Somente Pré-pago)

Quando uma sessão pré-paga começa, um registro de liquidação "início" é criado. Ele captura:

Custo calculado. O custo calculado pelo sistema para o tempo comprado.
Valor cobrado. O valor que o cliente efetivamente pagou (normalmente igual ao custo calculado).

Para o modo pré-pago "Travar na Compra", este valor travado determina o custo da sessão independente de alterações de preços durante a sessão.

Liquidação de Encerramento

Quando qualquer sessão (pré-paga ou pós-paga) é encerrada, um registro de liquidação "encerramento" é criado:

Campo	Descrição
Custo calculado	O total calculado pelo sistema de todos os segmentos de preços
Valor cobrado	O valor efetivamente cobrado (padrão é o custo calculado)
Valor ajustado manualmente	Se o operador ajustou manualmente o preço, o custo original calculado é preservado aqui
Taxa de comissão	Taxa de comissão do método de pagamento (como percentual)
commission_fee	O valor da comissão calculada
fixed_fee	Taxa fixa do método de pagamento
computed_timeline_snapshot	Um registro JSON de cada segmento de preços da sessão

O snapshot da timeline fornece uma trilha de auditoria completa mostrando exatamente como o custo foi calculado, segmento por segmento.

Taxas de Método de Pagamento

Cada método de pagamento pode ter dois tipos de taxas:

Comissão (Pontos Base)

A taxa de comissão é expressa como um percentual. A taxa de comissão é calculada aplicando esta taxa ao valor cobrado.

Exemplo: Se o valor cobrado é R$ 10,00 (1000 unidades menores) e o método de pagamento tem uma taxa de comissão de 2,5%, a taxa de comissão é R$ 0,25 (25 unidades menores).

Taxa Fixa

Uma taxa fixa descontada por transação, independente do valor. Por exemplo, uma taxa de processamento de cartão de crédito de R$ 0,30.

Ambas as taxas são informativas. Representam o custo para o negócio de aceitar aquele método de pagamento. São registradas na liquidação mas não são adicionadas à conta do cliente.

IVA (Imposto sobre Valor Agregado)

O IVA é configurado como um percentual (0-100%) em Configurações > Preços. Ele é aplicado sobre o valor calculado da sessão:

IVA = valor cobrado x (taxa de IVA / 100)

O valor do IVA é exibido separadamente na caixa de diálogo de pagamento para que o operador possa ver o detalhamento do imposto.

Modos de Preços Pré-pagos

Conforme descrito em Gestão de Sessões, sessões pré-pagas suportam dois modos de preços:

Travar na Compra

Quando uma sessão pré-paga começa, a liquidação de "início" trava o valor cobrado. Durante a duração da sessão:

O horário de término da sessão é fixo com base nos minutos comprados.
Mesmo que a agenda de preços mude, a sessão continua até o tempo travado expirar.
A liquidação de encerramento usa o valor travado da liquidação de início.

Agenda ao Vivo

O tempo restante da sessão é recalculado continuamente conforme as faixas de preços mudam:

Se a sessão entra em uma faixa mais barata, o tempo restante se estende (o cliente ganha mais minutos pelo dinheiro).
Se a sessão entra em uma faixa mais cara, o tempo restante se contrai.
A liquidação de encerramento reflete os preços reais aplicados ao longo da sessão.

Casas Decimais

O número de casas decimais usadas na exibição de moedas é configurável (2-4 casas decimais). Isso afeta como os valores são exibidos na interface mas não altera os cálculos internos em unidades menores.

Exemplo: Com 2 casas decimais, R$ 3,50 é exibido como "3,50". Com 3 casas decimais, seria exibido como "3,500".

Exemplos Práticos

Exemplo 1: Sessão Pós-paga Simples

Tarifa base: R$ 3,00/hora (300 unidades menores)
Agenda: Faixa padrão (multiplicador 1,0) o dia todo
Sessão: 10:00 a 11:30 (90 minutos)
Taxa de início: R$ 0,50

Cálculo:

Segmento 1: (300 * 1,0 * 5400) / 3600 = 450 unidades menores (R$ 4,50)
Total: max(R$ 4,50, R$ 0,50) = R$ 4,50

Exemplo 2: Sessão Cruzando Duas Faixas

Tarifa base: R$ 4,00/hora (400 unidades menores)
Agenda: Padrão (1,0) das 10:00-12:00, Happy Hour (0,5) das 12:00-14:00
Sessão: 11:00 a 13:00 (120 minutos)
Taxa de início: R$ 1,00

Cálculo:

Segmento 1 (11:00-12:00, padrao): (400 * 1,0 * 3600) / 3600 = 400 (R$ 4,00)
Segmento 2 (12:00-13:00, happy hour): (400 * 0,5 * 3600) / 3600 = 200 (R$ 2,00)
Total: R$ 4,00 + R$ 2,00 = R$ 6,00
Final: max(R$ 6,00, R$ 1,00) = R$ 6,00

Exemplo 3: Sessão com Pausa

Tarifa base: R$ 2,00/hora (200 unidades menores)
Agenda: Faixa padrão (multiplicador 1,0) o dia todo
Sessão: Início 10:00, Pausa 10:30, Retomada 11:00, Encerramento 11:45
Taxa de início: R$ 0,50

Cálculo:

Segmento 1 (10:00-10:30, ativo): (200 * 1,0 * 1800) / 3600 = 100 (R$ 1,00)
Periodo de pausa (10:30-11:00): sem cobranca
Segmento 2 (11:00-11:45, ativo): (200 * 1,0 * 2700) / 3600 = 150 (R$ 1,50)
Total: R$ 1,00 + R$ 1,50 = R$ 2,50
Final: max(R$ 2,50, R$ 0,50) = R$ 2,50

Próximos Passos

Gestão de Sessões: Conheça o ciclo de vida completo das sessões
Configurações: Preços: Configure a tarifa base, arredondamento e taxa de início
Configurações: Agenda de Preços: Monte a grade de agenda 7x24
Métodos de Pagamento: Configure métodos de pagamento com comissão e taxas