Visão geral
O Pipeline de Dados é um sistema de processamento em três estágios que transforma dados brutos de produtos em conteúdo de alta qualidade, pronto para feeds e marketplaces. Cada estágio adiciona uma camada de estrutura, validação e enriquecimento — inspirado na arquitetura medallion usada em engenharia de dados.Estágio 1 — Bronze (Ingestão Bruta)
Quando produtos entram no sistema — seja via upload de CSV, import por URL, API ou feed MCP — eles chegam na camada Bronze.Características
- Permissivo — todos os dados são aceitos como estão, com validação mínima
- Idempotente — reimportar o mesmo produto não cria duplicatas; registros existentes são atualizados
- Campos sem schema — colunas não padrão são armazenadas como
attributesflexíveis - Sem transformação — títulos, descrições e preços são preservados exatamente como fornecidos
O que acontece no Bronze
- O arquivo é parseado (CSV, XLSX, JSON feed ou HTML raspado)
- Cada linha é mapeada para o schema interno de produto
- Campos obrigatórios (
title,sku) são verificados quanto à presença - Todos os registros são gravados no repositório com
pipeline_stage: "bronze" - Resumo do import é retornado: total, criados, atualizados, erros
Tipos de entidade suportados
| Entidade | Descrição |
|---|---|
product | Registro base do produto com título, SKU, preço, marca, categoria |
variant | Variantes de tamanho/cor/configuração vinculadas a um produto |
media | URLs de imagens e vídeos associados aos produtos |
Estágio 2 — Silver (Normalizar)
Silver é o primeiro estágio de transformação ativa. Ele normaliza, deduplica e valida os dados de produto para garantir consistência em todo o catálogo.Acionando o Silver
Silver não é automático por padrão. Você o aciona:- Por produto — na página de detalhe do produto → botão “Normalizar”
- Em lote — via painel de ações em lote → selecionar produtos → “Normalizar”
- API —
POST /api/workspace/{workspaceId}/catalogs/{catalogId}/batch/silver
O acionamento automático do Silver pode ser habilitado nas Configurações do Pipeline. Quando habilitado, o Silver roda automaticamente após cada ingestão Bronze.
O que o Silver faz
| Operação | Detalhe |
|---|---|
| Normalização de campos | Title case, remoção de espaços, padronização de códigos de moeda |
| Mapeamento de categorias | Mapeia strings de categoria brutas para a taxonomia do workspace |
| Detecção de duplicatas | Encontra produtos com SKU, GTIN ou similaridade de título correspondentes |
| Validação de URLs | Verifica se URLs de imagens e mídia estão acessíveis (HTTP 200) |
| Correspondência de marcas | Vincula nomes de marcas brutas aos registros de marcas do workspace |
| Schema de atributos | Promove atributos comuns para campos estruturados |
Mapeamentos Silver personalizados
Você pode definir regras de mapeamento de campos personalizadas nas Configurações do Pipeline. Por exemplo:- Mapear
"nome_produto"→title - Mapear
"codigo_item"→sku - Mapear
"cat"→categoryPathcom prefixo"Roupas > "
Estágio 3 — Gold (Pontuar & Analisar)
Gold é o estágio opcional de pontuação de qualidade. Ele analisa cada produto de acordo com um critério configurável e produz uma pontuação de otimização — um número único de 0 a 100 que reflete a completude e qualidade do conteúdo.Acionando o Gold
Gold é sempre manual (ou acionado via API). Não roda automaticamente a menos que esteja explicitamente habilitado.- Por produto — botão “Analisar” no detalhe do produto
- Em lote — selecionar produtos → “Analisar”
- API —
POST /api/workspace/{workspaceId}/catalogs/{catalogId}/batch/gold
Pontuação de otimização
A pontuação é calculada em 7 estágios:| Estágio | Peso | O que é avaliado |
|---|---|---|
| Identidade | 20% | Presença de SKU, GTIN, marca |
| Taxonomia | 15% | Profundidade de categoria, subcategoria |
| Conteúdo | 25% | Comprimento do título, qualidade da descrição, bullet points |
| Mídia | 20% | Contagem de imagens, presença de vídeo, resolução mínima |
| Precificação | 10% | Preço presente, moeda, preço original para descontos |
| Atributos | 5% | Atributos-chave para a categoria do produto |
| SEO | 5% | Slug, meta descrição, densidade de palavras-chave |
Limites de pontuação
| Faixa | Rótulo | Significado |
|---|---|---|
| 85–100 | Excelente | Pronto para todos os canais |
| 65–84 | Bom | Pequenas melhorias necessárias |
| 40–64 | Atenção | Campos importantes ausentes |
| 0–39 | Ruim | Lacunas críticas, não pronto para feed |
Detecção de lacunas
O Gold produz uma lista degaps — campos que, se preenchidos, aumentariam mais a pontuação. Exemplo:
Pesos Gold personalizados
Os pesos de pontuação são configuráveis no nível de equipe ou organização via Configurações do Pipeline. Por exemplo, um catálogo com foco em mídia pode aumentar o peso de Mídia para 35%.Fluxo completo do pipeline
Configurações do pipeline
O comportamento do pipeline é configurável no nível do workspace:- Mapeamentos Silver personalizados — mapear qualquer campo fonte para o schema da Alana
- Pesos Gold personalizados — ajustar pesos de pontuação por workspace
- Auto-acionar Silver — rodar Silver automaticamente após Bronze
- Auto-acionar Gold — rodar Gold automaticamente após Silver (não recomendado para catálogos grandes)
- Modo preview — simular mudanças no pipeline sem gravar nos produtos
Boas práticas
Execute o Silver antes de revisar os produtos
Execute o Silver antes de revisar os produtos
Dados Bronze brutos podem ter capitalização inconsistente, links de marcas ausentes e URLs de imagens quebradas. Executar o Silver primeiro fornece dados limpos para revisar.
Gold é opcional — use-o para priorização
Gold é opcional — use-o para priorização
Você não precisa de uma pontuação Gold para publicar ou distribuir. Use o Gold para identificar quais produtos precisam de mais trabalho antes de uma campanha importante ou envio de feed.
Use ações em lote para catálogos grandes
Use ações em lote para catálogos grandes
Em vez de executar Normalizar ou Analisar produto por produto, use o painel de ações em lote para processar milhares de produtos em uma única operação.
Configure mapeamentos personalizados antes do primeiro import
Configure mapeamentos personalizados antes do primeiro import
Se os arquivos do fornecedor usam nomes de colunas não padrão, configure os mapeamentos Silver antes de importar. Isso garante que o primeiro import chegue no formato correto.