Módulo Ótica PrestaShop: instalação e configuração
Instalar o módulo, configurar lentes, tratamentos e armações, compreender a viabilidade, verificar as receitas e tratar as encomendas de óculos graduados.
Apresentação
O módulo dfopticlens permite vender óculos graduados no PrestaShop 8 e 9. Na página de uma armação, o cliente escolhe uma utilização, introduz a sua receita, compara as lentes com a respetiva espessura estimada, adiciona tratamentos e confirma um resumo. O servidor verifica cada valor, calcula o preço e confirma que a graduação pode ser montada na armação. O preço das lentes é somado à linha da armação através da personalização nativa do PrestaShop, e a receita acompanha a encomenda até à fatura.
A versão 2.0.0 acrescenta a verificação pelo ótico, um painel, a encriptação dos ficheiros de receita, o consentimento explícito do cliente, um configurador totalmente redesenhado e o resumo das lentes no carrinho.

Instalação e atualização
- Em Módulos > Gestor de módulos, clique em Carregar um módulo e envie o ficheiro
dfopticlens-2.0.0.zip. - A instalação cria o menu Vender > Ótica: Painel, Receitas, Armações, Lentes e índices, Tratamentos. Uma barra de navegação comum liga estas páginas e as definições.
- São criadas cinco lentes (1.50, 1.59 policarbonato, 1.60, 1.67, 1.74) e sete tratamentos com preços e descrições de exemplo nos 8 idiomas. Adapte-os antes de abrir ao público.
- A pasta
upload/dfopticlens/é criada e protegida. Cada ficheiro de receita é aí guardado encriptado, com um nome aleatório.
Atualização a partir da 1.x: envie o ZIP 2.0.0 por cima do módulo instalado. O script de atualização acrescenta as novas colunas e as novas definições, encripta no local os ficheiros já recebidos e coloca as encomendas dos últimos 14 dias na fila de verificação. Nenhuma receita, armação, lente ou tratamento é eliminado.
Desativar o módulo retira o campo de personalização oculto das armações: continuam a poder ser compradas normalmente. É recriado quando o módulo é reativado.
Painel
Vender > Ótica > Painel resume os últimos 30 dias, comparados com os 30 dias anteriores:
- pares encomendados, faturação de lentes sem IVA (lentes, tratamentos e suplementos) e média por par;
- taxa «Do configurador à encomenda»: receitas encomendadas divididas pelas receitas adicionadas a um carrinho;
- receitas a verificar (incluindo as que têm observações de viabilidade) e receitas a aguardar o cliente;
- fila de verificação, gráfico dos pares encomendados em 12 semanas e distribuição por tipo de lente;
- lentes mais encomendadas, tratamentos escolhidos e lista de configuração: lentes e tratamentos ativos, armações, pasta protegida, encriptação, consentimento, limpeza.

Configuração do módulo
A página de configuração agrupa as definições em cinco separadores.
Introdução da receita
- Convenção de cilindro enviada ao laboratório: cilindro negativo, positivo ou mantido como escrito. O cliente introduz sempre os valores da sua receita; a transposição é feita ao guardar.
- Envio do ficheiro da receita: desativado, opcional ou obrigatório, com um tamanho máximo em MB.
- Avisar quando a receita tiver mais de X anos (0 desativa).
- Envio do ficheiro a partir da conta após a encomenda: acrescenta a página As minhas receitas à conta do cliente.
- Opção «Não sei a minha distância pupilar» e distância pupilar média usada (63 mm por defeito). A encomenda fica então assinalada.
Regras de viabilidade
- Bloquear as lentes que não podem ser fabricadas: ativado por defeito. Se desativado, a encomenda é aceite com um aviso.
- Margem de biselagem e margem do diâmetro efetivo quando o ED da armação é desconhecido (ED estimado = A + margem).
- Altura mínima para progressivas (28 mm) e corredor curto abaixo de (32 mm).
- Limiares de aviso: diferença entre os olhos, descentramento por olho, potência positiva em fio nylon.
- Espessura pretendida da lente recomendada, espessura central das lentes negativas e da borda das lentes positivas (em armações sem aro ou não).
Preços
- Preços introduzidos com IVA ou sem IVA. A regra de imposto do produto armação é aplicada às lentes.
- Suplementos de potência elevada e cilindro elevado: limiar em dioptrias e valor (0 desativa).
Privacidade e dados
- Pedir consentimento explícito antes de guardar uma receita (ativado por defeito). Uma receita é um dado de saúde na aceção do artigo 9.º do RGPD. A data do consentimento é guardada e mostrada na encomenda.
- Página de privacidade ligada no texto de consentimento (uma página CMS).
- Eliminar as receitas de carrinhos abandonados após X dias.
- Apagar os ficheiros de receita X dias após a encomenda (0 mantém-nos). Os valores introduzidos ficam na encomenda.
- Manter os dados ao desinstalar: armações, lentes, tratamentos, receitas e ficheiros são mantidos.
Apresentação
- Cor de destaque do configurador (botões, seleção, barra de progresso).
- Resumo das lentes sob cada armação no carrinho.
Os valores fora do intervalo são recusados com uma mensagem que indica o intervalo aceite.

Lentes e índices
Em Lentes e índices, cada lente tem:
- um nome e uma descrição curta mostrados ao cliente, em cada idioma;
- o índice de refração, usado para estimar a espessura, e o material para a ficha de oficina;
- os tipos de lente em que é proposta e um preço por par para cada um: monofocal, progressiva, sem graduação;
- a esfera mínima e máxima e o cilindro máximo (lidos em cilindro negativo, como as gamas dos fabricantes);
- o maior diâmetro da lente em bruto disponível (0 desativa esta verificação) e a possibilidade de furação para as armações sem aro.
A ordem de apresentação altera-se arrastando e largando na lista.

Tratamentos
Cada tratamento tem um nome, uma descrição curta e um preço por par. Um preço a 0 mostra-o como incluído e sempre selecionado. O grupo exclusivo impede combinar dois tratamentos: os que têm o mesmo código, por exemplo tint para fotocromático, tinta solar e polarizado, excluem-se entre si. Também pode limitar um tratamento a certas lentes, por exemplo o polarizado aos índices 1.50 e 1.60. A ordem altera-se arrastando e largando.
Armações
Uma armação liga um produto, ou uma das suas combinações, às suas medidas. O bloco das lentes só aparece nos produtos com uma armação ativada.
Criar uma armação
- Em Armações, clique em Adicionar uma armação, ou na página do produto, separador Módulos, em Adicionar as medidas da armação.
- Procure o produto pelo nome, referência ou ID e escolha Todas as combinações ou uma combinação específica. Uma armação definida para uma combinação tem prioridade.
- Indique o tipo (aro completo, fio nylon, sem aro), a largura da lente A, a ponte DBL e a altura da lente B. São os números impressos na haste: 52□18 dá A = 52 e DBL = 18.
- Opcional: o diâmetro efetivo ED (caso contrário é estimado) e a potência máxima aceite pela armação.
- Marque os tipos de lente propostos e, se necessário, Vender apenas com lentes.
Com «Vender apenas com lentes», o botão nativo do carrinho abre a escolha das lentes. Se uma chamada direta ao carrinho adicionar mesmo assim a armação sozinha, o módulo retira-a do carrinho.

Importação e exportação CSV
O botão Exportar CSV fornece um ficheiro no formato certo. A importação aceita ponto e vírgula ou vírgula e as colunas:
product;combination;frame_type;lens_width;lens_height;bridge;ed;max_power;vision_types;lens_required;active
product: ID ou referência do produto;combination: ID ou referência da combinação, vazio ou 0 para todas.frame_type: full, semi ou rimless;vision_types: single|progressive|plano.- Uma armação existente (mesmo produto e mesma combinação) é atualizada. As linhas recusadas são listadas com o respetivo número.

Percurso do cliente
Na página da armação, o bloco «Adicione as suas lentes graduadas» mostra o preço inicial das lentes, o tipo e o tamanho da armação. Abre um painel em cinco passos, com uma coluna «A sua seleção» atualizada em tempo real e o total da armação e das lentes no rodapé.
- Utilização: monofocal, progressiva ou sem graduação, conforme o que a armação propõe, com o preço «desde» de cada tipo. Sem graduação, o passo da receita é saltado.
- Receita: grelha OD / OE, distância pupilar em um ou dois valores, data, ficheiro por arrastar e largar e nota para o ótico. O botão Como ler a minha receita mostra uma receita de exemplo anotada. Um cliente com sessão iniciada pode reutilizar a receita de uma encomenda anterior.
- Lente: cartões com preço por par, corte da lente à escala, espessura estimada e lente recomendada. As lentes impossíveis ficam a cinzento com o motivo.
- Tratamentos: os tratamentos indisponíveis para a lente escolhida ficam a cinzento, as tintas excluem-se entre si.
- Resumo: estado de viabilidade, observações, receita, detalhe do preço, total e consentimento.
Os erros aparecem por baixo do campo em causa e desaparecem assim que são corrigidos. Os dados introduzidos são mantidos se o cliente recarregar a página e apagados após adicionar ao carrinho. O painel pode ser usado com o teclado e adapta-se ao telemóvel.






Regras de viabilidade
| Verificação | Efeito |
|---|---|
| Esfera ou cilindro fora do intervalo da lente | Lente indisponível |
| Diâmetro da lente em bruto necessário (ED + 2 × descentramento + margem) superior ao da lente | Lente indisponível se o bloqueio estiver ativo |
| Armação sem aro e material não furável | Lente indisponível se o bloqueio estiver ativo |
| Altura B inferior ao mínimo para uma progressiva | Bloqueante (ou aviso) |
| Altura B abaixo do limiar de corredor curto | Informação |
| Potência superior ao máximo da armação | Bloqueante (ou aviso) |
| Diferença entre os olhos, forte descentramento, potência positiva elevada em fio nylon, receita antiga, distância pupilar desconhecida | Aviso |
Os cálculos são feitos na forma em cilindro negativo. A espessura é estimada com a fórmula da flecha: é uma referência para comparar os índices, não o cálculo do laboratório.
Carrinho, e-mails e fatura
O preço das lentes é guardado sem IVA na personalização da linha do carrinho. O PrestaShop soma-o ao preço da armação e aplica o IVA do produto. Se a armação tiver um desconto em percentagem, o PrestaShop aplica-o também às lentes: o painel mostra-o com o preço riscado, para que o total anunciado corresponda ao carrinho.
- Carrinho: sob cada armação, um resumo indica o tipo de lente, a lente, os valores OD / OE, a distância pupilar, os tratamentos, o preço das lentes e a receção do ficheiro.
- E-mails da encomenda e fatura PDF: a receita aparece por baixo do produto, uma linha por informação (lente, OD, OE, distância pupilar, tratamentos).

Verificação pelo ótico
Cada receita encomendada entra na fila de verificação com o estado A verificar. Tanto na página da receita como na página da encomenda, o bloco Verificação pelo ótico permite:
- mudar o estado para Verificada ou A aguardar o cliente;
- escrever uma nota interna, nunca visível para o cliente;
- ver o ficheiro da receita em pré-visualização, desencriptado no momento, ou descarregá-lo;
- pedir informações ao cliente: é enviado um e-mail no idioma da encomenda com a sua mensagem e uma ligação para a página As minhas receitas. O estado passa a «A aguardar o cliente».
Quando o cliente volta a enviar o ficheiro, o estado regressa a «A verificar». O autor e a data da última alteração são mostrados. A lista Receitas filtra-se por estado de verificação e por viabilidade, e indica as receitas acompanhadas de um ficheiro.



Encomendas e ficha de oficina
- A página da encomenda no back-office mostra um bloco por receita: valores transpostos, lente, tratamentos, medidas da armação, descentramento e lente em bruto mínima por olho, observações de viabilidade, detalhe do preço, consentimento e verificação.
- Imprimir a ficha de oficina abre uma página A4 pronta a imprimir, com campos para verificação, biselagem e controlo final.


Conta do cliente: As minhas receitas
Um cliente que encomendou lentes vê a ligação As minhas receitas na sua conta, com um contador quando o ótico aguarda uma informação. A página mostra cada receita com a armação, a encomenda e o estado da verificação: recebida, verificada ou informação pedida. O cliente pode aí enviar o seu ficheiro, ou substituí-lo quando o ótico o pede.

Dados de saúde e RGPD
- Consentimento explícito antes de guardar, com a respetiva data conservada.
- As imagens são recodificadas (metadados EXIF e GPS removidos), os PDF são verificados e cada ficheiro é encriptado em AES-256-GCM numa pasta protegida. A pré-visualização e a transferência só passam pelo back-office.
- As receitas de carrinhos nunca encomendados são eliminadas após o prazo definido. Os ficheiros podem ser apagados automaticamente após a encomenda.
- Um cliente eliminado no back-office perde as suas receitas de carrinho; as das suas encomendas perdem o ficheiro e a ligação ao cliente.
- Com o módulo oficial psgdpr, a exportação e a eliminação dos dados de um cliente incluem as suas receitas.
Resolução de problemas
O bloco das lentes não aparece na página do produto
Verifique se o módulo está ativado, se o produto tem uma armação ativada e se o tema mostra o hook displayProductAdditionalInfo. Limpe a cache do PrestaShop.
O botão nativo do carrinho não abre o painel numa armação com «lentes obrigatórias»
O módulo interceta os botões com data-button-action="add-to-cart". Se o seu tema usar outro atributo, o bloqueio do lado do servidor continua ativo: a armação sozinha é retirada do carrinho.
O e-mail de pedido de informações não chega
Verifique a configuração de e-mail do PrestaShop (Parâmetros avançados > E-mail). Em caso de falha, o estado é guardado e uma mensagem indica-o na página.
O total do painel é diferente do carrinho
Um desconto de valor fixo só se aplica à armação, e uma regra de carrinho aplica-se ao carrinho inteiro: não aparecem no painel das lentes.