Análise dos casos reportados entre 24/07 e 05/08/2026, correções aplicadas, comparação com o escopo contratado e as condições necessárias para concluir a entrega com a estabilidade que o projeto merece.
Sete situações foram reportadas pela operação entre 24/07 e 05/08. Todas foram investigadas com dados reais do sistema, tiveram a causa identificada e foram corrigidas. Este relatório apresenta cada uma delas e, principalmente, o que a análise conjunta revelou.
A conclusão central é que os problemas não eram independentes. Cinco dos sete compartilham a mesma origem técnica, e essa origem é uma condição de infraestrutura que ainda não pôde ser atendida — não uma falha de programação. Enquanto essa condição permanecer, novos sintomas da mesma família continuarão aparecendo, por mais que cada um seja corrigido individualmente. Foi exatamente esse ciclo que a operação de vocês percebeu.
O sistema precisa manter uma cópia local do estoque para funcionar, porque a integração disponível hoje não permite consultar o Oracle de forma pontual. É o envelhecimento dessa cópia que gera os erros relatados. A solução definitiva está descrita na seção 6 e depende de um conjunto pequeno de consultas novas.
Cada caso abaixo foi reproduzido e medido no ambiente de produção antes de qualquer alteração. Os números citados são do sistema de vocês, no momento do relato.
Dois achados explicam o comportamento que a operação percebeu como "as regras estão certas, mas o resultado sai errado".
Em 05/08 identificamos que o ambiente de produção não estava executando a versão mais recente do sistema. Havia aproximadamente um mês de correções que não estavam em operação.
Isso explica por que, em determinado momento, as regras estavam corretas no sistema e o resultado observado no chão continuava errado: parte das correções simplesmente não estava rodando. O processo de publicação foi corrigido — a versão agora é carimbada dentro da própria imagem e conferida na subida, de modo que a situação não pode se repetir silenciosamente.
Registramos isso com transparência porque parte do retrabalho da operação nesse período teve essa origem, e entendemos que vocês precisam saber disso.
Os casos 2.1, 2.2, 2.4, 2.5 e parte do 2.3 têm a mesma raiz: o sistema decide com base em uma cópia local do estoque, e essa cópia envelhece entre uma atualização e outra.
Essa cópia não é uma escolha de arquitetura nossa. Ela existe porque a integração hoje
disponível — o /estoque/exportar — não aceita nenhum filtro. Não há como perguntar
ao Oracle "onde está a peça X", "quantas peças há no box Y" ou "onde estão as peças do pedido Z".
A única resposta possível é a listagem inteira, com cerca de 32 mil peças.
Entre duas leituras, o sistema opera com informação defasada, e é nessa janela que os erros acontecem. Cada correção que aplicamos foi, na prática, o fechamento de uma janela específica. Elas funcionam — mas são defesas contra uma limitação que permanece.
Continuar apenas fechando janelas leva exatamente ao que a operação vivenciou: correções constantes com problemas novos surgindo. A solução definitiva é o sistema consultar o Oracle no momento de cada decisão — e isso depende das consultas descritas na seção 6.
Situação de cada item previsto no contrato de 09/03/2026 e em seus anexos, com franqueza sobre o que está entregue, o que está em andamento e o que depende de condições externas.
| Previsto no contrato | Situação | Observação |
|---|---|---|
| 2.2 Agrupar peças do mesmo pedido e sugerir movimentação para o mesmo box ou boxes próximos | Entregue | Motor de agrupamento em operação. O ajuste de 04/08 (caso 2.6) tornou o agrupamento mais efetivo, elevando o limite prático por box. |
| 2.3 Operadores percorrerem a menor distância possível | Entregue | Viagem montada por proximidade real, com coleta e entrega encadeadas na mesma subida. |
| 2.4 Definição automática dos boxes ideais considerando proximidade, giro das peças, pedidos existentes e fluxo interno | Parcial | Proximidade, pedidos e fluxo em operação. O critério de giro (curva ABC) está implementado, porém opera com modelo que precisa ser recalibrado com o histórico atual — item em nossa lista de refinamento. |
| 2.5 Sugestão de percursos e caminhos mais curtos | Entregue | Roteiro por parada, com endereço real do box exibido ao operador. |
| 2.6 Fluxo de movimentação inteligente e contínuo, atualizado conforme novas demandas | Entregue | Planejamento automático em ciclo contínuo, sem necessidade de acionamento manual. |
| Previsto no contrato | Situação | Observação |
|---|---|---|
| Backend: API em Python (FastAPI) assíncrona | Entregue | Em operação. |
| Orquestração de GPU | Ajuste técnico | Durante o desenvolvimento, o motor de decisão evoluiu para lógica determinística por regras, sem inferência em GPU. O resultado é superior para este caso de uso: resposta imediata, decisão auditável (cada endereço tem justificativa rastreável) e custo operacional menor. Ajuste amparado pelo Anexo II, parágrafo segundo, por não alterar o escopo funcional. |
| Frontend para o operador em tablet, com rotas otimizadas e mapa de calor | Entregue | Aplicação em uso pela operação, com visualização do armazém, indicadores e gêmeo digital tridimensional. |
| Sistema de fácil manuseio | Entregue | Fluxo de bipagem com dupla conferência (box e peça), validado no chão de fábrica. |
| Velocidade na tomada de decisões e assertividade | Entregue | Decisão de endereçamento em tempo interativo. A assertividade depende diretamente do frescor do dado — ver seção 5. |
| Arquitetura Hybrid Cloud (Oracle Cloud + RunPod) | Ajuste técnico | Solução migrada para infraestrutura dedicada, decisão tomada em conjunto ao longo do projeto e alinhada à preferência de manter os dados em ambiente controlado. Sem impacto no escopo funcional. |
| Alta disponibilidade e escalabilidade horizontal | Em evolução | O sistema opera de forma estável no volume atual. A escalabilidade horizontal plena depende de reestruturação já mapeada por nós, cuja primeira etapa foi entregue em 04/08. |
| Fase | Situação | Observação |
|---|---|---|
| Fase 1 — Setup de infraestrutura e base técnica | Concluída | Infraestrutura, banco, servidores de aplicação, segurança, acessos e monitoramento operacionais. |
| Fase 2 — Conectores e engenharia de dados | Concluída com restrição | Conectores implementados e funcionando sobre a interface disponibilizada. A forma de integração prevista no Anexo II (captura de mudanças direto do banco) não pôde ser utilizada — detalhamento na seção 5. |
| Fase 3 — Core de inteligência | Concluída | Algoritmos de otimização logística, lógica de cálculo e simulação de cenários em produção. |
| Fase 4 — Integração de frontend e experiência do usuário | Concluída | Interface integrada ao core, com visualizações operacionais e indicadores. |
| Fase 5 — Go-live, treinamento e estabilização | Em curso | Sistema publicado e em uso pela operação, com acompanhamento assistido. A estabilização é justamente a etapa em andamento, e é o objeto principal deste relatório. |
"Ainda que realizada a ativação definitiva do sistema, será considerado um período de utilização para validação operacional pelo prazo de 120 (cento e vinte) dias, durante o qual poderão ser realizados ajustes ou modificações necessárias para adequação do funcionamento às condições reais de uso, sem que isso descaracterize a ativação ou implique reconhecimento de falha da CONTRATADA."
É exatamente nesse período que o projeto se encontra. Os casos relatados são o funcionamento esperado dessa etapa: o sistema em uso real revela ajustes que nenhum ambiente de teste revelaria. Cada um foi tratado em prazo curto, com causa identificada e correção verificada.
Este é o ponto central do relatório, e pedimos atenção especial a ele — não como cobrança, mas porque é a informação que muda o desfecho do projeto.
A arquitetura contratada, descrita no Anexo II e parte integrante do contrato, previa a integração com o Oracle da seguinte forma:
"A arquitetura foi projetada para operar sobre o banco de dados Oracle existente da CONTRATANTE, utilizando captura de mudanças via logs do banco para sincronização em tempo real, processamento por modelos de Machine Learning e visualização tridimensional do armazém em aplicação web."
A sincronização em tempo real prevista nessa arquitetura não pôde ser implementada, pois o acesso à captura de mudanças do banco não foi disponibilizado. O que recebemos foi uma interface REST com uma única operação de leitura: a listagem completa do estoque, sem qualquer filtro.
Construímos a solução sobre o que estava disponível, e ela funciona. Mas é importante que fique claro, de forma serena e objetiva: a "cópia local que envelhece" — origem de cinco dos sete casos deste relatório — é consequência direta dessa substituição. Com sincronização em tempo real, aquela família de problemas não existiria.
Não trazemos isso como atribuição de culpa. A equipe de vocês tem suas próprias restrições técnicas e de segurança, que respeitamos integralmente. Trazemos porque:
"O prazo estimado para a execução completa do projeto (...) será de 120 (cento e vinte) dias, contados exclusivamente a partir da data de aprovação formal e expressa do briefing técnico inicial pelo CONTRATANTE, bem como do efetivo recebimento, em sua integralidade, de todos os acessos, informações, materiais e autorizações necessárias à execução do projeto, conforme solicitado pela CONTRATADA."
"O cronograma descrito neste Anexo possui caráter estimativo-operacional, podendo ser ajustado mediante comum acordo entre as partes, em razão de dependências técnicas, atrasos no fornecimento de informações, acessos ou dados pela CONTRATANTE, ou eventos de força maior."
A alternativa, caso o acesso direto ao banco permaneça inviável, é igualmente eficaz e bem mais simples de implementar do lado de vocês: um conjunto de cinco consultas de leitura sobre a mesma view que já utilizamos. É o que apresentamos a seguir.
Todas são somente leitura, sobre a mesma view e com as mesmas colunas do
/estoque/exportar atual. Mesma autenticação, mesmo formato de resposta. Nenhuma
altera os endpoints existentes — são adições.
Existe precedente no próprio módulo: o /faturado/exportar já aceita filtro por
data (dtfaturamento_ini e dtfaturamento_fim). É exatamente o mesmo
padrão que solicitamos.
GET /estoque/ocupacao-por-box resposta: cdbox, qtd_pecas, soma_area_m2
Para decidir onde guardar um rolo, o sistema precisa conhecer a ocupação de todos os boxes candidatos simultaneamente. Como agregado, são cerca de 4.600 linhas (uma por box) em vez de 32 mil peças. É um agrupamento simples sobre a view existente.
É esta consulta que torna possível o sistema decidir sem depender de cópia local. Resolve a origem dos casos 2.3, 2.5 e 2.6.
GET /estoque/por-pedido?pedido=532077
A regra central do endereçamento é manter o pedido junto. Sem esta consulta, descobrir onde o pedido já está guardado exige varrer o estoque inteiro. Relacionada diretamente ao caso 2.6.
POST /estoque/por-ids
body: { "ids": [5370890, 5370808, ...] } (até ~200 por chamada)
Ao montar uma viagem, conferir ao vivo onde cada peça está, se entrou em romaneio e se já foi faturada. Resolve a origem dos casos 2.2 e 2.4.
GET /estoque/por-cdpeca?cdpeca=G000443749
O código impresso na etiqueta que o operador bipa não é o identificador interno da peça, por isso precisa ser uma busca própria. Resolve a origem do caso 2.1.
GET /estoque/exportar?alterado_desde=2026-08-10T09:00:00
Retornando também o que saiu do estoque — uma coluna de situação (DISPONIVEL ou BAIXADA),
como o /estoque/atualizar já reporta. Mantém as telas de acompanhamento
atualizadas sem baixar o estoque completo. Requer um carimbo de última alteração por peça;
se já existir coluna de auditoria na tabela, basta expor o filtro sobre ela.
| Consulta | Natureza | Alvo |
|---|---|---|
| Peças de um pedido · Lote de peças · Código de barras | Interativa, com o operador aguardando | 800 ms (percentil 95) |
| Mapa de ocupação por box | Consultada a cada decisão de endereçamento | 1 segundo |
| Alteradas desde um horário | Processo de fundo, a cada 1 a 2 minutos | 10 segundos |
São buscas por chave natural (pedido, identificador, código). Caso a view atual não entregue esses tempos, um índice nessas colunas resolve. Se algum alvo não for viável na infraestrutura de vocês, precisamos saber antes — o desenho do nosso lado se adapta ao que for possível.
Do nosso lado, cada consulta é ativada individualmente por configuração, com retorno imediato ao comportamento anterior. Isso permite validar item por item, em produção, sem qualquer risco para a operação. Nenhuma delas altera endpoints existentes.
Este tópico é apresentado com o objetivo de proteger o resultado do projeto e o investimento de vocês — não de restringir a colaboração, que tem sido produtiva.
Ao longo da fase de estabilização, chegam solicitações de naturezas bastante diferentes, hoje tratadas todas pelo mesmo canal e com a mesma urgência. Distingui-las torna a entrega mais rápida para todos:
| Natureza | Exemplo real deste projeto | Tratamento |
|---|---|---|
| Defeito | Rolo não aparece na bipagem; tarefa apontando para box cheio | Prioridade máxima Correção imediata, sem custo. É garantia contratual. |
| Regra operacional nova | Artigo 55020 passar a ser tratado como ramado; filas 26 a 32 como complemento | Incorporada Ajuste pequeno, absorvido sem custo (cláusula 4.4, parágrafo único). |
| Mudança de diretriz | Alteração de critério de capacidade, prioridade ou fluxo já homologado | Requer alinhamento Impacta prazo e demanda revalidação. Contrato: cláusulas 3.6-IV e 4.4. |
| Escopo novo | Funcionalidade não prevista no briefing aprovado | Termo aditivo Prazo e valor definidos previamente. Contrato: cláusulas 2.8 e 11.2. |
"A CONTRATADA será responsável pela condução técnica do projeto, incluindo a definição das soluções, metodologias, arquitetura e critérios de validação técnica, em razão de sua comprovada expertise profissional. A CONTRATANTE ficará responsável por homologar a funcionalidade final da solução, manifestando sua aprovação ou eventuais ressalvas exclusivamente ao término da implantação, não lhe cabendo a validação técnica, operacional ou metodológica das etapas intermediárias."
Trazemos essa cláusula não para nos afastarmos do diálogo — ao contrário, o retorno da operação de vocês tem sido essencial e queremos que continue. Trazemos porque, na prática recente, decisões de caráter técnico têm sido revisadas durante as etapas intermediárias, e cada revisão desse tipo reinicia ciclos de validação já concluídos.
Um exemplo concreto e recente ilustra bem o ponto. O caso 2.6 (pedido espalhado) decorria de duas regras conflitantes, ambas definidas pela operação de vocês: o cálculo de capacidade por área do box e o limite por contagem de peças. Nenhuma das duas estava errada isoladamente; juntas, se anulavam. O sistema obedecia fielmente às duas. Situações assim não são resolvidas com mais correções — são resolvidas definindo qual regra prevalece.
"Compete à CONTRATADA, na qualidade de especialista técnica, assegurar que o desenvolvimento, a parametrização e a implementação do sistema sejam realizados em conformidade com o briefing técnico aprovado (...), não lhe sendo imputável responsabilidade por erros, inconsistências ou inadequações decorrentes de informações, conteúdos, diretrizes ou aprovações fornecidas pelo CONTRATANTE."
O objetivo é um só: menos retrabalho, entregas mais previsíveis e uma operação que ganha estabilidade a cada semana.
Solicitamos, de forma respeitosa e fundamentada, a prorrogação do prazo de estabilização, com a definição conjunta de novos marcos.
A fundamentação está descrita ao longo deste relatório e se resume a três fatores objetivos:
"A CONTRATADA poderá propor ajustes nos prazos ou etapas do cronograma, desde que devidamente justificados e condicionados à anuência formal da CONTRATANTE."
"Alterações em APIs de terceiros, mudanças legais ou descontinuação de serviços de infraestrutura que impactem o funcionamento do sistema constituem eventos de risco tecnológico. Nesse caso, as partes negociarão aditivo para ajuste de prazo e/ou de custo, sem que se configure inadimplemento."
| Marco | Condição | Prazo proposto |
|---|---|---|
| Estabilização sobre a integração atual | Independe de terceiros | Contínua, com relatório de acompanhamento quinzenal |
| Integração das consultas de prioridade 1 | A partir da disponibilização pelo TI da Urbano | Até 15 dias corridos após a liberação |
| Integração das consultas de prioridade 2 e 3 | A partir da disponibilização | Até 20 dias corridos adicionais |
| Homologação final e encerramento da estabilização | Após operação assistida com as consultas ativas | 30 dias corridos após a última integração |
Os prazos acima são propostas de trabalho e estão abertos a ajuste conjunto. Colocamo-nos à disposição para revisá-los na próxima reunião, com o cronograma formalizado por termo aditivo, como o contrato prevê.
O sistema está em operação, com todas as correções da seção 2 aplicadas e verificadas em produção.
Entre 07 e 10/08 os tablets ficaram sem alcançar o sistema. A causa foi a indisponibilidade do serviço externo que publicava o endereço de acesso — não do sistema, que permaneceu no ar e saudável durante todo o período. Assumimos a responsabilidade por aquela escolha de infraestrutura e já a substituímos. O acesso agora é direto, com domínio e certificado próprios, sem qualquer intermediário:
https://urbano.plim.ai
Essa dependência específica deixou de existir.
Seguimos integralmente comprometidos com a entrega deste projeto e com o resultado operacional que ele se propõe a gerar. As correções continuam sendo tratadas com prioridade máxima, independentemente das definições acima. O que este relatório propõe é apenas o caminho para sair do ciclo de correções pontuais e chegar à estabilidade definitiva.