209 lines
10 KiB
Markdown
209 lines
10 KiB
Markdown
# 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.*
|