🛠️ Documentação Técnica de Engenharia & Arquitetura — AIO Dispatcher

> Plataforma: AIO Dispatcher (All-In-One Dispatcher)

> Versão: 1.0.1 (Build 2026.11)

> Stack: Electron 34+ / Node.js 24 / Vanilla ES6+ / HTML5 Canvas / Leaflet & MapLibre GL / Supabase PostgreSQL & Realtime

> Organização: DHL Supply Chain & Express — Last Mile Operations / Mercado Livre Partner

> Classificação: Documentação Técnica de Arquitetura e Engenharia de Software

1. Visão Geral da Arquitetura & Stack Tecnológica #

O AIO Dispatcher foi concebido sob o modelo arquitetural de Desktop Edge Hub utilizando Electron. A plataforma opera como uma ponte bidirecional entre os sistemas corporativos em nuvem (Supabase PostgreSQL / Edge APIs) e as interfaces internas do Mercado Livre Logistics, unificando coleta de dados, enriquecimento geoespacial, tratamento de falhas em campo e automação gráfica de relatórios executivos.

flowchart TB
    subgraph ClientLayer ["Camada Cliente (Desktop Host)"]
        MP["Electron Main Process
(Node.js 24 + Chromium Host)"]
        PB["Preload Bridge
(contextBridge / IPC Safe API)"]
        RP["Renderer Thread
(HTML5 / Vanilla ES6+ / CSS3)"]
        Canvas["HTML5 Canvas 2D Engine
(Hora a Hora & Fechamento)"]
        GeoEngine["Leaflet & MapLibre GL
(Pins Vetoriais & Traçado OSRM)"]
    end

    subgraph IntegrationLayer ["Camada de Integração & Sessão"]
        BrowserDet["Browser Detector
(Chrome / LibreWolf Profiler)"]
        SessionStore["Cookie & Token Vault
(AES Storage / x-auth-token)"]
        PnrParser["PNR Parser & Haversine Calc
(Verificação Forense de Raio)"]
    end

    subgraph ExternalServices ["Serviços Externos & Nuvem"]
        MeliAPIs["Mercado Livre Logistics APIs
(AdminML / Shipping / Case Center)"]
        Supabase["Supabase Cloud PostgreSQL
(Auth, RLS, Storage & Realtime WebSockets)"]
        WhatsApp["WhatsApp Desktop & Web Engine
(Disparos de Reversão e Reportes)"]
    end

    MP <--> PB
    PB <--> RP
    RP --> Canvas
    RP --> GeoEngine
    MP --> BrowserDet
    MP --> SessionStore
    MP --> PnrParser
    MP <--> MeliAPIs
    RP <--> Supabase
    RP --> WhatsApp

1.1 Decisões de Engenharia & Performance #

• Vanilla JavaScript sem Frameworks Pesados: O front-end dispensa o overhead de reconciliação de Virtual DOM (React/Vue/Angular), garantindo tempo de inicialização < 400ms, renderização instantânea de tabelas com mais de 2.000 pacotes e consumo de memória RAM estabilizado em torno de 110 MB a 140 MB.
• Isolamento de Processos (Security Sandbox): A comunicação entre o processo de renderização e os recursos do sistema operacional (acesso a arquivos, área de transferência, processos do Windows) é estritamente mediada pelo preload.js através de canais IPC seguros (contextBridge), mantendo nodeIntegration: false e contextIsolation: true.
• Zero-Flicker DOM Updates: O ciclo de atualização do monitoramento (a cada 30 segundos) compara as assinaturas de dados (hashes de estado) e executa in-place patching, eliminando piscamentos de tela e preservando o scroll do operador.

2. Camada de Sessão, Autenticação & Scraping Resiliente #

2.1 Descoberta e Extração Automática de Sessão #

O módulo src/main/browserDetector.js inspeciona os diretórios de dados locais de navegadores baseados em Chromium e Firefox no Windows:

• %LOCALAPPDATA%\Google\Chrome\User Data\Default
• %APPDATA%\LibreWolf\Profiles\*.default-release
• %LOCALAPPDATA%\Microsoft\Edge\User Data\Default

O sistema realiza a leitura dos arquivos de cookies SQLite (Network/Cookies ou cookies.sqlite), descriptografando as chaves de autenticação do domínio mercadolivre.com.br (_csrf, ssid, org_session, auth_token).

2.2 Estrutura do Preload Bridge (src/main/preload.js) #

O objeto global window.aioApi expõe métodos controlados para o front-end:

3. Especificação Técnica dos Módulos do Sistema #

3.1 Módulo 1: Monitoramento Last Mile (moduleView_monitoring) #

• Fonte de Dados: Endpoint corporativo /admin/operational-monitoring/routes-summary.
• Filtro Estrito SC (Service Center):

```javascript

// Regra de Isolamento SC em src/renderer/app.js

const isStrictSC = (route.nodeType === 'SC' || route.type === 'SERVICE_CENTER') &&

route.base.toUpperCase() === currentActiveBase.toUpperCase();

```

• Classificação Automática de Rotas "Sem Rota":
• Se a rota não possui código oficial mas contém pacotes transferidos de outra rota em campo: batizada automaticamente como Ambulância.
• Seletor inline com persistência local permite ao operador marcar como Catado, Saca de Agência ou Backup.
• Gestão de Pernoite / Retorno Pausado: Rotas despachadas no dia anterior com status pausado são segregadas do cálculo do dia corrente, impedindo distorções no indicador de SPR (Shipment Performance Rate).
• 7 Alertas Preditivos em Tempo Real:
1
Veículos Inativos: Posição GPS estática por tempo > 40 minutos.
2
Atraso no Stem Out: Saída do galpão após a janela planejada.
3
Entregas Atrasadas: Progresso real abaixo da curva horária esperada.

3.2 Módulo 2: Central de Insucessos & Tratativas (moduleView_failures) #

• Mecanismo de Polling Inteligente: Scanner assíncrono a cada 120 segundos que consulta paradas não concluídas em todas as rotas ativas do dia.
• Detecção de Gargalos Imediatos: Paradas registradas com motivos críticos ("Endereço não localizado", "Cliente ausente 1ª tentativa", "Comércio fechado") entram no topo com badge piscante e alerta sonoro opcional.
• Reverse Lookup de Telefones: Quando a API do feed não retorna o contato direto do cliente, o sistema executa requisição pontual em segundo plano ao detalhe da remessa (/shipment/{shipment_id}/contact), preenchendo o botão do WhatsApp sem travar a interface.
• Auto-Reversão em Rua: Se o motorista retorna à parada tratada e realiza a entrega com sucesso, o sistema detecta a transição FAILED -> DELIVERED e move o card automaticamente para Revertidas / Entregues, incrementando a métrica de reversão da base.
• Modo de Exibição:
• Visualização Contínua (Default): Fila única linear com ordenação cronológica decrescente.
• Agrupamento por Motorista: Sanfonas/accordions expansíveis com contagem individual de falhas pendentes.

3.3 Módulo 3: Disparo Operacional Hora a Hora (moduleView_hourly) #

• Algoritmo de Cálculo Ponderado:

$$\text{DPPH} = \frac{\text{Total de Pacotes Entregues}}{\sum (\text{Tempo Efetivo em Rota dos Motoristas})}$$

$$\text{ETA Estimado} = \text{Horário Atual} + \left( \frac{\text{Pacotes Pendentes}}{\text{Velocidade Horária da Frota}} \right)$$

• Geração de Imagem Offscreen via HTML5 Canvas:
• Resolução de Renderização: $1920 \times 1080$ pixels (Full HD) em escala $2\times$ para nitidez em telas Retina e displays móveis.
• Composição Gráfica: Background degradê corporativo DHL (#FFCC00 para #D40511), tipografia Frutiger Bold/Black simulada via fontes do sistema, grid com 4 KPIs principais e tabela Top 4 de rotas críticas.
• Exportação: canvas.toBlob('image/png') com injeção direta no clipboard via navigator.clipboard.write([new ClipboardItem(...)]).

3.4 Módulo 4: Fechamento Diário & Delivery Success (moduleView_closing) #

• Fórmula Corporativa de DS (Delivery Success):

$$\text{DS (\%)} = \left( \frac{\text{Pacotes Entregues}}{\text{Total de Pacotes Expedidos}} \right) \times 100$$

• Snapshot Histórico em Nuvem:
• Salva o fechamento na tabela Supabase daily_closings com as seguintes colunas:

base, closing_date, expedited, delivered, failures, ds_percentage, operator_name, created_at.

• Possibilita auditoria cruzada e reconciliação com os dados financeiros faturados pelo parceiro logístico.

3.5 Módulo 5: Central Forense de PNRs (moduleView_pnr) #

• Auditoria de Distância Geoespacial (Fórmula de Haversine):

$$d = 2R \cdot \arcsin\left( \sqrt{ \sin^2\left(\frac{\Delta \phi}{2}\right) + \cos(\phi_1)\cos(\phi_2)\sin^2\left(\frac{\Delta \lambda}{2}\right) } \right)$$

Onde $R = 6.371\text{ km}$. Se a distância calculada entre as coordenadas do check-in móvel do motorista e o centróide do endereço do cliente for $> 150\text{ metros}$, o sistema emite o alerta "Entrega Fora do Raio", fornecendo base jurídica para contestações.

• Trava Anticolisão Multi-Operador:

Implementada via Supabase Realtime (WebSockets). Quando um analista abre um chamado de PNR, um evento de broadcast bloqueia o card nos terminais de outros operadores:

```json

{

"event": "PNR_LOCK",

"case_id": "ML-202611-9874",

"locked_by": "DHL-PC",

"timestamp": 1793836800000

}

```

• Classificação Cromática da Grade por Status e Contato (getPnrRowVisualClass):

Para otimização da esteira de auditoria, cada linha de PNR recebe preenchimento de fundo e borda indicadora de $5\text{px}$ com suporte nativo aos modos Claro e Escuro:

• 🟦 Azul (pnr-row-blue): Casos em WAITING_RECEIPT com mensagem pendente de envio (!msgSent).
• 🟧 Laranja (pnr-row-orange): Casos em WAITING_RECEIPT com mensagem já enviada ao comprador (msgSent).
• 🟩 Verde (pnr-row-green): Casos em CLOSED/NOT_BILLED ou anulados sem débito.
• 🟥 Vermelho Claro (pnr-row-red): Casos com penalidade aplicada (TO_BILL).
• 🟪 Roxo (pnr-row-purple): Casos finalizados e encaminhados para cobrança (CLOSED/BILLED).
• ⬛ Cinza Escuro (pnr-row-darkgray): Ocorrências sem comprovante de entrega anexado (WITHOUT_RECEIPT / CARRIER_NO_POD).

3.6 Módulo 6: Rotina Operacional Personalizada & Checklist Diário (moduleView_routine) #

• Estrutura de Armazenamento Local:
• Definição de Tarefas da Rotina: aio_custom_routine_tasks_v1 (JSON Array persistente).
• Estado Diário de Conclusão: aio_custom_routine_checks_YYYY-MM-DD (JSON Object { [taskId]: boolean }).
• Categorias de Agrupamento Operacional:
• morning: Abertura de Base & Matinal (06h - 09h)
• afternoon: Acompanhamento & Tarde (09h - 15h)
• pnr: Gestão Ativa de PNR & Ocorrências
• closing: Fechamento de Turno & DS (16h - 20h)
• general: Atividades Gerais & Contínuas
• Mecanismo de Reset Inteligente: O botão resetCustomRoutineChecklist() limpa exclusivamente o hash da data vigente, mantendo intactas todas as tarefas e horários customizados pelo operador.

3.7 Módulo 7: Links & Portais Importantes #

• Chave de Persistência: aio_important_links_v2.
• Proteção contra Regressão de Estado: A flag aio_important_links_initialized_v2 distingue a primeira inicialização do sistema de uma lista esvaziada intencionalmente pelo usuário ([]). Uma vez inicializado, nenhum item apagado é ressuscitado ao trocar de abas ou reiniciar o Electron.

4. Esquemas de Dados (JSON / Supabase) #

4.1 Modelo de Rota (RouteData) #

{
  "id": "467314373",
  "name": "D11_PM1",
  "driver": "Elias Ferreira de Brito",
  "plate": "SDD-ONT2G11",
  "vehicleType": "Utilitário SDD",
  "carrier": "DHL",
  "badge": "Bronze",
  "base": "SGO3",
  "nodeType": "SC",
  "status": "IN_PROGRESS",
  "spr": {
    "totalPackages": 114,
    "delivered": 40,
    "pending": 73,
    "failures": 1
  },
  "metrics": {
    "ozh": "02:18h",
    "orh": "03:10h",
    "dpph": 12.6,
    "plannedKm": 47.18
  },
  "alerts": ["COMMERCIAL_CLOSING", "INSUCESSOS_PENDENTES"],
  "updatedAt": "2026-11-04T18:45:00.000Z"
}

4.2 Modelo de Insucesso (PackageFailure) #

{
  "id": "fail_48409921963",
  "packageId": "48409921963",
  "routeId": "467314373",
  "routeName": "D11_PM1",
  "driverName": "Elias Ferreira de Brito",
  "driverPhone": "62991234567",
  "clientName": "Antonia Cleunici de Souza Dias",
  "clientPhone": "62989864313",
  "reason": "O pacote não pertence à minha região",
  "reasonCategory": "ERRO_ROTEIRIZACAO",
  "address": "Rua F4, Qd3, Residencial Flórida, Goiânia - GO",
  "complement": "Condomínio Indiana - Apt 65 bloco 02",
  "stopNumber": 83,
  "failedAt": "2026-11-04T17:32:00.000Z",
  "treatmentStatus": "PENDING",
  "reverted": false
}

4.3 Modelo de Tarefa de Rotina (CustomRoutineTask) #

{
  "id": "task_1730761234_abc",
  "text": "Conferência física do carregamento dos veículos no galpão",
  "category": "morning",
  "time": "06:30",
  "createdAt": "2026-11-04"
}

5. Procedimentos de Build, Sincronização & Distribuição #

O pipeline local de distribuição garante que o código desenvolvido na pasta de trabalho seja imediatamente refletido em todas as instâncias portáteis e instaladores corporativos:

flowchart TD
    Dev["src/ (Código Fonte de Desenvolvimento)"] --> Script["scripts/syncAllLocations.js"]
    Script --> Target1["resources/app/src (Executável Local de Teste)"]
    Script --> Target2["Instalador_Para_Compartilhar/AIO Dispatcher/resources/app/src"]
    Script --> Target3["D:/AIO_Dispatcher_Atualizado_Para_Compartilhar/resources/app/src"]
    Target3 --> ZipGen["Compress-Archive (PowerShell)"]
    ZipGen --> ZipFile["D:/AIO_Dispatcher_Atualizado_Para_Compartilhar.zip"]

5.1 Comandos de Manutenção & Verificação #

• Validação de Sintaxe em Lote:

```powershell

node scripts/verifyAllFiles.js

```

• Sincronização Completa com Drive D e Instalador:

```powershell

node scripts/syncAllLocations.js

```

6. Guia de Resolução de Problemas Técnicos (Troubleshooting) #

6.1 Desconexão de Sessão do Mercado Livre (Erro 401/403) #

• Sintoma: O monitoramento para de atualizar e exibe a mensagem "Sessão expirada ou não autenticada".
• Ação Técnica:
1
Clique em Trocar Conta / Relogar na barra superior.
2
Caso o navegador padrão seja o Chrome ou LibreWolf, certifique-se de que a conta está conectada no portal oficial do Mercado Livre no mesmo perfil do Windows.
3
O módulo browserDetector importará os novos tokens automaticamente em até 5 segundos.

6.2 Falha de Conexão com a Nuvem Supabase #

• Sintoma: Alertas de PNR ou status da rotina não propagam para outros operadores.
• Ação Técnica:
1
Acesse o menu Configurações & Gestão de Equipe.
2
Verifique o chip de status da nuvem (Cloud Status).
3
Clique em Testar Conexão. O sistema fará um ping HTTPS nos endpoints de Edge Functions e restabelecerá o canal de WebSockets.

> Aprovado pela Engenharia de Operações:

> Sistema validado em ambiente de produção para os Service Centers da rede DHL Supply Chain Brasil.