Excursões - Custeio e Análise por IA

O que é

A aba Custeio é o centro financeiro do planejamento de cada excursão. Reúne, em uma única tela, os custos fixos (por viagem) e variáveis (por passageiro), a configuração de precificação, o preço sugerido calculado, a tabela de cenários por ocupação com break-even e a rentabilidade real gerada pelas vendas confirmadas.

O complemento dessa aba é a Análise Inteligente, que envia o cenário montado ao Gemini e devolve um parecer textual com projeção de lucro, sugestão de preço, alertas marcados com [!] (risco) e [+] (oportunidade), além de comparação com excursões anteriores da sua empresa. O usuário normalmente chega aqui logo depois de criar a excursão, antes de publicar o preço de venda - e volta sempre que o cenário muda (novo custo lançado, ajuste de capacidade, ocupação real diferente da prevista).

Como usar

1. Vá em Excursões no sidebar, abra a excursão desejada e clique na aba Custeio no topo da página de edição.
2. Em Custos Fixos, clique em Adicionar (botão azul à direita do total) para lançar despesas que não variam com o número de passageiros (fretamento, pedágio, estacionamento, seguro, etc.).
3. Em Custos Variáveis, clique em Adicionar (botão verde) para lançar despesas por passageiro (alimentação, ingresso, guia local). Use os campos de desconto para definir o valor proporcional de criança, idoso e bebê.
4. Em Configuração de Precificação (card roxo), preencha:
   • Overhead (%) - custos administrativos e imprevistos diluídos no preço.
   • Taxa financeira média (%) - calculada automaticamente pelo Mix Financeiro logo abaixo, mas pode ser sobrescrita manualmente.
   • Comissão vendedor (%) - percentual destinado ao vendedor ou afiliado.
   • Lucro desejado (%) - margem líquida-alvo da viagem.
5. O card roxo mostra em destaque o Preço sugerido, o Markup total e o Divisor usados no cálculo. Esse preço é gravado em precificacao.preco_sugerido e alimenta os demais cards.
6. No card Cenários de Ocupação, clique em Recalcular para regenerar a tabela com o preço atual. A linha de break-even fica destacada em amarelo com o selo BE; abaixo da tabela aparece o resumo "Break-even: X passageiros (Y%)".
7. No card Análise Inteligente (último da aba), clique em Analisar com IA. O sistema escolhe automaticamente entre dois modos:
   • Planejamento - para excursões com data futura. Foca em sugestão de preço, ocupação provável e alertas para o ciclo de vendas.
   • Pós-viagem - para excursões já realizadas. Avalia se o preço foi adequado, aponta custos que poderiam ser reduzidos e sugere melhorias para o próximo embarque ao mesmo destino.
8. O resultado fica em cache por 1 hora por excursão. Clicar em Atualizar no mesmo botão (label muda depois da primeira execução) força nova chamada ao Gemini e descarta o cache.

Casos especiais

Excursão sem capacidade definida

Se vagas_total for zero, o endpoint de cenários responde com "A excursão não possui capacidade definida." e nenhuma simulação é gerada. Defina a capacidade nas abas Geral ou Logística antes de voltar ao Custeio.

Sem precificação salva ainda

Os cenários só são montados quando existe precificacao.preco_sugerido maior que zero. Sem precificação, o card Cenários de Ocupação fica em estado vazio com a mensagem "Salve a configuração de preço e clique em 'Recalcular' para gerar os cenários."

Reverter um custo pago por engano

Na coluna Ações de qualquer tabela de custo, o ícone âmbar de seta-voltar (substitui o check verde quando o custo está pago) reverte o pagamento. O status volta para pendente ou, se a data de vencimento já passou, para vencido - e os campos valor_pago, data_pagamento e pago_por são limpos.

Excursão passada vs. futura

A escolha entre análise de planejamento e pós-viagem usa excursao.data_inicio->isPast(). Não há toggle manual: para forçar uma ou outra, ajuste a data da excursão na aba Geral.

Mix Financeiro com soma diferente de 100%

Dentro do simulador de preço há a seção colapsável Mix Financeiro. O total das participações precisa fechar em 100% - caso contrário, a linha "Total" fica vermelha com o aviso "(deve somar 100%)" e a taxa ponderada continua sendo calculada, mas pode distorcer o preço sugerido.

Erros comuns e como resolver

• "Defina um preço de venda ou configure a precificação primeiro." - Causa: tentou recalcular cenários sem preco_sugerido salvo nem preço enviado manualmente. Solução: salve a precificação no card roxo antes de clicar em Recalcular.
• "A excursão não possui capacidade definida." - Causa: vagas_total está zerado. Solução: preencha a capacidade na aba Geral ou cadastre os transportes na aba Logística para somar os assentos.
• "Serviço de IA não configurado." - Causa: a chave services.gemini.api_key não foi definida no ambiente da sua empresa. Solução: solicite ao suporte a ativação da chave Gemini para o empresa.
• "Não foi possível obter resposta da IA." - Causa: o Gemini não retornou conteúdo (quota, timeout de 60s ou rate limit do GeminiRateLimiter, 10 req/min globais). Solução: aguarde alguns segundos e clique em Atualizar novamente.
• "Este custo já está marcado como pago." / "Este custo não está marcado como pago." - Causa: ação repetida (clicou em pagar em um custo já pago, ou em desmarcar em um custo pendente). Solução: recarregue a aba para sincronizar os ícones com o status atual.
• "Custo não encontrado para esta excursão." - Causa: tentativa de editar/excluir/pagar um custo que pertence a outra excursão (URL manipulada). Solução: volte para a aba Custeio da excursão correta.

Onde encontrar

• URL: /admin/excursoes/{excursao}/custeio
• Caminho no menu: Excursões > [abrir a excursão] > aba Custeio
• Permissão necessária: editar as viagens
• Módulo necessário: nenhum (a aba é nativa do módulo de excursões; a Análise Inteligente exige apenas a chave Gemini configurada na plataforma)

Veja também

• Excursões - Financeiro da Excursão
• Excursões - Categorias e Preços
• Excursões - Criar Excursão
• Excursões - Gerenciar Passageiros