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.

44 notas

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

Guias técnicos/docs/guias/catalogo-painel-api-e-storefront

Catalogo - Painel API e Storefront

O catalogo deixou de ser apenas um conjunto de mocks locais.

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.

Atualizado19 de mar. de 2026
Seções20
Tags4
guiacatalogoprodutosapi

O que mudou

O catalogo deixou de ser apenas um conjunto de mocks locais.

Agora ele tem uma camada propria de dominio com:

  • store administrativo;
  • persistencia hibrida;
  • APIs do painel;
  • API publica versionada;
  • consumo real pelo storefront.

Modelo atual do dominio

O catalogo nao esta sendo montado como um JSON solto gigante.

Hoje ele combina:

  • produto como entidade principal;
  • categoria como estrutura de organizacao;
  • colecao como agrupamento comercial;
  • campos tipados para o nucleo operacional;
  • JSON opcional para extensoes futuras.

Nucleo tipado

O que e critico para operacao e performance segue em campos claros:

  • identificacao;
  • status;
  • disponibilidade;
  • preco;
  • estoque;
  • fornecedor;
  • dimensoes;
  • atributos;
  • variacoes;
  • SEO;
  • categorias;
  • departamentos;
  • colecoes.

Extensao controlada

Quando surge uma propriedade nova que ainda nao merece virar coluna fixa, o sistema usa:

  • customFields no produto;
  • metadata em categoria;
  • metadata em colecao.

Isso permite:

  • continuar persistindo mesmo com campos vazios;
  • inserir novos atributos sem quebrar a leitura do storefront;
  • depois promover um campo para estrutura fixa, se ele virar parte obrigatoria do negocio.

Ordem de resolucao

Painel

  1. o admin lista produtos por /api/ecommpanel/catalog/products;
  2. cria ou atualiza por POST e PUT;
  3. faz o mesmo para categorias e colecoes;
  4. a operacao grava em arquivo, banco ou ambos, conforme o modo de persistencia.

O runtime do catalogo e a camada que fica entre painel e banco.

Ele concentra:

  • normalizacao de dados;
  • estrategia de persistencia;
  • seed inicial do banco em modo hybrid;
  • leitura consolidada para API publica;
  • fallback quando o banco nao esta disponivel.

Em resumo: o painel nao escreve direto no storefront. Ele escreve no runtime do catalogo, e a loja le esse runtime pela API.

API publica

  1. /api/v1/catalog/products consulta o runtime do catalogo;
  2. aplica filtros, facets e paginacao;
  3. devolve envelope v1 com cache HTTP.

Storefront

  1. quando NEXT_PUBLIC_DATA_SOURCE=app, a PLP consulta /api/v1/catalog/products;
  2. a PDP consulta /api/v1/catalog/products/[slug];
  3. se a API falhar, o frontend ainda consegue cair no fallback local.

Contrato atual

Escrita

  • admin -> /api/ecommpanel/catalog/*
  • rotas admin -> catalogStore
  • catalogStore -> arquivo, banco ou ambos

Escrita em modo demonstração

Quando a sessão autenticada for do perfil demo:

  • admin -> /api/ecommpanel/catalog/*
  • rotas admin -> catalogStore
  • catalogStore -> snapshot temporário daquela sessão

Nesse caso, o banco e os arquivos oficiais não são alterados.

Leitura

  • loja -> /api/v1/catalog/*
  • API publica -> catalogStore
  • catalogStore -> banco ou arquivo, conforme o modo

Isso significa que o contrato atual ja esta consolidado:

  • painel e storefront nao implementam regras separadas;
  • os dois passam pelo mesmo dominio;
  • a loja recebe uma visao integra do que foi salvo.

Expansao atual do produto

O formulario administrativo do catalogo agora cobre mais camadas do produto:

  • base comercial: nome, slug, SKU, marca, categorias e preco;
  • estoque: saldo disponivel, reservado, entrada, seguranca, reposicao e flags de oversell/backorder;
  • identificacao: GTIN, EAN, referencia interna, MPN, NCM, CEST e origem;
  • fornecedor: id, nome, SKU no fornecedor e custo;
  • dimensoes: peso, altura, largura e comprimento;
  • atributos e variacoes: listas JSON controladas para SKU derivado e filtros comerciais.

Isso deixa o contrato mais proximo do que sera usado no modulo real de produto e estoque, sem obrigar uma migracao brusca do schema a cada novo detalhe operacional.

No modo demo, a mesma regra continua valendo, mas só dentro da sessão de demonstração. O storefront oficial permanece isolado.

Estado atual do cache

Hoje existe uma separacao intencional:

  • a API publica envia Cache-Control;
  • o storefront ainda consome com no-store em modo app;
  • isso evita leitura velha durante a fase de consolidacao do banco.

Portanto:

  • consistencia primeiro;
  • cache forte depois, por camada de projecao.

Como isso deve evoluir

Quando o catalogo estiver mais maduro, a recomendacao e:

  1. banco como fonte de verdade;
  2. runtime administrativo escrevendo no banco;
  3. API publica lendo uma projecao otimizada;
  4. cache com invalidação por alteracao de produto, categoria, colecao, preco e estoque.

Arquivos e codigo principais

  • src/features/catalog/server/catalogStore.ts
  • src/features/catalog/server/catalogDatabaseStore.ts
  • src/app/api/ecommpanel/catalog/products/route.ts
  • src/app/api/ecommpanel/catalog/products/[productId]/route.ts
  • src/app/api/ecommpanel/catalog/categories/route.ts
  • src/app/api/ecommpanel/catalog/categories/[categoryId]/route.ts
  • src/app/api/ecommpanel/catalog/collections/route.ts
  • src/app/api/ecommpanel/catalog/collections/[collectionId]/route.ts
  • src/app/api/v1/catalog/products/route.ts
  • src/app/api/v1/catalog/products/[slug]/route.ts
  • src/app/api/v1/catalog/categories/route.ts
  • src/features/ecommerce/lib/plpDataSource.ts
  • src/features/ecommerce/lib/gatekeeper.ts

Por que isso importa

Essa mudanca cria a ponte que faltava:

  • o painel passa a operar um produto real;
  • a API publica passa a refletir esse produto;
  • a loja passa a ler a mesma fonte;
  • o catalogo fica pronto para sair do arquivo e consolidar em banco sem reescrever o storefront.

Depois desta base, as proximas evolucoes naturais sao:

  • familias e variacoes mais estruturadas;
  • modulo de estoque transacional;
  • precificacao promocional;
  • promocoes, cupons e gift card.

Leitura seguinte