Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

...

Índice


01. Visão Geral

...

01. VISAO GERAL

02. ARQUITETURA PROTHEUS INSIGHTS

Image Removed

03. ARQUITETURA TOTVS APPS

...

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;


Deck of Cards
idtableStructure
Card
labelControle Mensagens de Insights

Nesta nova estrutura, existirá a possibilidade de monitorar o recebimento de mensagens e seu conteúdo real através da tabela I19, onde as mensagens serão armazenadas para análise e posterior processamento/re-processamento, liberando assim a thread do consumer do Smartlink para posteriores recebimentos, solicitando baixa quantidade de recurso e tempo de execução para o simples recebimento de mensagens de insights.


CampoTipoTamanhoTítuloDescrição
I19_FILIALCaracter8FilialFilial do Sistema
I19_UIDMSGCaracter36Message UUIDID da Mensagem (UUID)
I19_TIDMSGCaracter36Transact. IDID da Transação da Mensagem
I19_TENANTCaracter36Tenant UUIDID do Rac Tenant
I19_INSIGTCaracter30Tipo InsightTipo de Insight
I19_PAYLODMemoXXPayload MensConteúdo da Mensagem
I19_DTRECVCaracter30Dt. Recebim.Data de Recebimento
I19_STRECVCaracter3Status Rece.Status do Recebimento
I19_DTSCHDCaracter30Dt. Agend.Data do Último Agendamento
I19_DTPROCCaracter30Dt. Process.Data do Último Processamento
I19_STPROCCaracter3Status Proc.Status do Último Processamento
I19_LSTPRVCaracter6Ult. Vers. PÚltima Versão da Configuração de Processamento
I19_LSTPRMMemoXXUlt. Pr. MsgMensagens de Processamento
Card
labelConfigurações de Insights

Com a criação da tabela I20, poderão ser armazenados os tipos de Insights que serão processados pelo cliente Protheus e suas respectivas classes de processamento das Regras de Negócio, as quais deverão ser desenvolvidas em ADVPL/TLPP e adicionadas ao repositório, facilitando assim o desenvolvimento de novos insights. Estas configurações podem ser controladas também por um versionamento, o que facilita o rastreio de alterações no decorrer do tempo para cada tipo de Insight.


CampoTipoTamanhoTítuloDescrição
I20_FILIALCaracter8FilialFilial do sistema
I20_INSIGTCaracter30InsightTipo de Insight
I20_VERSAOCaracter6Versao InsigVersão da Configuração
I20_CLSPRCCaracter254Classe Proc.Classe de Processamento da Regra de Negócio
I20_PRIORILógico1PrioritarioIndica se Insight é Prioritário
I20_HASKEYLógico1Calc. ChaveIndica se Insight Calcula Chave de Busca
I20_HASFILLógico1Calc. FiltroIndica se Insight Calcula Filtro de Pesquisa
I20_STATUSCaracter1Status Conf.Status da Configuração, Ativo = 1
I20_DTCREACaracter30Dt. CriacaoData de Criação da Configuração
I20_DTALTCaracter30Dt. Altera.Data de Alteração da Configuração
I20_TABLESCaracter254Aliases UtilTabelas para abertura de ambiente, referente a Regra de Negócio (ex. SA1,SB1)
Card
labelInsights Unificada

A tabela I21 é uma implementação de tabela unificada de Processamento de Insights, ela poderá ser adotada pelas classes de Regras de Negócio para armazenamento do produto resultante do processamento aplicado a uma mensagem de Insight. Esta tabela suporta o armazenamento de dados diversos formatos através de um campo MEMO (inclusive JSON) e possui campos  facilitadores de busca e filtro bem como campos para data inicial e final (todos usados de forma opcional na utilização da classe de regra de negócio).


CampoTipoTamanhoTítuloDescrição
I21_FILIALCaracter8FilialFilial do Sistema
I21_BRANCHCaracter8Filial InsigCampo de controle de Filiais abrangidas pelo Insight (não controlada pelo sistema)
I21_UIDINSCaracter36Id. InsightID da linha de Insight
I21_UIDMSGCaracter36Id MensagemID da mensagem de origem do Insight (I19)
I21_INSIGTCaracter30InsightTipo de Insight
I21_MODULOCaracter20Modulo InsigModulo do Insight
I21_PAYLODMemoXXPayload Ins.Conteúdo do Insight
I21_KEYCaracter240Chave BuscaCampo de Chave unica de busca a ser gerada pelo processamento da Regra de Negócios referente ao Insight (opcional)
I21_FILTERCaracter240FiltroCampo de Valor de Filtro de busca a ser preenchido pelo processamento da Regra de Negócios referente ao Insight (opcional)
I21_DTDEData8Data DeCampo de Valor de Data Inicial de busca a ser preenchido pelo processamento da Regra de Negócios referente ao Insight (opcional)
I21_DTATEData8Data AteCampo de Valor de Data Final de busca a ser preenchido pelo processamento da Regra de Negócios referente ao Insight (opcional)
I21_DTPROCCaracter30Dt. Process.Data do último processamento
I21_VSPROCCaracter6Vers. Proce.Última versão de configuração de processamento (I20)
I21_STATUSCaracter3StatusStatus do último processamento
I21_DESCSTCaracter50Desc. StatusDescrição do status de último processamento
I21_DTREPRCaracter30Dt. Reproce.Data do último re-processamento
I21_VSREPRCaracter6Vers. Repro.Versão do último re-processamento


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:

Image Added

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

Image Added

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

Image Added

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

Image Added

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:


Deck of Cards
historyfalse
idFuncionamentoEstrutura
Card
labelRecebimento e Agendamento

Recebimento e Agendamento de Processamento de Mensagens


Durante o recebimento de uma nova mensagem de insight (InsightModel), o processo "InsightModels Message Consumer" será responsável por fazer uma breve validação estrutural da mensagem e gravar o recebimento de nova mensagem, ou atualização de antiga mensagem na tabela I19 e, em seguida, delegará para o "Agendador de Processamento de Insight" a responsabilidade de direcionar para o local de execução desta mensagem, utilizando o tipo de Modelo de Insight recebido será adquirida a configuração de Insight (tabela I20) para o tipo de Modelo e última versão ativa.

Esta configuração define se o Insight possui prioridade comum de execução ou trata-se de um insight prioritário:

Prioridade Comum: Insights de prioridade comum serão agendados utilizando a ferramenta de "Gerenciamento de Tarefas" disponibilizada pelo Totvs Framework e o processo do Agendador será finalizado;

Insight Prioritário: Insights Prioritários devem ser executados no momento de seu recebimento, o "Agendador de Processamento de Insight" não agendará este insight do modo convencional, ele executará uma nova thread delegando para o "Executor de Mensagens de Insights" a execução. Como esta chamada de uma nova thread não depende de uma resposta de retorno, o processo do Agendador pode ser finalizado;

Após a finalização desta decisão, o processamento da mensagem será concluído, retornando assim um reconhecimento de recebimento da mensagem para o SmartLink, removendo a mensagem da fila e disponibilizando o Consumer para recebimento da próxima mensagem.

Card
labelExecução de Mensagens

Execução de Mensagens de Insight

Quando solicitada a execução de uma mensagem de Insight, o ID da mensagem (tabela I19), bem como sua configuração (tabela I20) deverão ser informados para o "Executor de Mensagens de Insight".

Este então será o responsável por instanciar a classe de Regra de Negócios informada na configuração do tipo de modelo de Insight (tabela I20) e iniciar o processamento chamando as funções definidas pela classe de interface que toda classe de Regra de Negócios de Insights deve implementar.

Recomenda-se a utilização de uma rotina em TLPP para desenvolvimento da classe de Regra de Negócio e a utilização do NAMESPACE "totvs.protheus.backoffice.ba.insights" para então implementar a interface InsightsProcess.

Os métodos a serem implementados deverão ser os seguintes:


Bloco de código
themeMidnight
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


Um exemplo simples de implementação de uma classe de Regra de Negócios de Insights utilizando a tabela de Insights Unificada (I21)

Bloco de código
themeMidnight
#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"])

Dica

Os objetos oInsightMessage e oInsightConfig são providos pelo "Executor de Mensagens de Insight" e referentes a Mensagem de Insight (tabela I19) e Configuração de Insight (tabela I20) referentes a mensagem a ser processada.

A utilização da Tabela de Insights Unificada (I21) é opcional e vai de acordo com a necessidade de cada Regra de Negócio em particular.

Card
labelProcessamentos Agendados

Execução de Processamentos Agendados

A execução do processamento de Insights deverá ocorrer de acordo com a ferramenta de "Gerenciamento de Tarefas" e esta iniciará o processamento do Insight em seu tempo seguindo os mesmos passos da Execução de Mensagens de Insight

Card
labelInsights On-Line

Insights On-Line

A requisição de um Insight On-Line deve partir da rotina que foi executada durante a utilização do usuário e deve ser realizada através da biblioteca de Insights disponiblizada pela equipe de BA.

Esta solicitação então será encaminhada para a fila do SmartLink que será processada pelo Protheus Insights Totvs Apps e será retornada e processada pela rotina de Recebimento e Agendamento

Aviso
O Insight On-Line deve ter a configuração como Insight Prioritário na tabela de Configurações de Insight (I20)


05. Front-End

Image Added


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. Arquitetura Carol

Image Added


Glossário

Customer Organization: Ambiente de administração geral que agrupa as várias Tenants de clientes.

Unified Tenant: Ambiente Unificado que recebe os dados de todos os clientes e faz o processamento dos insights.

Staging Area: Área de preparação, ou zona de aterrissagem, é uma área de armazenamento intermediária usada para armazenamento dos dados brutos, antes do processamento. 

ERP Connectors: Conjunto de conectores responsáveis por receber os dados dos ERPs.

Insights Connector: Conjunto de conectores responsáveis por receber os dados de insights. Cada insight possui o seu conector. 

Data Transformation Pipelines: Conjunto de pipelines responsáveis pela transformação dos dados dos ERPs em modelos de dados genéricos que serão consumidos pelos modelos de Machine Learning.

AI Process: Conjunto de Carol Apps (Batch e Online) responsáveis pelo processamento dos insights.

Batch Apps: Aplicativos responsáveis pelo processamento dos insights com execução agendada.

Service Account: Conta de serviço utilizada para comunicação com os serviços do GCP.

Data Validation: Batch App responsável pela validação dos dados.

BQ ML: Tecnologia utilizada para criar e executar modelos de machine learning (ML) usando consultas do GoogleSQL. 

Vertex AI: Plataforma de desenvolvimento de IA unificada e totalmente gerenciada.

Workflow: Aplicativo utilizado para orquestração dos serviços de machine learning. 

Terraform: Ferramenta de infraestrutura como código usada para provisionar recursos e permissões para vários serviços do Google Cloud, incluindo a Vertex AI.

Cloud Functions: Solução de computação sem servidor do Google para criar aplicativos baseados em eventos.

Alerts Management: Módulo de alertas da plataforma Carol que possibilita a monitorização de eventos na esteira de dados da plataforma. 

Pipelines: Pipelines SQL utilizados para processamento dos dados e geração dos golden records.

Data Models:  Estrutura e regras de dados que transformam staging tables em Golden Records;

Data Sync: Solução que tem como principal objetivo enviar registros armazenados em Data Models para bancos de dados de baixa latência e alta disponibilidade (como por exemplo o PostgreSQL).

Looker Studio: Ferramenta on-line para criação de relatórios e painéis informativos personalizáveis a partir de banco de dados, possui integração com o Big Query.

Totvs Apps: Plataforma de software para as aplicações cloud native da TOTVS.


07. Data Model (Unified Insights)

Tabela única responsável por armazenar os dados de todos os insights.

CampoTipoTítuloDescrição
branchStringBranchEmpresa | Unidade de Negócio | Filial dos dados de origem do insight
company_groupStringCompany GroupCompany Group dos dados de origem do insight
insightStringInsightIdentificador do Insight
tenantidStringTenant IdTenant Id dos dados de origem do insight
keyStringKeyChave de negócio do insight
jsoncontentStringJson ContentJson contendo os dados do insight