Cadastro de Produtos

Tela para gerenciar o catálogo de produtos da empresa. Cada produto criado aqui alimenta o fluxo de Gerar Ativos, etiquetas e inventários. A tela oferece suporte completo para campos personalizados, importação e exportação em massa via planilha XLSX, além de controle de quantidades por produto.

Como acessar

• Rota: /cadastro-produto
• Permissão necessária: produto.cadastro_produto
• Feature flag: inventario_2d (controla a coluna/gestão de quantidades por produto)

O que a tela mostra

A tela é composta de:

• Uma barra de ações no topo com botões para criar, gerenciar, importar e exportar.
• Um campo de pesquisa que localiza produtos por qualquer coluna (descrição, código, campos personalizados).
• Uma grade de produtos com paginação (8 produtos por página).
• Colunas dinâmicas que variam conforme os campos personalizados cadastrados.

Quando a feature inventario_2d está ativa, aparece uma coluna de Quantidade e um ícone adicional para gerenciar quantidades por níveis.

O que você pode fazer

• Listar todos os produtos com paginação de 8 por página.
• Pesquisar um produto pelo conteúdo de qualquer coluna (nome, código de barras, campos extras).
• Criar um novo produto informando código de barras, descrição e campos personalizados.
• Editar um produto existente alterando qualquer campo.
• Excluir um produto do catálogo.
• Adicionar novos campos personalizados para expandir o cadastro.
• Exportar um modelo de planilha XLSX com a estrutura esperada para importação em massa.
• Importar múltiplos produtos a partir de uma planilha XLSX preenchida.
• Quando habilitado: gerenciar quantidades de cada produto por nível (modo 2D).

Visão geral da tela principal

Barra de ações

Na parte superior ficam os quatro botões principais:

• Criar Novo Produto: abre o formulário para adicionar um produto à lista.
• Gerenciar Campos: permite criar ou remover campos personalizados do cadastro.
• Exportar Modelo: baixa uma planilha XLSX vazia com a estrutura para importação.
• Importar Produtos: abre o seletor para enviar uma planilha XLSX preenchida.

Campo de pesquisa

Um campo de texto que filtra a grade em tempo real. Busca por:

• Descrição do produto
• Código de barras
• Conteúdo de campos personalizados

A busca é case-insensitive e funciona na página atual.

Grade de produtos

Exibe os produtos em formato de tabela com as seguintes colunas:

• Descrição: nome comercial do produto.
• Código de Barras: identificador do produto (EAN, UPC, etc.).
• Quantidade: quantidade em estoque (visível apenas com inventario_2d ativo).
• Campos Personalizados: colunas extras criadas via Gerenciar Campos.
• Ações: botões para editar, excluir e gerenciar quantidades.

A grade pagina 8 produtos por página. Use os botões de navegação abaixo para mudar de página.

Ações por linha

Cada produto tem três ações rápidas:

• Editar (lápis): altera qualquer campo do produto.
• Excluir (lixeira): remove o produto do catálogo.
• Gerenciar Quantidades (caixa): abre o controle de estoque por nível (quando ativo).

Como usar

Cenário 1: Criar um único produto

1. Clique em Criar Novo Produto.
2. Preencha o Código de Barras (obrigatório).
3. Preencha a Descrição (obrigatório).
4. Preencha os campos personalizados disponíveis (se existirem).
5. Clique em Adicionar para salvar.
6. O novo produto aparece na grade.

Cenário 2: Editar um produto existente

1. Clique no botão Editar (lápis) na linha do produto.
2. Altere os campos desejados.
3. Clique em Salvar para confirmar as mudanças.

Cenário 3: Importar produtos em massa

1. Clique em Exportar Modelo para baixar a planilha vazia.
2. Abra o arquivo em Excel ou Planilhas Google.
3. Preencha as colunas codigo_barras, descricao, quantidade e outros campos (conforme o modelo).
4. Salve o arquivo como XLSX.
5. Retorne à tela e clique em Importar Produtos.
6. Selecione o arquivo preenchido.
7. O sistema processa e adiciona todos os produtos ao catálogo.

Cenário 4: Criar campos personalizados

1. Clique em Gerenciar Campos.
2. Na tela que abre, informe o nome do novo campo no campo "Novo campo".
3. Clique em Adicionar.
4. O novo campo aparece em "Campos Existentes" e também na grade de produtos.
5. Feche o modal; agora você pode preencher este campo ao criar/editar produtos.

Cenário 5: Gerenciar quantidades por nível

Apenas visível quando inventario_2d está ativo:

1. Clique no ícone Gerenciar Quantidades (caixa) na linha do produto.
2. Uma tela abre mostrando os níveis organizacionais.
3. Defina a quantidade para cada nível.
4. Clique em Salvar para confirmar.

Tela Criar/Alterar Produto

Este modal é usado tanto para criar quanto para editar um produto.

Campos:

• Código de Barras: identificador único do produto (obrigatório).
• Descrição: nome comercial ou descrição do produto (obrigatório).
• Quantidade: estoque total do produto (opcional, apenas com inventario_2d).
• Campos Personalizados: qualquer campo extra criado via Gerenciar Campos.

Botões:

• Cancelar: fecha o modal sem salvar.
• Adicionar ou Salvar: confirma a criação ou edição.

Tela Gerenciar Campos

Use esta tela para criar ou remover campos extras do cadastro de produtos.

Campos:

• Novo campo: nome do campo que deseja adicionar.

Seção Campos Existentes:

• Lista todos os campos criados.
• Cada campo tem um ícone de ação para removê-lo.

Comportamento:

• O novo campo fica disponível imediatamente nos formulários de criar/editar.
• A coluna correspondente aparece na grade de produtos.
• Campos personalizados são incluídos automaticamente no modelo de importação.

Tela Exportar Modelo

Um arquivo XLSX é baixado com a seguinte estrutura:

• Coluna A (codigo_barras): identificador do produto.
• Coluna B (descricao): descrição do produto.
• Coluna C (quantidade): quantidade em estoque.
• Colunas D+: cada campo personalizado criado.

Todas as colunas estão vazias, pronta para você preencher os dados dos produtos.

Após preencher, salve como XLSX e use Importar Produtos para enviar.

Tela Importar Produtos

Após clicar em Importar Produtos:

1. Um seletor de arquivo abre.
2. Escolha um arquivo XLSX preenchido.
3. O sistema valida a estrutura e o conteúdo.
4. Se estiver correto, os produtos são adicionados/atualizados no catálogo.
5. Uma mensagem de sucesso ou erro aparece.

Regras de importação:

• O arquivo deve estar em formato XLSX.
• As colunas devem corresponder ao modelo exportado.
• Produtos com código de barras duplicado atualizam o registro existente.
• Campos obrigatórios (código de barras, descrição) não podem estar vazios.

Campos e Colunas principais

• produto_id: identificador único gerado automaticamente.
• codigo_barras: código único do produto (obrigatório).
• descricao: nome ou descrição do produto (obrigatório).
• quantidade: estoque total (opcional, controlado por inventario_2d).
• Campos Personalizados: qualquer campo criado via Gerenciar Campos.

Regras e comportamentos

• A tela depende da permissão produto.cadastro_produto.
• A coluna de Quantidade só aparece quando inventario_2d está ativo.
• A pesquisa é case-insensitive e funciona em todas as colunas visíveis.
• Produtos são paginados com 8 itens por página.
• Ao excluir um produto, o registro é removido do catálogo.
• Campos personalizados não podem ter nomes duplicados.
• A importação valida a estrutura do XLSX antes de processar.
• Produtos duplicados (mesmo código de barras) atualizam o registro anterior.

Estados esperados

• Produto criado com sucesso: novo produto aparece na grade.
• Produto editado com sucesso: alterações aparecem imediatamente.
• Produto excluído com sucesso: linha desaparece da grade.
• Campo criado com sucesso: novo campo aparece em Campos Existentes e na grade.
• Modelo exportado com sucesso: arquivo XLSX baixado.
• Importação concluída: produtos adicionados/atualizados, mensagem de status exibida.
• Erro de validação: mensagem explicando o campo faltante ou formato inválido.
• Quantidade gerenciada com sucesso: distribuição por níveis salva.