ProtheusClienteFull (STATUS: PARCIAL)

Documentação Técnica

Sumário

• Documentação Técnica
  
• Sumário
• Histórico de Versões
• Descrição Geral dos Processos
  • Monitor
  • Queue
• Fluxo do Processo
• Critérios de Aceitação

Histórico de Versões

Descrição Geral dos Processos

AEsta integraçãobiblioteca ProtheusClienteFull é composta por três camadas lógicas: Monitor, Queue e Sistema Externo (Protheus). O fluxo é totalmente assíncrono, controlado por persistência de estado e executado por agendamentos (cron).

O processo inicia no Monitor, responsável pela captura incremental de registros elegíveis na view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL. O Monitor controla continuidade por meio de offset, chave de posição e data de referência (DATA_PARA_TRANSFERENCIA), evitando reprocessamento indevido e garantindo ordenação cronológica. Cada registro identificado como elegível é sanitizado e enfileirado na tabela wosk_queue com status inicial “Aguardando Integração”. O estado da execução é persistido na tabela wosk_monitor, permitindo retomada controlada em caso de interrupção.

Apósdocumenta o enfileiramento, a responsabilidade é transferida para a Queue ProtheusClienteFull. Essa camada realiza o processamento assíncrono dos registros pendentes na fila (situacao = 0). Para cada item:

• Atualiza o status para “Enviando”.

• Reorganiza o payload conforme o mapeamento estrutural exigido pelo Protheus.

• Aplica normalizações finais (remoção de acentos, limpeza de caracteres inválidos, padronização de códigos).

• Executa o envio via integração HTTP.

• Interpreta a resposta da API.

• Atualiza a situação para sucesso (2) ou erro (4).

• Persiste retorno, mensagem, tempo de execução.

Em caso de sucesso, o registro é marcado como integrado.
Em caso de erro, o registro permanece armazenado com situacao = 4, mantendo histórico completo da falha e permitindo notificação e reprocessamento controlado.

A rastreabilidade é garantida por:

• Controle de estado no wosk_monitor.

• Controle transacional e auditoria detalhada no wosk_queue.

• Uso de chave composta (A1_LOJA-A1_COD) como identificador único.

• Persistência de token para controle de reprocessamento.

O fluxo fim-a-fim pode ser resumido da seguinte forma:

1. Monitor captura incrementalmente registros elegíveis.

2. Monitor persiste controle e envia registros para a fila.

3. Queue processa cada item de forma assíncrona.

4. Queue transforma e envia para o Protheus.

5. Queue registra sucesso ou erro com auditoria completa.

6. Em caso de falha, mecanismos de tratamento e notificação são acionados.

A arquitetura separa claramente responsabilidades:

Monitor → captura e controle incremental.
Queue → transformação, envio e auditoria.

Essa separação garante:

• Escalabilidade (processamento desacoplado).

• Continuidade transacional.

• Reprocessamento seguro.

• Controle de duplicidade.

• Observabilidade operacional.

Monitor

1. 1. DESCRIÇÃO DO FLUXO

O Monitor ProtheusClienteFull é responsável exclusivamente pela captura incremental de registros da view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL e pelo encaminhamento estruturado desses registros para a fila de integração de Clientes (Full) para o Protheus. Ela separa o trabalho em duas etapas: uma etapa de captura (Monitor) e outra de processamento assíncrono (Queue).

Na prática, o Monitor localiza os dados do cliente em uma visão de serviço e cria (ou atualiza) um item na fila para integração. Depois, a Queue consome esse item, prepara o payload final e realiza o envio para o Protheus, registrando o resultado para auditoria e acompanhamento.

O processoobjetivo do fluxo é acionadogarantir que o envio ocorra de forma controlada, com rastreabilidade de erros e possibilidade de reprocessamento, sem depender de uma execução única e sincrona.

Monitor

Conceito: Monitor

Processo: 
Classe: WOSK\ProtheusClienteFull\Monitor
Entrada: chave no formato A1_LOJA-A1_COD (ex.: 01SD0001-000123) ou lista de chaves.
Origem dos dados: consulta na view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL com WHERE construído dinamicamente a partir da chave.

Query base (sem filtro):

SELECT
    A1_COD,
    A1_LOJA,
    CGC_CPF,
    NOME,
    PESSOA,
    NOME_REDUZ,
    ENDERECO,
    BAIRRO,
    COMPLEMENTO,
    TIPO,
    UF,
    COD_MUNICIPIO_IBGE,
    CEP,
    DDI,
    DDD,
    TELEFONE,
    CONTATO,
    A1_PFISICA,
    A1_INSCR,
    INSC_MUNICIPAL,
    DATA_NASC,
    EMAIL,
    COD_PAIS_SISCOMEX,
    COD_PAIS_BC,
    A1_CONTA,
    A1_CONTRIB,
    A1_TPESSOA,
    A1_SUFRAMA,
    A1_CALCSUF,
    A1_CODMUN,
    STATUS,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL

WHERE dinâmico aplicado por agendamentochave:

WHERE
    A1_LOJA = '{A1_LOJA}'
    AND A1_COD = '{A1_COD}'

Reestruturações e transformações (cron)pré-insert atravésna fila):
- Todos os campos do métodoregistro run(retornado sofrem trim() (não tratado como alteração relevante).
- SuaO responsabilidadecampo DATA_PARA_TRANSFERENCIA é convertido/normalizado para Y-m-d H:i:s e usado como data de captura do item na fila.
- Destaque (conceito cronológico): ao normalizar e usar DATA_PARA_TRANSFERENCIA para ordenar/capturar, o fluxo passa a depender de data/hora como controle de processamento. Referência: Cronológico.

Persistência:
- O Monitor insere/atualiza o item na fila pela Queue (tabela wosk_queue) usando:

• acao:
  ProtheusClienteFull
  • chave:

    Recuperar{A1_LOJA}-{A1_COD}

  • conteudo: o estadoregistro anteriorbruto deretornado execução.
    pela view (inclui CGC_CPF, NOME, ENDERECO, etc.)
  • data_adicionado: DATA_PARA_TRANSFERENCIA normalizada
  • situacao: 0 (Aguardando integração)

  Controlar- continuidadeA incrementaltabela (offsetwosk_monitor eé chavea persistência padrão de posição).

• Evitar reprocessamento indevido.

• Garantir ordenação cronológica por DATA_PARA_TRANSFERENCIA.

• Persistir o o/controle transacional do processamento.

• Encaminhar registros válidos para a Queue.

Fluxo de execução:

1. 1. Recupera o estado atual do monitor na base de controle.

   2. Avalia a situação armazenada:

      • Se CONCLUÍDOMonitor (2)via →Monitor::set()), redefinequando parautilizada PARADOpelo (0).

      • Se PARADO (0) → reinicia execução.

      • Se EXECUTANDO (1) → continua do ponto persistido.

   3. Caso iniciado do zero:

      • Offset é redefinido.

      • Chave de posição é limpa.

      • Data de posição é reiniciada.

   4. Normaliza filtros internos.

   5. Atualiza situação para EXECUTANDO (1).

   6. Executa consulta paginada na view.

   7. Para cada registro retornado:

      • Sanitiza dados.

      • Atualiza filtro incremental.

      • Enfileira o registro na Queue.

      • Atualiza offset e posição no controle.

   8. Quando não houver mais registros:

      • Atualiza situação para CONCLUÍDO (2).

   9. Em caso de erro:

      • Atualiza situação para PROBLEMA (4).

      • Registra erro no filtro persistido.

O Monitor não realiza integrações externas nem transformações finais de payload. Sua responsabilidade termina no momento do enfileiramento.

2. DADOS NECESSÁRIOS

Ele opera sobre a view: WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL

Campos capturados:

A1_COD
A1_LOJA
CGC_CPF
NOME
PESSOA
NOME_REDUZ
ENDERECO
BAIRRO
COMPLEMENTO
TIPO
UF
COD_MUNICIPIO_IBGE
CEP
DDI
DDD
TELEFONE
CONTATO
A1_PFISICA
A1_INSCR
INSC_MUNICIPAL
DATA_NASC
EMAIL
COD_PAIS_SISCOMEX
COD_PAIS_BC
A1_CONTA
A1_CONTRIB
A1_TPESSOA
A1_SUFRAMA
A1_CALCSUF
A1_CODMUN
STATUS
DATA_PARA_TRANSFERENCIA

Campos obrigatórios para captura incremental:

A1_LOJA
A1_COD
DATA_PARA_TRANSFERENCIA

Esses campos compõem a chave lógica e o controle cronológico da captura.

3. REESTRUTURAÇÃO DOS DADOS

3.1 Recuperação do estado do monitor
Momento: Início do capturar()

Dados recuperados da tabela de controle:

offset
chavePosicao
dataPosicao
filtro
situacao
dataIniciado
token

Regra:
Se situacao = 2 (CONCLUÍDO) → redefinir para 0 (PARADO).

3.2 Reset ao iniciar agendamento/execução
Momento: Quando situacao ≠ 1

SELECT 
/*+ SQL_BIG_RESULT */ /*+ SQL_NO_CACHE */ `token`
FROM `{$this->bancoIntegrador}`.`wosk_queue`
WHERE `acao` = 'ProtheusClienteFull'
  AND `situacao` = 0
  {AND `data` <= '{agora - delay em minutos}'}
ORDER BY DATA_PARA_TRANSFERENCIA`data_adicionado` ASC

tenantId: "01,01SD0001"