Documentação Técnica — Lorentz Server¶

1. Visão geral da arquitetura¶

O Lorentz Server é uma aplicação .NET 9 que funciona como Background Service (serviço hospedado), executando um ciclo de processamento contínuo a cada segundo.

Componentes principais¶

LorentzCTI/
├── Program.vb             Ponto de entrada — configura o host
├── Worker.vb              Serviço em background — ciclo principal
├── modPhoenixCTI.vb       Módulo global — variáveis compartilhadas e TCP/UDP
├── Classes/
│   ├── clsServidor.vb     Servidor principal — distribuição de chamadas
│   ├── clsProcesso.vb     Sessão de agente/supervisor conectado
│   ├── clsDispositivo.vb  Ramal/tronco monitorado
│   ├── clsClienteWeb.vb   Agentes web (comunicação via banco de dados)
│   ├── clsData.vb         Camada de acesso a dados (SQL Server)
│   ├── clsParametro.vb    Leitura/escrita do arquivo .ini
│   ├── clsLog.vb          Sistema de logging em arquivos
│   ├── clsLicenca.vb      Validação de licença
│   ├── ICentral.vb        Interface para centrais telefônicas
│   ├── cls3cx.vb           Implementação para 3CX
│   ├── clsImpacta.vb      Implementação para Asterisk/Intelbras
│   ├── clsCanal.vb        Canal de comunicação (Asterisk)
│   └── AESCrypt.vb        Criptografia AES para senhas
└── CSTA/
    └── clsAsnOne.vb       Processamento ASN.1 para protocolo CSTA

2. Modelo de execução¶

Inicialização¶

1. Program.vb cria um HostApplicationBuilder com .NET Generic Host
2. Registra Worker como BackgroundService
3. Worker.ExecuteAsync() instancia o servidor e entra em loop

Loop principal¶

Worker.ExecuteAsync():
    ServidorCTI = new clsServidor()     ← abre portas, conecta centrais
    while not cancellation:
        ServidorCTI.Servidor()           ← ciclo completo
        await Task.Delay(1000)           ← intervalo de 1 segundo

Inicialização do servidor¶

O construtor do servidor realiza:

1. Lê parâmetros do arquivo .ini
2. Abre socket TCP na porta de integração (agentes desktop)
3. Abre socket TCP na porta de serviço (Supervisor web)
4. Abre socket TCP na porta URA (IVR)
5. Conecta-se a cada central telefônica configurada (suporta múltiplas)
6. Atualiza banco de dados com evento de reinício do servidor

3. Portas e protocolos¶

Protocolo de comunicação com agentes¶

Os pacotes são delimitados por CHR(3) (início) e CHR(7) (fim), com campos separados por ;:

CHR(3) + código_pacote + ";" + sequência + ";" + dados... + CHR(7)

Códigos de pacote (agente ↔ servidor)¶

Pacotes de notificação (servidor → agente, código 0)¶

4. Protocolo de monitoramento (UDP)¶

O monitor externo se comunica via pacotes UDP com cabeçalho de 3 bytes:

Byte 0: 0x30 + (comprimento >> 8)
Byte 1: comprimento AND 0xFF
Byte 2: código do comando
Byte 3+: dados (texto Latin1)

5. Protocolo XML da URA¶

A URA se comunica via TCP na porta 4000 com mensagens XML:

Screen Pop (URA → Servidor)¶

<URA>
  <acao>screenpop</acao>
  <ramal>200</ramal>
  <!-- dados adicionais específicos do cliente -->
</URA>

Pesquisa de chamada (URA → Servidor)¶

<URA>
  <acao>pesquisa</acao>
  <ramal>200</ramal>
</URA>

Resposta da URA (URA → Servidor)¶

<URA>
  <acao>resposta</acao>
  <codigo>12345</codigo>
  <!-- dados de navegação -->
</URA>

Respostas do servidor¶

<URA><acao>screenpop</acao><retorno>sucesso</retorno></URA>
<URA><acao>screenpop</acao><retorno>falha</retorno></URA>
<URA><acao>pesquisa</acao><retorno>sucesso</retorno><codigo>12345</codigo></URA>

6. Interface com centrais telefônicas¶

O servidor utiliza uma interface comum para todas as centrais, permitindo trocar a implementação sem alterar o restante do sistema.

Operações suportadas¶

Implementações disponíveis¶

• 3CX (cls3cx.vb): conexão via API/banco de dados do 3CX
• Intelbras/Asterisk (clsImpacta.vb): conexão via protocolo CSTA/ASN.1 ou AMI

7. Agentes web (sem TCP)¶

O mecanismo de agentes web permite que operadores utilizem o sistema via navegador, sem instalar o aplicativo desktop. A comunicação acontece inteiramente via banco de dados:

Tabela de situação CTI¶

Ciclo de comunicação¶

1. Agente web grava comando na coluna "Cliente"
2. Servidor lê a coluna a cada 1 segundo
3. Servidor processa o comando (mesmo formato de pacote dos agentes TCP)
4. Servidor grava resposta na coluna "Servidor"
5. Agente web lê a resposta

8. Algoritmo de distribuição (ACD)¶

Seleção de agente¶

1. Para cada chamada na fila (ordenada por hora de entrada): a. Consulta se o serviço permite distribuição b. Carrega o fluxo de roteamento do serviço c. Para cada etapa do fluxo:
   • Se grupo: procura agente livre (prioritário primeiro, depois mais antigo)
   • Se agente: verifica se o agente específico está livre
   • Se ramal: verifica se o ramal está desocupado
   • Se condição: avalia e segue caminho verdadeiro ou falso d. Se encontrou destino: transfere a chamada via central e. Se transbordo expirou: avança para próxima etapa

Critérios para agente estar "disponível"¶

Um agente é considerado disponível quando todas as condições são verdadeiras:

• Está no grupo correto
• Tem receptivo ativado
• Ramal está livre
• Pausa está desligada
• Está logado (com apelido definido)
• Não está selecionado para outra distribuição

Prioridade¶

• Agentes com receptivo prioritário são avaliados primeiro
• Entre agentes com mesma prioridade, o que está livre há mais tempo é selecionado

9. Armazenamento de configuração¶

O arquivo .ini usa formato INI padrão com seção [Parametros]:

[Parametros]
ServidorSQL=127.0.0.1
BancoSQL=LorentzCTI
UsuarioSQL=sa
SenhaSQL=<criptografado>
PhoenixPortaTCP=8001
CTI_Impacta_Ip=192.168.1.10
CTI_Impacta_Porta=7001
Fabricante=3CX
Modelo=3cx

• O arquivo é criado automaticamente se não existir
• Senhas são armazenadas com criptografia simétrica
• O encoding é Latin1 (ISO-8859-1)
• Alterações via Monitor CTI são gravadas imediatamente

10. Criptografia¶

O sistema utiliza dois métodos de criptografia:

11. Considerações de desempenho¶

• O servidor processa uma chamada por ciclo na distribuição (para evitar condições de corrida)
• A fila de espera usa SortedDictionary para ordenação eficiente por timestamp
• Sessões de URA expiram automaticamente após 5 minutos sem atividade
• Limite de 50 conexões simultâneas de URA (proteção contra vazamento)
• O fluxo de roteamento tem limite de 50 etapas por avaliação (proteção contra loop infinito)
• A atualização de fila de espera para supervisores ocorre a cada 25 ciclos (~25 segundos)
• O garbage collector é invocado explicitamente ao fim de cada ciclo

Última atualização: Junho 2025