req-239 — Refinamentos e Correções do Painel Tailwind e E-commerce decorrentes da Auditoria Humana (Fases 1 e 2)

• Status: in-review

• Modo de Autonomia: autonomo_monitorado

• Lote Alvo Core: BATCH-248 (conn2flow)

• Lote Alvo Site: BATCH-099 (conn2flow-site)

• Data de Atualização: 2026-10-05

• Origem: Auditoria manual detalhada do Engenheiro Chefe Humano no Lab (Fase 1 — Core Tailwind e Fase 2 — E-commerce & Produtos).

• Repositórios:

  • Core: conn2flow em [REDACTED]

  • Site: conn2flow-site em [REDACTED]

1. Visão Geral & Diagnóstico da Auditoria

Após a homologação e merge da Master REQ-238 (13085415 Core / 6fa8a6c4 Site), o Engenheiro Chefe Humano conduziu a inspeção prática no Lab dividida em fases:

1. Fase 1 (Core): 15 pontos de ajuste visual, densidades do Dashboard, z-index no editor de páginas, família publisher e módulos administrativos.

2. Fase 2 (E-commerce & Produtos no Site): 5 apontamentos críticos que inviabilizam o teste operacional dos módulos products e stripe-products (ausência de editor rico Quill, máscaras monetárias inexistentes aceitando texto livre, quebra do layout da imagem, herança travada do catálogo Stripe, ausência dos métodos de frete e vazamento grave de código que quebra a edição da página do produto).

Esta especificação Master consolida as correções em 9 blocos de ação técnica direta entre Core e Site.

2. Especificação Técnica & Critérios de Aceite

PARTE I: REFINAMENTOS DO CORE (FASE 1)

BLOCO 1: Refinamentos do Dashboard (Densidades P e G)

• CA-1.1 (Densidade P — Pequeno/Compacto):

  • Problema: Imagem descentralizada (margem dobrada à direita) e usabilidade empobrecida ao exibir apenas uma miniatura crua.

  • Solução Normativa:

  • Centralizar o enquadramento do container da miniatura.

  • Em vez de uma imagem isolada sem contexto, renderizar o card com fundo suave/translúcido, exibindo o ícone do módulo + nome do módulo legível em linha com tipografia compacta (text-xs font-semibold text-slate-800 line-clamp-1), tornando o card compacto e perfeitamente identificável.

• CA-1.2 (Densidade G — Grande/Operacional):

  • Problema: Enquadramento da capa exibe apenas do meio para cima da ilustração, cortando a área útil central.

  • Solução Normativa:

  • Ajustar o posicionamento ótico vertical da capa (object-position: center 15% ou ajuste vertical de offset negativo) para exibir plenamente o centro e a base da arte isométrica.

BLOCO 2: admin-paginas (Editor HTML, Controles de Sessão, Z-Index & Arquivos)

• CA-2.1 (Controles de Seção no Editor HTML):

  • Problema: Ao alterar o alvo da modificação da página, os menus de seção falham em carregar e exibem "nenhum resultado".

  • Solução Normativa:

  • Corrigir os seletores AJAX e ganchos JavaScript responsáveis por popular a lista dinâmica de seções para o alvo ativo.

• CA-2.2 (Z-Index / Stacking Context dos Controles da Barra do Editor):

  • Problema: O botão "Adicionar novo elemento" não abre opções, e seu tooltip/title é cortado pelo container do iframe inferior. As opções de exibição e os botões de desfazer/refazer apresentam a mesma falha de corte e sobreposição.

  • Solução Normativa:

  • Elevar o contexto de empilhamento da barra de ferramentas do editor (relative z-50 com overflow: visible !important).

  • Garantir que os menus dropdown e balões de tooltip flutuem com z-index: 100050, sempre por cima do iframe visual.

• CA-2.3 (Integração com admin-arquivos na Aba Share & Collaborate):

  • Problema: A imagem de destaque está apontando para o módulo legado arquivos (em vias de descontinuação) em vez do moderno admin-arquivos.

  • Solução Normativa:

  • Atualizar os seletores de mídia e botões de chamada de modal para abrir exclusivamente o /admin-arquivos/.

• CA-2.4 (Histórico de Alterações & Ícones Semânticos):

  • Problema: Registros do histórico renderizando em 3 linhas quebradas; ícones aparecendo como círculos vazios sem o pictograma de informação.

  • Solução Normativa:

  • Estruturar cada registro do histórico em linha única horizontal (flex flex-row items-center gap-3 text-sm text-slate-600).

  • Substituir os círculos vazios pelo ícone canônico de informação Lucide <i data-lucide="info" class="size-4 text-sky-600"></i>.

BLOCO 3: Família Publisher (publisher, publisher-highlights, publisher-index, publisher-pages)

• CA-3.1 (publisher — Telas de Adicionar & Vinculação):

  • Remover a borda espúria de 1px ao redor do ícone de livro no campo de caminho prefixo.

  • Bloco "Modelos vinculados ao publicador": estruturar em card de aviso limpo (c2fc-alerta), sem quebras desnecessárias de linha no sininho; alinhar horizontalmente Modelo ➔ Publicador.

  • Botões de ação com cores semânticas padronizadas: "Adicionar" (azul primário c2fc-botao-primario), "Editar" (teal/âmbar c2fc-botao-editar) e "Clonar" (indigo/violeta).

  • Vinculação de campos: eliminar visual monocromático cru; readequar alinhamento dos labels e setas direcionais.

  • Cards de campos vinculados: substituir o layout de 2 colunas gigantes por cards compactos horizontais, posicionando os botões de ação (excluir, subir, descer) no canto direito em tamanho pequeno (size-7), recuperando a densidade e elegância visual original.

• CA-3.2 (publisher-highlights — Editor e Banners):

  • Conectar a barra de abas do editor HTML diretamente ao topo da caixa de conteúdo (eliminando o espaçamento/gap que desconecta a barra da caixa).

  • Padronizar as caixas de mensagem com ícones Lucide adequados (sem círculos vazios).

• CA-3.3 (publisher-index — Formulários & Variáveis):

  • Badge informativo do "Publicador de origem": adicionar fundo estilizado consistente com os demais módulos.

  • Padronizar os selects de "Publicador de origem", "Regra de alimentação" e "Modelo de recursos" com o componente c2fc-campo-selecao.

  • Corrigir a renderização do bloco de mapeamento de variáveis e os botões do editor visual.

• CA-3.4 (publisher-pages — Tipagem & Listagem):

  • Substituir o switch quebrado da seleção de tipo pelo seletor de rádio padronizado do admin-paginas (ou switch funcional com estado semântico).

  • Tabela de listagem: remover a borda cinza grossa espúria em todas as células, aplicando a folha limpa de tabelas Tailwind (border-b border-slate-100 hover:bg-slate-50/80).

BLOCO 4: Módulos Administrativos (variables, admin-ia, admin-prompts-ia, admin-arquivos, cookie-consent)

• CA-4.1 (variables):

  • Processar e substituir a tag não resolvida #select_module# pelo dropdown seletor de módulo.

  • Corrigir os botões de ação removendo bordas circulares anômalas e preenchendo as variáveis globais esperadas.

• CA-4.2 (admin-ia):

  • Nas telas de conexão (adicionar/editar): aplicar fundo branco sólido (bg-white border border-slate-200 rounded-xl shadow-sm) nas caixas de histórico de testes e de modelos disponíveis globalmente, eliminando a transparência sem contraste.

• CA-4.3 (admin-prompts-ia — Mensagens de Validação):

  • Mensagens de erro de validação (ex: "É obrigatório preencher..."): estilizar com o componente oficial de alerta (c2fc-alerta c2fc-alerta-erro), com padding adequado, ícone de erro e sem bullet HTML colado na borda esquerda.

• CA-4.4 (admin-arquivos):

  • Corrigir a barra de ferramentas: caixas de busca e filtro com fundo branco e bordas nítidas (removendo transparência).

  • Breadcrumbs: renderizar em trilha horizontal fluida (flex items-center gap-1.5 text-sm), com separadores / e links ativos destacados.

  • Restaurar ícones de pastas, ações e botões de tamanho de visualização (substituindo os círculos genéricos pelos pictogramas Lucide corretos).

• CA-4.5 (cookie-consent):

  • Padronizar a navegação por abas com o layout do admin-paginas (c2fc-abas).

  • Restaurar o ícone informativo no label da aba Geral.

  • Tabela de Categorias: aplicar espaçamento e padding adequado entre os inputs das colunas (ID, Identificador, Nome, Descrição), evitando elementos encavalados.

PARTE II: COMPONENTES CORE REUTILIZÁVEIS (interface)

BLOCO 5: Controles de Formulário e Mídia da Biblioteca interface

• CA-5.1 (Máscara Monetária Dinâmica):

  • Criar/habilitar controle reutilizável de input monetário (c2fc-campo-moeda ou hook data-c2f-mascara="moeda") em gestor/modulos/interface/ ou script global do painel.

  • Formatação em tempo real conforme a digitação: separador de milhar com ponto (.), separador de centavos com vírgula (,), prefixo de moeda (R$), garantindo que o valor submetido seja parseado corretamente pelo backend (products_decimal).

• CA-5.2 (Seletor Unificado de Imagem com admin-arquivos):

  • Padronizar o seletor widget-imagem-tailwind para fornecer simultaneamente:

    1. Input de texto para digitação direta da URL da imagem.

    2. Botão compacto com ícone de pasta aberta (folder-open) para disparar o modal de seleção do módulo admin-arquivos.

    3. Container de prévia da imagem contido (max-h-40 / w-auto com object-contain) para não deformar nem empurrar botões para fora do viewport.

• CA-5.3 (Normalização Canônica de Hash LF no Cache do Tailwind — Blindagem contra CRLF/LF):

  • Em gestor/controladores/agents/arquitetura/tailwind-recursos.php: substituir a leitura crua de hash_file('sha256', ...) para arquivos de texto (.html, .css, .js) por leitura com normalização mandatória de quebras de linha (str_replace(["\r\n", "\r"], "\n", $conteudo)).

  • Tornar o fingerprint do .tailwind-build-manifest.json 100% determinístico e imune a conversões automáticas entre Git Bash (LF), PowerShell (CRLF), Windows e Linux, eliminando de vez a invalidação acidental de cache e falsas recompilações em massa.

PARTE III: E-COMMERCE & PRODUTOS NO SITE (FASE 2)

BLOCO 6: Módulo products (Cadastro & Edição)

• CA-6.1 (Editor de Texto Rico Quill):

  • Substituir o textarea cru do campo "Descrição" pelo editor Quill canônico do framework, utilizando gestor/bibliotecas/editor-texto.php e a estrutura Tailwind com suporte a tradução e barra de ferramentas rica.

• CA-6.2 (Selects Padronizados):

  • Atualizar os campos <select> do formulário para o componente canônico c2fc-campo-selecao da UI.

• CA-6.3 (Seletor de Imagem):

  • Adotar o seletor unificado CA-5.2, permitindo entrada por URL direta ou seleção pelo admin-arquivos (pastinha aberta).

• CA-6.4 (Máscara Monetária nos Preços):

  • Aplicar a máscara monetária (CA-5.1) nos campos "Preço" e "Preço Promocional".

• CA-6.5 (Métodos de Entrega / Frete):

  • Quando o tipo de produto for físico (physical), consultar dinamicamente e renderizar a lista de métodos de entrega configurados no módulo shipping-methods, permitindo ao lojista selecionar quais métodos são válidos para o produto.

• CA-6.6 (Link Direto da Página Pública):

  • Na tela de edição do produto, exibir card/link de acesso rápido direto para a página pública do produto (/produto/<slug>/ ou URL canônica gerada), espelhando o comportamento e padrão do módulo admin-paginas.

BLOCO 7: Módulo stripe-products (Produtos Stripe)

• CA-7.1 (Editor Quill):

  • Integrar o editor Quill na caixa de descrição do produto Stripe.

• CA-7.2 (Prévia de Imagem Contida):

  • Conter a imagem do produto em container responsivo proporcional (max-h-48 max-w-xs object-cover rounded-lg border).

  • Eliminar o vazamento visual que joga os botões "Nenhuma imagem", "Adicionar" e "Remover" para fora da tela.

• CA-7.3 (Máscara Monetária):

  • Aplicar a máscara monetária no campo "Valor".

BLOCO 8: Integração Catálogo Stripe vs Produto Local (products)

• CA-8.1 (Seletor de Origem no Topo):

  • Inserir seletor claro no topo do formulário: Produto Local vs Produto Stripe.

• CA-8.2 (Herança e Bloqueio de Preço):

  • Ao selecionar um item do catálogo Stripe, preencher automaticamente o preço e a moeda herdados e desabilitar/travar os campos de edição manual de preço básico (readonly ou estilização desabilitada transparente com aviso explicativo).

  • Garantir que a validação de envio do formulário no backend e frontend reconheça a herança do preço sem disparar erro de campo obrigatório vazio.

• CA-8.3 (Vigência do Preço Promocional):

  • Criar opção de vigência para o preço promocional: "Sempre Ativo" ou "Período Específico" (com inputs de Data Início e Data Fim).

  • Se vinculado a item Stripe sem suporte a preço promocional, fornecer tratamento claro sem inputs conflitantes.

BLOCO 9: Edição da Página do Produto (products-page) & Variações

• CA-9.1 (Correção de Vazamento no Template HTML):

  • Em gestor/modulos/products/resources/{pt-br,en}/pages/products-page/products-page.html:

  • Remover a tag #html-editor# de dentro do comentário de cabeçalho (<!-- req-219 ... -->), eliminando o vazamento de código Vem na variante tailwind do core .--> no DOM.

  • Garantir substituição única e correta do marcador #html-editor# pelo markup do editor.

• CA-9.2 (Aba Modelos & Editor HTML):

  • Eliminar o carregamento infinito (infinite loading) na aba "Modelos", garantindo carregamento assíncrono seguro dos templates.

  • Eliminar a exibição crua de # nas variáveis do editor HTML.

• CA-9.3 (Variações de Produto):

  • Corrigir a renderização dos botões "Desativar" e "Excluir" nas linhas de variações: restaurar os ícones Lucide visíveis (power-off / trash-2) e os tooltips nativos, eliminando a renderização de bolinhas pretas cegas.

  • Aplicar máscara monetária nos campos de preço das variações.

  • Permitir configuração de preço promocional por variação com datas de início e término de vigência.

3. Live Todo List da Missão

Parte I — Core (Fase 1):

• [x] Bloco 1 (Dashboard): densidade P (centralizar + ícone e nome) e densidade G (enquadramento ótico 15%).

• [x] Bloco 2 (admin-paginas): seções dinâmicas AJAX, z-index 100050 na barra do editor sobre o iframe, mídia para admin-arquivos, histórico em linha única com ícone Lucide.

• [x] Bloco 3 (Publisher): bordas, alertas, botões semânticos, densidade dos cards em publisher, abas conectadas em publisher-highlights, selects em publisher-index, rádio/switch e tabela em publisher-pages.

• [x] Bloco 4 (Módulos Admin): tag #select_module# em variables, fundos sólidos em admin-ia, alertas em admin-prompts-ia, busca/breadcrumbs em admin-arquivos, abas e tabela em cookie-consent.

• [x] Bloco 5 (interface & compilação): máscara monetária (c2fc-campo-moeda), seletor widget-imagem-tailwind e normalização canônica CRLF/LF no hash do Tailwind (tailwind-recursos.php).

Parte II — Site (Fase 2):

• [x] Bloco 6 (products): Quill na descrição, selects c2fc-campo-selecao, seletor de imagens, máscara de preço/promoção, métodos de frete do shipping-methods e link público /produto/<slug>/.

• [x] Bloco 7 (stripe-products): Quill na descrição, imagem contida sem overflow dos botões e máscara no campo valor.

• [x] Bloco 8 (Stripe vs Local): seletor de origem no topo, herança e trava de preço sem erro de submissão, e vigência de promoção (sempre vs período).

• [x] Bloco 9 (products-page & variações): remoção do vazamento de comentário HTML, resolução do infinite loading da aba Modelos e tag # crua, botões de ação nas variações com ícones Lucide/tooltips e máscaras monetárias nas variações.

Testes & Validação:

• [x] Vitest e PHPUnit verdes em ambos os repositórios (conn2flow e conn2flow-site).

• [x] Pipeline oficial executado sequencialmente: php cli/c2f.php project:update-all [REDACTED] --confirmar-remoto

• [x] Relatórios e evidências preenchidos em BATCH-248.md (Core) e BATCH-099.md (Site).