Vanguru Mobile

Aplicativo em Flutter para gerenciamento e acompanhamento de rotas de transporte escolar.

✨ Funcionalidades

🚌 Gestão de Rotas e Execução

  • Criação e edição de rotas de transporte escolar
  • Execução de rotas em tempo real com rastreamento GPS
  • Visualização de rotas no mapa com Google Maps
  • Notificações automáticas para responsáveis ("Cheguei", etc.)
  • Histórico completo de execuções

👥 Gestão de Passageiros

  • Cadastro completo de passageiros e responsáveis
  • Múltiplos responsáveis por passageiro
  • Integração com instituições de ensino
  • Perfis completos vs. incompletos
  • Gerenciamento de endereços e contatos

📄 Sistema de Contratos

  • Criação e gestão de contratos (Free e Premium)
  • Suspensão e reativação de contratos
  • Histórico de atividades (audit trail)
  • Diferentes tiers de serviço
  • Contratos vinculados a passageiros

💰 Sistema de Pagamentos

  • Modo Free: Pagamentos manuais com comprovante
  • Modo Premium: Integração com gateway de pagamento (Asaas)
  • Geração automática de boletos e PIX
  • Acompanhamento de status (pendente, pago, vencido)
  • Histórico completo de atividades de pagamento
  • Notificações de vencimento
  • Dashboard financeiro na tela inicial

🔐 Autenticação e Segurança

  • Autenticação via Firebase Authentication
  • Controle de acesso por perfil (motorista, responsável, admin)
  • API keys gerenciadas via variáveis de ambiente
  • Firestore Security Rules implementadas

🏛️ Arquitetura

O projeto utiliza uma arquitetura limpa (Clean Architecture) dividida em camadas, com uma separação clara de responsabilidades. A estrutura de pastas é orientada a funcionalidades (features).

  • State Management & Injeção de Dependência: A gerência de estado e a injeção de dependência são feitas com flutter_riverpod, que provê uma solução reativa e robusta para o estado da aplicação.
  • Imutabilidade: Os modelos e estados usam o pacote equatable para facilitar comparações e evitar rebuilds desnecessários da UI.

📁 Estrutura do Projeto

lib/
├── core/                      # Código compartilhado
│   ├── domain/               # Modelos de domínio core
│   ├── providers/            # Providers globais
│   ├── theme/                # Tema e estilos
│   └── utils/                # Utilitários
├── features/                  # Funcionalidades (Clean Architecture)
│   ├── contracts/            # Sistema de contratos
│   │   ├── domain/          # Modelos e enums
│   │   ├── data/            # Repositories e data sources
│   │   └── presentation/    # Screens, widgets e providers
│   ├── payments/             # Sistema de pagamentos
│   ├── passengers/           # Gestão de passageiros
│   ├── routes-creations/     # Criação de rotas
│   ├── routes-executions/    # Execução de rotas
│   └── ...
└── main.dart

Cada feature segue a Clean Architecture com separação clara entre: - Domain: Modelos, enums e interfaces - Data: Implementação de repositories e acesso a dados - Presentation: UI, widgets e state management

📚 Documentação Técnica

Para informações detalhadas sobre funcionalidades específicas, consulte: - API de Segurança: api/functions.md - API de Pagamentos: api/payments.md - Guia de LGPD: seguranca/lgpd.md - Guia de Desenvolvimento de Pagamentos: guia/pagamentos.md

🛠️ Serviços e APIs Externas

O aplicativo depende dos seguintes serviços externos:

  • Firebase:
    • Firebase Authentication: Para o sistema de login e gerenciamento de usuários.
    • Cloud Firestore: Utilizado como banco de dados NoSQL para armazenar todas as informações da aplicação (rotas, usuários, etc.).
  • Google Maps Platform:
    • Google Maps for Flutter: Para a exibição dos mapas.
    • Geolocator: Para obter a localização do dispositivo.
    • Directions API: Para traçar as polilinhas das rotas no mapa (através do flutter_polyline_points).

🚀 Guia de Instalação e Execução Local

Siga os passos abaixo para configurar o ambiente de desenvolvimento e rodar o projeto localmente.

1. Pré-requisitos

  • Flutter: Certifique-se de ter o Flutter SDK instalado. A versão utilizada está no pubspec.yaml.
  • Firebase CLI: Instale a Firebase CLI para configurar o projeto.

2. Configuração do Firebase

  1. Crie um novo projeto no Firebase Console.
  2. Configure um aplicativo para Android e um para iOS dentro do seu projeto Firebase.
  3. Para Android: Baixe o arquivo google-services.json e coloque-o em android/app/.
  4. Para iOS: Baixe o arquivo GoogleService-Info.plist e coloque-o em ios/Runner/.

3. Chaves de API (API Keys)

  1. No Google Cloud Console (associado ao seu projeto Firebase), ative as seguintes APIs e gere as chaves:

    • Maps SDK for Android: Gere uma chave de API.
    • Maps SDK for iOS: Gere uma chave de API.
    • Directions API: Gere uma chave de API.

  2. As chaves precisam ser fornecidas ao Flutter no momento da execução. Este projeto utiliza dart-define para injetar as chaves como variáveis de ambiente.

4. Executando o Aplicativo

Para compilar e rodar o app, utilize o comando flutter run com os seguintes argumentos --dart-define:

flutter run --dart-define=GOOGLE_MAPS_API_KEY="SUA_CHAVE_MAPS_AQUI" --dart-define=GOOGLE_APIS_REST_KEY="SUA_CHAVE_DIRECTIONS_AQUI"

Substitua: * SUA_CHAVE_MAPS_AQUI: Pela chave que você gerou para o Maps SDK (Android ou iOS). * SUA_CHAVE_DIRECTIONS_AQUI: Pela chave que você gerou para a Directions API.

5. Scripts Úteis

  • Gerar Ícones: Se você alterar o ícone do app em assets/images/app_icon.png, rode o seguinte comando para atualizar os ícones de todas as plataformas: bash flutter pub run flutter_launcher_icons

6. Build Web

Para fazer o build da versão web do aplicativo:

flutter build web \
  --dart-define=GOOGLE_MAPS_API_KEY="SUA_CHAVE_MAPS_AQUI" \
  --dart-define=GOOGLE_APIS_REST_KEY="SUA_CHAVE_DIRECTIONS_AQUI" \
  --web-renderer canvaskit \
  --release

Os arquivos compilados estarão em build/web/.

7. Controle LGPD (Dev vs Prod)

Para garantir segurança total em produção e redução de custos em desenvolvimento, o app utiliza o Firebase Remote Config para controlar o fluxo de dados sensíveis (LGPD).

  • Produção (Release Mode): Sempre utiliza Cloud Functions (Segurança Máxima). A flag de bypass é ignorada/removida pelo compilador.
  • Desenvolvimento (Debug Mode): O comportamento é definido pela flag security_use_functions_bypass no Remote Config.
    • false (Padrão): Usa Cloud Functions (Simula produção, consome cotas/custo).
    • true: Usa Firestore Bypass (Escrita direta no banco, custo zero, menor segurança).

Para ativar o Modo Econômico em Dev (Backoffice): 1. Acesse o Firebase Console > Remote Config. 2. Crie/Edite o parâmetro security_use_functions_bypass. 3. Defina o valor como true (Tipo Boolean). 4. Publique as alterações. 5. Reinicie o app (o fetch ocorre na inicialização).