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.

Base do projeto/docs/catalogo-operacao

Catalogo - Operacao

O catalogo concentra os produtos operados pela 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.

Atualizado19 de mar. de 2026
Seções24
Tags4
catalogoecommerceecommpanelprodutos

Papel do modulo

O catalogo concentra os produtos operados pela loja.

Nesta primeira fase, ele cobre:

  • cadastro e edicao de produto no EcommPanel;
  • cadastro e edicao de categorias e colecoes no EcommPanel;
  • leitura publica para PLP e PDP;
  • organizacao do dominio em produto, categoria e colecao;
  • preco, disponibilidade e estoque expandido;
  • campos centrais tipados com area de extensao opcional;
  • migracao gradual entre arquivo e banco.

Rotas principais

Painel

  • /ecommpanel/admin/catalog
  • /api/ecommpanel/catalog/products
  • /api/ecommpanel/catalog/products/[productId]
  • /api/ecommpanel/catalog/categories
  • /api/ecommpanel/catalog/categories/[categoryId]
  • /api/ecommpanel/catalog/collections
  • /api/ecommpanel/catalog/collections/[collectionId]

Storefront e API publica

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

O storefront agora pode usar a propria API interna como fonte principal do catalogo.

Modos de persistencia

Variavel:

bash
ECOM_CATALOG_PERSISTENCE_MODE=hybrid

Modos:

  • files: usa apenas os arquivos administrativos do catalogo;
  • hybrid: prefere PostgreSQL e usa arquivos como fallback e semente;
  • database: usa apenas PostgreSQL e ignora os arquivos como fonte de runtime.

Sandbox de demonstração

Quando o usuário autenticado pertence ao perfil demo_operator, o catálogo administrativo passa a usar um snapshot temporário por sessão.

Comportamento:

  • produtos, categorias e coleções lidos no painel passam a sair desse snapshot;
  • novas alterações não tocam o banco nem os arquivos oficiais;
  • a duração acompanha a sessão demo, com limite de 30 minutos;
  • ao expirar, o snapshot é descartado automaticamente.

Isso vale para o painel administrativo. A loja pública e a API pública continuam lendo apenas a fonte oficial do catálogo.

Persistencia em arquivo

Arquivos administrativos do catalogo:

  • src/data/ecommpanel/catalog/products-index.json
  • src/data/ecommpanel/catalog/products/<productId>.json
  • src/data/ecommpanel/catalog/categories-index.json
  • src/data/ecommpanel/catalog/collections-index.json

Se esses arquivos ainda nao existirem, o sistema cria uma base inicial a partir do catalogo local que ja existia no storefront.

Persistencia em banco

Tabela atual:

  • catalog_products
  • catalog_categories
  • catalog_collections

Escopo atual da tabela:

  • identificacao do produto;
  • slug e SKU;
  • GTIN, EAN, NCM, CEST e referencias internas;
  • preco e preco de lista;
  • status e disponibilidade;
  • categorias, departamentos e colecoes;
  • imagem principal e galeria;
  • descricao curta e longa;
  • SEO;
  • fornecedor, custo e dimensoes;
  • estoque, reserva, entrada e locais de estoque;
  • variacoes / SKUs derivados e atributos comerciais;
  • metadados operacionais.

Estrutura de dados

O catalogo agora segue um modelo misto:

  • campos centrais tipados para o que e operacional e critico;
  • campos de extensao opcionais em JSON para evolucao futura.

Campos centrais tipados

Exemplos no produto:

  • slug
  • sku
  • name
  • brand
  • status
  • available
  • price
  • listPrice
  • categories
  • departments
  • collections
  • stock
  • identification
  • dimensions
  • supplier
  • attributes
  • variants
  • seo

Exemplos em categoria e colecao:

  • slug
  • name
  • description
  • status

Area maleavel

Para nao travar a evolucao do projeto, o banco tambem aceita campos opcionais:

  • catalog_products.custom_fields
  • catalog_categories.metadata
  • catalog_collections.metadata

Esses blocos recebem propriedades novas sem quebrar a leitura da loja. Se estiverem vazios, o runtime continua funcional normalmente.

Como isso evolui no painel

O admin agora opera a estrutura em camadas:

  • produto com formulario operacional;
  • estoque com camada mais detalhada de saldo, reserva, entrada e reposicao;
  • identificacao comercial/fiscal e fornecedor;
  • dimensoes e preparo logistico;
  • variacoes / SKUs derivados via estrutura JSON controlada;
  • categoria com CRUD proprio;
  • colecao com CRUD proprio;
  • campos adicionais e metadados em JSON quando for necessario expandir sem refazer o schema inteiro.

Isso permite crescer com seguranca:

  • o que e essencial fica explicito e tipado;
  • o que e novo ou experimental pode entrar como extensao;
  • depois, se um campo opcional virar regra do negocio, ele pode migrar para coluna propria.

Como a loja consome

Quando NEXT_PUBLIC_DATA_SOURCE=app, a loja deixa de depender diretamente dos mocks locais e passa a consumir:

  • GET /api/v1/catalog/products para PLP;
  • GET /api/v1/catalog/products/[slug] para PDP.

Com isso, o painel, a API publica e o storefront passam a ler a mesma camada de catalogo.

Contrato entre painel, banco e loja

Hoje o fluxo do catalogo funciona assim:

  1. o EcommPanel envia a alteracao para as rotas administrativas do catalogo;
  2. as rotas chamam o runtime do catalogo;
  3. o runtime decide como persistir conforme ECOM_CATALOG_PERSISTENCE_MODE;
  4. a API publica le esse mesmo runtime;
  5. a loja consome a API publica quando NEXT_PUBLIC_DATA_SOURCE=app.

Escrita administrativa

Rotas administrativas principais:

  • POST /api/ecommpanel/catalog/products
  • PUT /api/ecommpanel/catalog/products/[productId]
  • POST /api/ecommpanel/catalog/categories
  • PUT /api/ecommpanel/catalog/categories/[categoryId]
  • POST /api/ecommpanel/catalog/collections
  • PUT /api/ecommpanel/catalog/collections/[collectionId]

Em sessão demo:

  • essas escritas continuam funcionando no admin;
  • mas passam a gravar apenas no sandbox temporário daquela sessão.

Regra de persistencia

  • files: o painel grava so em JSON;
  • hybrid: o painel grava em JSON e tambem faz upsert no PostgreSQL;
  • database: o painel grava somente no PostgreSQL.

Em hybrid, a leitura prefere o banco. Se o banco estiver vazio, o runtime pode semear as tabelas a partir dos arquivos administrativos.

Leitura publica

As rotas publicas:

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

leem o runtime do catalogo, nao os formulários do painel diretamente. Isso garante que a loja enxergue a mesma estrutura consolidada que o admin acabou de salvar.

Integridade e performance no estado atual

Integridade

Hoje a ideia aplicada e:

  • o painel sempre grava no runtime do catalogo;
  • o site nunca consulta o formulario do painel;
  • o site consulta a camada publica do app;
  • produto, categoria e colecao compartilham o mesmo dominio de leitura;
  • o mesmo dominio agora carrega tambem a estrutura ampliada de estoque e variacoes.

Isso reduz divergencia entre o que foi salvo no admin e o que a loja exibe.

Cache

No estado atual:

  • a API publica ja responde com Cache-Control;
  • o storefront em modo app ainda usa fetch(..., { cache: 'no-store' });
  • isso privilegia consistencia durante a migracao para banco.

Ou seja: o contrato ja esta integro, mas o cache do storefront ainda esta num modo mais conservador.

Proxima etapa de performance

Para o catalogo ficar mais rapido em producao, a evolucao natural e:

  • manter o banco como fonte de verdade;
  • gerar uma camada publica de leitura bem estavel;
  • adicionar cache/projecao para PLP, PDP, categorias e colecoes;
  • invalidar ou renovar cache quando houver mudanca no painel.

Essa camada de cache ainda nao e o centro do catalogo hoje. Primeiro estamos consolidando o dominio e a persistencia.

Permissoes atuais

Permissoes relevantes:

  • catalog.products.manage
  • catalog.content.manage
  • catalog.pricing.manage
  • logistics.manage

Perfil pronto:

  • catalog_manager

Limite desta fase

Ainda nao entraram nesta rodada:

  • familias de produto;
  • SKUs separados por variacao;
  • estoque concorrente;
  • promocoes e cupons.

Essa fase resolve a base operacional do produto. A parte transacional mais forte continua para a etapa de banco mais avancada.

Leitura seguinte