Qualidade do catálogo

Um catálogo com muitos produtos acumula cadastros pobres: sem foto, com descrição de uma linha, sem título de SEO, sem as características que o cliente filtra. A Qualidade do catálogo dá a cada produto uma nota de 0 a 100, mostra onde está o maior déficit da loja, ordena os produtos pelo que mais compensa consertar e oferece uma correção assistida por IA para descrição e SEO.

Como funciona

Do diagnóstico à correção

1. Ver o panorama

   GET /summary mostra a nota média, a distribuição por faixa e quantos produtos têm problema em cada dimensão.

2. Escolher o que consertar

   GET /products devolve a fila por impacto. Filtre por max_score para pegar só os piores.

3. Pedir propostas

   POST /review-jobs com os ids e os campos. O job gera um texto por produto e para em review.

4. Decidir

   Liste as propostas, aprove ou rejeite cada uma (ou aprove todas) e chame apply.

Ciclo de vida do job de correção

Na correção automática o job pula review e applying: vai de running direto para done. cancelled é possível enquanto o job está em queued ou running.

Conceitos-chave

A nota e as seis dimensões

photos (25), description (20), attributes (25), seo (10), price (10) e variations (10). A tabela de regras está em Nota e fila de qualidade. A nota é recalculada quando o produto muda e numa varredura de madrugada.

Produto sem foto

A IA precisa da imagem para escrever. Na correção automática, produtos sem foto são pulados. O campo needs_photo da fila marca esses casos.

Revisão e aplicação

Aprovar e rejeitar só mexem no estado da proposta. A gravação acontece em apply, que é síncrono. Um item pode falhar sem derrubar os outros.

Vendedores têm a própria versão

Cada seller (lojista) vê a nota apenas dos próprios produtos em rotas do painel do lojista, que não fazem parte desta seção.

Endpoints

Erros comuns

• Usar a correção automática em produto importante e ficar surpreso com o texto: ela grava sem ninguém ler. Prefira review-jobs.
• Esperar que apply aplique tudo: ele só grava os itens aprovados.
• Ler proposed com as chaves de current: short_description, meta_title e meta_description aparecem com outros nomes no valor atual.
• Esperar 404 ao cancelar um job que não existe: a rota responde 200 do mesmo jeito.
• Filtrar a fila com dim=seo esperando só os produtos sem SEO: o limite do filtro é 25 pontos e SEO vale 10, então ele não exclui ninguém.
• Esperar que o job de revisão termine sozinho em done: ele para em review até alguém aplicar.
• Tratar 403 ai fix unavailable como falta de permissão: é a loja que não tem o preenchimento por IA.

Próximos passos