Painel - Cadastro de Produto

Objetivo

Explicar o cadastro de produto no EcommPanel em linguagem operacional.

Esta nota foi pensada para quem precisa usar o painel sem depender de leitura técnica do código.

Quando usar esta tela

Use /ecommpanel/admin/catalog/products quando a operação precisar:

• criar um produto novo;
• corrigir preço, estoque ou disponibilidade;
• ajustar a forma de venda;
• definir embalagem e conteúdo real do item;
• preparar variações por cor, tamanho, voltagem ou outras combinações;
• revisar dados fiscais, fornecedor e SEO.

Outras entradas relacionadas do módulo:

• /ecommpanel/admin/catalog: visão geral operacional do catálogo;
• /ecommpanel/admin/catalog/taxonomy: categorias e coleções;
• /ecommpanel/admin/catalog/media: biblioteca de imagens já tratadas;
• /ecommpanel/admin/settings/media: política de upload, compressão e presets.

Ordem recomendada de preenchimento

Para reduzir erro de cadastro, siga esta ordem:

1. base comercial;
2. venda, embalagem e composição;
3. perfil do item e variações;
4. estoque e abastecimento;
5. identificação e compliance;
6. fornecedor e dimensões;
7. conteúdo e SEO;
8. estrutura avançada, apenas se necessário.

Essa ordem acompanha a lógica real da operação: primeiro o que define o item, depois como ele é vendido, depois a grade SKU, e só no fim os blocos mais especializados.

Como ler cada seção

Base comercial

Esta parte responde: o que é o produto e como ele aparece comercialmente.

Campos principais:

• Nome: nome exibido no catálogo e na página do produto.
• Slug: caminho público da URL.
• SKU / Ref: referência principal do produto pai.
• Marca: fabricante ou marca comercial.
• Situação: rascunho, ativo ou arquivado.
• Preço e Preço de lista: preço praticado e preço de referência.
• Imagem principal: URL final usada pelo produto.
• Upload otimizado: envio de arquivo para o pipeline de mídia do painel.
• Categoria principal: classificação principal do item.
• Subcategorias: aprofundamento da navegação.
• Coleções: agrupamento comercial, campanha ou curadoria.
• Disponível para venda: libera ou trava o item para operação comercial.

Regra prática:

• rascunho serve para item ainda em preparação;
• ativo serve para item pronto para operar;
• arquivado tira o item da operação corrente sem apagar histórico.

Como funciona a imagem do produto

Agora o painel aceita duas formas:

• colar uma URL manualmente no campo Imagem principal;
• usar Upload otimizado para o servidor gerar versões leves automaticamente.

Quando usar upload:

• a imagem passa por compressão e redimensionamento;
• o sistema gera variantes físicas para PDP, thumb, zoom e outros usos;
• o campo principal do produto já recebe a variante pensada para PDP.

Recomendação operacional:

• prefira usar o upload do painel;
• deixe URL manual apenas para casos externos, migração ou exceção controlada.

Venda, embalagem e composição

Esta parte responde: como o item é vendido de verdade.

Campos principais:

• Modo de venda: unidade, peso, volume, comprimento ou área.
• Unidade de venda: un, kg, caixa, kit, L e similares.
• Base de preço: a base usada para cobrança.
• Conteúdo de referência: o conteúdo real da unidade vendida.
• Multiplicador interno: quantas unidades existem dentro da unidade comercial.
• Tipo de embalagem: bandeja, caixa, pacote, saco, blister etc.
• Conteúdo por embalagem: quantidade real dentro da embalagem.
• Unidades por pacote: quantas peças internas existem.

Essa separação existe para resolver casos em que o item é vendido de um jeito, mas o conteúdo físico é outro.

Perfil do item e variações

Esta parte responde: qual é o segmento do produto e quais eixos realmente geram SKU.

Perfis atuais:

• Genérico
• Alimentos
• Eletrinho
• Eletro maior
• Vestuário

Campos principais:

• Voltagens
• Cores
• Tamanhos
• Sistema de tamanhos
• Público / gênero
• Eixos operacionais em JSON

Atalhos operacionais:

• Sugerir eixos: usa as listas preenchidas para sugerir a grade de variação.
• Gerar grade: monta as combinações no bloco de variações.

Exemplos:

• vestuário: cor x tamanho
• eletro: voltagem x cor
• alimento simples: normalmente sem grade, ou com uma única variação comercial

Estoque e abastecimento

Esta parte responde: quanto temos, quanto já está comprometido e quando precisa repor.

Campos principais:

• Disponível
• Reservado
• Em entrada
• Segurança
• Ponto de reposição
• Lead time
• Controlar estoque
• Aceitar encomenda
• Permitir venda além do saldo

Regra prática:

• use Segurança para sinalizar alerta;
• use Ponto de reposição para orientar compra;
• use Reservado quando a operação já separou parte do saldo;
• evite Permitir venda além do saldo sem uma regra operacional clara.

Identificação e compliance

Use este bloco quando o item exige rastreio fiscal, comercial ou regulatório.

Campos principais:

• GTIN
• EAN
• Ref. interna
• MPN
• NCM
• CEST
• País de origem

Fornecedor e dimensões

Use este bloco para custo, origem do item e logística física.

Campos principais:

• Fornecedor
• ID do fornecedor
• SKU no fornecedor
• Custo
• Peso
• Altura
• Largura
• Comprimento

Conteúdo e SEO

Use esta parte para o texto público do item.

Campos principais:

• Resumo curto
• Descrição longa
• SEO título
• SEO descrição
• SEO palavras-chave

Estrutura avançada

Use apenas quando o cadastro padrão não cobre a necessidade.

Campos principais:

• Atributos em JSON
• Variações / SKUs em JSON
• Campos adicionais em JSON

Regra prática:

• primeiro tente resolver no formulário padrão;
• só use JSON quando o caso ainda não virou campo operacional do painel.

Exemplos reais de cadastro

1. Carne bovina vendida por unidade com peso variável

Exemplo: peça de picanha de 1.5 kg, vendida como 1 unidade.

Configuração sugerida:

• Modo de venda: unit
• Unidade de venda: un
• Conteúdo de referência: 1.5
• Unidade do conteúdo: kg
• Base de preço: 1
• Unidade da base de preço: un
• Aceitar quantidade fracionada: desligado

Leitura operacional:

• a loja vende uma peça fechada;
• o conteúdo real da peça é em peso;
• a referência em quilo continua documentada sem transformar o item em venda por quilo.

2. Caixa de cerveja com 15 unidades

Exemplo: caixa fechada com 15 latas.

Configuração sugerida:

• Modo de venda: unit
• Unidade de venda: caixa
• Multiplicador interno: 15
• Unidade do multiplicador: lata
• Tipo de embalagem: caixa
• Unidades por pacote: 15
• Vender pela embalagem fechada: ligado

Leitura operacional:

• o cliente compra 1 caixa;
• a composição interna continua explícita para logística, conferência e comunicação.

3. Air fryer com voltagem e cor

Configuração sugerida:

• Perfil do item: Eletrinho
• Voltagens: 110V, 220V
• Cores: Preto, Inox
• Sugerir eixos
• Gerar grade

Resultado esperado:

• quatro combinações operacionais:

- Preto / 110V - Preto / 220V - Inox / 110V - Inox / 220V

4. Camiseta com cor e tamanho

Configuração sugerida:

• Perfil do item: Vestuário
• Cores: Preto, Branco, Azul
• Tamanhos: P, M, G, GG
• Sistema de tamanhos: BR
• Sugerir eixos
• Gerar grade

Resultado esperado:

• uma grade operacional pronta para SKU por cor e tamanho.

Quando usar a grade de variações

Use a grade quando:

• o item muda estoque por combinação;
• o preço pode mudar por combinação;
• a disponibilidade depende de combinação;
• a operação precisa distinguir SKU por cor, tamanho, voltagem ou capacidade.

Não precisa usar grade quando:

• o item é simples;
• o produto pai já representa a unidade final vendida;
• a variação é apenas descritiva e não muda operação.

Checklist antes de publicar

Antes de ativar o produto, confirme:

1. nome, slug e SKU estão corretos;
2. categoria principal foi escolhida;
3. preço está preenchido;
4. forma de venda está coerente com o conteúdo real;
5. estoque inicial foi revisado;
6. item está marcado como disponível apenas se realmente puder vender;
7. grade SKU foi gerada quando houver cor, tamanho ou voltagem;
8. descrição curta e imagem principal estão válidas.

Erros mais comuns

Usar `kg` no campo errado

Se o item é vendido por peça, mas pesa 1.5 kg, não transforme a unidade de venda em kg sem necessidade.

Use:

• venda por un;
• conteúdo de referência em kg.

Misturar pacote com unidade de venda

Se o cliente compra a caixa inteira, a unidade de venda deve refletir isso.

Não trate uma caixa fechada como se fosse uma lata avulsa.

Criar variação só no texto

Se cor, tamanho ou voltagem mudam estoque, preço ou disponibilidade, isso precisa virar variação operacional.

Publicar sem estoque ou sem disponibilidade coerente

ativo e disponível para venda não significam a mesma coisa.

Um item pode continuar ativo no cadastro, mas indisponível para venda naquele momento.

Quando isso acontecer, a vitrine pode seguir dois caminhos:

• esconder o item das listagens;
• manter o item visível com CTA bloqueado e texto como Esgotado ou Disponível em breve.

Essa decisão fica na política operacional do catálogo.

O que o sistema faz depois do salvar

Ao salvar o produto:

1. o painel envia a alteração para as rotas administrativas do catálogo;
2. o runtime normaliza os dados;
3. o runtime grava conforme o modo de persistência;
4. a API pública lê essa mesma camada;
5. a loja passa a enxergar o mesmo contrato consolidado.

Ou seja: o cadastro do painel não é um formulário solto. Ele já conversa com a camada real do catálogo.

Relação com banco e pacote base

O modelo atual do produto já foi expandido para contemplar:

• commercialUnit
• packaging
• merchandising

Esses blocos também foram refletidos:

• no PostgreSQL do catálogo;
• no dicionário interno;
• na modelagem do Data Studio;
• no pacote base de banco.

Leitura seguinte

• 16 - Catalogo - Operacao
• 21 - Catalogo - Painel API e Storefront
• 14 - Mapa de APIs