Equipamentos - Listagem de Estoques

O que é

A página Estoque de Equipamentos é o cadastro central do inventário físico compartilhado da operação de passeios. Cada linha representa um pool (recipiente lógico) de um recurso limitado: caiaques individuais, pranchas de SUP, bicicletas elétricas, quadriciclos, kits de mergulho, rádios, GPS, kits de primeiros socorros, microfones, veículos próprios, ingressos pré-comprados ou até vagas em passeios guiados. O ponto-chave é que o mesmo pool pode ser referenciado por várias categorias de várias experiências, garantindo que o sistema não venda mais unidades do que existem fisicamente.

O usuário chega aqui normalmente em dois momentos: ao montar a operação pela primeira vez, antes de cadastrar categorias e horários das experiências, ou quando precisa ajustar a quantidade (compra de novos equipamentos, perda, manutenção). Quando uma categoria de experiência está vinculada a um pool, o controle de disponibilidade considera todos os horários sobrepostos do mesmo dia: se um cliente aluga uma prancha das 06h às 12h, a mesma prancha fica indisponível também para os horários 06h–09h e 09h–12h que compartilham aquele pool.

Como usar

1. Vá em Módulos > Passeios / Experiências no sidebar e acesse a URL /admin/passeios/estoques (a página não tem item de menu próprio - chega-se a ela a partir do Dashboard de Experiências ou diretamente pela URL).
2. Leia o cartão azul informativo no topo. Ele explica a regra de sobreposição de horários no mesmo dia.
3. A tabela principal lista todos os estoques cadastrados com seis colunas:
   • Nome - rótulo do recurso (e a primeira linha das observações, truncada em 80 caracteres, se houver).
   • Tipo - identificador interno opcional (ex: caiaque_individual).
   • Quantidade - total físico disponível.
   • Vinculado - quantas categorias de experiências apontam para esse pool.
   • Status - Ativo (verde) ou Inativo (cinza).
   • Ações - links Editar e Excluir.
4. Para cadastrar um novo pool, clique em Novo Estoque (botão teal no canto superior direito do cabeçalho).
5. Preencha o formulário:
   • Nome (obrigatório, até 100 caracteres) - use um rótulo que a equipe reconheça, como "Caiaques individuais", "Pranchas de SUP", "Bicicletas elétricas", "Rádios HT", "Kits de primeiros socorros".
   • Quantidade total (obrigatório, 0 a 99999) - número de unidades físicas que você realmente possui hoje.
   • Tipo (opcional, até 50 caracteres) - identificador livre para organização interna; útil para diferenciar variantes do mesmo recurso.
   • Observações (opcional, até 1000 caracteres) - anotações sobre manutenção, fornecedor, garantia, etc.
   • Estoque ativo (checkbox marcado por padrão) - estoques inativos não são ofertados em novas reservas, mas o histórico das vendas anteriores é preservado.
6. Confirme em Cadastrar estoque (na criação) ou Salvar alterações (na edição). O sistema redireciona para a listagem com um toast de sucesso informando o nome do estoque criado ou atualizado.

Casos especiais

Recursos compartilhados entre experiências

O grande motivo de existir um pool é permitir que duas experiências diferentes consumam o mesmo equipamento físico. Exemplo: a experiência "Passeio de Caiaque 2h" e a experiência "Caiaque + SUP combo" podem apontar para o mesmo pool Caiaques individuais (10 unidades). Se a primeira vende 8 lugares para sábado às 09h, a segunda só conseguirá vender 2 lugares para qualquer horário do sábado que se sobreponha àquele intervalo.

Recursos não-equipamento (vagas, ingressos, veículos)

Apesar do nome técnico ser Equipamento Pool, a tela aceita qualquer recurso limitado da operação: vagas em passeios guiados (quando o limite é o guia, não o transporte), ingressos pré-comprados de atrações terceiras, lugares em vans próprias, acomodações. Use o campo Nome para deixar claro o que o pool representa.

Desativar em vez de excluir

Quando um equipamento está temporariamente fora de operação (manutenção, sazonalidade) mas pode voltar, desmarque o checkbox Estoque ativo em vez de excluir. O pool deixa de ser ofertado em novas reservas, mas todas as vendas históricas continuam apontando para ele corretamente.

Estoque vinculado não pode ser excluído

A exclusão é bloqueada quando o pool está vinculado a qualquer categoria de experiência. A coluna Vinculado mostra o número de categorias atuais. Antes de excluir, abra cada experiência afetada e troque o pool da categoria por outro (ou remova a vinculação).

Erros comuns e como resolver

• "Este estoque está vinculado a categorias. Desvincule antes de excluir." - Causa: o pool ainda é referenciado por uma ou mais categorias de experiências (coluna Vinculado > 0). Solução: abra a experiência correspondente, edite a categoria que usa este estoque e aponte para outro pool, ou simplesmente desative o estoque em vez de excluir.
• "The nome field is required." - Causa: o campo Nome ficou em branco no formulário. Solução: informe um rótulo descritivo (até 100 caracteres).
• "The quantidade total field must be at least 0." / "may not be greater than 99999." - Causa: valor de quantidade fora do intervalo permitido. Solução: ajuste para um inteiro entre 0 e 99999. Use 0 para registrar o pool sem unidades ainda disponíveis.
• Disponibilidade aparenta estar errada no site público - Causa: a categoria da experiência ainda não foi vinculada ao pool, ou o pool foi marcado como inativo. Solução: confirme na coluna Vinculado da listagem que o pool tem ao menos uma categoria apontando, e verifique se o status está Ativo.

Onde encontrar

• URL: /admin/passeios/estoques
• Caminho no menu: Módulos > Passeios / Experiências (acesso pelo Dashboard de Experiências ou pela URL direta - não há item dedicado no sidebar)
• Permissão necessária: editar as experiências
• Módulo necessário: Passeios e Experiências (passeios-experiencias)

Veja também

• Experiências - Dashboard
• Passeios - Configurações do Módulo
• Criar Experiência
• Editar Experiência