Sistemas Envolvidos, Arquitetura Técnica e Integração RPInfo

Documento de especificação técnica e arquitetural do Projeto de Inventário da Plurix, detalhando a segregação de responsabilidades entre o ERP RPInfo (Flex ONE) e o RUB, o novo Job de integração no módulo rpinfo, os contratos oficiais das APIs REST e as diretrizes operacionais de contagem e recontagem.

🖥️ Ecossistema de Sistemas Envolvidos e Segregação de Responsabilidades

A esteira de inventário opera através de uma fronteira de responsabilidades rigorosamente definida para garantir máxima eficiência operacional e integridade dos saldos:

flowchart TD
    subgraph Retaguarda_ERP["ERP RPInfo (Flex ONE)"]
        ERP_Abertura["Abertura de Inventário no ERP<br/>(Geração de Pendências de Auditoria)"]
        ERP_Proc["Processamento e Conciliação Contábil"]
    end

    subgraph Camada_API_RPInfo["API REST RPInfo (ServicosFlex)"]
        API_GET["GET /v1.1/produtounidade/auditoriaestoque/...<br/>(Consulta de Pendências / lastID)"]
        API_POST["POST /v1.3/produtounidade/auditoriaestoque<br/>(Inclusão de Auditoria / Devolução de Saldos)"]
    end

    subgraph Modulo_RPInfo_RUB["Módulo rpinfo (RUB)"]
        Job_RPInfo["Novo Job de Integração RPInfo<br/>• Polling incremental via lastID<br/>• Identificação de itens não integrados<br/>• Estoque na abertura para divergências<br/>• Geração de novo Inventário no RUB"]
        Writer_RPInfo["Mecanismo de Devolução de Saldos<br/>• Envio consolidado via POST REST"]
    end

    subgraph Chão_Loja_RUB["Operação e Execução (RUB Mobile & Retaguarda)"]
        App_Count1["1ª Contagem Física (Coletores Android)"]
        RUB_Painel["Telemetria e Painel em Tempo Real"]
        RUB_Diverg["Decisões no Painel Web<br/>• Recontagens deliberadas<br/>• Encerramento pelo operador"]
        App_Count2["Contagem 2 e 3 com Gestor de Loja"]
        App_Sign["Assinatura Digital de Homologação"]
    end

    ERP_Abertura --> API_GET
    API_GET --> Job_RPInfo
    Job_RPInfo -->|Gera Lote no RUB| App_Count1
    App_Count1 --> RUB_Painel
    RUB_Painel --> RUB_Diverg
    RUB_Diverg -->|Operador seleciona itens na Web| App_Count2
    App_Count2 --> App_Sign
    App_Sign --> Writer_RPInfo
    Writer_RPInfo --> API_POST
    API_POST --> ERP_Proc

🔄 O Ciclo Macro em 6 Etapas e a Matriz de Responsabilidade Sistêmica

A distribuição de papéis entre os sistemas em cada etapa macro do ciclo de vida do inventário está padronizada na matriz abaixo:

🔌 Especificação dos 2 Endpoints Oficiais da RPInfo e Funcionamento do Novo Job

A integração entre a RPInfo e o RUB fundamenta-se estritamente nos dois endpoints oficiais disponibilizados no Swagger da RPInfo (http://servicosflex.rpinfo.com.br:9000/v1.0/documentacao#), eliminando qualquer necessidade de aberturas manuais ou acessos diretos a tabelas internas.

1. Endpoint de Carga e Consulta de Pendências (Abertura na RPInfo)

Permite ao RUB capturar as pendências de auditoria de estoque cadastradas pela equipe da Plurix no Flex ONE.

GET /v1.1/produtounidade/auditoriaestoque/{lastID}/datainicial/{dataInicial}/datafinal/{dataFinal}?unidades={unidades}&departamento={departamento}

Parâmetros da Requisição:

• token (Header, String, Obrigatório): Token de autenticação da API RPInfo.
• lastID (Path, String, Obrigatório): Ponteiro sequencial do último registro/comprador consultado. Enviar "0" na primeira chamada para trazer todos os registros paginados. Nas chamadas subsequentes, informa o código do último item recebido para controle incremental.
• dataInicial (Path, String, Obrigatório): Data inicial do período no formato dd-mm-yyyy.
• dataFinal (Path, String, Obrigatório): Data final do período no formato dd-mm-yyyy.
• unidades (Query, String, Obrigatório): Códigos das filiais separados por ponto e vírgula (ex.: unidades=001;002;003).
• departamento (Query, String, Opcional): Código do departamento para filtragem do sortimento.

Estrutura do Payload de Retorno (RespostaGetAuditoriaEstoque):

{
  "response": {
    "status": "ok",
    "messages": [
      { "message": "Dados carregados" }
    ],
    "auditorias": [
      {
        "codigo": 1000000001,
        "codigoProduto": 10162,
        "unidade": "001",
        "codEstoque": "1",
        "data": "16/10/2026",
        "qtde": 0,
        "estoque": 24,
        "transacao": "",
        "sobraFalta": "F",
        "reauditar": "S"
      }
    ]
  }
}

2. Funcionamento do Novo Job no Módulo rpinfo (Geração do Inventário no RUB)

Para materializar o processo de inventário dentro do ecossistema RUB a partir das pendências abertas na RPInfo, será implantado um novo Job de integração no módulo rpinfo:

Regras de Processamento do Job:

1. Controle Incremental (lastID): O Job armazena em tabela de controle o último codigo processado, garantindo idempotência e prevenindo reprocessamentos desnecessários.
2. Criação Atômica do Inventário: Caso a lista traga novos produtos, o Job instancia um novo cabeçalho de inventário com situação inicial PENDENTE, associa os SKUs ao lote e disponibiliza a ordem para que os operadores realizem a contagem nos coletores móveis.
3. Cálculo de Divergências: Para cálculo de divergências, será usada a posição de estoque do RUB na abertura do inventário.

3. Endpoint de Inclusão e Devolução de Saldos Físicos (Consolidação no ERP)

Ao finalizar todas as contagens e recontagens no RUB, o RUB devolve os saldos físicos apurados para conciliação contábil no ERP através do endpoint:

POST /v1.3/produtounidade/auditoriaestoque

Parâmetros e Headers:

• token (Header, String, Obrigatório): Token de autenticação.
• Content-Type: application/json.

Payload de Envio (IncluirAuditoriaPostV1_3):

{
  "id": "INV-20261016-001",
  "origem": "RUB",
  "dataHoraDispositivo": "16/10/2026 17:30:00 -0300",
  "auditorias": [
    {
      "id": "1",
      "unidade": "001",
      "codigoProduto": 10162,
      "quantidade": 23.000,
      "data": "16/10/2026",
      "idEstoque": "1",
      "acumular": false,
      "dataHoraLeitura": "16/10/2026 16:45:12 -0300"
    },
    {
      "id": "2",
      "unidade": "001",
      "codigoProduto": 11193,
      "quantidade": 45.500,
      "data": "16/10/2026",
      "idEstoque": "1",
      "acumular": false,
      "dataHoraLeitura": "16/10/2026 17:10:05 -0300"
    }
  ]
}

Resposta da API RPInfo (RespostaPostAuditoriaEstoqueV1_3):

{
  "response": {
    "status": "ok",
    "messages": [
      { "message": "Dados salvos com sucesso" }
    ],
    "content": 152
  }
}

O atributo content retorna o número do recibo gerado na RPInfo, permitindo consulta de processamento assíncrono via GET /v1.0/produtounidade/auditoriaestoque/recibo/{recibo} se necessário.

🔄 Diagrama de Sequência de Integração (ERP RPInfo ⇄ RUB)

Detalha a troca de mensagens entre o ERP RPInfo (Flex ONE) e o RUB através dos dois endpoints oficiais da API REST, ilustrando a carga incremental via GET, a instanciação do inventário no RUB (com estoque na abertura para divergências) e a devolução de saldos físicos consolidados via POST:

sequenceDiagram
    autonumber
    participant RPInfo as ERP RPInfo (API REST Flex ONE)
    participant Job as Novo Job (Módulo rpinfo)
    participant RUB as Núcleo RUB (Inventário / DB)

    Note over Job,RUB: 1. Ciclo de Polling e Carga Incremental via GET
    Job->>Job: Executa rotina periódica de sincronização
    Job->>RUB: Consulta último lastID persistido
    RUB-->>Job: Retorna lastID de controle (ex.: "1000000000" ou "0")
    Job->>RPInfo: GET /v1.1/produtounidade/auditoriaestoque/{lastID}/...
    RPInfo-->>Job: 200 OK (Payload com lista de auditorias pendentes)
    Job->>Job: Compara SKUs recebidos com itens já integrados
    alt Existem itens pendentes não integrados
        Job->>RUB: Cria nova entidade Inventario (Loja, Data, Situação: PENDENTE)
        Job->>RUB: Vincula SKUs não integrados ao novo lote de inventário
        Job->>RUB: Registra posição de estoque do RUB na abertura do inventário
        Job->>RUB: Atualiza e persiste novo ponteiro lastID
        Note over Job,RUB: Lote disponibilizado para execução no RUB
        Note over RUB: Execução do processo em chão de loja e retaguarda
        RUB->>Job: Evento de Inventário Encerrado pelo Operador (Saldos Físicos Consolidados)
        Note over Job,RPInfo: 2. Devolução de Saldos Físicos Consolidados via POST
        Job->>Job: Monta payload IncluirAuditoriaPostV1_3
        Job->>RPInfo: POST /v1.3/produtounidade/auditoriaestoque (Payload consolidado)
        RPInfo->>RPInfo: Processa auditoria, gera conciliação e atualiza estoque no ERP
        RPInfo-->>Job: 200 OK (RespostaPostAuditoriaEstoqueV1_3 com recibo / content: 152)
    else Nenhum item pendente
        Job->>Job: Aguarda próximo ciclo de execução
    end

🎯 Diretrizes Técnicas de Recontagem, Encerramento e Cálculo de Divergências

1 - Governança das Decisões de Recontagem e Encerramento via Web

• Decisão de Recontagem pelo Operador via Web: A responsabilidade pela decisão é do RUB, sendo deliberada pelo operador através da interface Web (não é automática e não é feita via coletor).

  • O coletor móvel possui papel estritamente executor em campo (bipagem e leituras físicas). Ao finalizar a 1ª contagem, os quantitativos apurados são transmitidos em tempo real para a retaguarda do RUB.
  • O painel analítico da interface Web do RUB confronta as quantidades contadas com a posição de estoque do RUB na abertura do inventário e organiza as divergências por impacto financeiro (curva de Pareto de sobras e faltas).
  • O operador analisa a tela de divergências e seleciona manualmente quais SKUs devem passar pela Contagem 2. O sistema não dispara recontagens automaticamente por gatilhos cegos, nem permite que o operador de coletor escolha o que recontar.
  • A lista de produtos selecionados pelo operador na Web é transmitida para os coletores para execução da Contagem 2 presencial com o Gestor de Loja (e eventual Contagem 3 de desempate, sob teto de até 3 contagens).

• Decisão de Encerramento pelo Operador via Web (Sem Decisão Algorítmica):

  • O encerramento do inventário também é uma decisão deliberada do operador via interface Web, não existindo qualquer decisão algorítmica para o mesmo.
  • O RUB não encerra nem fecha lotes de inventário automaticamente com base em fórmulas ou algoritmos de convergência.
  • O operador analisa o quadro consolidado com todas as contagens e recontagens na tela da retaguarda Web do RUB e aciona expressamente o comando de encerramento do inventário.
  • Somente após a confirmação deliberada do operador na Web, o inventário é liberado para coleta de assinaturas digitais de ciência no coletor móvel e posterior devolução à RPInfo via endpoint POST /v1.3.

2 - Posição de Referência para Cálculo de Divergências

• Para cálculo de divergências, será usada a posição de estoque do RUB na abertura do inventário.