Gestão de Passageiros - Vanguru

Visão Geral

O sistema de gestão de passageiros é o núcleo do Vanguru, permitindo o cadastro completo e organizado de todos os passageiros, seus responsáveis e informações relacionadas.

Funcionalidades Principais

Cadastro de Passageiros

Informações Básicas

  • Nome Completo: Identificação do passageiro
  • Data de Nascimento: Para verificação de idade e organização
  • Instituição de Ensino: Vinculação com escola/creche
  • Endereço de Coleta: Local de embarque
  • Status: Ativo/Inativo

Campos Derivados (LGPD)

  • Dia e Mês de Nascimento: Para "chamada" sem expor data completa
  • Idade Calculada: Atualizada automaticamente

Gestão de Responsáveis

Múltiplos Responsáveis

  • Cada passageiro pode ter múltiplos responsáveis
  • Definição de responsável principal (pagante)
  • Responsáveis podem ser compartilhados entre passageiros (irmãos)

Informações do Responsável

  • Nome Completo
  • CPF (criptografado - LGPD)
  • Email
  • Telefone(s): Celular e fixo
  • Endereço Completo
  • Relação com Passageiro: Pai, Mãe, Avô, Tio, etc.

Integração com Instituições

Cadastro de Instituições

  • Nome da Instituição
  • Tipo: Escola, Creche, Curso
  • Endereço Completo
  • Horários de Funcionamento
  • Contatos

Vinculação

  • Passageiro vinculado a uma instituição
  • Facilita planejamento de rotas por destino
  • Permite agrupamento de passageiros

Perfis Completos vs Incompletos

Status de Completude

Perfil Completo (✅): - Nome preenchido - Data de nascimento preenchida - Instituição vinculada - Endereço de coleta definido - Pelo menos 1 responsável cadastrado

Perfil Incompleto (⚠️): - Falta alguma informação essencial - Indicador visual na listagem - Bloqueio para criação de contratos

Validações

  • Campos obrigatórios marcados
  • Validação de CPF (dígitos verificadores)
  • Validação de email
  • Validação de telefone (formato brasileiro)

Arquitetura de Dados

Estrutura no Firestore

passengers/
  {passengerId}/
    - name: string
    - birthDate: timestamp
    - birthDay: number (derivado)
    - birthMonth: number (derivado)
    - institutionId: string (referência)
    - pickupAddress: map
    - status: 'active' | 'inactive'
    - businessOwnerId: string
    - createdAt: timestamp
    - updatedAt: timestamp

    responsibles/ (subcoleção)
      {responsibleId}/
        - name: string
        - cpfHash: string (mascarado)
        - email: string
        - phone: string
        - address: map
        - relationship: string
        - isPrimary: boolean

institutions/
  {institutionId}/
    - name: string
    - type: 'school' | 'daycare' | 'course'
    - address: map
    - businessOwnerId: string
    - createdAt: timestamp

Centralização de Responsáveis (Roadmap)

Objetivo: Evitar duplicação e facilitar LGPD

responsibles/ (coleção de topo)
  {responsibleId}/
    - name: string
    - cpfHash: string
    - email: string
    - phone: string
    - address: map
    - businessOwnerId: string

passengers/
  {passengerId}/
    - responsibleIds: array<string> (referências)
    - primaryResponsibleId: string

Vantagens: - ✅ Sem duplicação de dados - ✅ Atualização centralizada - ✅ Facilita retificação/exclusão (LGPD) - ✅ Irmãos compartilham responsáveis

Funcionalidades por Tier

Free Tier

  • ✅ Cadastro ilimitado de passageiros
  • ✅ Cadastro ilimitado de responsáveis
  • ✅ Cadastro ilimitado de instituições
  • ✅ Busca e filtros
  • ✅ Status ativo/inativo
  • ✅ Validações completas

Premium Tier

  • ✅ Tudo do Free
  • ✅ Exportação de dados (CSV)
  • ✅ Relatórios avançados
  • ✅ Histórico de alterações (audit trail)
  • ✅ Backup automático

Fluxos de Uso

Cadastro de Novo Passageiro

1. Usuário acessa "Passageiros" → "Novo Passageiro"
2. Preenche informações básicas:
   - Nome
   - Data de nascimento
   - Instituição (seleciona ou cria nova)
   - Endereço de coleta
3. Adiciona responsável:
   - Seleciona existente OU
   - Cria novo responsável
4. Define responsável principal (pagante)
5. Salva passageiro
6. Sistema valida completude
7. Passageiro aparece na listagem com status

Edição de Passageiro

1. Usuário seleciona passageiro na listagem
2. Acessa tela de detalhes
3. Edita informações desejadas
4. Adiciona/remove responsáveis
5. Salva alterações
6. Sistema revalida completude
7. Atualiza timestamp de modificação

Inativação de Passageiro

1. Usuário seleciona passageiro
2. Acessa opções → "Inativar"
3. Sistema verifica:
   - Tem contratos ativos? → Alerta
   - Tem pagamentos pendentes? → Alerta
4. Usuário confirma inativação
5. Status muda para "inactive"
6. Passageiro não aparece em seleções de rota

Busca e Filtros

Busca por Nome

  • Busca em tempo real
  • Case-insensitive
  • Busca parcial (substring)

Filtros Disponíveis

  • Status: Todos / Ativos / Inativos
  • Completude: Todos / Completos / Incompletos
  • Instituição: Filtrar por escola/creche
  • Com Contrato: Sim / Não

Ordenação

  • Nome (A-Z, Z-A)
  • Data de cadastro (Recente, Antigo)
  • Instituição (A-Z)

Validações e Regras de Negócio

Validações de Cadastro

  • ✅ Nome: Mínimo 3 caracteres
  • ✅ Data de nascimento: Não pode ser futura
  • ✅ CPF: Validação de dígitos verificadores
  • ✅ Email: Formato válido
  • ✅ Telefone: Formato brasileiro (11 ou 10 dígitos)
  • ✅ Endereço: CEP válido

Regras de Negócio

  • ❌ Não pode excluir passageiro com contrato ativo
  • ❌ Não pode excluir responsável se for o único
  • ❌ Não pode criar contrato com passageiro incompleto
  • ✅ Pode ter múltiplos passageiros na mesma instituição
  • ✅ Pode compartilhar responsáveis entre passageiros

Segurança e LGPD

Dados Sensíveis

CPF: - Armazenado criptografado (AES-256) - Exibido mascarado (***.***.***-62) - Acesso via Cloud Functions apenas

Dados Pessoais: - Criptografia at-rest nativa (Firebase) - Security Rules granulares - Acesso apenas pelo dono do negócio

Direitos dos Titulares

  • Acesso: Visualização de dados cadastrados
  • Correção: Edição direta no app
  • Exclusão: Mediante solicitação (se sem vínculos)
  • Portabilidade: Exportação em CSV

Melhorias Futuras

Roadmap

Q2 2026: - [ ] Centralização de responsáveis (coleção de topo) - [ ] Histórico de alterações (audit trail) - [ ] Exportação avançada (PDF, Excel)

Q3 2026: - [ ] Fotos de passageiros (opcional) - [ ] Documentos anexos (RG, certidão) - [ ] Observações médicas (alergias, medicações)

Q4 2026: - [ ] Integração com sistemas escolares - [ ] Importação em lote (CSV) - [ ] App para pais (visualização de dados)

Métricas de Sucesso

  • Completude: 80%+ dos passageiros com perfil completo
  • Tempo de Cadastro: < 2 minutos por passageiro
  • Erros de Validação: < 5% dos cadastros
  • Satisfação: NPS > 8 para facilidade de uso

Documento: Gestão de Passageiros
Versão: 1.0
Data: Janeiro 2026