CLIENTE (LojaCliente) (STATUS: PARCIAL)

De forma resumida, o fluxo operacional ocorre da seguinte maneira:

1) Endpoint → aciona WebService → valida e persiste CLIENTES_VAREJO  
2) Cron → aciona Monitor → captura incremental → envia para Queue  
3) Cron → aciona Queue → transforma → integra com sistema externo

Essa arquitetura separa claramente as responsabilidades de entrada, captura e envio, proporcionando maior robustez, controle transacional e tolerância a falhas.

Monitor

1. DESCRIÇÃO DO FLUXO

O processo Monitor é responsável por habilitar e executar a captura incremental de registros de CLIENTES_VAREJO, preparando-os para integração assíncrona via Queue.

Ao ser acionado, o método run() recupera o estado anterior do monitor (offset, chave de posição, datas e filtros). Com base na situação armazenada:

- Se CONCLUÍDO (2) → o estado é redefinido para PARADO (0).
- Se PARADO (0) ou EM EXECUÇÃO (1) → o processamento é iniciado ou continuado.

Quando iniciado do estado PARADO:
- A data de posição e a data de início são redefinidas.
- O offset retorna a 0.
- A chave de posição é limpa.

Em seguida:
- Os filtros são normalizados.
- Define-se a DATA_PARA_TRANSFERENCIA mínima caso não informada.

O processo entra em loop de paginação utilizando OFFSET/FETCH:

1) Atualiza o monitor para situação EXECUTANDO (1).
2) Executa a consulta paginada ordenada por DATA_PARA_TRANSFERENCIA.
3) Para cada registro retornado:
   - Os valores são tratados (trim).
   - Atualiza-se o novo filtro de posição.
   - O registro é enviado para a Queue.
   - Offset e posição são persistidos.

O loop encerra quando não há mais registros.

Ao final:
- O monitor é marcado como CONCLUÍDO (2).

Em caso de erro:
- O monitor é marcado como PROBLEMA (4).
- A mensagem de erro é armazenada no filtro.

2. DADOS NECESSÁRIOS PARA O ENDPOINT

Os dados capturados são provenientes da viewQuery aplicada sobre CLIENTES_VAREJO.

Campos utilizados:

- CODIGO_CLIENTE
- CLIENTE_VAREJO
- CPF_CGC
- RG_IE
- ANIVERSARIO
- TIPO_LOGRADOURO
- ENDERECO
- NUMERO
- COMPLEMENTO
- BAIRRO
- CIDADE
- UF
- CEP
- PAIS
- IBGE
- PAIS_BC
- DDD
- TELEFONE
- DDD_CELULAR
- CELULAR
- EMAIL
- CODIGO_CONTATO
- FILIAL
- ESTRANGEIRO
- TIPO_VAREJO
- TIPO_BLOQUEIO
- CADASTRAMENTO
- OBS
- SEXO
- STATUS
- DATA_PARA_TRANSFERENCIA

Observação:
IBGE e PAIS_BC dependem de joins auxiliares (município e país).

3. REESTRUTURAÇÃO DOS DADOS

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

- offset ← valor persistido
- chavePosicao ← valor persistido
- dataPosicao ← valor persistido
- filtro ← valor persistido
- situacao ← valor persistido

Regra:
- Se situacao = 2 → redefinir para 0

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

- dataPosicao ← Data/hora atual
- dataIniciado ← Data/hora atual
- offset ← 0
- chavePosicao ← ''

3.3 Normalização dos filtros
Momento: Antes da query

- CODIGO_CLIENTE ← '' se vazio
- DATA_PARA_TRANSFERENCIA ←
    • valor informado → convertido para datetime
    • vazio → '2023-06-01 00:00:00'

3.4 Atualização do estado para EXECUTANDO
Momento: Antes da consulta

- situacao ← 1

3.5 Paginação dos registros
Momento: Execução da query

Regra:
- ORDER BY DATA_PARA_TRANSFERENCIA ASC
- OFFSET offset
- FETCH NEXT limiteConfigurado

3.6 Sanitização dos dados
Momento: Ao ler cada registro

Transformação:
- trim() em todos os campos

3.7 Atualização do filtro de posição
Momento: Após fetch()

- novoFiltro['CODIGO_CLIENTE'] ← registro atual
- novoFiltro['DATA_PARA_TRANSFERENCIA'] ← data do registro

3.8 Enfileiramento
Momento: Dentro do loop

Operação:
- Queue::set()

Parâmetros:
- chave ← CODIGO_CLIENTE
- payload ← registro completo
- status ← 'Aguardando Integração'
- situacao ← 0

3.9 Atualização incremental da posição
Momento: Após inserir na fila

- offset ← offset + 1
- chavePosicao ← CODIGO_CLIENTE
- dataPosicao ← DATA_PARA_TRANSFERENCIA

3.10 Finalização
Momento: Fim do loop

- situacao ← 2 (Concluído)

3.11 Tratamento de erro
Momento: catch(Exception)

- situacao ← 4 (Problema)
- filtro['ERRORS'][] ← mensagem + timestamp

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

4.1 Controle do monitor
Método: _set("LojaCliente")

Dados persistidos:

- offset
- chavePosicao
- dataPosicao
- filtro
- situacao
- dataIniciado
- token

Situações:

- 0 → Parado
- 1 → Executando
- 2 → Concluído
- 4 → Problema

4.2 Fila de integração
Classe: Queue

Operação:

- INSERT / UPDATE em wosk_queue

Dados gravados:

- chave
- conteudo (payload)
- status
- situacao
- data_referencia
- token (quando reaproveitado)

5. RESULTADO DO PROCESSAMENTO

Execução normal:

- Monitor atualizado como CONCLUÍDO (2)
- Registros enviados para Queue

Execução com erro:

- Monitor marcado como PROBLEMA (4)
- Mensagem registrada no filtro

6. OPERAÇÃO MANUAL – capturar()

Permite capturar clientes específicos.

Fluxo:

- Recebe chave(s) (CODIGO_CLIENTE)
- Executa consulta direta
- Sanitiza os dados
- Reenvia para Queue

Regra adicional:

- Se já existir na fila → reaproveita token existente

Queue

1. DESCRIÇÃO DO FLUXO

O componente Queue é responsável pelo processamento assíncrono das mensagens de integração relacionadas ao contexto "LojaCliente". O método run() é acionado com um token identificador da mensagem a ser processada.

Inicialmente, o sistema recupera um item da fila utilizando o token informado. Caso exista conteúdo pendente, o registro é imediatamente atualizado para o status "Enviando", garantindo rastreabilidade e evitando reprocessamentos simultâneos.

Em seguida, o sistema inicia o processamento do payload (conteudo), realizando:

- Montagem dos dados de contato (telefone, celular, e-mail)
- Normalização dos números telefônicos
- Composição do logradouro completo
- Validação de códigos obrigatórios (IBGE / BACEN)
- Construção da estrutura final de integração
- Identificação do tipo de pessoa (Física / Jurídica)

Após a montagem do objeto final, é realizada a chamada ao endpoint externo de integração (setIlli).

Dependendo do retorno:

- Sucesso → registro atualizado com situacao = 2
- Erro → registro atualizado com situacao = 4

Ao final, o tempo de execução é calculado e persistido junto ao resultado do processamento.

2. DADOS NECESSÁRIOS PARA O ENDPOINT

O processamento da fila pressupõe que o conteúdo já tenha sido previamente estruturado. Os seguintes campos são esperados:

Campos relevantes:

- CODIGO_CLIENTE
- CLIENTE_VAREJO
- CPF_CGC
- RG_IE
- ENDERECO
- TIPO_LOGRADOURO
- NUMERO
- COMPLEMENTO
- BAIRRO
- CIDADE
- UF
- CEP
- PAIS
- PAIS_BC
- IBGE
- TELEFONE
- DDD
- CELULAR
- DDD_CELULAR
- EMAIL
- SEXO
- STATUS
- ANIVERSARIO
- CADASTRAMENTO
- DATA_PARA_TRANSFERENCIA
- FILIAL
- TIPO_VAREJO
- ESTRANGEIRO

Observação:
Campos como IBGE e PAIS_BC devem estar previamente resolvidos. A ausência desses dados pode interromper o processamento.

3. REESTRUTURAÇÃO DOS DADOS

3.1 Atualização de status inicial da fila
Momento: Imediatamente após recuperar o item

Regra:
- situacao ← 1 (Enviando)

3.2 Montagem dos contatos
Momento: Início do processamento do payload

Transformações:

- Remove caracteres não numéricos de:
  • DDD
  • TELEFONE
  • DDD_CELULAR
  • CELULAR

- Concatenação:
  • TELEFONE → DDD + TELEFONE
  • CELULAR → DDD_CELULAR + CELULAR

- Inclusão condicional:
  • Apenas se houver valor informado

3.3 Composição do logradouro
Momento: Antes da montagem do endereço

Regra:
- logradouro ← TIPO_LOGRADOURO + ENDERECO

3.4 Normalização do CEP
Momento: Montagem da estrutura final

Regra:
- CEP → somente números
- CEP → preenchido à esquerda até 8 dígitos

3.5 Normalização de campos numéricos
Momento: Montagem do endereço

Transformações:

- NUMERO → somente números
- RG_IE → somente números

3.6 Validação de código IBGE
Momento: Pré-integração

Regra:
- Obrigatório para clientes nacionais
- Se ausente → exceção

3.7 Validação de código BACEN
Momento: Pré-integração

Regra:
- PAIS_BC obrigatório
- Se ausente → exceção

3.8 Normalização da UF
Momento: Montagem do endereço

Regra:
- Se UF inválida ou vazia:
    • Estrangeiro → "EX"
    • Nacional → vazio

3.9 Definição do código IBGE
Momento: Montagem do endereço

Regra:
- Nacional → usa IBGE informado
- Estrangeiro → "9999999"

3.10 Conversão do STATUS
Momento: Montagem do objeto final

Regra:
- STATUS ≠ '1' → situacao ← '0'
- STATUS = '1' → situacao ← '1'

3.11 Identificação do tipo de pessoa
Momento: Montagem final

Regra:

- CPF_CGC > 11 dígitos →
    tipo ← JURIDICA
    cnpj ← normalizado (14 dígitos)
    ie ← RG_IE normalizado

- CPF_CGC ≤ 11 dígitos →
    tipo ← FISICA
    cpf ← normalizado (11 dígitos)
    identidade ← RG_IE normalizado

3.12 Controle de truncamento
Momento: Montagem do endereço

Regra:
- logradouro → máx. 250 caracteres
- COMPLEMENTO → máx. 250 caracteres

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

Tabela de controle da fila:
→ wosk_queue

Operações realizadas:

- Atualização ao iniciar processamento
  Método: set(..., 'Enviando', situacao = 1)

- Atualização ao finalizar processamento
  Método: set(..., retorno, mensagem, tempo, situacao)

Situações possíveis:

- 2 → Processado com sucesso
- 4 → Erro no processamento

Dados registrados:

- Conteúdo original
- Retorno do endpoint externo
- Mensagem de erro/sucesso
- Dump da requisição (CURL)
- Tempo de execução

5. RESULTADO DO PROCESSAMENTO

Sucesso:

- situacao = 2
- Mensagem retornada pelo serviço externo

Erro:

- situacao = 4
- Mensagem detalhada do erro
- Retorno estruturado indicando falha

6. ROTINAS AUXILIARES

prepare():
- Prepara o contexto da fila "LojaCliente"

notificar():
- Consulta registros com erro (situacao = 4)
- Envia notificação por e-mail

get():
- Recupera itens pendentes ou específicos

set():
- Persiste atualizações da fila

getConteudo():
- Extrai conteúdo normalizado do payload

WebService

1. DESCRIÇÃO DO FLUXO

O WebService recebe uma requisição contendo os dados cadastrais de um cliente varejo. Ao ser acionado, o método run() executa inicialmente o processo de validação dos parâmetros recebidos. Caso exista qualquer inconsistência (campo obrigatório ausente, tipo inválido ou tamanho excedido), a execução é interrompida e uma exceção é retornada.

Após validação bem-sucedida, os dados são encaminhadosconvertidos ao método setClientesVarejo(), ondepara o processamentoformato principalesperado ocorrepelo dentrodestino.

Em seguida, o sistema verifica se já existe um cliente cadastrado:

- Se NÃO existir: realiza INSERT na tabela CLIENTES_VAREJO.
- Se EXISTIR: realiza UPDATE conforme regras de atualização.

Ao final, a transação épara confirmadagarantir (commit).atomicidade.