teste
/
testes
Template
2
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects 1 Releases Wiki Activity
testes/docs/zentulo_system_deep_dive.md

10 KiB
Raw Permalink Blame History

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.

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.

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.

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.

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.

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.