req-235 — Estabilização Visual e Operacional do Dashboard V3.0 (Logomarca, Geometria dos Cards de Módulos, Malha e Seleção de Widgets, e Topbar Lateralizada)

• Status: ready-for-implementation

• Modo de Autonomia: autonomo_monitorado

• Lote Alvo: BATCH-244

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

• Repositório: conn2flow (Core) em [REDACTED]

• Origem: Engenheiro Chefe Humano / Diretriz de Arquitetura: Ajustes e blindagens visuais de infraestrutura crítica após o ciclo V3.0.

• Aviso de Concorrência: Isolar na branch feat/req-235 via worktree limpo derivado de main. Proibido usar git add -A ou git add ..

1. Contexto & Diagnóstico dos Defeitos

1. Logomarca da Topbar Gigante:

   • Em determinadas telas e rotas onde o cache do Tailwind CLI ainda não compilou classes utilitárias arbitrárias (h-11, max-w-[190px], w-auto), a imagem <img> da logomarca renderiza em resolução bruta nativa (milhares de pixels), cobrindo mais da metade da tela.

   • Causa Raiz: Dependência exclusiva de classes Tailwind sem estilos defensivos inline (style="...") e sem classe travada no <style> do layout administrativo.

2. Geometria dos Cards de Módulos Quebrada (Deslocamento e Alça de Arrasto):

   • Sintoma com Imagem (Capa): A imagem fica deslocada para a direita com um pedaço vazio/quebrado na esquerda; a alça de arrasto fica colada na esquerda na metade da altura e seu tooltip ("title") é cortado na borda superior.

   • Sintoma sem Imagem (Ícone SVG): O ícone SVG fica descentralizado para a direita e a alça de arrasto fica deslocada para a esquerda.

   • Causa Raiz: O container pai .dashboard-card-header utilizava display: flex; align-items: center; justify-content: center;. A alça de arrasto (.dashboard-card-drag-handle) possui o atributo data-c2f-dica, que na folha de estilos global gestor/assets/interface/controles.css recebe a regra [data-c2f-dica] { position: relative; }. Sem position: absolute !important, a alça perdia o posicionamento absoluto e entrava como o primeiro item do flexbox horizontal, empurrando o cover e o SVG 32px para a direita e se alinhando no centro vertical (items-center). O tooltip padrão posicionava-se no topo (bottom: calc(100% + 6px)), sendo cortado pelo overflow: hidden do cabeçalho.

3. Capas dos Módulos Pequenas (Muito Wide / Sem Destaque):

   • A altura das capas no tamanho M (padrão) em 7rem (112px) tornava as imagens achatadas, dificultando a visualização das ilustrações isométricas 3D.

   • Necessidade de aumentar em 30% a 40% a altura (para 9rem / 144px em M e 12rem / 192px em G).

4. Aba Widgets & Métricas em Estado Esqueleto:

   • A interface atual possuía poucas opções de colunas em select estático, sem suporte a redimensionamento interativo com mouse nas bordas/cantos e sem um mecanismo transparente no próprio card para trocar qual widget está alocado no bloco.

   • Necessidade de malha canônica de 12 colunas com snap magnético e seletor evidente de widgets.

5. Menu Superior / Topbar Muito Verticalizado:

   • O painel de atalhos e favoritos estava com pouca largura horizontal e quebrava textos de botões de criação.

   • Necessidade de lateralidade confortável (w-80 mínimo ou layout de grade) e dicas posicionadas abaixo (bottom).

2. Critérios de Aceite (Critérios Normativos)

CA-1: Blindagem Estrita e Imutável da Logomarca na Topbar

• A tag <img> do logo principal em gestor/resources/{pt-br,en}/components/admin-topbar-tailwind/admin-topbar-tailwind.html DEVE conter:

  • Classe identificadora .admin-topbar-logo.

  • Estilo inline mandatório: style="height: 2.75rem !important; max-height: 2.75rem !important; max-width: 190px !important; width: auto !important; object-fit: contain !important; display: block !important;".

• O layout pai gestor/resources/{pt-br,en}/layouts/layout-administrativo-tailwind/layout-administrativo-tailwind.html DEVE incluir no <head> a regra CSS travando .admin-topbar-logo com as mesmas dimensões.

• Garantir que a renderização nunca exceda 190px de largura e 44px (2.75rem) de altura, sob qualquer circunstância de cache ou ausência de CSS.

CA-2: Arquitetura Desacoplada em Camadas Absolutas nos Cards de Módulos

• O elemento .dashboard-card-header NÃO PODE ter classes flexbox de linha (flex, items-center, justify-center).

• O cabeçalho DEVE possuir estilo defensivo inline: style="position: relative !important; overflow: hidden !important; width: 100% !important;".

• A alça de arrasto .dashboard-card-drag-handle DEVE:

  • Possuir position: absolute !important; top: 0.625rem !important; left: 0.625rem !important; z-index: 20 !important; width: 2rem !important; height: 2rem !important; display: flex !important; align-items: center !important; justify-content: center !important;.

  • Conter as classes utilitárias absolute top-2.5 left-2.5 z-20 cursor-grab rounded-md bg-white/90 p-1 text-slate-500 shadow-sm backdrop-blur-sm transition-colors hover:bg-white hover:text-slate-800.

  • Ter o atributo data-c2f-dica-pos="bottom right", garantindo que o balão da dica se projete para baixo e para o interior do card, sem corte por overflow: hidden.

• A camada de capa .dashboard-card-cover-wrapper DEVE ocupar todo o cabeçalho: style="position: absolute !important; inset: 0 !important; width: 100% !important; height: 100% !important; overflow: hidden !important;".

• A tag <img> da capa gerada em dashboard_modulo_visual_e_atalhos() em dashboard.php DEVE incluir style="width: 100% !important; height: 100% !important; object-fit: cover !important; display: block !important;".

• A camada de ícone SVG .dashboard-card-svg DEVE ter: style="position: absolute !important; inset: 0 !important; width: 100% !important; height: 100% !important; display: flex !important; align-items: center !important; justify-content: center !important; color: #334155 !important;".

• O ícone <svg> interno DEVE estar centralizado perfeitamente, sem qualquer desvio para a direita provocado pela alça de arrasto.

CA-3: Altura Proporcional das Capas dos Módulos

• No tamanho M (padrão): altura do cabeçalho fixada em 9rem (144px), permitindo 30% a 40% a mais de área útil visual.

• No tamanho G (expandido): altura do cabeçalho fixada em 12rem (192px).

• No tamanho P (compacto): layout horizontal de 2.25rem (36px) com alça de arrasto oculta (display: none !important;).

• Manter regras com !important em dashboard-cards-tailwind.css em ambos os idiomas (pt-br e en).

CA-4: Grade Canônica de 12 Colunas e Redimensionamento com Mouse na Aba Widgets

• A malha de widgets DEVE utilizar grid de 12 colunas no desktop (grid-template-columns: repeat(12, minmax(0, 1fr))) e 6 no tablet (grid-template-columns: repeat(6, minmax(0, 1fr))), com altura mínima base de 220px.

• Cada widget card DEVE possuir uma alça de redimensionamento (.dashboard-widget-resize-handle) no canto inferior direito, com cursor nwse-resize.

• O script JavaScript (dashboard.js) DEVE suportar redimensionamento por arrasto do mouse via pointerdown, pointermove e pointerup, calculando as novas dimensões e efetuando snap magnético nas larguras modulares:

  • 4 colunas (col-span-4), 6 colunas (col-span-6), 8 colunas (col-span-8) e 12 colunas (col-span-12).

  • Alturas: 1x (220px) e 2x (460px).

  • PROIBIDO o uso de cálculo por gridAutoRows de 8px.

• Cada card de widget DEVE possuir botão/menu evidente (.dashboard-widget-switch-btn / replaceWidget) para trocar diretamente o widget alocado no bloco, listando widgets ativos e disponíveis a partir do catálogo.

• As dimensões, posições e tipos de widgets DEVEM ser persistidos no banco de dados via AJAX (usuarios_preferencias).

CA-5: Topbar Administrativa com Lateralidade e Acessibilidade

• O container e painel de atalhos e favoritos DEVE possuir largura mínima w-80 (320px) para acomodar rótulos e botões sem quebra forçada ou sobreposição.

• Ordenação de favoritos na topbar suportada por arrasto (data-topbar-drag-handle) e teclado (ArrowUp / ArrowDown).

• Seletor de largura do layout operacional (normal, expanded, full) conectado ao container do painel.

• Tooltips de todos os controles da topbar DEVEM utilizar data-c2f-dica-pos="bottom".

• Paridade multilíngue estrita (pt-br e en) em arquivos HTML, CSS, JS e variáveis.

3. Arquivos Envolvidos e Responsabilidades

4. Live Todo List para Agentes Executores

• [ ] Criar e isolar worktree na branch feat/req-235 a partir de main.

• [ ] Aplicar blindagem da logomarca na topbar e nos layouts em pt-br e en.

• [ ] Aplicar arquitetura de camadas absolutas no cabeçalho dos cards de módulos (pt-br e en).

• [ ] Adicionar data-c2f-dica-pos="bottom right" na alça de arrasto dos cards.

• [ ] Garantir estilo inline na tag <img> gerada por dashboard.php.

• [ ] Validar e ajustar regras em dashboard-cards-tailwind.css (alturas 9rem e 12rem, alça e SVG centralizado).

• [ ] Assegurar funcionalidade de redimensionamento e seletor de widgets no dashboard.js.

• [ ] Rodar testes unitários Vitest e PHPUnit (DashboardCoversReq233Test, DashboardWidgetsReq233Test, AdminTopbarReq233Test).

• [ ] Executar minificação de assets (php cli/c2f.php assets:minify).

• [ ] Registrar lote em sdd/implementation/BATCH-244.md.

• [ ] Executar pipeline de atualização e validar integridade no navegador.