# DataFirefly Guia de Tamanhos: documentação

> Visão geral DataFirefly Guia de Tamanhos acrescenta à sua loja PrestaShop um sistema completo de guias de tamanhos modulares por categoria, fabricante ou produto, com tabelas de correspondência EU/US/UK/FR/JP, calculadora…

- Página: <https://www.datafirefly.com/pt/documentation/guide-des-tailles-prestashop/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/guide-des-tailles-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/guide-des-tailles-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/guide-des-tailles-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/guide-des-tailles-prestashop/index.md), [pl](https://www.datafirefly.com/pl/documentation/guide-des-tailles-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/guide-des-tailles-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/guide-des-tailles-prestashop/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## Visão geral

**DataFirefly Guia de Tamanhos** acrescenta à sua loja PrestaShop um sistema completo de guias de tamanhos modulares por categoria, fabricante ou produto, com tabelas de correspondência EU/US/UK/FR/JP, calculadora interativa de recomendação de tamanho, página SEO indexável dedicada por categoria e widget de feedback pós-compra com pontuação de desvio agregada.

O módulo destina-se a lojas de vestuário e calçado em que mais de 20% das devoluções estão ligadas a um problema de tamanho. Transforma essa fricção num percurso de compra tranquilizador: o cliente vê automaticamente a tabela certa, pode introduzir as suas medidas para obter uma recomendação personalizada, e a loja recolhe feedback qualificado que permite detetar os produtos com graduação incorreta.

**Adaptação para Portugal:** as 13 tabelas pré-carregadas e as etiquetas do módulo são entregues em 7 idiomas (FR, EN, ES, DE, IT, NL, PL). O português não faz parte do pacote: após a instalação, traduza os nomes, introduções, instruções de medição e rodapés das tabelas em **Internacional → Traduções** e nos campos multilingue de cada tabela, caso contrário o visitante verá as etiquetas em inglês.

### Compatibilidade

- PrestaShop 8.0.x, 8.1.x, 8.2.x, 9.0.x
- PHP 8.1, 8.2, 8.3
- Multiloja (todas as atribuições são delimitadas por `id_shop`)
- Traduções FR/EN/ES/DE/IT/NL/PL prontas a usar
- Temas classic, hummingbird e temas personalizados (7 posições diferentes disponíveis)

## Instalação

1. Carregue o ZIP `dfsizeguide.zip` em **Módulos → Gestor de módulos → Carregar um módulo**.
2. Clique em **Instalar**. As 13 tabelas predefinidas (vestuário de senhora e de homem, parte de cima e parte de baixo, vestidos, soutiens, calçado de senhora, de homem e de criança, vestuário de criança, luvas, chapéus, anéis, cintos) são criadas automaticamente em 7 idiomas, e é criada uma atribuição por defeito na tabela de vestuário de senhora.
3. Logo após a instalação, o separador "Guia de tamanhos" aparece em todas as páginas de produto sem configuração adicional.
4. Aceda a **Módulos → DataFirefly Guia de Tamanhos → Configurar** para ajustar as posições, a unidade por defeito e as funcionalidades ativas.

## Conceitos-chave

### O resolvedor de tabelas com 5 níveis

Quando um cliente chega a uma página de produto, o módulo procura a tabela a mostrar seguindo uma prioridade estrita:

1. **Produto**: se atribuiu explicitamente uma tabela a esse produto específico, é ela que ganha.
2. **Categoria + Fabricante**: caso contrário, a tabela atribuída ao par formado por uma categoria do produto e a sua marca. Por ser mais específico do que cada uma das duas dimensões isoladas, este nível sobrepõe-se aos dois seguintes. As categorias são percorridas da mais profunda para a mais geral.
3. **Fabricante**: caso contrário, a tabela atribuída à marca do produto.
4. **Categoria**: caso contrário, a primeira categoria do produto que tenha uma tabela, a começar pela mais profunda (respeito pela especificidade).
5. **Por defeito**: caso contrário, a tabela marcada como fallback global.

Esta hierarquia permite manter uma única tabela por marca ou por secção sem tocar nas páginas de produto individuais, mantendo a possibilidade de uma substituição cirúrgica.

### Tipos de colunas

Cada tabela é composta por colunas tipadas:

- **Coluna "tamanho"**: um único valor textual por linha (S, M, 38, XL). Usada para as correspondências internacionais (EU, US, UK, FR, JP).
- **Coluna "medida"**: um intervalo numérico mín./máx. por linha (ex.: perímetro do peito 88–92 cm). Usada para indicar as medidas que correspondem a cada tamanho.

A calculadora interativa baseia-se exclusivamente nas colunas "medida" para determinar o tamanho recomendado.

## Configuração

### Posições na página de produto

O módulo disponibiliza 7 posições ativáveis individualmente em **Configurar → Posições na página de produto**:

- **Separador de produto** (ativo por defeito, recomendado): hook `displayProductExtraContent`, acrescenta um separador próprio ao lado de "Descrição" e "Detalhes". Funciona na quase totalidade dos temas PS 1.7+.
- **Por baixo do preço**: hook `displayProductPriceBlock` (tipo `after_price`), apresenta uma ligação compacta logo abaixo do preço.
- **Junto ao botão "Adicionar ao carrinho"**: hook `displayProductActions`, apresenta um botão compacto.
- **Por baixo das informações do produto**: hook `displayProductAdditionalInfo`, apresenta um botão em destaque.
- **No bloco de confiança**: hook `displayReassurance`, integra-se visualmente com os outros argumentos (entrega, devoluções).
- **Depois das imagens do produto**: hook `displayAfterProductThumbs`, apresenta um botão compacto logo abaixo da galeria.
- **No fundo da página de produto**: hook `displayFooterProduct`, apresenta um botão em destaque no rodapé.

Pode ativar várias posições em paralelo: a janela modal do guia é instanciada uma única vez no DOM (anti-duplicação), e os botões adicionais abrem a mesma modal.

O separador de produto é a única posição que apresenta a tabela _inline_. As outras 6 posições apresentam um botão que abre a modal.

### Parâmetros gerais

- **Unidade por defeito**: cm ou polegadas. O cliente pode alternar em tempo real, e a preferência é mantida no cálculo.
- **Calculadora interativa**: ativa a introdução das medidas e a recomendação de tamanho (ativa por defeito).
- **Feedback dos clientes pós-compra**: ativa o widget que pergunta ao cliente se o tamanho era adequado (ativo por defeito).
- **Dados estruturados JSON-LD**: ativa a injeção da marcação Schema.org para melhorar o SEO (ativa por defeito).
- **Cor de destaque**: cor dos botões, da unidade ativa e da linha realçada. A harmonizar com o seu tema; a tonalidade de hover é calculada automaticamente.
- **Slug da página SEO**: prefixo do URL das páginas de guia dedicadas (por defeito `size-guide`, a traduzir para `guia-de-tamanhos` se quiser um URL em português).

## Criar e editar uma tabela

Menu **Módulos → Guias de tamanhos → Tabelas**. Clique em "Adicionar" para criar uma nova tabela, ou no ícone de lápis para editar uma tabela existente.

### Campos da tabela

- **Código interno**: identificador técnico único (ex.: `senhora-vestidos-2026`). Usado nos URLs SEO e nos registos.
- **Tipo**: vestuário parte de cima, vestuário parte de baixo, vestido, calçado ou personalizado.
- **Nome**: etiqueta multilingue apresentada aos clientes (título do separador, título da modal, h1 da página SEO).
- **Introdução (HTML)**: conteúdo multilingue apresentado acima da tabela.
- **Instruções de medição (HTML)**: bloco expansível que explica como tirar cada medida.
- **Rodapé (HTML)**: conteúdo multilingue apresentado abaixo da tabela (aviso, ligação para a política de devoluções, etc.).
- **Meta title / Meta description**: para a página SEO dedicada.
- **Ativa**: interruptor on/off. Uma tabela inativa nunca é servida, mesmo que esteja atribuída.

### Editar a grelha

Por baixo do formulário da tabela, um editor visual permite construir a grelha:

1. Clique em **Coluna tamanho** para adicionar uma coluna textual. Preencha o código (ex.: `eu`, `intl`) e a etiqueta multilingue.
2. Clique em **Coluna medida** para adicionar uma coluna numérica. Preencha o código (ex.: `chest_cm`) e a unidade (cm, polegadas, mm).
3. Clique em **Linha** para adicionar uma linha. Preencha as células: texto simples para as colunas "tamanho", valores mín./máx. para as colunas "medida".
4. Clique em **Guardar**. A gravação é feita numa transação SQL atómica: ou é tudo guardado, ou nada é.

### Duplicar uma tabela

O botão **Duplicar** da lista copia a tabela, as suas traduções, as suas colunas e respetivas etiquetas, as suas linhas e todas as células. Útil para derivar uma variante de uma tabela existente em vez de partir de uma grelha vazia.

Dois pontos a ter em conta. As atribuições não são copiadas: são únicas por alvo, pelo que duplicá-las roubaria os alvos à tabela de origem. E a cópia é criada **inativa**, para que não possa ser servida antes da sua revisão. O código interno é derivado automaticamente (`senhora-cima` passa a `senhora-cima-copy`), já que tem de permanecer único.

## Atribuir uma tabela

Menu **Módulos → Guias de tamanhos → Atribuições**.

1. Escolha a tabela a atribuir na lista.
2. Escolha o tipo de alvo: Por defeito (fallback global), Categoria, Fabricante, Categoria + Fabricante ou Produto.
3. Consoante o tipo, aparece um segundo campo para escolher a categoria (numa árvore indentada), a marca (lista pendente) ou o ID do produto (introdução direta).
4. Clique em **Adicionar / Atualizar**. Se já existir uma atribuição para esse alvo, é substituída (upsert).

Todas as atribuições são delimitadas por loja em modo multiloja. Pode ter uma tabela diferente para a mesma categoria em duas lojas do mesmo grupo.

### Modificar uma atribuição

O lápis no fim da linha recarrega a atribuição no formulário, com a sua tabela, o seu tipo de alvo e o seu alvo. Pode então mudar a tabela, mas também deslocar a atribuição para outro alvo ou transformar uma atribuição simples numa combinação categoria + fabricante. A linha em causa é realçada na lista, e um botão Cancelar permite sair sem alterar nada.

Deslocar uma atribuição para um alvo já ocupado por outra é recusado com uma mensagem explícita, uma vez que cada alvo só pode ter uma única tabela.

## A calculadora de tamanho

A calculadora aparece por baixo da tabela, apenas se a tabela tiver pelo menos uma coluna "medida".

### Algoritmo de pontuação

O cliente introduz as suas medidas nos campos (um campo por coluna "medida"). Ao submeter:

1. Os valores são normalizados em centímetros (conversão automática se o utilizador escolheu polegadas: ×2,54).
2. Para cada linha da tabela, o módulo calcula uma pontuação: **+2 pontos** se a medida do cliente cair exatamente no intervalo mín./máx. da célula, **+1 ponto** se estiver próxima (a ±5% do intervalo), **0 pontos** caso contrário.
3. A linha com a pontuação mais elevada é declarada vencedora.
4. Em caso de empate, é escolhida a linha cujos intervalos estão mais centrados nos valores do cliente.
5. O tamanho recomendado é extraído prioritariamente da coluna `eu`, depois `fr`, `intl`, `uk`, `us`, `jp`.

### Feedback ao utilizador

A calculadora apresenta o tamanho recomendado com uma pontuação de confiança em percentagem, o top 3 das candidatas possíveis, cada uma com a sua pontuação, o realce da linha recomendada na tabela acima, e a lista das medidas que não correspondem a nenhuma linha (com aviso).

## Feedback dos clientes pós-compra

Um widget "O tamanho era adequado?" aparece no fundo da página de produto com 5 opções: demasiado pequeno, um pouco pequeno, perfeito, um pouco grande, demasiado grande. É apresentado apenas nas seguintes condições:

- O cliente tem sessão iniciada (sessão ativa).
- O cliente comprou efetivamente esse produto (join com `orders` e `order_detail`, estado válido).
- O cliente ainda não deu a sua opinião sobre esse produto.

A verificação é feita integralmente do lado do servidor, sem risco de contorno.

### Painel do feedback

Menu **Módulos → Guias de tamanhos → Feedback dos clientes**. Uma síntese acima da tabela mostra o número de respostas em cada categoria nos 5 níveis. Por baixo, a lista completa do feedback por produto com o ID do cliente, o tamanho comprado e a data.

### Pontuação de desvio

Para cada produto com pelo menos 3 respostas, é calculada uma pontuação de desvio:

```
score = ((too_large × 2 + slightly_large) − (too_small × 2 + slightly_small)) / total
```

Uma pontuação **positiva** indica que o produto veste sistematicamente grande (a corrigir um tamanho para baixo). Uma pontuação **negativa** indica que veste pequeno (a corrigir um tamanho para cima). Uma pontuação próxima de zero indica uma boa graduação.

## Página SEO dedicada

O módulo disponibiliza uma rota pública por categoria: `/{slug}/{category-link-rewrite}`, em que `{slug}` é o prefixo configurado (por defeito `size-guide`).

Exemplo: `https://asualoja.pt/guia-de-tamanhos/vestidos-senhora`

A página contém um caminho de navegação, o título h1 da tabela, a introdução, as instruções de medição e a tabela completa, a calculadora (se ativa), o rodapé HTML da tabela, e uma marcação JSON-LD `WebPage` Schema.org que ajuda o Google a perceber que a página é um guia prático.

As etiquetas meta title e meta description vêm dos campos SEO da tabela. Configure-as corretamente para captar pesquisas de cauda longa do tipo "guia de tamanhos vestidos senhora".

## Multilingue e multiloja

O módulo é multilingue ao nível das tabelas (nome, introdução, instruções, rodapé, meta), ao nível das etiquetas das colunas e ao nível das etiquetas de tradução dos URLs.

Em multiloja, cada atribuição (guia → alvo) é delimitada por `id_shop`. Pode assim mostrar a tabela A para a categoria "Calçado" na loja portuguesa e a tabela B para a mesma categoria na loja espanhola.

## Estrutura técnica

### Base de dados

8 tabelas com o prefixo `dfsg_`: `dfsg_guide`, `dfsg_guide_lang`, `dfsg_column`, `dfsg_column_lang`, `dfsg_row`, `dfsg_cell`, `dfsg_assignment`, `dfsg_feedback`. Todas as tabelas são removidas de forma limpa na desinstalação.

### Hooks utilizados

- `actionFrontControllerSetMedia`: injeção de CSS/JS no front-office
- `displayBackOfficeHeader`: injeção de CSS/JS no back-office
- `displayProductExtraContent`: separador na página de produto (recomendado)
- `displayProductPriceBlock`, `displayProductActions`, `displayProductAdditionalInfo`, `displayReassurance`, `displayAfterProductThumbs`, `displayFooterProduct`: posições alternativas
- `displayHeader`: injeção de JSON-LD nas páginas de produto
- `actionValidateOrder`: gatilho para eventuais lembretes (v2)
- `moduleRoutes`: página SEO dedicada

## FAQ

### O guia não aparece na minha página de produto, o que fazer?

Verifique primeiro em **Configurar → Posições na página de produto** que pelo menos uma posição está ativa (Separador de produto por defeito). Se o seu tema personalizado não apresentar os hooks nativos do PrestaShop, ative várias posições em paralelo: pelo menos uma das 7 deverá funcionar. Verifique também que existe pelo menos uma tabela ativa e uma atribuição por defeito em **Guias de tamanhos → Atribuições**.

### Posso importar tabelas a partir de um CSV?

Ainda não. O editor visual permite construir e modificar as tabelas em tempo real, coluna a coluna e linha a linha. A importação CSV está em estudo para uma versão posterior.

### A calculadora funciona sem JavaScript?

Não, a calculadora é interativa e precisa de JavaScript para fazer a chamada AJAX ao servidor. Em contrapartida, a tabela estática é apresentada perfeitamente sem JS, o que preserva a acessibilidade e o SEO.

### Existe risco de marcação JSON-LD duplicada?

Não. O hook `displayHeader` emite um único script JSON-LD por página de produto, e a página SEO dedicada tem a sua própria marcação `WebPage` distinta. O validador Schema.org do Google não assinala nenhum duplicado.

### Compatível com a migração de PrestaShop 8 para 9?

Sim. O módulo declara `ps_versions_compliancy` de 8.0.0 a 9.99.99, utiliza as classes ObjectModel e HelperForm que continuam suportadas no PS 9, e não utiliza nenhuma API obsoleta.

### Como apagar todos os dados do módulo?

A desinstalação através do Gestor de módulos remove todas as tabelas `dfsg_*` e todas as configurações `DFSG_*`. Não fica nenhum rasto na base de dados.

## Suporte

E-mail: [support@datafirefly.com](mailto:support@datafirefly.com). Resposta em 5 dias úteis, em francês ou em inglês.