req-141: Resolução de Conflitos e Paridade Visual das Três Camadas de Tailwind CSS entre Projeto, Templates (CDN) e Páginas Públicas

• Status do intake: ready-for-intake

• Data: 2026-08-28

• Origem: solicitação do Engenheiro Chefe após constatação de perda de características visuais e classes utilitárias do Tailwind CSS em páginas publicadas (ex: http://localhost/[REDACTED]/artigos/teste-de-pagina/), onde elementos como a legenda de imagem aparecem desalinhados (em itálico à esquerda) enquanto no editor de templates (admin-templates via CDN em https://novo.[REDACTED].com/admin-templates/editar/?id=template-artigo) renderizam corretamente alinhados à direita com classes utilitárias ativas

• Classificação: arquitetura CSS (3 camadas), paridade Tailwind CLI x CDN, roteador (gestor.php), módulos admin-templates e publisher-pages, injeção de dependências de templates

• Batch candidato: BATCH-144

1. Contexto e Diagnóstico Técnico Aprofundado

O sistema Conn2Flow opera com uma arquitetura de estilização em três camadas para o Tailwind CSS v4:

1. css: CSS autoral customizado escrito pelo usuário ou desenvolvedor;

2. css_precompiled: CSS Tailwind compilado offline pelo Tailwind CLI durante release/deploy/sincronização de recursos físicos;

3. css_compiled: CSS Tailwind compilado no navegador pelo @tailwindcss/browser quando o conteúdo é criado ou modificado no Editor Visual / Live Editor.

Apesar desse modelo, constatou-se uma divergência crônica entre o que o operador visualiza no Editor HTML (CDN em tempo de execução) e o que é entregue no navegador final da página publicada.

Evidências Medidas no Caso Concreto ([REDACTED])

Inspecionando o ambiente local ativo (http://localhost/[REDACTED]/artigos/teste-de-pagina/) e sua respectiva base MySQL ([REDACTED]):

1. Na Tabela paginas (registro teste-de-pagina):

   • framework_css: tailwindcss;

   • css: NULL;

   • css_precompiled: NULL;

   • css_compiled: NULL. Constatação: A publicação não possui nenhum CSS próprio compilado ou pré-compilado associado diretamente a ela.

2. No HTML da Página Pública (GET /artigos/teste-de-pagina/):

   • O elemento de legenda abaixo da capa possui o markup:

     <figcaption class="ml-auto text-right">
      <p class="text-sm md:text-base font-medium opacity-70 leading-relaxed border-r-2 border-(--color-mp-ink)/20 italic pr-4">
          Imagem Capa ou Qualquer Outro Descritivo da Imagem
      </p>
     </figcaption>

   • No <head>, a folha de estilo injetada como <style data-c2f-css-role="compiled"> contém apenas as regras base de Preflight, com o bloco @layer utilities 100% vazio.

   • Nenhuma folha com papel page-precompiled ou resource-precompiled referente ao artigo é entregue.

   • Resultado Visual: As classes .text-right, .ml-auto, .border-r-2, .pr-4, etc., não existem em nenhuma folha CSS da página. O navegador aplica o alinhamento de texto padrão (esquerda), desfazendo o layout planejado.

3. No Módulo admin-templates (template-artigo):

   • Na tabela templates, o registro template-artigo possui css_precompiled com 8.286 bytes de regras utilitárias compiladas (incluindo .italic, .border-r-2, etc.).

   • No editor visual (admin-templates/editar/?id=template-artigo), o iframe carrega o script @tailwindcss/browser@4.3.0. O compilador no navegador varre dinamicamente o DOM do iframe e injeta em tempo real todas as classes presentes no markup (como .text-right e .ml-auto).

   • Por essa razão, dentro do editor visual o template funciona e parece perfeito, gerando uma falsa paridade.

2. Causas-Raiz Identificadas

Causa-Raiz 1: Ruptura de Herança de CSS entre Templates e Publicações no Roteador Público

Quando uma página de publicação (como /artigos/teste-de-pagina/) é requisitada:

• gestor_roteador() em gestor/gestor.php busca na tabela paginas onde caminho = 'artigos/teste-de-pagina/'.

• A página é encontrada, mas o roteador apenas inclui:

  • O CSS do layout (layout-precompiled);

  • O CSS da própria página (page-precompiled), que no caso de publicações é NULL;

  • Os CSS de widgets invocados (dependency-precompiled).

• O roteador nunca consulta a tabela templates nem carrega o css_precompiled ou css_compiled do template pai (template-artigo) vinculado ao publicador (publisher_id = 'artigos').

• Essa lacuna já havia sido sinalizada normativamente na DEC-109 §5 ("Template escolhido dinamicamente é dependência da página... omitir o campo foi a causa da imagem clínica sem max-h-56"), mas o carregamento no runtime público de publicações permaneceu pendente.

Causa-Raiz 2: Descompasso entre Recursos em Banco e o Compilador Offline (CLI)

• O compilador Tailwind CLI (tailwind-recursos.php acionado via c2f resources:sync) apenas varre arquivos físicos estáticos no diretório resources/.

• Templates e páginas criados ou editados no banco de dados através dos painéis administrativos (admin-templates, publisher-pages, admin-paginas) não possuem representação física em disco na hora da edição.

• Se o projeto utiliza um arquivo central (ex: contents/tailwindcss/output.css ou project-css via config-project.php), esse bundle estático ignora todas as classes introduzidas exclusivamente via banco de dados, a menos que tenham sido previamente catalogadas em arquivos estáticos.

Causa-Raiz 3: Não Extração de css_compiled ao Salvar Publicações (publisher-pages)

• No módulo publisher-pages, o usuário preenche campos de formulário (Quill, inputs, imagens) e a página substitui as variáveis via getUpdatedHtmlWithValues().

• No momento do envio (submit), o formulário anexa htmlWithValues, mas o campo css_compiled não é re-extraído pelo HtmlEditorCssCapture contra o HTML preenchido, sendo gravado como NULL na tabela paginas.

Causa-Raiz 4: Conflitos de Precedência entre Cascata Monolítica e Classes de Recurso

• Arquivos de projeto (project-css) carregados fora de camadas normatizadas (@layer) competem diretamente com os seletores utilitários. Se uma regra de projeto ou reset possuir maior especificidade que um @layer utilities, a utility do Tailwind é sobreposta.

3. Escopo Técnico Requerido

Módulo 1: Resolução Dinâmica de CSS de Templates no Roteador (gestor.php)

• Localização: gestor/gestor.php (no fluxo de gestor_roteador() e montagem de recursos da página).

• Ações:

  1. Ao processar uma página com publisher_id:

     • Identificar o template_id vinculado consultando o registro do publicador em publisher;

     • Carregar o css_precompiled e o css_compiled do template correspondente na tabela templates;

     • Injetar esses estilos através de gestor_pagina_recursos_incluir() com o papel normativo data-tailwind-role="dependency-precompiled" (ou resource-precompiled);

     • Assegurar que os seletores utilitários do template estejam presentes na resposta final de qualquer artigo ou publicação pública renderizada.

Módulo 2: Extração e Persistência de css_compiled no publisher-pages

• Localização: gestor/modulos/publisher-pages/publisher-pages.php e publisher-pages.js.

• Ações:

  1. Durante a criação (adicionar) e edição (editar) de uma página de publicador:

     • Copiar ou herdar o css_compiled e css_precompiled do template para a linha de paginas no ato do salvamento;

     • Garantir que o payload de POST envie o css_compiled atualizado para que a linha em paginas não fique com valores NULL.

Módulo 3: Paridade e Blindagem da Extração no admin-templates

• Localização: gestor/modulos/admin-templates/admin-templates.php e admin-templates.js.

• Ações:

  1. Assegurar que ao salvar um template, o updateCSSCompiled e o HtmlEditorCssCapture gravem fielmente todas as utilities geradas no campo templates.css_compiled.

  2. Garantir que alterações de classes no template reflitam imediatamente no css_compiled persistido no banco de dados.

Módulo 4: Governança de Camadas contra project-css Monolítico

• Localização: gestor/gestor.php (gestor_css_precompiled_ordenar e montagem do cabeçalho).

• Ações:

  1. Garantir que a ordem de inclusão em gestor.php preserve a precedência: $css_padrao $\rightarrow$ $project-css $\rightarrow$ css_precompiled (layout $\rightarrow$ dependência/template $\rightarrow$ página) $\rightarrow$ css_compiled $\rightarrow$ css autoral.

  2. Prevenir que regras sem @layer de arquivos legados de projeto sobrescrevam utilitários sem declaração explícita.

Módulo 5: Testes Automatizados Unitários e de Integração

• Localização: tests/Unit/PHP/ e tests/Feature/.

• Cobertura:

  1. Teste no roteador comprovando que páginas públicas com publisher_id carregam o CSS utilitário do template associado;

  2. Teste no publisher-pages validando que a inserção de publicação persiste o CSS utilitário na tabela paginas;

  3. Teste garantindo que classes utilitárias específicas (como .text-right, .ml-auto, .border-r-2) estejam presentes no HTML entregue e não sejam descartadas por bundles de página.

4. Critérios de Aceite e Validação

1. Paridade Visual Idêntica: A página http://localhost/[REDACTED]/artigos/teste-de-pagina/ deve exibir a legenda da imagem alinhada à direita, com borda lateral e estilo idênticos ao visualizado no editor de admin-templates.

2. Presença das Classes no CSS: O CSS emitido no <head> da rota pública deve conter as definições de .text-right, .ml-auto, .border-r-2, .pr-4 e demais utilities usadas no template.

3. Persistência no Banco: Ao salvar templates no admin-templates ou páginas no publisher-pages, as colunas de CSS compilado/pré-compilado devem ser preenchidas, sem permanecer como NULL.

4. Sem Efeito Cascata Negativo: A inclusão do CSS do template não deve quebrar ou desalinhar outros componentes (menus, cabeçalhos, rodapés) nem sofrer anulação por project-css.

5. Suíte Automatizada 100% Verde: Todos os testes unitários (composer test e npx vitest run) devem passar sem erros ou regressões.