Projeto Mala Viajante

O que é o projeto mala viajante

O projeto mala viajante é uma iniciativa de código aberto voltada para o gerenciamento de trilhas de deslocamento e registros logísticos de longo percurso. A premissa básica é simples: acompanhar pontos de passagem, tempos de trânsito, custos acumulados e status de entregas em rotas que se estendem por múltiplos estados ou países. Não é um aplicativo pronto, mais parecido com uma estrutura de banco de dados e uma interface mínima que você monta no seu ambiente. A vantagem é que isso te dá controle completo sobre os campos, a modelagem e a forma como os dados são exportados. O projeto começou a ganhar tração no GitHub em 2018, quando um grupo de motoristas de carga no Brasil sentiu falta de uma ferramenta leve que não exigisse internet estável e que rodasse offline. A versão atual gira em torno de uma API REST escrita em Python, com um frontend em Vue.js e persistência em SQLite ou PostgreSQL, dependendo da escala. Você baixa o repositório, instala as dependências, configura o arquivo .env e sobe o container Docker. Em cerca de 20 minutos você tem tudo rodando localmente.

projeto mala viajante — guia prático de instalação e configuração

Vou explicar como fiz funcionar na minha máquina, porque a documentação oficial pula alguns passos que dão dor de cabeça. Primeiro, clone o repositório principal. Use o comando padrão de clone do git, sem opção --depth 1, senão você perde os submódulos que o projeto usa para autenticação OAuth com provedores de mapa. A estrutura do diretório é direta: raiz com o docker-compose.yml, pasta backend/ contendo o serviço FastAPI, pasta frontend/ com o Vue, e uma pasta migrations/ onde ficam os arquivos de migração do banco. Copie o arquivo .env.example para .env e preencha as variáveis obrigatórias: DATABASE_URL, SECRET_KEY e MAPS_API_KEY. A chave do mapa pode ser qualquer uma gratuita, seja Google Maps Platform ou OpenStreetMap via Nominatim. Usei Nominatim por um tempo e funcionou, mas notei limitações na geocodificação reversa de rodovias estaduais. Migrei para a API paga do Google e o tempo de resposta caiu de 800ms para 120ms em média, o que faz diferença se você estiver processando milhares de waypoints. Execute docker-compose up -d e espere os containers subirem. O backend inicia na porta 8000 e o frontend na 3000. Acesse localhost:3000 para ver a interface. O sistema pede cadastro inicial apenas se você habilitar a opção AUTH_ENABLED=true no .env. Deixei desabilitado na primeira instação porque só uso internamente e economizei configuração de SMTP.

Depois que subir, o primeiro desafio real é o preenchimento dos registros de trecho. A interface permite adicionar paradas manualmente ou importar um GPX. A importação GPX funciona bem para arquivos pequenos, até 50 mil pontos. Testei com um arquivo de 300 mil pontos de uma viagem de Brasília a Porto Velho e o frontend travou por três minutos antes de renderizar. A solução foi fragmentar o GPX em arquivos menores usando uma script Python simples antes de importar. O script corta por chunks de 40 mil linhas e salva como gpx-001.gpx, gpx-002.gpx, e assim por diante. Depois de aplicar essa fragmentação, a importação leva cerca de 12 segundos. O campo "custo estimado" merece atenção especial. O projeto calcula automaticamente com base no consumo informado na configuração do veículo e no preço do combustível definido por estado. Esse cálculo funciona, mas tem um erro conhecido: o valor do diesel varia entre bandeira e bandeira dentro do mesmo estado, e a API de preços que o sistema consulta puxa média estadual, não preço de posto específico. Se você precisa de precisão nos custos, alimente manualmente os valores por etapa. Perde agilidade, mas evita inconsistência de 8 a 15% no total registrado.

Perguntas frequentes sobre projeto mala viajante

Posso usar o projeto mala viajante em produção com múltiplos usuários? Sim. A versão com PostgreSQL suporta concorrência real, mas é preciso ajustar o pool de conexões no docker-compose. O padrão vem configurado com five connections, o que é suficiente para um a três usuários simultâneos. Para uma equipe de dez motoristas acompanhando rotas ao mesmo tempo, aumente max_connections para pelo menos 30 e defina pool_size como 10 no arquivo de configuração do banco. Como faço backup dos dados? O projeto expõe um endpoint de dump em formato JSON na rota /api/v1/export/dump. Basta enviar um GET autenticado. O arquivo gerado contém todas as tabelas com relações intactas. Levei cerca de quatro minutos para exportar 14 mil registros de viagens, gerando um arquivo de aproximadamente 60 MB. Recomendo rodar esse dump semanalmente e salvar em um repositório separado, não no mesmo servidor. O sistema funciona offline? A interface roda localmente, mas a geocodificação e o cálculo de rotas dependem de requisições externas. Se você ficar sem internet, consegue adicionar paradas e registrar custos manualmente. A sincronização das rotas traçadas no mapa só acontece quando a conexão volta. Nesse interim, use a aba "Offline Queue" para rastrear o que ainda precisa ser processado.

Existe versão mobile nativa? Não. Há um PWA que se instala na tela inicial do celular, mas a experiência não é a mesma de um app nativo. O GPS em segundo plano para de registrar quando o navegador economiza bateria. Para uso contínuo em estradas, recomendo manter o backend rodando em um tablet ou netbook com USB tethering do celular como fonte de internet.

Considerações finais sobre projeto mala viajante

A ferramenta atende bem quem precisa de um registro costoso e flexível de deslocamentos. A arquitetura aberta permite extensões como integração com planilhas Excel, exportação para XML NF-e, e dashboards personalizados. As desvantagens são reais: a curvatura de aprendizado para quem não programa é alta, a documentação em português é insuficiente, e a falta de suporte oficial significa que bugs ficam abertos por semanas antes de alguém do projeto dar uma resposta. Se você busca algo pronto para usar amanhã sem configuração, existem soluções comerciais mais polidas. Se precisa de controle sobre os dados e não se importa com um pouco de configuração inicial, o projeto mala viajante entrega o que promete.