ProtheusCliente (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_protheuscliente/protheusCliente.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: executar captura incremental de clientes a partir de uma fonte SQL e enfileirar cada registro para processamento assíncrono.
- Disparo: execução agendada (cron) chamando Monitor::run().

Ao iniciar, o processo carrega o estado persistido do monitor via get("ProtheusCliente"), obtendo:
- data_posicao, data_iniciado, offset, chave_posicao, filtro, token e situacao.

Regras de continuidade:
- Se situacao = 2 (Concluído) → redefine para 0 (Parado) e permite nova execução.
- Se situacao estiver em [0, 1] → inicia/continua o processamento.

Quando inicia a partir de estado não-executando (situacao ≠ 1):
- dataPosicao ← agora
- dataIniciado ← agora
- offset ← 0
- chavePosicao ← vazio

Em seguida, normaliza o filtro (garantindo defaults) e define a data mínima de captura:
- A1_LOJA, A1_COD, CGC_CPF → string vazia quando ausente
- DATA_PARA_TRANSFERENCIA → se ausente, define 2023-05-01 00:00:00

O monitor executa paginação com OFFSET/FETCH NEXT usando limite configurado em woskLimiteCaptura::ProtheusCliente, consultando a fonte WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES com:
- WHERE DATA_PARA_TRANSFERENCIA >= filtro.DATA_PARA_TRANSFERENCIA
- ORDER BY DATA_PARA_TRANSFERENCIA ASC

Para cada registro retornado:
- Sanitiza os valores com trim() (recursivo em todos os campos).
- Atualiza o filtro de posição (A1_LOJA, A1_COD, CGC_CPF, DATA_PARA_TRANSFERENCIA).
- Monta a chave da fila no formato: A1_LOJA-A1_COD-CGC_CPF.
- Enfileira via Queue::set() com status Aguardando Integração e situacao = 0.
- Persiste incrementalmente offset, chavePosicao e dataPosicao após enfileirar.

Encerramento:
- Quando não há mais registros, marca o monitor como situacao = 2 (Concluído) e persiste o último filtro efetivo.

Em caso de erro (catch):
- Marca o monitor como situacao = 4 (Problema).
- Armazena a mensagem em filtro.ERRORS[] com data e descrição do erro.


2. DADOS NECESSÁRIOS PARA O ENDPOINT

Não há endpoint (WebService) implementado neste arquivo. Para o Monitor, os dados de entrada são originados da fonte SQL consultada em viewQuery.

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

Campos capturados (conjunto completo):
- Identificação: A1_COD, A1_LOJA, CGC_CPF
- Cadastro: 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

Observação: no fluxo automático (run()), apenas DATA_PARA_TRANSFERENCIA é aplicada na cláusula WHERE da consulta (os demais filtros são normalizados e persistidos como estado).


3. REESTRUTURAÇÃO DOS DADOS

3.1 Recuperação do estado do monitor
Momento: Início do run()
- Lê estado via get("ProtheusCliente") (offset, chave, datas, filtro, token, situação).
- Regra: se situacao = 2, redefine para 0 antes de prosseguir.

3.2 Reset ao iniciar execução
Momento: Quando situacao ≠ 1
- Reseta dataPosicao, dataIniciado, offset e chavePosicao para reinício controlado.

3.3 Normalização dos filtros
Momento: Antes da query
- Preenche A1_LOJA, A1_COD, CGC_CPF com string vazia quando ausente.
- Define DATA_PARA_TRANSFERENCIA:
    - informado → convertido para datetime e formatado
    - ausente → 2023-05-01 00:00:00

3.4 Atualização do estado para EXECUTANDO
Momento: Antes da consulta
- Persiste situacao = 1 com o estado atual (offset, chave, datas, filtro, token).

3.5 Paginação dos registros
Momento: Execução da query
- Ordena por DATA_PARA_TRANSFERENCIA ASC.
- Aplica paginação com OFFSET baseado no estado e FETCH NEXT no limite configurado.

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 cada registro
- Atualiza novoFiltro com os campos-chave do registro e a DATA_PARA_TRANSFERENCIA normalizada.

3.8 Enfileiramento
Momento: Dentro do loop de registros
- Monta chave no padrão A1_LOJA-A1_COD-CGC_CPF.
- Enfileira com Queue::set(chave, registro, ...).
- Status gravado: Aguardando Integração.
- Situação gravada: 0.

3.9 Atualização incremental da posição
Momento: Após inserir na fila
- offset ← offset + 1
- chavePosicao ← chave
- dataPosicao ← DATA_PARA_TRANSFERENCIA
- Persiste o estado imediatamente para garantir retomada em caso de interrupção.

3.10 Finalização
Momento: Encerramento do loop
- Persiste situacao = 2 com o último novoFiltro (estado efetivo de posição).

3.11 Tratamento de erro
Momento: catch(Exception)
- Adiciona registro em filtro.ERRORS[] contendo DATE e MESSAGE.
- Persiste situacao = 4 (Problema).


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

4.1 Controle do monitor
Momento: Durante a execução e finalização do run()
- Persistência ocorre via Monitor::set() (método _set da biblioteca wosk_monitor).
- Campos persistidos (visíveis neste arquivo): offset, chave_posicao, data_posicao, filtro, situacao, data_iniciado, token.
- Tabela/estrutura física do armazenamento: não há SQL explícito neste arquivo, portanto o nome da tabela não está identificado aqui.

4.2 Fila de integração
Momento: Enfileiramento (3.8)
- Operação executada por Queue::set() (persistência interna via biblioteca wosk_queue).
- Tabela explicitamente referenciada neste arquivo: wosk_queue (consultas e notificação de erros).


5. RESULTADO DO PROCESSAMENTO

Execução normal:
- Monitor marcado como Concluído (2) ao final.
- Registros enfileirados com status Aguardando Integração para processamento posterior.

Execução com erro:
- Monitor marcado como Problema (4).
- Erro registrado em filtro.ERRORS[].


6. OPERAÇÃO MANUAL – capturar()

Objetivo: capturar (re-enfileirar) manualmente um ou mais clientes a partir da chave.

Fluxo:
- Entrada: chave string ou array, no padrão A1_LOJA-A1_COD[-CGC_CPF].
- Para cada chave:
    - Consulta a fila via Queue::get('', chave) para reaproveitar token quando existir.
    - Consulta a fonte por A1_LOJA, A1_COD e opcionalmente CGC_CPF.
    - Sanitiza com trim() e enfileira via Queue::set() com o token reaproveitado.

Queue

Processo:
1. DESCRIÇÃO DO FLUXO

- Responsabilidade: consumir um item da fila, transformar/normalizar o payload e enviar para o Protheus, registrando retorno e status na própria fila.
- Disparo: execução agendada (cron) chamando Queue::run(token).

Ao iniciar, a fila busca um registro via get(token). Se houver registro, atualiza o mesmo para status Enviando e situacao = 1 antes do envio.

Montagem e transformação do payload:
- O conteúdo armazenado na fila é convertido em estrutura de envio por getConteudo() (internamente _getConteudo), usando o mapeamento de campos definido em $field.
- Normalizações aplicadas antes do envio:
    - A1_NOME e A1_NREDUZ: remove | e 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.
- Se resposta não for array ou não contiver Mensagem → erro.
- situacao final do item:
    - 2 quando sucesso.
    - 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 o cliente como integrado via setProtheusClienteIntegrado("A1_LOJA-A1_COD", true).
- Erro (situacao = 4): tenta reprocesso alternativo acionando WOSK\\ProtheusClientePadrao\\Monitor::capturar() para a mesma chave (estratégia de fallback). Se existir item correspondente na fila com acao = 'ProtheusClientePadrao' e token, o registro atual pode ser removido do fluxo original.

Persistência do status do item (fila):
- Em fluxo padrão, ao final atualiza o mesmo registro com retorno, mensagem, dump de requisição (_CURL_DUMP), tempo e situação final.
- Em caso de remoção condicional (erro + fallback capturado), executa exclusão via setProtheusExcluir(['ProtheusCliente'], 'chave', chave).


2. DADOS NECESSÁRIOS PARA O ENDPOINT

Não há endpoint (WebService) implementado neste arquivo. Para a Queue, os dados de entrada são os registros persistidos na fila.

Estrutura do item de fila (visível pelo uso neste arquivo):
- token: identificador do item para consumo.
- chave: A1_LOJA-A1_COD-CGC_CPF.
- conteudo: registro completo capturado pelo monitor (campos do cliente).
- data_adicionado: referência temporal 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 para indicar consumo em andamento.

3.3 Normalização do payload
Momento: Pré-envio
- Aplica mapeamento de campos via $field durante a preparação do conteúdo.

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

3.5 Paginação dos registros
Momento: Não aplicável (a Queue processa um 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) com tenantId configurado.

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 registro da fila com retorno, mensagem, dump e tempo.

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


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

4.1 Controle do monitor
Não aplicável (esta classe não persiste estado de monitor).

4.2 Fila de integração
- Tabela explicitamente referenciada neste arquivo: wosk_queue.
- Atualizações ocorrem via Queue::set() em fases distintas:
    - Pré-envio: status Enviando, situacao = 1
    - Pós-envio: persistência de retorno, mensagem, dump de requisição, tempo e situacao final


5. RESULTADO DO PROCESSAMENTO

Execução normal:
- Item de fila finaliza com situacao = 2 e registra retorno do Protheus.

Execução com erro:
- Item de fila finaliza com situacao = 4 e registra a mensagem de erro.
- Pode acionar fallback para captura por ProtheusClientePadrao e, se confirmado, remover o item do fluxo original.


6. OPERAÇÃO MANUAL

Não há operação manual específica nesta classe além do consumo via run(token). A notificação de erros é realizada por notificar(), que consulta itens com situacao = 4 e envia e-mail para uma lista fixa de destinatários.

Fluxo do Processo

Critérios de Aceitação