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.

Base do projeto/docs/e-commerce-operacao

E-commerce - Operação

O `E-commerce` é o storefront da loja.

Recorte da seçãoBase estrutural do projeto

Nota de referência para contratos, arquitetura, runbook e organização do workspace. É a camada mais estável da documentação.

Atualizado15 de abr. de 2026
Seções14
Tags2
ecommercestorefront

Papel do app

O E-commerce é o storefront da loja.

Hoje ele entrega:

  • home;
  • blog editorial;
  • PLP e PDP;
  • leitura do catalogo via API interna do proprio projeto;
  • carrinho e checkout;
  • área Minha conta como primeira camada de relacionamento com o cliente;
  • pedidos operacionais com rascunho, consolidação e timeline;
  • coleta interna de analytics;
  • páginas dinâmicas publicadas pelo painel;
  • leitura do template publicado para header, home, footer, tema e mega menu.

Também já consegue trocar a home padrão por uma página dinâmica publicada quando o override da home estiver ativo no template.

Como as páginas dinâmicas entram

O storefront tenta resolver o caminho pedido por runtime.

Ordem prática:

  1. normaliza o caminho;
  2. procura no snapshot publicado;
  3. se não achar, verifica se pertence a uma rota nativa;
  4. caso contrario, retorna not_found.

Como o blog entra

O blog segue uma resolução separada do builder genérico.

Rotas:

  • /e-commerce/blog
  • /e-commerce/blog/[slug]

Leitura prática:

  • a listagem usa o índice publicado do blog;
  • o detalhe lê o documento publicado do slug;
  • comentários e reações consultam documentos próprios.

Como o catalogo entra

Quando NEXT_PUBLIC_DATA_SOURCE=app, a PLP e a PDP passam a ler:

  • /api/v1/catalog/products
  • /api/v1/catalog/products/[slug]

Leitura pratica:

  • o storefront deixa de depender diretamente dos mocks antigos;
  • a loja passa a consumir a mesma camada operada pelo painel;
  • se a API falhar, o frontend ainda consegue cair no fallback local.

Como a logistica entra

O storefront agora consulta uma malha logistica real do projeto.

Camadas:

  • origins, para loja, CD, seller ou ponto de retirada;
  • docks, para operacao e janela;
  • zones, para cobertura;
  • policies, para prazo e custo;
  • manualOffers, quando um produto precisa de sobreposicao por origem.

Rotas praticas:

  • /api/ecommerce/logistics/simulate
  • /api/v1/logistics/simulate

Leitura pratica:

  • a PDP simula prazo por produto;
  • o carrinho simula entrega e retirada por CEP;
  • o checkout trava a opcao escolhida na jornada;
  • o pedido consolidado passa a guardar o snapshot logistico escolhido.

Como o template entra

O app tenta ler storefront-template.published.json.

Se não houver snapshot válido:

  • usa fallback interno do próprio storefront.

Override opcional da home

Quando as flags de runtime da home dinâmica estiverem ligadas e o template publicado estiver com home.override.enabled = true:

  1. o storefront tenta localizar o slug publicado definido no template;
  2. se encontrar, renderiza essa página como entrada principal de /e-commerce;
  3. o header e o footer podem ser mantidos ou ocultados conforme a configuração do override;
  4. se não houver página válida, o storefront volta para a home padrão.

Como o analytics entra

O storefront inicializa uma camada interna de analytics no próprio layout.

Hoje ela cobre:

  • page view;
  • heartbeat de sessão;
  • cliques em elementos interativos;
  • busca pelo header;
  • atualização de carrinho;
  • andamento de checkout;
  • compra concluída.

Se o admin habilitar GTM e/ou GA4, os scripts também passam a entrar a partir da configuração publicada do painel, sem edição manual de código.

Como a Minha conta entra

Rota:

  • /e-commerce/minha-conta

Leitura prática:

  • o cliente entra por código enviado ao próprio e-mail;
  • o storefront abre uma sessão dedicada de cliente;
  • cadastro, pedidos e endereços passam a ser lidos do banco;
  • pedidos concluídos no checkout já podem alimentar essa conta;
  • o contrato do cliente fica separado do auth do admin.

Como os pedidos entram agora

O checkout deixou de gerar apenas um orderId solto.

Agora existem duas camadas:

  • commerce_order_drafts, para rascunho e retomada;
  • commerce_orders, para o pedido operacional consolidado.

Leitura prática:

  • o OrderFormContext pode persistir um rascunho durante a jornada;
  • o POST /api/checkout consolida o pedido real;
  • a área do cliente continua lendo sua própria projeção em customer_orders;
  • o painel pode operar o pedido por API sem depender do storefront.

Estado desta etapa:

  • útil para operação e UX agora;
  • já usa persistência real para cliente;
  • já cobre exportação e solicitação de exclusão da conta;
  • ainda falta ampliar recuperação de acesso, favoritos e governança completa de retenção LGPD.

Prioridade do tema

  1. snapshot publicado pelo painel;
  2. query string explicita para inspecao local;
  3. defaults internos.

Rotas reservadas

  • plp
  • cart
  • checkout
  • paginas
  • padrão de PDP /<slug>/p

API pública de leitura

Além das páginas visuais, o ecossistema agora expõe uma camada pública em /api/v1 com cache HTTP para leitura de:

  • páginas publicadas;
  • posts do blog;
  • catálogo;
  • categorias;
  • coleções;
  • simulação logística;
  • rastreio público de pedido por token;
  • saúde operacional do runtime.

Leitura seguinte