01. Visão Geral

Este documento visa fornecer uma visão abrangente sobre a estrutura e funcionalidades do Protheus Insights, detalhando tanto a modelagem de dados quanto a infraestrutura backend, front-end, pipelines carol e data models carol. Seu propósito é esclarecer a arquitetura atual e sugerir melhorias para otimizar o processamento de mensagens de insights, aumentar a resiliência do sistema e facilitar o desenvolvimento de novas funcionalidades.


Estrutura e Componentes

A estrutura atual do Protheus Insights é composta por diversas tabelas que gerenciam alertas e insights. Embora funcional, essa estrutura foi inicialmente projetada como um protótipo e apresenta limitações significativas, como falta de visibilidade no recebimento de mensagens e travamentos no processamento. Este documento propõe uma nova estrutura mais eficiente, detalhando as novas tabelas (I19, I20, I21) e suas funções específicas para melhorar o controle, processamento e monitoramento de mensagens de insights. Além disso, descreve as atualizações necessárias no backend TOTVSApps e ADVPL, e sugere melhorias para o front-end, incluindo a implementação de uma nova biblioteca de serviços REST para suportar insights online de maneira mais eficiente.

02. Modelagem de Dados Protheus Insights

Estrutura Atual

A atual estrutura do Protheus Insights é constituída das seguintes tabelas:

• I14 - Controle de Msg Smartlink: Tabela de alertas de Insights (Permissão de Insight, Financeiros, Ruptura de Estoque, Demandas de Compras, Relatório de Previsão de Fluxo de Caixa);
• I16 - Insight Contabil: Tabela de matches de Insights Contábeis provenientes dos Alertas de Insights Contábeis;

Apesar desta estrutura estar funcional, ela foi criada como protótipo e apresenta diversas limitações no controle de recebimento e processamento de mensagens de insight provenientes do Smartlink e será descontinuada com a implementação da estrutura sugerida mais abaixo.

Algumas destas limitações são:

• Falta de visibilidade no recebimento de mensagens de insights por parte do cliente Protheus;
• Travamento da thread do consumer de mensagens devido ao processamento de regras de insights no recebimento;
• Limitação no desenvolvimento de novos insights tornando-os, aumentando os custos e requerimentos de recursos para o desenvolvimento dos mesmos;
• Pouco tolerante a falhas;

Estrutura Sugerida

Para a nova estrutura sugerida serão implementadas as seguintes tabelas: 

• I19 - Controle Mensagens de Insights: Tabela utilizada para Controle de Recebimento e Status de Mensagens de Insights provenientes do Smartlink, para serem utilizadas em futuros processamentos de Regras de Negócios de Insight;
• I20 - Configurações de Insights: Tabela utilizada para armazenamento das configurações de Processamento de Insights;
• I21 - Insights Unificada: Tabela unificada utilizada para armazenamento do produto do processamento das regras de negócios de insights;

Vantagens da Estrutura Sugerida:

• Maior controle e monitoramento no recebimento de mensagens de Insights pelo cliente Protheus;
• Modelo configurável e flexível de Regras de Negócios aplicadas as mensagens de Insights;
• Maior visibilidade nos resultados dos processamentos das Regras de Negócios;
• Tabela unificada para armazenamento de resultado de processamento posteriormente utilização dos dados por parte do ERP;
• Melhor tolerância a falhas;
• Baixa requisição de recursos (financeiros e temporais) para o desenvolvimento de Insights;

03. Backend TOTVSApps

Estrutura Atual

A atual infra-estrutura do Protheus Insights Totvs Apps pode ser apresentada pelo seguinte diagrama:

A atual estrutura do Protheus Insights Totvs Apps provou ser uma estrutura resiliente porém, com algumas limitações, as quais serão minimizadas na estrutura proposta mais abaixo.
Algumas destas limitações são listadas a seguir:

• Esquema de autenticação fraco utilizando-se de chaves de API;
• Armazenamento de dados de diversos Tenants em mesmas tabelas, facilitando o vazamento de informações entre Tenants se muita precaução não for tomada na descida de mensagens para a fila do SmartLink;
• Não possui suporte 100% a Insights Online;
• Difícil enumeração de custo de recurso por Tenant;

Estrutura Proposta

A estrutura proposta para o Totvs Apps Protheus Insights visa melhorar a atual estrutura, adicionando novos recursos para aumentar sua resiliência a falhas de disponibilidade e segurança. Esta estrutura contará com a implementação de um banco de dados com a separação de schemas por Tenants, novos meios de autenticação de clientes e novas APIs que suportarão também o uso de Insights Online.

As vantagens apresentadas a seguir estarão efetivamente em funcionamento no momento de sua implementação:

• Esquema de autenticação integrado com o Fluig Identity para Tenants e usuários da API de administração (utilizando JWT);
• Base de dados Multi-Tenant para armazenamento de mensagens de Insights provenientes do Big-Query Carol;
• Tabela unificada de armazenamento de Modelos de Insights;
• Provisionamento em real-time de novos schemas para recém adicionados Tenants;
• APIs seguras de gerenciamento de Provisionamento e controle de Mensagens de Insights;
• Novo sistema de mensageria capaz de processar requisições de Insights Online;
• Melhor visibilidade nos recursos utilizados por cada Tenant, devido ao banco de dados multi-esquema;

04. Backend ADVPL

Estrutura Atual

Esta atual estrutura de Insights desenvolvida para o cliente Protheus, tem se provado pouco eficiente no tratamento de mensagens on-line e pouco resiliente no tratamento de exceções quando o processamento de mensagens de Insights.

Um outro ponto de atenção é o desempenho no recebimento de mensagens e a execução do processamento da Regra de Negócio do Insight na mesma Thread de recebimento da mensagem, o que impossibilita o Smartlink de processar novas mensagens enquanto as Regras para a atual ainda estiver processando, causando um congestionamento na liberação da fila em momentos de muita demanda.

A seguir serão apresentados alguns pontos que fez parte do aprendizado com a implementação desta estrutura:

• Congestionamento de Fila: Como mencionado anteriormente, a execução de Regras de Negócio de Insights na mesma thread de recebimento da mensagem causa atraso no recebimento de novas mensagens o que torna inviável a utilização desta estrutura em ambientes de alta demanda/disponibilidade;
• Flexibilidade de Dados: Quando utilizada a definição de "criação de uma tabela por Insight", o processo de desenvolvimento de novos Insights torna-se lento e dependente de janelas específicas de release que estão fora do controle da equipe;
• Complexidade do Desenvolvimento: Novos insights tornam-se cada vez mais complexos de serem desenvolvidos devido a certas limitações apresentadas pela inflexibilidade de dados;
• Desempenho Insatisfatório para Insights Online: O congestionamento de Fila torna o custo de tempo para uma resposta de insights online praticamente inviável e pouco performático (como por exemplo o Insight Financeiro de Relaótio de Fluxo de Caixa);
• Limitação de Front-End (Angular App): Os atuais aplicativos utilizando Angular/PO-UI estão utilizando o mecanismo de websocket WebChannel para comunicação com a thread protheus, isto inviabiliza certas funcionalidades como por exemplo paginação de payload de resposta do endpoint;

Estrutura Proposta

A estrutura proposta visa implementar um sistema mais eficiente no recebimento de mensagens de Insights, mais resiliente a falhas e transparente durante o processo desde o início até sua conclusão.

A seguir será apresentado um resumo do funcionamento desta estrutura:

Public Method ProcessInsight(oInsightMessage As Object) As Logical
Public Method GetKey() As Character
Public Method GetFilter() As Character
Public Method GetDateFrom() As Date
Public Method GetDateTo() As Date

#INCLUDE "tlpp-core.th"
#include 'totvs.ch'

NAMESPACE defina.seu.namespace
USING NAMESPACE totvs.protheus.backoffice.ba.insights

Class SimpleInsightProcess From InsightsProcess
    
    Public Data oJsonPayload       As Object

    Public Method New() Constructor

    // Overrides
    Public Method ProcessInsight(oInsightMessage As Object) As Logical
    Public Method GetKey() As Character
    Public Method GetFilter() As Character
    Public Method GetDateFrom() As Date
    Public Method GetDateTo() As Date

EndClass

Method New() Class PermissionAlertsProcess
    _Super:New()
Return Self

Method ProcessInsight(oInsightMessage As Object) As Logical Class PermissionAlertsProcess

    Local lProcessOk        As Logical
    Local oException        As Object
    Local oInsightEntry     As Object
    Local xJsonParse        As Variant
    Local lReprocess        As Logical

    _Super:ProcessInsight(oInsightMessage)

    Try
        // Extrai o payload da mensagem e aloca o atributo oJsonPayload
        // para futura utilizacao em outras funcoes que serao executadas
        ::oJsonPayload := JsonObject():New()
        xJsonParse := ::oJsonPayload:FromJson(oInsightMessage:cMsgPayload)

       	// Atualiza mensagem de insight (tabela I19) com a informação de início de processamento
		oInsightMessage:UpdateProc("Processamneto de insight iniciado", .T., ::oInsightConfig:cVersao)

        // Inicia uma nova linha de insight (tabela I21)
        oInsightEntry := InsightEntry():New()
        
        oInsightEntry:cMsgUuid := ::oInsightMessage:cMsgUuid
        oInsightEntry:cInsightName:= ::oInsightMessage:cMsgInsight
        oInsightEntry:cModulo := cModulo
        oInsightEntry:cPayload := ::oJsonPayload:toJson()
        oInsightEntry:cDtProcess := FWTIMESTAMP(5)
        oInsightEntry:cVersaoProcess := ::oInsightConfig:cVersao

        // Calcula o campo key (I21_KEY) - Opcional
        If ::oInsightConfig:lCalcKey
            oInsightEntry:cKey := ::GetKey()
        EndIf

        // Calcula o campo key (I21_FILTER) - Opcional
        If ::oInsightConfig:lCalcFilter
            oInsightEntry:cFilter := ::GetFilter()
        EndIf

        // Retorna as datas referente aos campos I21_DTDE e I21_DTATE - Opcional
        oInsightEntry:dDataDe   := ::GetDateFrom()
        oInsightEntry:dDataAte  := ::GetDateTo()
        
        // Insere a linha da I21 na tabela
        oInsightEntry:Insert(lReprocess)
        oInsightMessage:UpdateProc("Processamneto de insight finalizado", .T., ::oInsightConfig:cVersao)
        lProcessOk := .T.
    Catch oException
        lProcessOk := .F.
		// Caso exista alguma excecao no processamento, informa na tabela I19 o erro de processamento
        oInsightMessage:UpdateProc("Processamneto de insight finalizado com erro: " + oException:description, .F., ::oInsightConfig:cVersao)
        Throw oException
    Finally
        FreeObj(oInsightEntry)
    EndTry

Return lProcessOk

Method GetKey() As Character Class PermissionAlertsProcess
	// Retorna um valor caracter que pode ser utilizado para pesquisar o registro por SQL na tabela I21 campo I21_KEY
    Local cKey As Character
    cKey := ::oJsonPayload["key"]
Return cKey

Method GetFilter() As Character Class PermissionAlertsProcess
	// Retorna um valor caracter que pode ser utilizado para filtrar o registro por SQL na tabela I21 campo I21_FILTER 
	Local cFilter As Character
	cFilter := ::oJsonPayload["key"] + ::oJsonPayload["filter"]
Return cFilter

Method GetDateFrom() As Date Class PermissionAlertsProcess
	// Retorna um valor do tipo data que pode ser utilizado para pesquisar o registro por SQL na tabela I21 campo I21_DTDE
Return dDataBase

Method GetDateTo() As Date Class PermissionAlertsProcess
	// Retorna um valor do tipo data que pode ser utilizado para pesquisar o registro por SQL na tabela I21 campo I21_DTATE
Return StoD(::oJsonPayload["dataAte"])

05. Front-End

A estrutura de execução de um aplicativo de Front-End do Protheus Insights será remodelada e terá a adição de uma biblioteca de serviços REST que farão parte da biblioteca de Insights (ADVPL) disponibilizada pela equipe de BA.

Estas alterações visam remover a limitação imposta pela utilização do WebChannel como meio de comunicação e bem como habilitando a utilização de Insights On-Line de uma forma simples.

Uma biblioteca desenvolvida para o framework Angular será implementada para intermediar a comunicação com os serviços disponibilizados pelo back-end Protheus de uma forma modular e simples.

06. Pipelines Carol

Esta seção está em desenvolvimento e será atualizada em breve.

07. Data Models Carol

Esta seção está em desenvolvimento e será atualizada em breve.