Catálogo de Produtos — Visão Geral

Última atualização: 15 de julho de 2026

O que é este fluxo

O catálogo é a tela onde o vendedor consulta produtos, preço, estoque e promoções. É importante deixar claro desde já um ponto que muda a forma de ler o resto desta documentação: o catálogo é uma tela de consulta, não um ponto de entrada para o carrinho. Não existe, em nenhum lugar do código desta feature, uma ação de "adicionar ao carrinho" ou de navegação para o rascunho de venda a partir de um produto do catálogo. Quem monta o carrinho de uma venda usa a lista de produtos própria da tela de nova venda, documentada em Carrinho e Itens. O catálogo existe ao lado disso, para consulta e para gerar um catálogo digital em PDF.

Esta seção documenta o fluxo em seis partes:

Doc	Conteúdo
Visão Geral (este documento)	Arquitetura, flag de habilitação, gate de filtro vazio
Busca, Filtros e Tipos de Produto	FTS5, tipos de produto, condição de promoção, fallback de similaridade
Cliente e Persistência de Filtro	Handoff vindo da carteira, persistência do filtro, cálculo de preço
Modos de Visualização e Detalhes do Produto	Os cinco modos de exibição, badges, modal de detalhes
Análise de Produto	Busca e ordenação sobre uma lista ainda mockada
Catálogo Digital	Wizard de seleção, geração de PDF e compartilhamento

Arquitetura em camadas

Assim como nos outros fluxos, app/(tabs)/catalogo.tsx é só a camada de roteamento, e toda a lógica mora em features/catalog. A tela em si é sempre envolvida por CatalogGroupsProvider, que resolve os grupos de produtos usados nos carrosséis de categoria (destaques, mais vendidos e afins) de forma independente do useCatalogController.

A feature inteira é gated por flag

Igual à carteira de clientes, a rota redireciona para a home se o catálogo estiver desabilitado:

// app/(tabs)/catalogo.tsx
export default function CatalogoScreen() {
  const settings = useSettings();

  if (settings.get("cfg-ativarcatalogodeprodutos") !== "S") {
    return <Redirect href="/(tabs)/home" />;
  }

  return <CatalogScreen />;
}

Duas outras flags controlam pedaços específicos dentro do catálogo já habilitado: cfg-ativaranalisedeprodutos decide se a opção "Análise de Produto" aparece no menu de mais opções, e cfg-ativarcodigodebarras decide se a opção de leitura por código de barras aparece.

O catálogo não mostra nada sem cliente ou tabela de preço

Antes de qualquer busca acontecer, a tela verifica se já existe um cliente selecionado ou uma tabela de preço (codTab) no filtro. Sem nenhum dos dois, a tela mostra um estado vazio em vez de tentar listar produtos:

// catalog.controller.ts
const isFilterEmpty = !filter?.client && !filter?.codTab;

// catalog.tsx
{controller.isFilterEmpty ? (
  <CatalogEmptyState />
) : (
  <CatalogProductsList controller={controller} />
)}

Isso existe porque preço e disponibilidade de produto dependem diretamente de quem é o cliente e em qual tabela de preço ele está enquadrado, então listar produtos sem esse contexto não faria sentido para o vendedor. A forma mais comum de sair desse estado vazio é chegar ao catálogo a partir de um cliente já selecionado na carteira, documentado em Cliente e Persistência de Filtro.

Arquivos-chave

Arquivo	Responsabilidade
app/(tabs)/catalogo.tsx	Rota da tab, redireciona para home se a flag estiver desligada
features/catalog/catalog.tsx	Screen: cabeçalho, lista, modais e bottom sheets
features/catalog/catalog.controller.ts	Hub de estado: filtro, paginação, modos de visualização, ações de navegação
features/catalog/catalog-groups.provider.tsx	Carrega os grupos/carrosséis de categoria (destaques, mais vendidos, etc.)
services/product/product.service.ts	Orquestra busca, cálculo de preço e fallback de similaridade
repositories/product/product.repository.ts	Queries SQLite, FTS5 de busca e de similaridade
storage/catalog-preferences.storage.ts	Persistência do filtro do catálogo e de preferências de exibição
app/catalog/*	Rotas de pilha para análise de produto e catálogo digital