ProtheusClientePadrao (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

Escopo deste arquivo:

- Este documento foi gerado exclusivamente a partir de wosk_protheus_padrao/wosk_protheus_padrao.php.
- Classes presentes neste arquivo: Monitor e Queue.
- Classe ausente neste arquivo: Webservice (não há endpoint implementado aqui).

Monitor

Processo: 
1. DESCRIÇÃO DO FLUXO

- Responsabilidade: capturar (de forma pontual/manual) registros de clientes da fonte SQL WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO e enfileirar cada registro para integração assíncrona.
- Disparo: operação manual via Monitor::capturar(chave).
- Observação crítica: o método Monitor::run() está vazio neste arquivo; portanto, não há captura automática/cron implementada aqui.

No fluxo manual, para cada chave informada, o processo:
- Reaproveita token existente na fila (quando houver item já criado) consultando Queue::get('', chave).
- Consulta a fonte SQL filtrando por A1_LOJA e A1_COD.
- Sanitiza o registro com trim() recursivo em todos os campos.
- Reestrutura o controle de posicionamento (novoFiltro) com A1_LOJA, A1_COD e DATA_PARA_TRANSFERENCIA (normalizada).
- Monta a chave da fila no formato A1_LOJA-A1_COD e enfileira via Queue::set() com status Aguardando Integração e situacao = 0.


2. DADOS NECESSÁRIOS PARA O ENDPOINT

Não há endpoint (WebService) implementado neste arquivo. Para o Monitor, os dados necessários são:

Entrada do processo manual:
- Parâmetro chave: string ou array.
- Formato obrigatório da chave: A1_LOJA-A1_COD.
- Regra: se a chave não possuir exatamente 2 segmentos, o processo lança exceção (Chave inválida).

Fonte de dados:
- View/Tabela lógica: WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO

Campos capturados (conjunto completo do viewQuery):
- Identificação: A1_COD, A1_LOJA
- Cadastro: CGC_CPF, NOME, PESSOA, NOME_REDUZ, TIPO, STATUS
- Endereço: ENDERECO, BAIRRO, COMPLEMENTO, UF, CEP, COD_MUNICIPIO_IBGE
- Contato: DDI, DDD, TELEFONE, CONTATO, EMAIL
- Documentos/Complementos: A1_PFISICA, A1_INSCR, INSC_MUNICIPAL, DATA_NASC
- País/Tributos/Outros: COD_PAIS_SISCOMEX, COD_PAIS_BC, A1_CONTA, A1_CONTRIB, A1_TPESSOA, A1_SUFRAMA, A1_CALCSUF, A1_CODMUN
- Controle incremental: DATA_PARA_TRANSFERENCIA


3. REESTRUTURAÇÃO DOS DADOS

3.1 Recuperação do estado do monitor
Momento: Não aplicado no fluxo atual (run() vazio).
- O controle de estado existe via Monitor::get()/Monitor::set(), persistindo em wosk_monitor quando utilizado por integrações que exigem retomada/continuidade.

3.2 Reset ao iniciar execução
Momento: Não aplicado no fluxo atual (run() vazio).

3.3 Normalização dos filtros
Momento: Pré-consulta no fluxo manual (capturar()).
- Deriva filtros diretamente da chave: A1_LOJA e A1_COD.

3.4 Atualização do estado para EXECUTANDO
Momento: Não aplicado no fluxo atual (não persiste situacao no capturar()).

3.5 Paginação dos registros
Momento: Não aplicável.
- A consulta manual filtra por chave e processa o resultado via fetch() sem paginação/offset.

3.6 Sanitização dos dados
Momento: Ao ler cada registro (loop de fetch).
- Aplica trim() recursivamente em todos os campos do registro.

3.7 Atualização do filtro de posição
Momento: Após ler o registro (fluxo manual).
- Define novoFiltro['A1_LOJA'] e novoFiltro['A1_COD'] com valores do registro.
- Normaliza novoFiltro['DATA_PARA_TRANSFERENCIA'] para Y-m-d H:i:s.

3.8 Enfileiramento
Momento: Dentro do loop do capturar().
- Monta key no padrão A1_LOJA-A1_COD.
- Enfileira via Queue::set(key, registro, [], 'Aguardando Integração', ...).
- Reaproveita token se o item já existir na fila (obtido via Queue::get).

3.9 Atualização incremental da posição
Momento: Não aplicável.
- O fluxo manual não atualiza offset/chave_posicao em wosk_monitor.

3.10 Finalização
Momento: Final do capturar().
- Não há persistência de encerramento do monitor (situação) neste fluxo manual; a finalização é implícita após enfileirar.

3.11 Tratamento de erro
Momento: catch(Exception) do capturar().
- Registra erro via errorByexception e encerra o processamento do lote atual.


4. PERSISTÊNCIA DOS DADOS (BANCO DE DADOS)

4.1 Controle do monitor
Momento: Quando Monitor::set() é utilizado (não ocorre no capturar()).
- Tabela persistida (implementação da trait wosk_monitor): {$this->bancoIntegrador}.wosk_monitor.
- Campos persistidos: token, evento, offset, filtro, chave_posicao, situacao, data_posicao, data_iniciado.

4.2 Fila de integração
Momento: Enfileiramento (3.8).
- Tabela persistida (biblioteca wosk_queue): {$this->bancoIntegrador}.wosk_queue.


5. RESULTADO DO PROCESSAMENTO

Execução normal:
- Itens gravados na fila com status Aguardando Integração para processamento posterior pela Queue.

Execução com erro:
- O erro é registrado e o item pode deixar de ser enfileirado (dependendo do ponto de falha).


6. OPERAÇÃO MANUAL – capturar()

Objetivo: enfileirar manualmente um ou mais clientes para integração, usando chave conhecida.

Fluxo:
- Entrada: chave string ou array, no padrão A1_LOJA-A1_COD.
- Para cada chave:
    - Consulta a fila para reaproveitar token (quando existir).
    - Consulta a fonte SQL filtrando por A1_LOJA e A1_COD.
    - Sanitiza o registro com trim() recursivo.
    - Enfileira via Queue::set() com status Aguardando Integração e situacao = 0.

Queue

Processo:
1. DESCRIÇÃO DO FLUXO

- Responsabilidade: consumir um item da fila, reestruturar/normalizar o payload para o padrão Protheus e executar o envio, persistindo retorno, tempo e status na própria fila.
- Disparo: execução agendada (cron) chamando Queue::run(token).

Ao iniciar, o processo busca um item via get(token). Se houver registro:
- Atualiza o mesmo para status Enviando e situacao = 1 antes do envio (marcando consumo em andamento).
- Converte o conteúdo persistido em payload de integração via getConteudo() (internamente _getConteudo), aplicando o mapeamento definido em $field.

Transformações e normalizações pré-envio (aplicadas no payload Protheus):
- A1_NOME e A1_NREDUZ: remove o caractere | e remove acentos.
- A1_END, A1_BAIRRO, A1_CONTATO: remove acentos.
- A1_CODPAIS: converte para inteiro e aplica zero-pad à esquerda até 5 dígitos.

Envio ao Protheus:
- Executa integração via setProtheus('cliente', payload, 'POST', headers).
- Header aplicado: tenantId no formato "01,01SD0001" (derivado de 01SD0001).

Validação e classificação do retorno:
- Se não houver resposta → erro: JSON: NÃO HOUVE RESPOSTA.
- Se resposta não for array ou não contiver Mensagem → erro: JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA.
- Situação final do item:
    - 2 quando sucesso (sem code e Mensagem diferente de ERRO).
    - 4 quando houver code no retorno ou quando Mensagem = "ERRO".
- Mensagem gravada prioriza Mensagem Detalhada (quando presente).

Ações adicionais por resultado:
- Sucesso (situacao = 2): marca como integrado via setProtheusClienteIntegrado(chave, true) e sinaliza remoção de itens correlatos na fila.
- Pós-sucesso (limpeza de fila): tenta remover registros relacionados em wosk_queue para as ações ProtheusCliente (por SUBSTRING_INDEX(chave, '-', 2)) e ProtheusClienteFull (por chave), evitando duplicidade de processamento.

Persistência do status do item (fila):
- Atualiza o item com retorno, mensagem, dump de requisição (_CURL_DUMP), tempo e situação final (2 ou 4).

Notificação de erros:
- O método notificar() consulta itens com acao = 'ProtheusClientePadrao' e situacao = 4 na tabela wosk_queue, formata a mensagem e aciona o mecanismo interno de notificação (_getNotificarErros).


2. DADOS NECESSÁRIOS PARA O ENDPOINT

Não há endpoint (WebService) implementado neste arquivo. Para a Queue, os dados necessários são os itens persistidos na fila.

Estrutura do item de fila (campos utilizados neste arquivo):
- token: identificador do item para consumo.
- acao: ProtheusClientePadrao.
- chave: A1_LOJA-A1_COD.
- conteudo: registro completo capturado (campos do cliente).
- data_adicionado: data/hora de captura gravada no enfileiramento.


3. REESTRUTURAÇÃO DOS DADOS

3.1 Recuperação do item de fila
Momento: Início do run(token)
- Lê item via get(token).

3.2 Reset ao iniciar execução
Momento: Antes do envio
- Atualiza o item para status Enviando e situacao = 1.

3.3 Normalização do payload
Momento: Pré-envio
- Aplica mapeamento de campos via $field durante getConteudo().

3.4 Atualização do estado para EXECUTANDO
Momento: Pré-requisição
- Mantém o item como situacao = 1 até classificar o retorno.

3.5 Paginação dos registros
Momento: Não aplicável (processa 1 item por execução).

3.6 Sanitização dos dados
Momento: Pré-envio ao Protheus
- Remove acentos e caracteres | em campos textuais.
- Normaliza A1_CODPAIS para 5 dígitos com zero-pad.

3.7 Atualização do filtro de posição
Momento: Não aplicável (controle de posição é do Monitor).

3.8 Envio / Integração
Momento: Envio ao Protheus
- Dispara setProtheus('cliente', payload, 'POST', headers).

3.9 Atualização incremental da posição
Momento: Não aplicável (não há offset nesta classe).

3.10 Finalização
Momento: Pós-resposta do Protheus
- Define situacao final (2 ou 4) e atualiza o item na fila com retorno, mensagem, dump e tempo.

3.11 Tratamento de erro
Momento: catch(Exception) interno do processamento do item
- Registra erro, define situacao = 4 e persiste a mensagem no item de fila.


4. PERSISTÊNCIA DOS DADOS (BANCO DE DADOS)

4.1 Controle do monitor
Momento: Não aplicável para esta classe (não grava wosk_monitor).

4.2 Fila de integração
Momento: Durante todo o ciclo do item (get/set).
- Tabela persistida: {$this->bancoIntegrador}.wosk_queue.
- Atualização de log (em falhas internas da infraestrutura): {$this->bancoIntegrador}.wosk_queue_log (biblioteca wosk_queue).


5. RESULTADO DO PROCESSAMENTO

Execução normal:
- Item atualizado para situacao = 2, com retorno persistido e cliente marcado como integrado.

Execução com erro:
- Item atualizado para situacao = 4, com retorno/mensagem persistidos para auditoria e notificação.


6. OPERAÇÃO MANUAL – capturar()

Não aplicável para esta classe (a operação manual está na classe Monitor).

Fluxo do Processo

Critérios de Aceitação