# Relatório Zentulo System Deep Dive: Análise Técnica e Funcional

Este documento apresenta uma análise detalhada da arquitetura, lógica de negócios e fluxos operacionais do Sistema Zentulo, um ambiente de análise e simulação para a plataforma Zentulo.

## 1. Visão Geral da Arquitetura

O sistema Zentulo utiliza uma arquitetura **Híbrida Web/Electron**, projetada para operar tanto em navegadores quanto em ambiente desktop com permissões estendidas de sistema de arquivos.

*   **Frontend:** React com Tailwind CSS.
*   **Comunicação:** REST API e WebSockets (Socket.io) para atualizações em tempo real.
*   **Persistência Local:** `localStorage` com lógica de sincronização offline personalizada.
*   **Integração Nativa:** Electron Bridge (`window.electronAPI`) para processamento de arquivos XML locais e automação do Outlook.

---

## 2. Fluxos Visuais (Mermaid.js)

### Fluxo 1: Ciclo de Vida da Solicitação de Liberação
O coração do sistema é o fluxo de solicitações feitas por motoristas e aprovadas pela central de monitoramento.

```mermaid
sequenceDiagram
    participant M as Motorista (Portal)
    participant S as Socket.io / API
    participant C as Central (Painel Monitoramento)
    
    M->>S: Envia Solicitação (Placa, Operação, CTe/NF)
    S-->>C: Notificação Real-time (monitoring-update)
    C->>C: Supervisor clica em "Atender"
    Note right of C: Status muda para "ANÁLISE"
    C-->>M: Notificação: "Solicitação Atendida"
    C->>C: Validação de Perímetro/SST/Fiscal
    C->>S: Clica em "Aprovar" (Envia Rota/Mensagem)
    S-->>M: Notificação: "LIBERADO" (Verde)
    M->>M: Clica em "Saí em Rota"
    Note left of M: Status muda para "EM ROTA"
```

### Fluxo 2: Processamento Fiscal e Automação de E-mail
Este fluxo descreve como o sistema extrai dados de documentos fiscais sem intervenção manual pesada.

```mermaid
graph TD
    A[Outlook Automation] -->|Electron Select Folder| B[Download XMLs]
    B --> C{Tipo de Documento?}
    C -->|NF-e| D[FiscalAnalysis Component]
    C -->|CT-e / MDF-e| E[CTE Component]
    D -->|window.electronAPI.processFiscal| F[Validação contra Regras de Negócio]
    E -->|window.electronAPI.processCTEs| G[Validação de CTE / MDF-e]
    F --> H[Relatório de Divergências]
    G --> I[Log de Processamento e Auditoria]
```

### Fluxo 3: Sincronização Offline de Documentos
O sistema garante que motoristas possam salvar comprovantes mesmo em áreas de sombra de sinal.

```mermaid
graph LR
    A[Upload do Arquivo] --> B{Conexão Online?}
    B -- Não --> C[Salva em localStorage 'pending_sync']
    B -- Sim --> D[Envia para /api/documents]
    C --> E[Monitora Evento 'online']
    E --> F[syncPending Utility]
    F --> D
    D --> G[Cria Registro na Gestão de Documentos]
```

### Fluxo 4: Importação de Planilhas (Excel)
O sistema permite popular cadastros em massa via processamento local de arquivos `.xlsx`.

```mermaid
graph TD
    A[Selecionar Arquivo .xlsx] --> B[FileReader.readAsBinaryString]
    B --> C[XLSX.read Parser]
    C --> D[Mapeamento de Colunas Dinâmico]
    D --> E{Motorista Válido?}
    E -->|Sim| F[Lista de Prévia para Conferência]
    E -->|Não| G[Alerta de Erro de Formato]
    F --> H[Loop: POST /api/drivers]
    H --> I[Atualização Local da UI]
```

### Fluxo 5: Sistema de Telemetria e Rastreamento
Monitoramento em tempo real de veículos com integração a provedores externos.

```mermaid
sequenceDiagram
    participant W as Worker (30s polling)
    participant T as T4S API
    participant S as Sascar API
    participant DB as TelemetryDB (Memória)
    participant IO as Socket.io
    participant C as Cliente (Dashboard)
    
    loop A cada 30 segundos
        W->>T: Bulk Fetch (PRALOG + PETY)
        T-->>W: Array de Posições
        W->>S: Bulk Fetch (Se credenciais configuradas)
        S-->>W: Array de Posições
        W->>W: Normalização de Dados
        W->>W: Validação Geofence (lat > -21.0?)
        W->>W: Validação Velocidade (> 90 km/h?)
        W->>DB: Atualiza Posições + Histórico
        W->>IO: Emit 'positions-update'
        IO-->>C: Atualização Real-time
    end
    
    Note over W,C: Alertas: FORA_DA_ROTA, EXCESS_SPEED, SIGNAL_LOST
```

---

## 3. Análise Detalhada dos Módulos

### 3.1 Painel de Monitoramento
*   **Lógica de Status:** Transições coordenadas entre *Pending* -> *Analysis* -> *Approved* -> *In Progress* -> *Arrived*.
*   **Validação de Rota:** Contém lógica específica para impedir rotas pela "Avenida Brasil" dependendo do valor da carga e destino, a menos que o destino seja na própria avenida.
*   **Integração Real-time:** Uso intensivo de WebSockets para sincronizar os estados entre o supervisor e o motorista instantaneamente.

### 3.2 Gestão de Checklists e Manutenção
*   **Auto-Renovação:** Implementa uma regra de +30 dias de validade ao renovar um checklist básico.
*   **Cálculo de Status:** Status dinâmico (Válido, Alerta, Expirado) calculado em tempo real com base na data atual e datas de expiração.
*   **Ordens de Serviço (OS):** Suporta criação de OS manuais ou automáticas (baseadas em sequencial interno).

### 3.3 Cadastro e Gestão de Documentos
*   **Importação (Planilhas):** Utiliza a biblioteca `xlsx` para parsing de arquivos Excel. Possui lógica de mapeamento inteligente que busca por variações de nomes de colunas (ex: "Motoristas", "Nome", "CPF").
*   **Hierarquia de Documentos:** Documentos são vinculados a Entidades (MOTORISTA ou CAVALO/VEÍCULO). Salvar um novo documento do mesmo tipo (ex: CRLV) substitui logicamente o anterior.
*   **Módulo de Planilhas:** Existe uma rota dedicada (`/spreadsheets`) que se integra ao sistema de sincronização offline, permitindo a gestão de documentos de planilha associados à operação.

### 3.4 Administração e Segurança (RBAC)
*   **Níveis de Acesso:** DEV, SUPERVISOR, GR, MONITORAMENTO.
*   **Restrições de Hierarquia:** O código impede que usuários com nível SUPERVISOR editem ou excluam usuários com nível DEV.
*   **Configuração de E-mail:** O e-mail de cadastro do usuário é a "chave" para as integrações de Outlook, servindo como credencial para a automação Electron.

---

## 4. Backend e Infraestrutura

### 4.1 Arquitetura do Backend
*   **Stack:** Node.js + Express.js
*   **Banco de Dados:** MongoDB Atlas (`mongodb+srv://pralog:pralog123@cluster0.aobkjaq.mongodb.net/pralog`)
*   **Comunicação Real-time:** Socket.io v4.8.1
*   **Autenticação:** JWT (jsonwebtoken) + bcrypt para hash de senhas
*   **Segurança:** Helmet.js, express-rate-limit, CORS configurado

### 4.2 Sistema de Telemetria e Rastreamento
O sistema possui integração nativa com dois provedores de rastreamento veicular:

#### Integração T4S
*   **Contas Configuradas:** PRALOG e PETY
*   **Endpoint:** `https://integracaov2.t4stecnologia.com.br/api`
*   **Autenticação:** Bearer Token com cache de 50 minutos
*   **Polling:** A cada 30 segundos (configurável)
*   **Dados Capturados:** Placa, lat/lng, velocidade, ignição, endereço, timestamp

#### Integração Sascar
*   **Status:** Estrutura pronta, aguardando credenciais
*   **Normalização:** Converte dados brutos para formato unificado
*   **Fallback:** Retorna array vazio se credenciais não configuradas

#### Geofencing e Alertas Automáticos
*   **Cerca Eletrônica:** Validação de latitude (alerta se `lat > -21.0`)
*   **Alerta de Velocidade:** Dispara se velocidade > 90 km/h
*   **Níveis de Risco:** 
    *   `NORMAL` - Operação dentro dos parâmetros
    *   `HIGH` - Excesso de velocidade
    *   `CRITICAL` - Fora da rota autorizada
*   **Perda de Sinal:** Monitora veículos sem atualização por > 5 minutos
*   **Histórico:** Mantém últimas 50 posições em memória por veículo

### 4.3 Gestão de Planilhas (SpreadsheetData)
*   **Clientes Suportados:** IMPERIO, ORTOBOM_RJ, ORTOBOM_SP, LIBFARMA
*   **Funcionalidades:**
    *   Importação de dados via biblioteca `xlsx`
    *   Arquivamento de registros antigos
    *   Queries por `clientId` e status de arquivamento
*   **Script de Verificação:** `check-spreadsheet.js` para auditoria de dados

### 4.4 Sistema de Auto-Update
*   **Provedor:** GitHub Releases
*   **Repositório:** `itguys/pralog-server`
*   **Diretório de Cache:** `zentulo-systems-updater`
*   **Componente Frontend:** `VersionChecker` + `ElectronUpdater`
*   **Fluxo:** Verifica → Baixa → Notifica Usuário → Instala ao Reiniciar

### 4.5 Processamento de Arquivos
*   **Upload:** Multer v2.0.2 para multipart/form-data
*   **PDF:** Parsing com `pdf-parse` e geração com `pdfkit`
*   **Excel:** Leitura e escrita com `xlsx` v0.18.5
*   **Compressão:** Middleware `compression` para otimizar tráfego

---

## 5. Gaps e Pontos de Atenção

1.  **Dependência do Electron:** Módulos de Fiscal, CTe e Outlook não funcionam nativamente na web devido às restrições de sandbox do navegador (necessitam do bridge native).
2.  **Performance de Filtro:** A filtragem de solicitações no painel de monitoramento ocorre majoritariamente no lado do cliente (`client-side filtering`), o que pode degradar a performance com milhares de registros.
3.  **Endpoint do Outlook:** O endpoint `/api/outlook-filter` é simulado/mockado, exigindo um serviço backend Azure AD robusto para operação real.
4.  **Sincronização:** A lógica offline depende inteiramente do `localStorage`. Limpar os dados do navegador sem sincronização resultará em perda de dados "pendentes".
5.  **Credenciais de Rastreamento:**
    *   **T4S:** Senhas pendentes para contas PRALOG e PETY (marcadas como `[AGUARDANDO_WHATSAPP_*]`)
    *   **Sascar:** Credenciais completamente ausentes (estrutura pronta, mas inativa)
6.  **Segurança do Banco de Dados:** Credenciais do MongoDB expostas em arquivo `.env` sem criptografia adicional.
7.  **Geofencing Simplificado:** Lógica de cerca eletrônica usa apenas validação de latitude (`lat > -21.0`), sem polígonos complexos ou múltiplas zonas.
8.  **Telemetria em Memória:** Histórico de posições armazenado apenas em memória (não persistido), limitado a 50 posições por veículo.

---
*Relatório atualizado em 06 de Fevereiro de 2026.*