Mini site de documentaçãoDeveloper Atlas

Entrada rápida para navegar arquitetura, APIs, operação e guias técnicos do projeto sem depender da estrutura do repositório.

53 notas

Procure por módulo, API, rota, fluxo operacional ou termo do projeto.

Guias técnicos/docs/guias/logistica-operacao-e-simulacao

Logistica - Operacao e Simulacao

A camada logistica deixou de ser apenas um frete simplificado no frontend.

Recorte da seçãoGuia orientado por fluxo

Leitura pensada para explicar responsabilidades, ordem de execução e trechos reais do código com foco no fluxo da implementação.

Atualizado15 de abr. de 2026
Seções20
Tags5
guiaecommercelogisticapainelapi

O que este modulo cobre agora

A camada logistica deixou de ser apenas um frete simplificado no frontend.

Hoje ela cobre:

  • modo operacional simples ou regionalizado;
  • origens de estoque;
  • docas e janelas de retirada;
  • zonas de atendimento por CEP, estado e cidade;
  • politicas de entrega e retirada;
  • ofertas por origem, inclusive sobreposicao manual por produto;
  • simulacao de prazo e custo para PDP, carrinho e checkout;
  • snapshot logistico no pedido consolidado;
  • operacao de malha no painel.

Onde operar no painel

Rotas principais:

  • /ecommpanel/admin/logistics
  • /ecommpanel/admin/orders

Arquivos principais:

  • src/features/ecommerce/server/logisticsStore.ts
  • src/features/ecommerce/types/logistics.ts
  • src/features/ecommpanel/components/LogisticsOperationsManager.tsx
  • src/features/ecommpanel/components/OrderOperationsManager.tsx

Modo operacional da loja

No painel de logística agora existe um bloco de modo operacional.

Ele separa dois cenários:

  • sortimento único, para a fase atual da loja;
  • sortimento regionalizado, para quando a malha passar a esconder itens por cobertura.

Na fase de sortimento único, a operação recomendada é:

  • manter sortimento único;
  • usar seleção de entrega opcional;
  • trabalhar com origem única.

Com isso:

  • a vitrine continua geral;
  • o cliente pode navegar sem cair em um modal obrigatório;
  • entrega e retirada podem ser escolhidas no header, carrinho ou checkout;
  • a simulação ainda calcula prazo e custo antes da conclusão.

Quando a operação evoluir para múltiplas origens ou marketplace:

  • o sortimento passa para regionalizado;
  • a seleção de entrega pode virar obrigatória;
  • o sistema passa a esconder itens sem cobertura para aquele contexto.

Como pensar a modelagem

Origem

Representa quem pode atender o pedido.

Exemplos:

  • loja fisica;
  • centro de distribuicao;
  • seller de marketplace;
  • ponto de retirada.

Cada origem pode:

  • entregar;
  • permitir retirada;
  • responder por um conjunto de estoques do produto.

Doca

Representa a operacao concreta daquela origem.

Exemplos:

  • doca de separacao do CD;
  • janela de retirada da loja;
  • fila de coleta do marketplace.

Zona

Representa a cobertura da malha.

Ela pode combinar:

  • prefixos de CEP;
  • estado;
  • cidade;
  • modos permitidos;
  • ajuste de taxa;
  • ajuste de lead time.

Hoje a cobertura operacional publicada usa principalmente:

  • prefixos de CEP;
  • estado;
  • cidade.

O campo de raio por origem já existe no modelo para preparar a evolução, mas o cálculo geográfico real ainda é uma etapa futura.

Politica

Representa a regra comercial e logistica.

Ela define:

  • modalidade;
  • classe de frete;
  • preco base;
  • preco por item;
  • prazo minimo e maximo;
  • regra de frete gratis;
  • elegibilidade para mesmo dia.

Oferta efetiva

E a combinacao real de:

  • produto;
  • origem;
  • estoque;
  • politica;
  • cobertura.

Ela pode nascer de duas formas:

  • derived, quando o sistema deriva a partir do catalogo e das origens;
  • manual, quando o operador sobrepoe preco, estoque ou SLA para uma origem especifica.

Como o catalogo entra nisso

O catalogo continua dono do produto.

A logistica nao duplica o cadastro base. Ela le:

  • preco;
  • estoque;
  • estoque por warehouse;
  • classe logistica;
  • regionalizacao;
  • disponibilidade.

Depois cruza isso com as origens e zonas.

Na pratica:

  • o produto define o que ele e;
  • a logistica define de onde e como ele sai.

Isso também resolve o cenário de marketplace ou seller parceiro:

  • o produto não precisa ser duplicado para cada loja;
  • a diferença comercial entra por origem e oferta efetiva;
  • o sortimento visível passa a depender da cobertura daquela origem para o cliente.

Como a simulacao funciona

A simulacao entra em tres pontos do storefront:

  • PDP;
  • carrinho;
  • checkout.

Fluxo resumido:

  1. recebe CEP ou endereco;
  2. resolve as zonas compativeis;
  3. busca as ofertas efetivas por item;
  4. monta opcoes de entrega e retirada;
  5. escolhe recomendacao inicial;
  6. grava o recorte no OrderFormContext.

Quando o cliente ainda não definiu como deseja receber, a loja continua mostrando a vitrine geral.

Depois que ele escolhe:

  • entrega, com um CEP válido;
  • ou retirada, com um ponto elegível;

o sortimento passa a ser filtrado para esconder itens sem atendimento naquele contexto, mas isso só acontece quando o módulo estiver em sortimento regionalizado.

Como o pedido usa isso

Quando o checkout consolida um pedido, ele grava:

  • endereco selecionado;
  • lista de opcoes de entrega;
  • lista de opcoes de retirada;
  • opcao escolhida;
  • modo escolhido;
  • snapshot logistico resumido com origem, prazo e politica.

Isso permite que o pedido continue operavel depois, mesmo que a malha mude.

Quando a opção logística vier com splitShipment:

  • o checkout mantém um grupo de compra;
  • cada origem elegível gera um subpedido próprio;
  • os pedidos passam a nascer como ORD-XXXXXX-01, ORD-XXXXXX-02 e assim por diante;
  • cada subpedido mantém sua própria timeline e operação no painel.

Esse comportamento é o que prepara o fluxo de marketplace ou multi-origem real sem duplicar o cadastro do produto.

Na experiência do cliente, esse split também aparece na tela de pedido concluído:

  • a compra base continua destacada;
  • cada pacote aparece com seu número próprio;
  • cada pacote mostra itens, origem e previsão;
  • isso espelha a leitura que depois também pode seguir por e-mail e em Minha conta.

Regra de sortimento na loja

O comportamento operacional esperado agora fica assim:

  • sortimento único

- home, vitrines e PLP mantêm a vitrine geral; - PDP continua normal; - carrinho e checkout calculam entrega quando o cliente informa o endereço ou escolhe retirada.

  • sortimento regionalizado

- home e vitrines mostram geral antes da regionalização, e sortimento filtrado depois; - PLP lista apenas itens com cobertura para o contexto escolhido; - PDP continua acessível, mas pode marcar indisponibilidade se o item não atender aquele endereço; - checkout revalida cobertura antes de concluir.

APIs envolvidas

Storefront interno

  • POST /api/ecommerce/logistics/simulate

API publica versionada

  • POST /api/v1/logistics/simulate

API autenticada de integracao

  • POST /api/integration/v1/logistics/simulate

Escopo:

  • logistics.read

Como operar a fila de pedidos com logistica

No painel de pedidos agora faz sentido usar duas camadas:

  • status, financialStatus e fulfillmentStatus;
  • metadados logisticos do pedido.

Exemplos de manutencao:

  • trocar endereco;
  • ajustar janela prometida;
  • definir transportadora;
  • registrar codigo de rastreio;
  • apontar doca responsavel;
  • manter observacao operacional.

O que ainda e evolucao futura

Esta etapa ja fecha o modulo logistico base.

Ainda pode evoluir depois para:

  • multi-origem mais avancada por seller;
  • regras por geocoordenada e raio real;
  • capacidade por doca;
  • agenda de entrega;
  • frota;
  • roteirizacao;
  • integracao com emissao fiscal e transportadora.

Leitura seguinte