> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.
# Pipeline de Dados
> Camadas de tratamento Bronze, Silver e Gold que refinam progressivamente os dados de produtos — do import bruto ao conteúdo pronto para distribuição.
## 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.
```mermaid theme={null}
graph LR
A["Import"] --> B["Bronze\n(bruto)"]
B --> C["Silver\n(normalizado)"]
C --> D["Gold\n(pontuado)"]
D --> E["Repositório"]
E --> F["Canvas"]
F --> G["Distribuição"]
style B fill:#cd7f32,color:#fff
style C fill:#aaa,color:#fff
style D fill:#ffd700,color:#000
```
***
## 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 `attributes` flexíveis
* **Sem transformação** — títulos, descrições e preços são preservados exatamente como fornecidos
### O que acontece no Bronze
1. O arquivo é parseado (CSV, XLSX, JSON feed ou HTML raspado)
2. Cada linha é mapeada para o schema interno de produto
3. Campos obrigatórios (`title`, `sku`) são verificados quanto à presença
4. Todos os registros são gravados no repositório com `pipeline_stage: "bronze"`
5. 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](/guides/pipeline-settings). 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](/guides/pipeline-settings). Por exemplo:
* Mapear `"nome_produto"` → `title`
* Mapear `"codigo_item"` → `sku`
* Mapear `"cat"` → `categoryPath` com 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 de `gaps` — campos que, se preenchidos, aumentariam mais a pontuação. Exemplo:
```json theme={null}
{
"score": 58,
"gaps": ["description", "gtin", "secondaryImages"],
"missingFields": ["description", "gtin"]
}
```
### 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](/guides/pipeline-settings). Por exemplo, um catálogo com foco em mídia pode aumentar o peso de Mídia para 35%.
***
## Fluxo completo do pipeline
```mermaid theme={null}
graph TD
A["Dados Brutos\n(CSV / URL / Feed / API)"] --> B["Ingestão Bronze\n(permissivo, idempotente)"]
B --> C{Silver\nacionado?}
C -- sim --> D["Normalização Silver\n(mapear, deduplicar, validar URLs)"]
C -- não --> E["Repositório\n(estado bronze)"]
D --> F{Gold\nacionado?}
F -- sim --> G["Pontuação Gold\n(critério de 7 estágios)"]
F -- não --> E
G --> E
E --> H["Canvas\n(revisar e editar)"]
H --> I["Distribuição\n(feeds, marketplace, API)"]
```
***
## 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
Consulte [Configurações do Pipeline](/guides/pipeline-settings) para a referência completa de configuração.
***
## Boas práticas
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.
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.
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.
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.