Detetor de Grupos Temáticos (Topic Clusters): documentação

Esta documentação descreve a instalação, a configuração e a utilização do módulo Detetor de Grupos Temáticos no PrestaShop 8 e 9. O módulo deteta automaticamente os agrupamentos temáticos do seu catálogo por clustering semântico e sugere as pillar pages em falta, com um rascunho SEO completo para cada oportunidade.

Apresentação

O Detetor de Grupos Temáticos analisa o seu catálogo de produtos para fazer emergir os topic clusters realmente presentes na sua oferta e depois deteta as pillar pages em falta: temas transversais muito cobertos pelos seus produtos, mas sem uma página-mãe estruturante (CMS ou categoria).

Para cada gap detetado, o módulo gera um rascunho completo:

• Título H1 otimizado para SEO
• Slug seguro para URL
• Meta description
• Plano H2 completo em markdown
• Lista das palavras-chave alvo
• Pontuação de prioridade (dimensão × coesão)

Instalação

Pré-requisitos

• PrestaShop 8.0+ ou 9.x
• PHP 8.0 no mínimo (PHP 8.1 ou 8.2 recomendado)
• memory_limit de 512 MB no mínimo (1024 MB recomendado para catálogos grandes)
• Opcional: chave de API OpenAI ou Mistral para o modo embeddings

Procedimento de instalação

1. Descarregue o ficheiro dftopicclusters.zip a partir da sua área de cliente DataFirefly.
2. No back-office do PrestaShop, vá a Módulos → Gestor de módulos e clique em Carregar um módulo.
3. Selecione o ZIP e confirme. O módulo instala-se automaticamente.
4. Depois de instalado, clique em Configurar.

Na instalação, o módulo cria automaticamente:

• As 5 tabelas SQL com o prefixo df_topicclusters_
• O separador principal DataFirefly no menu Melhorar (se ainda não existir)
• O separador filho Topic Clusters sob esse separador principal
• As 19 chaves de configuração por omissão

Primeiro acesso

Uma vez instalado, o módulo fica acessível em Melhorar → DataFirefly → Topic Clusters. O painel apresenta o formulário de lançamento de uma nova análise e o histórico das execuções anteriores (vazio na primeira abertura).

Configuração

Clique no botão Definições, no canto superior direito do painel, para aceder à página de configuração. As definições estão agrupadas em cinco secções.

Geral

Extração de texto

Permite escolher que campos do produto entram na análise. A ponderação por campo é fixa (nome × 3, meta × 2, descrição curta × 2, categorias × 2, etiquetas × 2, descrição longa × 1, características × 1).

• DFTC_INCLUDE_DESCRIPTION — Incluir a descrição longa (recomendado: ativado)
• DFTC_INCLUDE_CATEGORIES — Incluir os nomes das categorias (recomendado: ativado)
• DFTC_INCLUDE_TAGS — Incluir as etiquetas do PrestaShop (recomendado: ativado)
• DFTC_INCLUDE_FEATURES — Incluir as características do produto (recomendado: desativado, exceto se tiver características muito descritivas)

Definições TF-IDF

APIs de embeddings

Deteção das pillar pages

• DFTC_PILLAR_MATCH_THRESHOLD — Limiar de correspondência (por omissão 0.45). Abaixo desse valor, o cluster é marcado como pillar gap. Aumente o limiar para ser mais exigente, baixe-o para ser mais tolerante.

Os três modos em detalhe

Modo TF-IDF (recomendado para começar)

O TF-IDF (Term Frequency × Inverse Document Frequency) é um método estatístico clássico em NLP. O módulo constrói um vocabulário a partir de todos os textos dos produtos, filtra os termos demasiado raros ou demasiado frequentes e representa cada produto como um vetor esparso nesse espaço.

Vantagens: 100 % local, instantâneo, sem custo e sem dependências externas. Excelente para catálogos lexicalmente homogéneos (um domínio, um vocabulário coerente).

Limites: não compreende sinónimos (dois produtos que usem termos diferentes para o mesmo conceito ficam mal agrupados).

Modo OpenAI embeddings

Usa a API OpenAI text-embedding-3-small por omissão. Cada produto é representado por um vetor denso de 1536 dimensões que capta a sua semântica.

Vantagens: compreende os sinónimos, as variantes lexicais e o contexto. Excelente para catálogos diversificados ou com descrições narrativas.

Custo indicativo: cerca de 0,02 USD por milhão de tokens, ou seja, menos de 0,10 USD para um catálogo de 1000 produtos.

Modo Mistral embeddings

Usa a API Mistral mistral-embed por omissão. É um modelo multilingue com bom desempenho, incluindo em português.

Vantagens: alojado na Europa (conformidade com o RGPD facilitada), bons resultados nas línguas latinas e tarifário competitivo.

Lançar uma análise

No painel, o formulário Lançar uma nova análise propõe seis parâmetros:

• Idioma — o idioma em que os textos dos produtos são extraídos e analisados. Faça uma execução distinta para cada idioma ativo da sua loja.
• Modo — TF-IDF, OpenAI ou Mistral (sobrepõe-se à definição por omissão apenas nesta execução).
• N.º de clusters (k) — Deixe 0 para o k automático. Caso contrário, force um valor entre 2 e 100.
• Dimensão mínima — Clusters mais pequenos são descartados (por omissão 3).
• Limiar pillar — Limiar de correspondência abaixo do qual um cluster é marcado como gap (por omissão 0.45).
• Limite de produtos — Limita o número de produtos analisados (útil para depuração ou teste rápido). Deixe 0 para analisar todo o catálogo.

Clique em Lançar a análise. A execução começa de imediato. Para um catálogo de 1000 produtos:

• Modo TF-IDF: 5 a 15 segundos
• Modo embeddings (primeira execução): 30 segundos a 2 minutos, consoante o batch size
• Modo embeddings (execuções seguintes com cache quente): equivalente ao TF-IDF

Ler os resultados

Terminada a execução, acede à página de detalhe. Cada cluster é apresentado como um cartão com quatro secções.

Cabeçalho do cluster

O cabeçalho combina uma etiqueta de estado, um número de cluster e um rótulo gerado. A etiqueta é:

• PILLAR GAP (laranja) — Nenhuma pillar page existente cobre este tema. Oportunidade forte.
• OK (verde) — Já existe uma página CMS ou categoria a cobrir este tema (o módulo fez a correspondência).

O rótulo é composto pelos 3 principais termos do cluster unidos por ·. Exemplo: «ténis · pele premium · calçado».

Estatísticas

• Produtos — Número de produtos no cluster
• Coesão — Semelhança média dos membros em relação ao centroide (0 a 100 %). Quanto mais alta, mais homogéneo é o cluster.
• Correspondência — Pontuação de correspondência com a melhor pillar page existente. Se estiver abaixo do limiar → gap.

Principais termos

Os termos mais representativos do cluster. No modo TF-IDF, são os termos com maior componente no centroide. No modo embeddings, o módulo calcula um TF interno ao cluster ponderado pelo IDF global, para destacar os termos distintivos.

Sugestão de pillar page

Presente apenas quando o cluster está marcado como gap. Contém:

• Título — Título H1 otimizado para SEO, em português natural
• Slug — Seguro para URL, em kebab-case
• Meta description — 150 a 160 caracteres
• Prioridade — Pontuação combinada: dimensão (0.6) × coesão (0.4)
• Plano sugerido — Plano H2 em markdown com as secções habituais (introdução, o que é, como escolher, comparativo, melhores produtos, casos de utilização, erros a evitar, FAQ, CTA)

Produtos do cluster

Lista dos produtos agrupados com a respetiva pontuação de semelhança ao centroide, ordenados por semelhança decrescente. Clique no ID do produto para abrir a ficha diretamente numa nova janela.

Fluxo de trabalho recomendado

Eis uma utilização típica do módulo em 4 etapas.

1. Primeira auditoria — Execute uma análise TF-IDF no seu idioma principal, com os parâmetros por omissão. Examine os clusters marcados como gap: fazem sentido do ponto de vista editorial?
2. Triagem — Para cada gap, use o botão Ignorar se o cluster não justificar uma pillar page (por exemplo, um agrupamento acidental de produtos heterogéneos). Os gaps restantes são as suas prioridades.
3. Redação — Para cada gap retido, crie uma nova página CMS no PrestaShop com o título, o slug e a meta do rascunho. Use o plano H2 como esqueleto de redação. Clique em Marcar como feito depois de publicar.
4. Nova execução — Depois de publicar as novas páginas, volte a executar uma análise. Os gaps anteriores devem agora aparecer como OK (o módulo deteta as novas pillar pages).

Exportação

Na página de detalhe de uma execução, dois botões no canto superior direito permitem exportar:

• CSV — Tabela com uma linha por cluster e as colunas: id_cluster, label, n_members, coesão, pillar_gap, match_score, suggested_title, suggested_slug, suggested_meta, priority_score, target_keywords. Codificação UTF-8 com BOM (compatível com o Excel).
• JSON — Exportação completa, com a lista de produtos por cluster e o plano markdown integral. Ideal para automatização ou integração externa.

Arquitetura técnica

Base de dados

O módulo cria 5 tabelas com o prefixo df_topicclusters_:

• run — Metadados de cada execução (modo, idioma, estado, duração, contadores)
• cluster — Clusters individuais (rótulo, principais termos em JSON, coesão, flag pillar_gap, match_score)
• cluster_product — Pertença produto → cluster com a pontuação de semelhança
• pillar — Sugestões de pillar pages (título, slug, meta, plano, prioridade, estado)
• embedding_cache — Cache dos vetores de embeddings indexado por hash do texto

PSR-4 e autoload

O namespace raiz é DataFirefly/TopicClusters/. O autoload manual é registado através de spl_autoload_register no ficheiro principal do módulo, pelo que não é necessária qualquer dependência Composer.

Controllers e compatibilidade PS 8 / PS 9

O módulo usa um ModuleAdminController legacy (e não um controller Symfony) para garantir a compatibilidade com as duas versões principais. As consultas SQL foram escritas para respeitar os esquemas das duas versões, nomeadamente a remoção da coluna meta_keywords no PS 9.

Desempenho e limites

• Catálogos até 1000 produtos — Execuções em poucos segundos. Sem preocupações particulares.
• 1000 a 10 000 produtos — O modo TF-IDF continua rápido (10-60 s). Modo embeddings: contar com 1 a 5 minutos na primeira execução e tempo instantâneo depois, graças ao cache.
• Mais de 10 000 produtos — Privilegiar o parâmetro Limite de produtos para dividir o trabalho, ou aumentar o memory_limit para 2 GB.

A complexidade do k-means é O(n × k × iter × d), em que n é o número de produtos, k o número de clusters, iter o número de iterações (tipicamente 10-30) e d a dimensão dos vetores (variável em TF-IDF, 1536 na OpenAI).

Resolução de problemas

Nenhum cluster detetado

Verifique se os seus produtos têm conteúdo textual no idioma analisado (pelo menos um nome e, idealmente, uma descrição). Se DFTC_MIN_DOC_FREQ for demasiado alto para o seu catálogo, baixe-o para 1.

Todos os clusters estão marcados como pillar gap

O limiar DFTC_PILLAR_MATCH_THRESHOLD está provavelmente demasiado alto. Experimente 0.30 em vez de 0.45 se a sua loja tiver poucas páginas CMS. Confirme também que as suas páginas CMS e categorias estão ativas.

Erro «Unknown column meta_keywords»

Este erro ocorre no PrestaShop 9 com uma versão anterior do módulo. Atualize para a versão 1.0.0 ou superior, que retira todas as referências a meta_keywords (coluna eliminada no PS 9).

Erro «Compile Error: Access level to processExport() must be public»

Este erro ocorria numa versão anterior à 1.0.0. O nome do método passou a ser doExport(), para evitar a colisão com o AdminControllerCore. Atualize o módulo.

A execução falha com erro de API

Verifique se a chave de API indicada na configuração é válida e tem saldo. Teste com curl na linha de comandos para confirmar que o servidor consegue chegar a api.openai.com ou a api.mistral.ai.

Evoluções previstas

• Criação direta de páginas CMS a partir do rascunho (com um clique)
• Comparação de execuções (antes/depois da publicação das pillar pages)
• Visualização gráfica da rede semântica entre clusters
• Suporte dos embeddings Cohere e Voyage AI
• Cron automático para execuções periódicas