Passaportes

O passaporte é o tipo de ingresso que o cliente escolhe e compra: “Adulto”, “Infantil”, “VIP”, “Pacote 3 dias”. Ele fica pendurado em uma atração e carrega o preço base e as flags que definem como a venda se comporta.

O que é e para que serve

A atração é a “coisa” (Piscinas); o passaporte é a categoria vendável dela (Adulto a R$ 50, Infantil a R$ 30). O preço final quase nunca é o preço base: ele vem das regras de preço, resolvidas por dia e por antecedência.

Quem pode acessar

passports.view — navegar pelo módulo (inclusive pelas telas de regras de preço).
passports.manage — criar, editar e arquivar passaportes.
passports.manage_rules sensível — criar e editar regras de preço.

Diferença conhecida de granularidade

A navegação até a subárea de regras de preço hoje exige apenas passports.view; quem impede a gravação de uma regra é a permissão passports.manage_rules, validada no servidor. Ou seja: um usuário pode abrir a tela de regras e ver os valores sem poder alterá-los.

Como acessar

Menu lateral → Passaportes. O submenu Regras de preço leva ao motor de preços.

Visão geral da tela

A listagem tem busca por nome e descrição, filtros avançados, seletor de colunas, listas salvas e um botão para exibir os arquivados, com ação de restaurar. As listas de sistema são: Todos, Ativos, Inativos, Excluídos, Geram voucher, Consomem capacidade e Pacotes.

Abas da tela de detalhe

Resumo — atração, status, preço, flags e, no caso de pacote, as datas incluídas.
Detalhes — o formulário de edição.
Relacionados — contagem de vouchers e vendas.
Auditoria — histórico de alterações.

As três decisões de um passaporte

Configuração	Padrão	O que significa
Gera voucher	Ligada	Ao vender, emite um ingresso com código e QR. Desligada, a venda acontece sem emitir ingresso.
Consome capacidade	Ligada	Cada unidade vendida ocupa uma vaga da ocorrência. Desligada, o item não afeta a lotação — útil para categorias isentas.
Tipo de consumo	Padrão	Padrão vale para uma ocorrência. Pacote vincula várias ocorrências e gera um voucher para cada uma.

Pacotes

Um passaporte do tipo pacote (por exemplo “Passaporte 3 dias de Rodeio”) recebe uma lista de ocorrências. Ao vender uma unidade, o sistema emite um voucher por data incluída — cada um com código próprio e cada um consumindo a capacidade da sua ocorrência.

Divergência entre as duas telas da loja

A página de uma atração específica é consciente de pacotes: ela separa pacotes dos ingressos comuns e mostra um cartão com as datas incluídas. Já o fluxo em que o cliente escolhe primeiro a data (usado também pelo PDV) exibe o pacote como um ingresso comum daquela data. É um ponto de atenção conhecido — ao vender pacote pelo balcão, confira as datas incluídas com o cliente.

Regras de negócio

Nome único por atração, sem diferenciar maiúsculas de minúsculas.
A atração precisa aceitar passaportes — caso contrário a criação é recusada (attraction_no_passport).
Sem preço calculável, o passaporte não vende: ele aparece como “Preço indisponível” na loja.
Para pacote, o preço é obrigatório na prática — o formulário rotula o campo como “Preço do pacote” e avisa.
Preço negativo é recusado.
Arquivar avisa, mas não bloqueia, mesmo havendo vouchers vendidos. Foi uma decisão de produto — diferente do comportamento de atrações e ocorrências.
Nunca há exclusão definitiva: vouchers e itens de venda continuam apontando para o passaporte.

Status

	Inativo	Arquivado
Efeito	Pausa a venda; continua visível no painel	Sai da listagem ativa
Reversível	Sim	Sim (restaurar)
Vouchers vendidos	Continuam válidos	Continuam válidos

Passo a passo: criar os ingressos de uma atração

Confirme que a atração aceita passaportes (flag no cadastro da atração).
Crie o passaporte “Adulto”: nome, atração, status ativo, preço base, gera voucher ligado, consome capacidade ligado, tipo padrão.
Repita para as demais categorias (Infantil, Meia, Idoso), ajustando o preço base.
Se alguma categoria não ocupa vaga (por exemplo, criança de colo), desligue consome capacidade.
Cadastre as regras de preço para o dia da semana, o período de alta temporada e o preço antecipado.
Confira no calendário de preços se o valor de cada dia é o esperado.

Dependências com outros módulos

Atrações — dona do passaporte; a flag de aceitar passaportes é portão de criação.
Ocorrências — fornecem a data e a capacidade que o passaporte consome.
Regras de preço — penduradas no passaporte, resolvem o valor.
Vouchers — um por unidade vendida, quando “gera voucher” está ligado.
Loja e PDV — exibem apenas passaportes ativos, da atração selecionada e com preço calculável.

Erros e dúvidas comuns

Mensagem	Causa	Solução
Nome é obrigatório	Campo em branco	Preencher o nome
Selecione uma atração	Atração não escolhida	Escolher a atração dona
Já existe um passaporte com este nome nesta atração.	Nome duplicado	Renomear
Preço inválido	Valor negativo ou não numérico	Corrigir o valor
`attraction_no_passport`	A atração não aceita passaportes	Ligar a flag na atração
“Preço indisponível” na loja	Sem preço base e sem regra aplicável	Definir preço base ou criar regra

Boas práticas

Use nomes que o cliente entenda — eles aparecem na loja e no voucher.
Mantenha um preço base mesmo quando houver regras: ele é a rede de segurança contra “preço indisponível”.
Revise as flags antes de publicar: consome capacidade errado distorce a lotação do dia.
Ao criar pacote, confira se todas as datas do período estão vinculadas.