Precos de Sessao
O HandyCafe utiliza um motor de precos baseado em segmentos para calcular os custos das sessoes na sua lan house ou centro de jogos. Em vez de aplicar uma tarifa fixa unica para toda a sessao, o motor divide cada sessao em segmentos, cada um com seu proprio contexto de precos. Esta abordagem garante cobranca precisa mesmo quando as sessoes cruzam multiplas faixas de horario, alteracoes de precos, pausas ou desconexoes.
Conceitos Basicos
Antes de entrar nos detalhes, estes sao os termos essenciais:
| Termo | Definicao |
|---|---|
| Tarifa base por hora | O preco por hora antes de qualquer multiplicador ser aplicado. Definido em Configuracoes > Precos. |
| Faixa de precos | Um periodo nomeado com um multiplicador especifico. Existem 8 faixas, cada uma com uma cor. |
| Multiplicador | Um fator aplicado a tarifa base. 1,0 = preco padrao, 0,5 = meia tarifa, 2,0 = tarifa dobrada. |
| Segmento | Um periodo continuo dentro de uma sessao onde o contexto de precos (faixa, multiplicador, preco base) permanece inalterado. |
| Liquidacao | O calculo final que determina quanto o cliente deve quando uma sessao termina. |
Tarifa Base por Hora
A tarifa base por hora e a base de todos os calculos de precos. Ela e definida em Configuracoes > Precos e representa o preco padrao por hora de uso de PC.
Todos os calculos internos utilizam unidades menores de moeda (por exemplo, centavos para BRL). Se sua tarifa base e R$ 3,00 por hora, o valor interno e 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 cambio (FX). Se voce opera em um pais onde os precos internacionais diferem dos locais:
- Moeda base. A moeda usada para calculos internos de precos.
- Moeda local. A moeda exibida aos clientes e usada para pagamentos.
- Taxa FX. O fator de conversao entre as moedas base e local.
Se ambas as moedas forem iguais, a taxa FX e tratada como 1,0 e nao tem efeito.
Faixas de Precos
Existem 8 faixas de precos codificadas por cor, cada uma representando um nivel de precos diferente:
| Faixa | Cor | Uso Tipico |
|---|---|---|
| Azul | Azul | Tarifa padrao |
| Laranja | Laranja | Sobretaxa noturna ou de fim de semana |
| Vermelho | Vermelho | Premium de horario de pico |
| Verde | Verde | Desconto fora de pico |
| Teal | Teal | Tarifa para estudantes ou membros |
| Cinza | Cinza | Precos de feriado ou especiais |
| Ciano | Ciano | Tarifa noturna |
| Esmeralda | Esmeralda | Tarifa promocional |
Cada faixa possui tres propriedades:
- Nome. Um rotulo descritivo (por exemplo, "Horario de Pico" ou "Desconto Noturno").
- Multiplicador. Um valor decimal que modifica a tarifa base. Valores comuns incluem 1,0 (padrao), 0,5 (meia tarifa), 1,5 (sobretaxa de 50%), 2,0 (tarifa dobrada). O multiplicador deve ser zero ou positivo.
- Dados da agenda. Uma representacao interna que define em quais horas de quais dias a faixa se aplica. Isso e gerenciado automaticamente pela grade de agenda.
Faixas podem ser habilitadas ou desabilitadas individualmente. Faixas desabilitadas sao ignoradas pelo motor de precos.
A Grade de Agenda
A agenda de precos e uma matriz de 7 dias por 24 horas (168 blocos de uma hora no total). Cada bloco e atribuido a uma faixa de precos. A agenda determina qual multiplicador se aplica em qualquer momento.
A grade e configurada em Configuracoes > Agenda de Precos. Os dias vao de segunda a domingo e as horas vao de 00:00 a 23:00. Para atribuir uma faixa a um bloco de horario, selecione o bloco na grade e escolha a cor da faixa desejada.
Como o Motor Le a Agenda
Internamente, cada bloco de hora mapeia para uma posicao nos dados da agenda. O motor verifica os dados de cada faixa habilitada para determinar qual faixa esta ativa em qualquer dia e hora.
Se nenhuma faixa estiver definida para uma hora especifica, o motor utiliza a tarifa base com multiplicador 1,0.
Quando o recurso de agenda de precos esta completamente desabilitado (em Configuracoes > Precos), todas as sessoes usam a tarifa base com multiplicador 1,0 independente do horario.
Segmentos de Precos
Um segmento e um periodo continuo dentro de uma sessao onde o contexto de precos nao muda. O motor de precos cria um novo segmento sempre que qualquer um destes eventos de limite ocorre:
| Limite | Gatilho |
|---|---|
| session_start | Uma nova sessao comeca |
| session_stop | A sessao e encerrada |
| pause | O operador pausa a sessao |
| resume | O operador retoma uma sessao pausada |
| tick | O relogio cruza um limite de hora para uma faixa de precos diferente |
| disconnect | O PC cliente perde a conexao de rede |
| off-line | O cliente PC fica offline |
| load_recovery | O servidor reinicia e recupera uma sessao em andamento |
Cada segmento registra:
| Campo | Descricao |
|---|---|
| session_id | A sessao a qual este segmento pertence |
| segment_start | Timestamp Unix de quando o segmento comecou |
| segment_end | Timestamp Unix de quando o segmento terminou (nulo se ainda aberto) |
| pricing_slot_id | O ID da faixa de precos ativa (por exemplo, "blue", "red" ou "base") |
| multiplier | O valor do multiplicador da faixa de precos |
| 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 Preco Base?
O base_price_snapshot captura a tarifa base por hora no exato momento em que o segmento e aberto. Isso e essencial porque um administrador poderia alterar a tarifa base durante uma sessao. Ao registrar, cada segmento usa a tarifa vigente quando comecou, garantindo cobranca justa e auditavel.
Formula de Custo
O custo de um unico segmento e calculado como:
amount = ceil( (base_price_snapshot * multiplier * duration_seconds) / 3600 )
Mais precisamente, o motor usa aritmetica de inteiros escalados para evitar erros de ponto flutuante:
- O multiplicador e escalado para um inteiro de ponto fixo (multiplicado por 1.000.000).
- O calculo e realizado inteiramente em inteiros de 128 bits.
- A divisao com arredondamento para cima e usada. O resultado sempre arredonda para a proxima unidade menor.
Calculo por Minutos
Se a opcao "calcular por minutos" estiver habilitada em Configuracoes > Precos, a formula muda levemente:
amount = ceil( (base_price_snapshot * multiplier * used_minutes) / 60 )
Onde used_minutes = ceil(duration_seconds / 60). Isso significa que qualquer minuto parcial e contado como um minuto completo.
Calculo do Total da Sessao
O custo total da sessao e calculado em tres 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 e calculado em tempo real usando a formula 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 e configuravel em Configuracoes > Precos. Por exemplo, se o passo de arredondamento e 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 Minimo da Taxa de Inicio
final_total = max(rounded_total, startup_fee)
A taxa de inicio e a cobranca minima para qualquer sessao, independente da duracao. Se o total arredondado for menor que a taxa de inicio, a taxa de inicio e cobrada.
Liquidacao
Liquidacao e o processo de finalizar a cobranca de uma sessao. Existem dois estagios de liquidacao:
Liquidacao de Inicio (Somente Pre-pago)
Quando uma sessao pre-paga comeca, um registro de liquidacao "inicio" e 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 pre-pago "Travar na Compra", este valor travado determina o custo da sessao independente de alteracoes de precos durante a sessao.
Liquidacao de Encerramento
Quando qualquer sessao (pre-paga ou pos-paga) e encerrada, um registro de liquidacao "encerramento" e criado:
| Campo | Descricao |
|---|---|
| Custo calculado | O total calculado pelo sistema de todos os segmentos de precos |
| Valor cobrado | O valor efetivamente cobrado (padrao e o custo calculado) |
| Valor ajustado manualmente | Se o operador ajustou manualmente o preco, o custo original calculado e preservado aqui |
| Taxa de comissao | Taxa de comissao do metodo de pagamento (como percentual) |
| commission_fee | O valor da comissao calculada |
| fixed_fee | Taxa fixa do metodo de pagamento |
| computed_timeline_snapshot | Um registro JSON de cada segmento de precos da sessao |
O snapshot da timeline fornece uma trilha de auditoria completa mostrando exatamente como o custo foi calculado, segmento por segmento.
Taxas de Metodo de Pagamento
Cada metodo de pagamento pode ter dois tipos de taxas:
Comissao (Pontos Base)
A taxa de comissao e expressa como um percentual. A taxa de comissao e calculada aplicando esta taxa ao valor cobrado.
Exemplo: Se o valor cobrado e R$ 10,00 (1000 unidades menores) e o metodo de pagamento tem uma taxa de comissao de 2,5%, a taxa de comissao e R$ 0,25 (25 unidades menores).
Taxa Fixa
Uma taxa fixa descontada por transacao, independente do valor. Por exemplo, uma taxa de processamento de cartao de credito de R$ 0,30.
Ambas as taxas sao informativas. Representam o custo para o negocio de aceitar aquele metodo de pagamento. Sao registradas na liquidacao mas nao sao adicionadas a conta do cliente.
IVA (Imposto sobre Valor Agregado)
O IVA e configurado como um percentual (0-100%) em Configuracoes > Precos. Ele e aplicado sobre o valor calculado da sessao:
IVA = valor cobrado x (taxa de IVA / 100)
O valor do IVA e exibido separadamente na caixa de dialogo de pagamento para que o operador possa ver o detalhamento do imposto.
Modos de Precos Pre-pagos
Conforme descrito em Gestao de Sessoes, sessoes pre-pagas suportam dois modos de precos:
Travar na Compra
Quando uma sessao pre-paga comeca, a liquidacao de "inicio" trava o valor cobrado. Durante a duracao da sessao:
- O horario de termino da sessao e fixo com base nos minutos comprados.
- Mesmo que a agenda de precos mude, a sessao continua ate o tempo travado expirar.
- A liquidacao de encerramento usa o valor travado da liquidacao de inicio.
Agenda ao Vivo
O tempo restante da sessao e recalculado continuamente conforme as faixas de precos mudam:
- Se a sessao entra em uma faixa mais barata, o tempo restante se estende (o cliente ganha mais minutos pelo dinheiro).
- Se a sessao entra em uma faixa mais cara, o tempo restante se contrai.
- A liquidacao de encerramento reflete os precos reais aplicados ao longo da sessao.
Casas Decimais
O numero de casas decimais usadas na exibicao de moedas e configuravel (2-4 casas decimais). Isso afeta como os valores sao exibidos na interface mas nao altera os calculos internos em unidades menores.
Exemplo: Com 2 casas decimais, R$ 3,50 e exibido como "3,50". Com 3 casas decimais, seria exibido como "3,500".
Exemplos Praticos
Exemplo 1: Sessao Pos-paga Simples
- Tarifa base: R$ 3,00/hora (300 unidades menores)
- Agenda: Faixa padrao (multiplicador 1,0) o dia todo
- Sessao: 10:00 a 11:30 (90 minutos)
- Taxa de inicio: R$ 0,50
Calculo:
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: Sessao Cruzando Duas Faixas
- Tarifa base: R$ 4,00/hora (400 unidades menores)
- Agenda: Padrao (1,0) das 10:00-12:00, Happy Hour (0,5) das 12:00-14:00
- Sessao: 11:00 a 13:00 (120 minutos)
- Taxa de inicio: R$ 1,00
Calculo:
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: Sessao com Pausa
- Tarifa base: R$ 2,00/hora (200 unidades menores)
- Agenda: Faixa padrao (multiplicador 1,0) o dia todo
- Sessao: Inicio 10:00, Pausa 10:30, Retomada 11:00, Encerramento 11:45
- Taxa de inicio: R$ 0,50
Calculo:
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
Proximos Passos
- Gestao de Sessoes: Conheca o ciclo de vida completo das sessoes
- Configuracoes: Precos: Configure a tarifa base, arredondamento e taxa de inicio
- Configuracoes: Agenda de Precos: Monte a grade de agenda 7x24
- Metodos de Pagamento: Configure metodos de pagamento com comissao e taxas