req-226 — Dashboard V3.0: Grid Interativo de Módulos (P/M/G), Grid Flexível de Widgets e Links Canônicos de Documentação

O Dashboard é a porta de entrada e a principal vitrine da Versão 3.0 do Conn2Flow. Com a migração da interface administrativa para Tailwind CSS (req-219), o Dashboard precisa…

Status: in-review
Modo de Autonomia: autonomo_monitorado
Lote Alvo: BATCH-235
Data de Criação: 2026-10-04
Repositório: conn2flow (Core) em [REDACTED]
Origem: Engenheiro Chefe / Arquiteto Master: Especificação da vitrine da Versão 3.0 para o Dashboard inicial do Gestor.
Aviso de Concorrência: Outros agentes estão operando no repositório (req-219, req-224, req-225). Isolar o trabalho em branch/worktree dedicada (feat/req-226), sem alterar arquivos fora do módulo dashboard e dos seus recursos. Não usar git add -A.

1. Contexto e Objetivos

O Dashboard é a porta de entrada e a principal vitrine da Versão 3.0 do Conn2Flow. Com a migração da interface administrativa para Tailwind CSS (req-219), o Dashboard precisa deixar de ser uma grade estática de ícones e se transformar em uma central de comando dinâmica, modular e personalizável pelo usuário.

Principais Dores Resolvidas:

URLs de Documentação Quebradas: No gestor/modulos/dashboard/dashboard.php, as URLs ainda apontam para o caminho defasado no GitHub (https://github.com/otavioserra/conn2flow/blob/main/ai-workspace/...), gerando links 404.
Falta de Densidade e Controle de Visualização: Usuários com dezenas de módulos instalados precisam de visualizações mais densas (compactas) ou mais detalhadas (com métricas/atalhos rápidos).
Ausência de Grid Operacional de Widgets: Não há área de widgets personalizáveis onde o usuário possa organizar métricas, atalhos e mini-aplicações conforme sua necessidade.

2. Escopo Detalhado da Implementação

2.1. Resolução Canônica de Links de Documentação e Manuais

Corrigir a montagem de links no PHP (dashboard.php):
- Módulos Core / Oficiais: Devem apontar para a documentação pública e canônica do Conn2Flow:
- Docs: https://conn2flow.com/docs/reference/modules/<modulo-id>/
- Manual: https://conn2flow.com/docs/manual/modules/<modulo-id>/
- **Módulos Customizados / Privados do [REDACTED] Se o módulo possuir documentação interna local (verificar convenção de arquivo local ou metadado no JSON do módulo), apontar para a rota interna do painel: @[[pagina#url-raiz]]@documentation/<modulo-id>/.
- Se um módulo não possuir documentação registrada nem remota, o botão de documentação deve ser ocultado ou desabilitado com dica explicativa ("Documentação em breve").

2.2. Sistema de Abas no Dashboard

Implementar navegação por abas nativas Tailwind no topo da página:

Aba 1: ? Módulos (Visão Geral): Catálogo de aplicações com busca, ordenação e seletor de densidade.
Aba 2: ? Widgets & Métricas (Painel Operacional): Grid livre para montagem de widgets do sistema.

2.3. Seletor de Densidade de Módulos (P / M / G)

Adicionar controle visual ao lado do campo de busca (#dashboard-search-container) com três estados:

P (Pequeno / Compacto):
- Grid de 4 a 6 colunas (grid-cols-2 md:grid-cols-4 lg:grid-cols-6).
- Thumbnail reduzida (ícone ou mini-imagem de 32x32 px), nome do módulo e link direto de acesso. Ideal para navegação rápida de operadores frequentes.
M (Médio / Padrão):
- Grade balanceada (grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4).
- Imagem referencial/thumbnail de 80x80 px ou banner do módulo, categoria, breve descrição, botão "Acessar" e botões discretos de Manual e Docs.
G (Grande / Widget Operacional):
- Grid de 1 a 2 colunas (grid-cols-1 lg:grid-cols-2).
- Exibição expandida: banner visual de destaque, descrição completa, atalhos rápidos contextuais (ex.: "Novo Registro", "Configurações", "Histórico") e mini-indicadores pré-carregados quando o módulo fornecer.

2.4. Suporte a Imagens Referenciais de Módulos (Thumbnails)

Atualizar a montagem do card em dashboard-cards-tailwind.html:
- Priorizar imagem/thumbnail referencial WebP/PNG se configurada no metadado do módulo (gestor/modulos/<modulo-id>/cover.webp ou caminho informado no dashboard.json / metadado do módulo).
- Caso não haja imagem física, manter fallback gracioso para o #modulo-svg# / Lucide icon existente.

2.5. Grid Flexível de Widgets (Aba 2)

Criar a infraestrutura de Grid para Widgets na Aba 2:
- Sistema de encaixe tipo grid/quebra-cabeça com suporte a redimensionamento e arrasto nos modos de edição.
- O usuário deve poder adicionar qualquer widget registrado no sistema (hosts_widgets ou catálogo nativo).
- Persistência das preferências do layout de widgets:
- Backend Obrigatório: Salvar o estado do layout (posições, larguras e alturas dos widgets do usuário) no banco de dados (tabela de preferências do usuário ou metadados de sessão persistida do host), garantindo que ao trocar de dispositivo ou navegador a disposição dos widgets seja preservada.
- Fallback de cache local em localStorage apenas para renderização instantânea enquanto sincroniza com a API.

3. Critérios de Aceite (Definition of Done)

[x] CA-1 (Docs Canônicos): Todas as URLs de documentação e manual dos cards do dashboard apontam para as rotas corretas (pública no site conn2flow.com para o core, ou rota interna para módulos locais), sem qualquer link quebrado para o repositório antigo do GitHub.
[x] CA-2 (Seletor P/M/G): O usuário consegue alternar entre densidade Pequena, Média e Grande no seletor de visualização. O estado selecionado é respeitado imediatamente na UI sem recarregar a página e persiste na sessão/preferência do usuário.
[x] CA-3 (Abas Módulos e Widgets): As abas "Módulos" e "Widgets & Métricas" operam com chaveamento fluido, sem perda de estado da busca.
[x] CA-4 (Grid de Widgets Customizável): Na aba de Widgets, o usuário pode adicionar widgets registrados, organizar posições e redimensionar blocos, com persistência salva no backend para o usuário logado.
[x] CA-5 (Renderização e Fallback de Imagens): Módulos que tiverem thumbnails/covers são renderizados com a imagem correspondente; módulos sem imagem continuam exibindo o ícone SVG com renderização limpa e responsiva.
[x] CA-6 (Qualidade e Compatibilidade): Sem regressões de JavaScript no console, sem quebra de CSS na versão mobile (390px) e compatível com as regras de design tokens do Tailwind da req-219.

# req-226 — Dashboard V3.0: Grid Interativo de Módulos (P/M/G), Grid Flexível de Widgets e Links Canônicos de Documentação
- **Status:** `in-review`
- **Modo de Autonomia:** `autonomo_monitorado`
- **Lote Alvo:** `BATCH-235`
- **Data de Criação:** 2026-10-04
- **Repositório:** `conn2flow` (Core) em `[REDACTED]`
- **Origem:** Engenheiro Chefe / Arquiteto Master: Especificação da vitrine da Versão 3.0 para o Dashboard inicial do Gestor.
- **Aviso de Concorrência:** Outros agentes estão operando no repositório (`req-219`, `req-224`, `req-225`). Isolar o trabalho em branch/worktree dedicada (`feat/req-226`), sem alterar arquivos fora do módulo `dashboard` e dos seus recursos. Não usar `git add -A`.
---
## 1. Contexto e Objetivos
O Dashboard é a porta de entrada e a principal vitrine da **Versão 3.0** do Conn2Flow. Com a migração da interface administrativa para Tailwind CSS (`req-219`), o Dashboard precisa deixar de ser uma grade estática de ícones e se transformar em uma central de comando dinâmica, modular e personalizável pelo usuário.
### Principais Dores Resolvidas:
1. **URLs de Documentação Quebradas:** No [`gestor/modulos/dashboard/dashboard.php`](file:///[REDACTED]), as URLs ainda apontam para o caminho defasado no GitHub (`https://github.com/otavioserra/conn2flow/blob/main/ai-workspace/...`), gerando links 404.
2. **Falta de Densidade e Controle de Visualização:** Usuários com dezenas de módulos instalados precisam de visualizações mais densas (compactas) ou mais detalhadas (com métricas/atalhos rápidos).
3. **Ausência de Grid Operacional de Widgets:** Não há área de widgets personalizáveis onde o usuário possa organizar métricas, atalhos e mini-aplicações conforme sua necessidade.
---
## 2. Escopo Detalhado da Implementação
### 2.1. Resolução Canônica de Links de Documentação e Manuais
- Corrigir a montagem de links no PHP (`dashboard.php`):
  - **Módulos Core / Oficiais:** Devem apontar para a documentação pública e canônica do Conn2Flow:
    - Docs: `https://conn2flow.com/docs/reference/modules/<modulo-id>/`
    - Manual: `https://conn2flow.com/docs/manual/modules/<modulo-id>/`
  - **Módulos Customizados / Privados do [REDACTED] Se o módulo possuir documentação interna local (verificar convenção de arquivo local ou metadado no JSON do módulo), apontar para a rota interna do painel: `@[[pagina#url-raiz]]@documentation/<modulo-id>/`.
  - Se um módulo não possuir documentação registrada nem remota, o botão de documentação deve ser ocultado ou desabilitado com dica explicativa ("Documentação em breve").
### 2.2. Sistema de Abas no Dashboard
Implementar navegação por abas nativas Tailwind no topo da página:
1. **Aba 1: ? Módulos (Visão Geral):** Catálogo de aplicações com busca, ordenação e seletor de densidade.
2. **Aba 2: ? Widgets & Métricas (Painel Operacional):** Grid livre para montagem de widgets do sistema.
### 2.3. Seletor de Densidade de Módulos (P / M / G)
Adicionar controle visual ao lado do campo de busca (`#dashboard-search-container`) com três estados:
- **P (Pequeno / Compacto):**
  - Grid de 4 a 6 colunas (`grid-cols-2 md:grid-cols-4 lg:grid-cols-6`).
  - Thumbnail reduzida (ícone ou mini-imagem de 32x32 px), nome do módulo e link direto de acesso. Ideal para navegação rápida de operadores frequentes.
- **M (Médio / Padrão):**
  - Grade balanceada (`grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4`).
  - Imagem referencial/thumbnail de 80x80 px ou banner do módulo, categoria, breve descrição, botão "Acessar" e botões discretos de Manual e Docs.
- **G (Grande / Widget Operacional):**
  - Grid de 1 a 2 colunas (`grid-cols-1 lg:grid-cols-2`).
  - Exibição expandida: banner visual de destaque, descrição completa, atalhos rápidos contextuais (ex.: "Novo Registro", "Configurações", "Histórico") e mini-indicadores pré-carregados quando o módulo fornecer.
### 2.4. Suporte a Imagens Referenciais de Módulos (Thumbnails)
- Atualizar a montagem do card em [`dashboard-cards-tailwind.html`](file:///[REDACTED]):
  - Priorizar imagem/thumbnail referencial WebP/PNG se configurada no metadado do módulo (`gestor/modulos/<modulo-id>/cover.webp` ou caminho informado no `dashboard.json` / metadado do módulo).
  - Caso não haja imagem física, manter fallback gracioso para o `#modulo-svg#` / Lucide icon existente.
### 2.5. Grid Flexível de Widgets (Aba 2)
- Criar a infraestrutura de Grid para Widgets na Aba 2:
  - Sistema de encaixe tipo grid/quebra-cabeça com suporte a redimensionamento e arrasto nos modos de edição.
  - O usuário deve poder adicionar qualquer widget registrado no sistema (`hosts_widgets` ou catálogo nativo).
  - Persistência das preferências do layout de widgets:
    - **Backend Obrigatório:** Salvar o estado do layout (posições, larguras e alturas dos widgets do usuário) no banco de dados (tabela de preferências do usuário ou metadados de sessão persistida do host), garantindo que ao trocar de dispositivo ou navegador a disposição dos widgets seja preservada.
    - Fallback de cache local em `localStorage` apenas para renderização instantânea enquanto sincroniza com a API.
---
## 3. Critérios de Aceite (Definition of Done)
- [x] **CA-1 (Docs Canônicos):** Todas as URLs de documentação e manual dos cards do dashboard apontam para as rotas corretas (pública no site `conn2flow.com` para o core, ou rota interna para módulos locais), sem qualquer link quebrado para o repositório antigo do GitHub.
- [x] **CA-2 (Seletor P/M/G):** O usuário consegue alternar entre densidade Pequena, Média e Grande no seletor de visualização. O estado selecionado é respeitado imediatamente na UI sem recarregar a página e persiste na sessão/preferência do usuário.
- [x] **CA-3 (Abas Módulos e Widgets):** As abas "Módulos" e "Widgets & Métricas" operam com chaveamento fluido, sem perda de estado da busca.
- [x] **CA-4 (Grid de Widgets Customizável):** Na aba de Widgets, o usuário pode adicionar widgets registrados, organizar posições e redimensionar blocos, com persistência salva no backend para o usuário logado.
- [x] **CA-5 (Renderização e Fallback de Imagens):** Módulos que tiverem thumbnails/covers são renderizados com a imagem correspondente; módulos sem imagem continuam exibindo o ícone SVG com renderização limpa e responsiva.
- [x] **CA-6 (Qualidade e Compatibilidade):** Sem regressões de JavaScript no console, sem quebra de CSS na versão mobile (390px) e compatível com as regras de design tokens do Tailwind da `req-219`.