entregas_app/docs/ARQUITETURA_COMPLETA_APLICATIVO.md

Arquitetura Completa do Aplicativo de Entregas

Visão Geral

O aplicativo de entregas é uma solução mobile desenvolvida em React Native com Expo, projetada para gerenciar entregas de forma eficiente com funcionalidades offline e sincronização de dados.

Tecnologias Utilizadas

Framework e Plataforma

• React Native: Framework principal para desenvolvimento mobile
• Expo: Plataforma de desenvolvimento e deploy
• TypeScript: Linguagem de programação com tipagem estática

Bibliotecas Principais

• React Navigation: Navegação entre telas
• Expo SQLite: Banco de dados local
• AsyncStorage: Armazenamento local de dados
• Expo Maps: Integração com mapas
• Expo Location: Serviços de localização
• Expo Camera: Captura de fotos
• Expo Notifications: Notificações push
• Axios: Cliente HTTP para APIs
• React Native Vector Icons: Ícones

Arquitetura do Aplicativo

Estrutura de Pastas

src/
├── components/          # Componentes reutilizáveis
├── contexts/           # Contextos React (estado global)
├── hooks/              # Hooks customizados
├── navigation/         # Configuração de navegação
├── screens/            # Telas do aplicativo
│   ├── auth/          # Telas de autenticação
│   └── main/          # Telas principais
├── services/           # Serviços e APIs
├── types/              # Definições de tipos TypeScript
├── constants/          # Constantes e temas
└── config/             # Configurações

Contextos de Estado Global

1. AuthContext

Arquivo: src/contexts/AuthContext.tsx

Responsabilidades:

• Gerenciar autenticação do usuário
• Controlar login/logout
• Armazenar dados do usuário
• Verificar necessidade de roteirização

Estados:

• user: Dados do usuário logado
• isLoading: Estado de carregamento
• signIn(): Função de login
• signOut(): Função de logout

2. DeliveriesContext

Arquivo: src/contexts/DeliveriesContext.tsx

Responsabilidades:

• Gerenciar lista de entregas
• Controlar carregamento e refresh
• Implementar roteirização automática com TSP
• Ordenar entregas por sequência

Estados:

• deliveries: Lista de entregas
• loading: Estado de carregamento
• error: Mensagens de erro
• refreshDeliveries(): Atualizar entregas
• forceRefresh(): Forçar atualização

3. SyncContext

Arquivo: src/contexts/SyncContext.tsx

Responsabilidades:

• Monitorar estado da conexão
• Gerenciar sincronização de dados
• Controlar fila de sincronização

Estados:

• isOnline: Status da conexão
• isSyncing: Estado de sincronização
• lastSyncTime: Timestamp da última sincronização
• pendingSyncCount: Contador de itens pendentes
• syncNow(): Executar sincronização

4. OfflineContext

Arquivo: src/contexts/OfflineContext.tsx

Responsabilidades:

• Gerenciar modo offline
• Controlar armazenamento offline
• Monitorar sinal de conexão
• Gerenciar fila de sincronização

Estados:

• isOfflineMode: Modo offline ativo
• offlineStats: Estatísticas de dados offline
• pendingSyncCount: Itens pendentes
• saveOfflineData(): Salvar dados offline
• syncOfflineData(): Sincronizar dados

Sistema de Navegação

Estrutura de Navegação

App
├── AuthNavigator (Stack)
│   └── LoginScreen
└── MainNavigator (Stack)
    ├── RoutingScreen (Modal)
    └── TabNavigator
        ├── HomeScreen
        ├── RoutesScreen
        ├── DeliveriesStack (Stack)
        │   ├── DeliveriesScreen
        │   ├── DeliveryDetailScreen
        │   ├── CompleteDeliveryScreen
        │   ├── RescheduleDeliveryScreen
        │   └── DeliverySuccessScreen
        └── ProfileScreen

Fluxo de Navegação

1. Login: Usuário faz login na LoginScreen
2. Verificação de Roteirização: Sistema verifica se entregas precisam de roteamento
3. RoutingScreen: Se necessário, usuário é direcionado para roteirização
4. HomeScreen: Tela principal com próxima entrega
5. Detalhes: Navegação para detalhes da entrega
6. Finalização: Processo de conclusão da entrega

Telas do Aplicativo

1. LoginScreen

Arquivo: src/screens/auth/LoginScreen.tsx

Funcionalidades:

• Formulário de login (username/password)
• Validação de credenciais
• Redirecionamento baseado em necessidade de roteirização
• Indicador de carregamento
• Suporte a login social (preparado)

Estados:

• username: Nome de usuário
• password: Senha
• isLoading: Estado de carregamento
• showPassword: Visibilidade da senha

2. HomeScreen

Arquivo: src/screens/main/HomeScreen.tsx

Funcionalidades:

• Exibição da próxima entrega
• Estatísticas de entregas (pendentes, em rota, entregues, falhas)
• Card de sincronização pendente
• Verificação automática de roteirização
• Navegação para detalhes da entrega

Componentes Principais:

• Header com saudação e status de conexão
• Cards de estatísticas
• Card da próxima entrega
• Botões de ação

3. RoutesScreen

Arquivo: src/screens/main/RoutesScreen.tsx

Funcionalidades:

• Visualização de mapa com entregas
• Alternância entre visualização de mapa e lista
• Cálculo automático de rotas otimizadas
• Envio de roteirização para API
• Modo tela cheia

Componentes:

• DeliveryMap: Componente de mapa
• Lista de entregas
• Controles de visualização

4. DeliveriesScreen

Arquivo: src/screens/main/DeliveriesScreen.tsx

Funcionalidades:

• Lista completa de entregas
• Filtros por status
• Ordenação por diferentes critérios
• Busca de entregas
• Navegação para detalhes

Filtros Disponíveis:

• Status: pending, in_progress, delivered, failed
• Ordenação: deliverySeq, customerName, distance, outDate
• Ordem: ascendente/descendente

5. DeliveryDetailScreen

Arquivo: src/screens/main/DeliveryDetailScreen.tsx

Funcionalidades:

• Exibição detalhada da entrega
• Informações do cliente
• Notas fiscais
• Ações de entrega (iniciar, completar, reagendar)
• Captura de fotos e assinatura

6. CompleteDeliveryScreen

Arquivo: src/screens/main/CompleteDeliveryScreen.tsx

Funcionalidades:

• Formulário de conclusão de entrega
• Captura de fotos
• Coleta de assinatura
• Registro de observações
• Validação de dados obrigatórios

7. ProfileScreen

Arquivo: src/screens/main/ProfileScreen.tsx

Funcionalidades:

• Exibição de dados do usuário
• Estatísticas pessoais
• Configurações
• Logout

Serviços e APIs

1. ApiService

Arquivo: src/services/api.ts

Endpoints Principais:

Autenticação

• POST /auth/login - Login do usuário
• POST /auth/logout - Logout do usuário

Entregas

• GET /v1/driver/deliveries - Listar entregas
• GET /v1/driver/deliveries/{outId} - Obter entrega específica
• GET /v1/driver/deliveries/{outId}/customer/{customerId} - Notas fiscais
• POST /v1/delivery/create - Criar/concluir entrega
• POST /v1/driver/delivery/status - Atualizar status

Roteirização

• POST /v1/driver/routing - Enviar ordem de roteamento

Geolocalização

• GET /v1/geolocation/google - Obter coordenadas por endereço

Upload

• POST /api/v1/base/send-image - Upload de imagens

Funcionalidades Especiais:

• Algoritmo TSP (Traveling Salesman Problem) para otimização de rotas
• Geolocalização automática de endereços
• Cálculo de distâncias
• Ordenação inteligente de entregas

2. DatabaseService

Arquivo: src/services/database.ts

Tabelas SQLite:

users

CREATE TABLE users (
  id TEXT PRIMARY KEY,
  name TEXT,
  email TEXT,
  role TEXT,
  last_login INTEGER
);

deliveries

CREATE TABLE deliveries (
  id TEXT PRIMARY KEY,
  client TEXT,
  address TEXT,
  coordinates TEXT,
  status TEXT,
  scheduled_time TEXT,
  completed_time INTEGER,
  signature TEXT,
  photos TEXT,
  notes TEXT,
  sync_status TEXT
);

deliveries_offline

CREATE TABLE deliveries_offline (
  id TEXT PRIMARY KEY,
  outId INTEGER,
  transactionId INTEGER,
  deliveryDate TEXT,
  receiverDoc TEXT,
  receiverName TEXT,
  lat REAL,
  lng REAL,
  broken INTEGER,
  devolution INTEGER,
  reasonDevolution TEXT,
  deliveryImages TEXT,
  userId INTEGER,
  sync_status TEXT
);

settings

CREATE TABLE settings (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  key TEXT UNIQUE,
  value TEXT
);

Funcionalidades:

• Fallback para AsyncStorage quando SQLite não disponível
• Operações CRUD para todas as entidades
• Controle de sincronização
• Armazenamento offline

3. OfflineStorageService

Arquivo: src/services/offlineStorage.ts

Funcionalidades:

• Armazenamento de dados offline por tipo
• Fila de sincronização com retry
• Estatísticas de dados offline
• Controle de tentativas de sincronização
• Limpeza de dados sincronizados

Tipos de Dados Offline:

• delivery: Dados de entregas
• photo: Fotos capturadas
• signature: Assinaturas coletadas
• status: Atualizações de status

4. SyncService

Arquivo: src/services/sync.ts

Funcionalidades:

• Sincronização de entregas offline
• Upload de arquivos (fotos, assinaturas)
• Controle de estado de conexão
• Retry automático em caso de falha

Sistema de Estilização

Tema Principal

Arquivo: src/constants/theme.ts

Cores:

• Primary: #0A1E63 (Azul escuro)
• Secondary: #F5F5F5 (Cinza claro)
• Success: #4CAF50 (Verde)
• Warning: #FFC107 (Amarelo)
• Danger: #F44336 (Vermelho)
• Info: #2196F3 (Azul)

Tipografia:

• Regular: Roboto-Regular
• Medium: Roboto-Medium
• Bold: Roboto-Bold

Sombras:

• Small: Elevação 2
• Medium: Elevação 5

Tailwind CSS

Arquivo: tailwind.config.ts

Configuração completa do Tailwind CSS com:

• Sistema de cores customizado
• Bordas arredondadas
• Animações de accordion
• Suporte a modo escuro
• Cores para sidebar e charts

Componentes UI

Componentes Principais

1. Icon

Arquivo: components/Icon.tsx

• Suporte a múltiplas bibliotecas de ícones
• Material Icons, FontAwesome, Ionicons
• Props customizáveis (size, color, style)

2. FloatingPanicButton

Arquivo: components/FloatingPanicButton.tsx

• Botão de pânico flutuante
• Captura de localização
• Envio de alerta de emergência

3. DeliveryMap

Arquivo: src/components/DeliveryMap.tsx

• Integração com mapas
• Exibição de entregas
• Cálculo de rotas
• Marcadores customizados

4. MobileSignalIndicator

Arquivo: src/components/MobileSignalIndicator.tsx

• Indicador de força do sinal
• Controle de modo offline
• Alertas de conexão

Componentes UI (shadcn/ui)

Pasta: components/ui/

Componentes baseados no shadcn/ui:

• Accordion, Alert, Avatar, Badge
• Button, Card, Checkbox, Dialog
• Form, Input, Label, Select
• Table, Tabs, Toast, Tooltip
• E muitos outros componentes

Hooks Customizados

1. useMobileSignal

Arquivo: src/hooks/useMobileSignal.ts

Funcionalidades:

• Monitoramento de força do sinal
• Detecção de tipo de conexão
• Controle de modo offline baseado no sinal
• Alertas de qualidade de conexão

2. useMapboxDirections

Arquivo: src/hooks/useMapboxDirections.ts

Funcionalidades:

• Integração com Mapbox Directions API
• Cálculo de rotas otimizadas
• Suporte a múltiplos waypoints
• Cache de rotas calculadas

3. useRouting

Arquivo: src/hooks/useRouting.ts

Funcionalidades:

• Lógica de roteirização
• Algoritmo TSP
• Otimização de sequência de entregas
• Integração com API de roteamento

4. useNetworkStatus

Arquivo: hooks/useNetworkStatus.ts

Funcionalidades:

• Monitoramento de status da rede
• Detecção de mudanças de conectividade
• Callbacks para eventos de rede

Configurações e Ambiente

Variáveis de Ambiente

Arquivo: src/config/env.ts

Configurações:

• Google Maps API Key
• URL base da API
• Timeout de requisições
• Chaves de autenticação
• Token do Mapbox
• Configurações de notificação

Configuração do Expo

Arquivo: app.json

Configurações Principais:

• Bundle identifier
• Permissões (câmera, localização, armazenamento)
• Configuração do Google Maps
• Plugins necessários
• Configurações de notificação

Sistema de Sincronização Offline

Estratégia de Sincronização

1. Detecção de Modo Offline:

   • Monitoramento de força do sinal
   • Detecção de qualidade de conexão
   • Ativação automática do modo offline

2. Armazenamento Offline:

   • Dados salvos localmente no SQLite
   • Fila de sincronização
   • Controle de tentativas

3. Sincronização:

   • Execução automática quando online
   • Retry em caso de falha
   • Limpeza de dados sincronizados

Fluxo de Dados Offline

Usuário Executa Ação
    ↓
Verificar Conexão
    ↓
Se Offline → Salvar Localmente
    ↓
Adicionar à Fila de Sync
    ↓
Quando Online → Sincronizar
    ↓
Remover da Fila

Algoritmo de Roteirização TSP

Implementação

Arquivo: src/services/api.ts (função optimizeRouteWithTSP)

Processo:

1. Coleta de Coordenadas:

   • Usar coordenadas existentes
   • Geolocalizar endereços sem coordenadas
   • Normalizar formato de coordenadas

2. Cálculo de Matriz de Distâncias:

   • Fórmula de Haversine
   • Distâncias entre todas as entregas
   • Incluir centro de distribuição

3. Algoritmo Nearest Neighbor:

   • Começar do centro de distribuição
   • Selecionar próxima entrega mais próxima
   • Repetir até todas as entregas visitadas

4. Aplicação de Sequência:

   • Atribuir deliverySeq sequencial
   • Enviar para API de roteamento
   • Atualizar banco de dados

Considerações para Implementação de Sincronização Offline

1. Carregamento Inicial de Dados

Implementação Sugerida:

// Novo contexto para gerenciar sincronização inicial
interface InitialSyncContext {
  isInitialSyncComplete: boolean;
  syncProgress: number;
  startInitialSync: () => Promise<void>;
  retryInitialSync: () => Promise<void>;
}

Dados Necessários para Sincronização Inicial:

• Lista completa de entregas
• Dados de clientes
• Informações de produtos
• Configurações do sistema
• Dados de usuário

2. Estratégia de Sincronização Incremental

Implementação:

interface SyncStrategy {
  fullSync: () => Promise<void>;      // Sincronização completa
  incrementalSync: () => Promise<void>; // Sincronização incremental
  selectiveSync: (ids: string[]) => Promise<void>; // Sincronização seletiva
}

3. Controle de Versão de Dados

Implementação:

-- Adicionar campos de controle de versão
ALTER TABLE deliveries ADD COLUMN version INTEGER DEFAULT 1;
ALTER TABLE deliveries ADD COLUMN last_modified INTEGER;
ALTER TABLE deliveries ADD COLUMN sync_timestamp INTEGER;

4. Resolução de Conflitos

Estratégias:

• Last-Write-Wins (última modificação vence)
• Server-Wins (servidor sempre vence)
• Client-Wins (cliente sempre vence)
• Merge automático quando possível

5. Otimização de Performance

Implementações:

• Compressão de dados
• Sincronização em lotes
• Cache inteligente
• Lazy loading de dados

6. Monitoramento e Logs

Implementação:

interface SyncLogger {
  logSyncStart: (type: string) => void;
  logSyncProgress: (progress: number) => void;
  logSyncError: (error: Error) => void;
  logSyncComplete: (stats: SyncStats) => void;
}

Conclusão

O aplicativo possui uma arquitetura robusta e bem estruturada, com separação clara de responsabilidades e suporte completo para funcionamento offline. A implementação de sincronização de dados pode ser realizada de forma incremental, aproveitando a infraestrutura existente e expandindo as funcionalidades de armazenamento e sincronização já implementadas.

A documentação apresentada serve como base para implementar melhorias no sistema de sincronização, garantindo que o aplicativo funcione de forma eficiente tanto online quanto offline.