ProtheusCliente

Documentação Técnica

Sumário

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

Histórico de Versões

Descrição Geral dos Processos

LoremEscopo Ipsumdeste arquivo:

- isEste simplydocumento dummyfoi textgerado of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer tookexclusivamente a galleypartir ofde typewosk_protheuscliente/protheusCliente.php.
- andClasses scrambledpresentes itneste toarquivo: makeMonitor ae typeQueue.
- specimenClasse book.ausente Itneste hasarquivo: survivedWebservice not(não onlyhá fiveendpoint centuries,implementado but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsumaqui).

Monitor

Processo: 
PROCESSO_MONITOR1. 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:
PROCESSO_QUEUE

WebService

Processo:DESCRIÇÃO DO FLUXO
PROCESSO_WEBSERVICE

{realizada "key":por "34a20688-1bb6-4fcd-9592-d58ca9876de5"notificar(), "INTEGRADOR":que "cupom",consulta "FILIAL": "01LJ0206",
    "ID": "00000007188082",
    "DATA_RETORNO": "2024-10-29 00:37:05",
    "SITUACAO": "1",
    "MENSAGEM": "GravaBatch Executadoitens com Sucesso",situacao "DETALHE":= {4 "ZB_ID":e "000000000004156",envia "LQ_DOC":e-mail "000051206",para "LQ_PDV":uma "003",lista "ERGRVBT": "",
        "LQ_HORA": "20:41:19",
        "LQ_LOJA": "68",
        "LQ_VEND": "000001",
        "SITUAGB": "OK",
        "LQ_FORMA": "R$",
        "LQ_FRETE": 0,
        "LQ_SERIE": "65",
        "LQ_SITUA": "RX",
        "Mensagem": "OK",
        "LQ_CARTAO": 752.14,
        "LQ_CONDPG": "",
        "LQ_EMISNF": "27/07/2025",
        "LQ_FILIAL": "01LJ0299",
        "LQ_FORMPG": "CC",
        "LQ_NOMCLI": "XXXXXX",
        "LQ_OUTROS": 139.65,
        "LQ_SERSAT": "",
        "LQ_TPFRET": "S",
        "LQ_VALICM": 178.35,
        "LQ_VLRLIQ": 891.79,
        "LQ_VLRTOT": 891.79,
        "LQ_XCANAL": "VAREJO",
        "ZB_DATRET": "29/07/25",
        "ZB_FILIAL": "01LJ0299",
        "ZB_HORRET": "09:18:00",
        "LQ_CLIENTE": "XXXXX",
        "LQ_DINHEIR": 0,
        "LQ_EMISSAO": "27/07/2025",
        "LQ_ESPECIE": "NFCE",
        "LQ_KEYNFCE": "XXXXX",
        "LQ_NUMCFIS": "000051206",
        "LQ_OPERADO": "C24",
        "LQ_PARCELA": 0,
        "LQ_TIPOCLI": "F",
        "LQ_VALBRUT": 891.79,
        "LQ_VALMERC": 1044,
        "LQ_VENDTEF": "S",
        "LQ_VLRDEBI": 0,
        "LQ_XNATOPE": "100.80",
        "Mensagem Detalhada": "GravaBatch Executado com Sucesso"
    }
}

{
    "key": "34a20688-1bb6-4fcd-9592-d58ca9876de5",
    "INTEGRADOR": "cupom",
    "FILIAL": "01LJ0269",
    "ID": "00000001352422",
    "DATA_RETORNO": "2024-10-29 11:23:20",
    "SITUACAO": "0",
    "MENSAGEM": "D2_TES: Tipo Operacao '', do Item '0001', Invalido."
}

{
    "INTEGRADOR": "cupom",
    "FILIAL": "01LJ0269",
    "ID": "00000001352422",
    "DATA_RETORNO": "2024-10-29 11:23:20",
    "SITUACAO": "0",
    "Mensagem Detalhada": "Registrado com sucesso.",
    "Mensagem": "OK"
}

{
    "success":false,
    "message":"Sess\u00e3o Expirou",
    "data":false,
    "errors":{"reason":"Sess\u00e3o Expirou"}
}