Kowal Hyva Colors — cores da loja sob controlo

Painel e permissões

Abre o módulo através de kowal.store → Modules → Hyva Colors. A configuração é feita nas suas três vistas, e não numa secção separada Stores → Configuration.

O administrador atribui permissões em System → Permissions → User Roles. Disponibilize às funções os recursos de menu superiores Kowal adequados e os recursos Hyva Colors:

A importação que contenha novas definições de catálogo também exige a permissão para adicionar elementos. Após alterar uma função, poderá ser necessário iniciar sessão novamente.

Âmbito da loja

Na publicação, seleciona uma vista da loja (store view) ativa. O módulo verifica o tema atribuído: o perfil atual suporta exatamente Hyva/default com Default Theme 1.5.2–1.5.x. Não atribua outro tema apenas para contornar a validação — os temas filho precisam de preparação separada dos mapeamentos.

O conjunto é um rascunho reutilizável. Pode publicá-lo separadamente para várias vistas. Nesta versão, não existe configuração herdada ao nível default/website/store.

Conjuntos de sistema e próprios

As definições prontas a usar incluem sete paletas e um conjunto nativo vazio. As respetivas cópias guardadas estão disponíveis em «Os meus conjuntos». A forma mais conveniente é criar conjuntos próprios com base nelas — assim, os originais permanecem como ponto de referência.

Editor de cores

O editor divide o catálogo em secções: Global, Header, Buttons, Product cards e Catalog and product page. Os nomes podem permanecer em inglês. O catálogo inicial contém 34 elementos e 99 mapeamentos. Um único elemento pode ter entradas separadas para fundo, texto, moldura e estados de interação.

Formas disponíveis para definir valores:

native não insere CSS inherit. O valor transparent é uma cor transparente explícita, e não um regresso ao tema. Também pode usar currentColor. Funções CSS arbitrárias, como rgb() ou var(), não são aceites nos campos de cor.

Guarde o rascunho antes de mudar de secção ou de página do editor. A gravação não publica as alterações.

Cores comuns: tokens

Em «Paleta — definições avançadas (JSON)» são guardadas cores nomeadas. Exemplo de fragmento:

{ 'brand': {'mode': 'color', 'value': '#1d4ed8'}, 'on-brand': {'mode': 'color', 'value': '#ffffff'}}

Na linha do elemento, escolha «Cor da paleta» e introduza brand. A alteração do token atualiza todos os valores que fazem referência a ele na próxima publicação. Se editar um conjunto pronto a usar, mantenha os restantes tokens existentes — substituir todo o JSON pelo fragmento acima pode deixar referências por resolver. Ciclos e tokens em falta são rejeitados.

Adicionar elementos e secções

Não exige a modificação dos ficheiros do módulo, mas requer a identificação do seletor CSS correto. O módulo não tem inspetor visual de elementos.

1. Abra o editor de qualquer conjunto.
2. Expanda «Adicionar elemento próprio — modo avançado».
3. Introduza o nome, por exemplo «Banner promocional».
4. Escolha o nome de uma secção existente ou introduza um novo, por exemplo «Promoções».
5. Introduza um seletor estável, por exemplo #promo-banner, que exista na loja.
6. Escolha as propriedades, por exemplo background-color, color, border-color.
7. Escolha os estados, por exemplo normal e hover, e adicione o elemento.
8. Abra a secção adequada, atribua cores, guarde e publique o conjunto.

A definição é adicionada ao catálogo comum; a sua simples adição não define cores em todos os conjuntos. O seletor deve ser o mais preciso possível. Nesta versão, não são suportadas listas de seletores, :has() nem declarações CSS arbitrárias. A adição de um elemento não cria o respetivo HTML na loja. Ainda não existe edição no painel de seletores existentes nem arquivamento de elementos.

Configuração da infraestrutura

A publicação depende do cron, de media graváveis e da cache. A folha CSS é gerada antes da ativação e, em seguida, servida estaticamente. O módulo não adiciona JavaScript de cores ao storefront normal. Isto não significa garantia de um resultado de desempenho específico — as medições devem ser realizadas na loja de destino.

Com Varnish, verifique o acesso aos servidores purge. Com CDN e vários nós, verifique a propagação de HTML e a disponibilidade das folhas. Os detalhes de implementação estão na instrução de instalação.

Kowal Hyva Colors — instalação e atualização

Instruções para a versão 0.1.6. Execute os comandos no diretório raiz do Magento como utilizador de implementação, no âmbito do procedimento padrão de deployment da loja. Primeiro, verifique a instalação num ambiente de teste.

Requisitos

As dependências completas são definidas por composer.json. Os requisitos das dependências não constituem uma declaração de que todas as combinações de versões foram testadas. Atualmente, um tema filho é rejeitado pela validação da publicação, mesmo que herde de Hyvä.

1. Acesso ao Composer

Configure o repositório Composer que disponibiliza kowal/module-hyva-colors e kowal/base, de acordo com os dados recebidos do fornecedor. Também é necessário acesso autorizado ao repositório Hyvä. O endereço do repositório e o método de autorização dependem do acesso fornecido; estas instruções não pressupõem a disponibilidade pública do pacote.

Exemplo de esquema de configuração — substitua o endereço pelo endereço real do repositório Composer:

composer config repositories.kowal composer 'https://ADRES-REPOZYTORIUM-COMPOSER'

Guarde as credenciais fora do repositório do projeto, por exemplo, num auth.json privado ou na configuração CI. Não as copie para a documentação.

2. Instalação

Depois de a versão 0.1.6 ser disponibilizada no repositório:

composer require kowal/module-hyva-colors:0.1.6 --with-all-dependenciesphp bin/magento module:enable Kowal_Base Kowal_HyvaColorsphp bin/magento setup:upgradephp bin/magento setup:di:compilephp bin/magento setup:static-content:deploy pl_PL en_USphp bin/magento cache:clean config layout block_html full_pagephp bin/magento module:status Kowal_HyvaColorsphp bin/magento kowal:hyva-colors:diagnose

Os locales indicados são apenas um exemplo — implemente os idiomas utilizados pela loja e pelo painel. Integre a geração DI e de recursos no procedimento padrão de implementação, em vez de a executar durante o atendimento de tráfego no catálogo de produção ativo.

A instalação cria o catálogo e os conjuntos iniciais. Não publica cores nem altera o aspeto da loja. O comando diagnose verifica o catálogo do pacote e reporta o âmbito das funcionalidades; não é um teste completo do ambiente.

3. Cron e ficheiros CSS

O módulo utiliza a tarefa kowal_hyva_colors_publish no grupo cron default, agendada a cada minuto. O cron Magento padrão tem de estar em execução no servidor. Uma execução processa no máximo 10 tarefas; a publicação não tem de ser imediata.

Processamento manual da fila para diagnóstico:

php bin/magento kowal:hyva-colors:publication:process

Verifique o estado de uma tarefa específica em «Histórico de alterações» — a execução bem-sucedida do comando não significa que todas as tarefas tenham terminado com sucesso.

As folhas são guardadas em pub/media/kowal/hyva-colors//.css. Garanta a possibilidade de escrita e leitura via HTTP. Com vários nós, os media têm de ser partilhados. Para estes ficheiros imutáveis, pode configurar Content-Type: text/css, compressão e Cache-Control: public, max-age=31536000, immutable. O módulo não configura o servidor nem a CDN.

4. Validação da instalação

1. Abra kowal.store → Modules → Hyva Colors. Se o menu não estiver visível, verifique o Kowal Base e as permissões da função.
2. Verifique as três páginas: «Conjuntos e publicação», «Os meus conjuntos», «Histórico de alterações».
3. Num store view de teste, publique uma paleta e aguarde a conclusão da tarefa.
4. Verifique o cabeçalho, a conta, o minicarrinho, a categoria e o produto em desktop e telemóvel, incluindo hover/focus.
5. Confirme a disponibilidade do CSS, a atualização de FPC/Varnish e de todos os nós CDN.
6. Publique um reset para o tema nativo e, em seguida, verifique o restauro de uma publicação anterior.

Atualização

Depois de uma nova versão ser disponibilizada:

composer update kowal/module-hyva-colors kowal/base --with-all-dependenciesphp bin/magento setup:upgradephp bin/magento setup:di:compilephp bin/magento setup:static-content:deploy pl_PL en_USphp bin/magento cache:clean config layout block_html full_page

Verifique a restrição de versão no composer.json principal da loja: um 0.1.6 exato não permitirá que o comando update selecione uma versão mais recente. Altere-a conscientemente, por exemplo, através de composer require ...:NOWA-WERSJA --with-all-dependencies.

A atualização não substitui a publicação ativa por uma nova paleta. Após alterações de fábrica, selecione novamente o conjunto pronto a usar e publique-o. Os rascunhos próprios guardados mantêm os seus próprios valores.

Problemas durante a instalação

• O pacote não está disponível: verifique a disponibilidade da versão, os repositórios e a autorização Composer.
• Menu em falta: verifique a ativação de Kowal_Base, as permissões da função e a cache de configuração; atualize o painel.
• Conflito de catálogo: execute php bin/magento kowal:hyva-colors:catalog:sync --dry-run. Compare as definições alteradas antes da sincronização; não substitua manualmente elementos próprios.
• Erro Interceptor após uma versão antiga: certifique-se de que o Composer instalou o pacote corrigido e reconstrua o código gerado no processo padrão de deployment.
• As cores não mudam: verifique o histórico, o cron, o tema ativo, o CSS em media e a propagação da cache.

O reset das cores é efetuado no painel. Não requer a desinstalação do módulo nem a eliminação de tabelas. Antes de desativar ou remover o módulo, exporte os conjuntos necessários e faça uma cópia da base de dados de acordo com o procedimento de manutenção da loja.