Excursões - Criar com IA

O que é

"Criar com IA" é um assistente em estágio Beta disponível na listagem de Excursões. Ele usa o modelo gemini-2.5-flash do Google Gemini para ler o conteúdo de uma imagem de banner/flyer e/ou um texto descritivo fornecido pelo usuário e devolver os principais campos de uma excursão já preenchidos: nome, datas, horários, local, cidade, estado, descrição, inclusos, observações, categorias de preço e pontos de embarque.

O assistente não substitui o cadastro completo: a excursão é criada sempre como rascunho e o usuário é redirecionado para a tela de edição para complementar transporte, fotos, políticas e demais detalhes operacionais.

O botão só aparece quando a chave da API do Gemini está configurada no ambiente e o usuário tem permissão de criar as viagens. As rotas usadas pelo modal são POST /admin/excursoes/ai-wizard/extract (extração) e POST /admin/excursoes/ai-wizard/store (criação do rascunho).

Como usar

1. Vá em Excursões no menu lateral.
2. No canto superior direito, clique no botão violeta Criar com IA (com selo Beta). O modal abre no passo 1.
3. Forneça a entrada para a IA (pelo menos uma das opções):
   • Imagem do banner/flyer (opcional) - Clique na área tracejada e selecione um arquivo JPG, PNG ou WebP de até 10 MB.
   • Descrição do evento (opcional) - Cole ou digite um texto livre com no máximo 5.000 caracteres. Quanto mais detalhes (destino, datas, horários, valores, pontos de embarque), melhor a extração.
4. Clique em Analisar com IA. O modal vai para o passo 2 e exibe um spinner enquanto o Gemini processa (geralmente alguns segundos).
5. No passo 3, revise os campos retornados. O cabeçalho mostra a Confiança da extração (Alta, Média ou Baixa). Apenas os campos que a IA conseguiu identificar aparecem, com exceção do Nome da excursão, que é sempre obrigatório e fica sempre visível:
   • Nome da excursão - Obrigatório.
   • Data ida / Data volta / Hora saída / Hora retorno - Edite livremente se a IA errar.
   • Local / Cidade / Estado - Estado tem no máximo 2 letras.
   • Descrição / O que está incluso / Observações - Texto longo editável.
   • Categorias de preço identificadas - Lista de pares descrição + valor (R$). Use o "+" para adicionar e o "X" para remover linhas.
   • Pontos de embarque identificados - Lista de strings. Use o "+" para adicionar e o "X" para remover linhas.
6. (Opcional) Clique em Voltar para refazer a entrada e gerar de novo.
7. Quando estiver satisfeito, clique em Criar como Rascunho. A excursão é criada com status = rascunho, categorias e embarques são gerados a partir do que a IA identificou e o sistema redireciona para a tela de edição da nova excursão.

Casos especiais

Apenas texto, sem imagem

Funciona normalmente. A IA usa só o texto livre. É útil quando o usuário tem só uma descrição textual do evento.

Apenas imagem, sem texto

A IA processa só a imagem (banner/flyer). O modal aceita JPG, PNG ou WebP com até 10 MB.

Nenhuma data identificada

Se a IA não retornar data_inicio, o controller usa o dia atual como data_inicio (e como data_fim) para satisfazer a obrigatoriedade no banco. Ajuste manualmente na tela de edição.

Nenhuma categoria de preço identificada

Se precos_identificados estiver vazio, o sistema cria automaticamente uma única categoria chamada Adulto, sem preço definido.

empresa com módulo "Contratos Digitais" ativo

Ao criar o rascunho, o sistema aplica os defaults da sua empresa: exigir_contrato herda de contrato_exigir_padrao e contrato_template_id herda de contrato_template_padrao_id.

Rate limit

O extrator aplica limite de 50 extrações por hora por usuário. Ao estourar, a IA retorna a mensagem "Limite de extrações atingido. Tente novamente em alguns minutos."

Erros comuns e como resolver

• "Envie uma imagem ou digite uma descrição." - Causa: o passo 1 foi enviado sem imagem e sem texto. Solução: anexe um arquivo ou preencha o campo de descrição antes de clicar em Analisar com IA.
• "IA não está configurada neste ambiente." - Causa: a chave da API do Gemini (services.gemini.api_key) não está definida. Solução: o botão Criar com IA nem deve aparecer nesse caso; se aparecer, abra um chamado para o time de infraestrutura configurar a chave.
• "Imagem muito grande. Máximo 10MB." - Causa: o arquivo excede o limite. Solução: reduza a imagem (compressão ou recorte) e envie de novo.
• "Erro na API da IA. Tente novamente." - Causa: o Gemini devolveu status HTTP de erro. Solução: aguardar alguns segundos e tentar novamente; se persistir, conferir cota da chave.
• "IA não retornou resposta válida." / "Resposta da IA não pôde ser processada." - Causa: o Gemini não devolveu JSON parseável. Solução: refinar o texto da descrição (ser mais específico), tentar outra imagem ou clicar em Voltar e gerar de novo.
• "Limite de extrações atingido. Tente novamente em alguns minutos."
  • Causa: rate limit de 50 extrações por hora por usuário. Solução: aguardar o reset (1 hora) ou pedir para outro usuário gerar.
• "O nome é obrigatório." - Causa: campo Nome da excursão ficou vazio no passo 3. Solução: digitar o nome manualmente antes de clicar em Criar como Rascunho.
• "Erro de conexão. Tente novamente." - Causa: falha de rede entre o navegador e o backend. Solução: conferir conexão e clicar de novo.

Onde encontrar

• URL: /admin/excursoes (o assistente é um modal acionado na própria listagem)
• Caminho no menu: Excursões > botão Criar com IA no canto superior direito
• Permissão necessária: criar as viagens
• Módulo necessário: nenhum (depende apenas da chave do Gemini configurada no ambiente)

Veja também

• Excursões - Criar Excursão
• Excursões - Visão Geral