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
```sql
CREATE TABLE users (
  id TEXT PRIMARY KEY,
  name TEXT,
  email TEXT,
  role TEXT,
  last_login INTEGER
);
```

#### deliveries
```sql
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
```sql
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
```sql
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**:
```typescript
// 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**:
```typescript
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**:
```sql
-- 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**:
```typescript
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.