# Destaques — Resumo Executivo

> **Versão analisada:** `v6` (módulo idêntico em `v5`)
> **Slug do módulo:** `detaques` (tabela `modulos`, **com typo**) — o `menu_orders.slug` correspondente é `destaques`
> **Natureza:** CMS (painel administrativo) + Portal (público)
> **Estado:** novo na v6 (migration de 2025-03-31 presente também na v5)

---

## 1. Objetivo

O módulo "Destaques" permite à prefeitura publicar, no topo da página inicial do
portal, um conjunto de **faixas promocionais/imagens de destaque** (imagem de fundo +
título + subtítulo + botão com link). Cada destaque é uma linha da tabela `highlights`,
com uma imagem associada gravada na tabela `archives` (coluna `highlight_id`) e
armazenada fisicamente em `storage/highlights/<id>/<nome>`.

O módulo serve a dois públicos: o **operador do CMS**, que cadastra, ordena, publica e
despublica os destaques; e o **cidadão**, que visualiza o carrossel de destaques no topo
do portal (modelos 1 a 6), substituindo o carrossel de notícias quando existem
destaques ativos.

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Visualiza um carrossel de imagens de destaque com link no topo da home. Se nenhum destaque estiver com `status = true`, o portal exibe o carrossel de notícias (fallback). |
| Prefeitura (CMS) | Tela "Lista de Destaques" com CRUD completo, ordenação por `position`, ativar/desativar e upload de imagem. |
| Transparência e legalidade | Nada a declarar: o módulo é puramente comunicacional. |
| Operação técnica | Tabela nova (`highlights`) criada em 2025, com FK em `archives`; o módulo está **desabilitado** no menu do CMS (`modulos.status = 0`) e o slug contém typo. |

## 3. Comportamento

- Um destaque possui: `title`, `subtitle`, `text_button`, `url`, `position`, `status`,
  `status_button`, `layout` (1 = largura da página, 2 = centralizado), `is_blank`.
- A ordenação é por `position` (inteiro, único na prática). Ao criar, as posições
  `>= position` são incrementadas em 1; ao editar, o intervalo entre a posição antiga e a
  nova é deslocado (`HighlightController::store`, `HighlightController::update`).
- A tela "create" calcula a primeira posição livre (`HighlightController::create`).
- A imagem é obrigatória na prática (`HighlightRequest` exige `archive_highlight` como
  `image`, `max:20000`, mimes `jpg,jpeg,png,gif,webp`), gravada em
  `storage/highlights/<id>/<nome>` e registrada em `archives` com `highlight = 1` e
  `highlight_id = <id do destaque>`.
- `status` controla a exibição; `toggleStatus` alterna entre `true` e `null`
  (não `false`) — ver `08-GAPS-E-DIVIDAS.md`.
- O portal só carrega destaques com `status = true`, ordenados por `position`
  (`PortalController::index`).
- Se existir **um único** destaque com `layout = 1` e `status = true`, o portal entra em
  modo "fullscreen" (`ConfigHeaderServiceProvider`), mudando a largura da caixa de texto.

### Distinção crítica: três conceitos parecidos

| Conceito | Onde vive | Significado |
|---|---|---|
| **Destaque (módulo)** | tabela `highlights` | Faixa hero no topo do portal, gerenciada em `/cms/destaques` |
| `contents.highlights` | coluna booleana | Marca uma notícia como "destacada" dentro do carrossel de notícias (`ContentController::setHighlights`) |
| `archives.highlight` | coluna booleana | Marca **um arquivo** como a imagem principal de um conteúdo (`archives.highlight = 1`) |

## 4. Como o Usuário Interage

**Operador (CMS):** menu lateral "Destaques" → lista com colunas ID, Título, Posição e
Ações; botão "Cadastrar Destaque"; no formulário: checkbox "Publicar", Título (máx. 150
na UI), Subtítulo (textarea), Imagem Principal (upload), URL, Texto do botão, Layout de
exibição (Largura da página / Centralizado), Posição e "Exibir botão".

**Cidadão (portal):** carrossel de destaques no topo da home; clique no botão
"Ver mais"/CTA navega para `highlights.url`; se `is_blank` for verdadeiro, abre em nova
aba — **não verificado** se `is_blank` é efetivamente aplicado no portal (o Blade não o
utiliza).

## 5. Detalhes e Particularidades Técnicas

- Camadas: `Route` → `HighlightController` → `HighlightRequest` → `Highlight` (Eloquent)
  → `Archive` (imagem) → Blade do CMS; no portal: `PortalController`/`ConfigHeaderServiceProvider`
  → `portal/layouts/modelo1/home/destaque.blade.php (e equivalentes em modelo2..modelo6)`.
- **Ponto de atenção:** `DatatableController::get_highlight` consulta `DB::table('highlight')`
  — que é a **view SQL** `highlight` (criada por
  `v6/database/migrations/2025_03_31_212620_create_view_highligh_table.php`), não a tabela
  física `highlights`. A consulta funciona, mas ignora o model Eloquent e as colunas
  `text_button`, `url`, `status_button`, `layout` e `is_blank`.
- **Bug conhecido:** o slug em `modulos` é `detaques` (typo), o que impede a exibição do
  item de menu "Destaques" (o `MenuServiceProvider` exige `modulos.status` verdadeiro).
- `highlight_id` em `archives` é `ON DELETE CASCADE`: apagar o destaque apaga a imagem
  (registro), mas **não** o arquivo físico em disco.

## 6. Estrutura de Dados

| Objeto | Descrição |
|---|---|
| `highlights` | Tabela do módulo (11 colunas). Criada em `v6/database/migrations/2025_03_31_210313_create_highlights_table.php` |
| `archives.highlight_id` | FK `highlights(id)` `ON DELETE CASCADE`, nullable |
| `archives.highlight` | Booleano — **outro conceito** (imagem principal de conteúdo) |
| `modulos` | Registro `id = 55`, `slug = 'detaques'`, `status = 0` |
| `menu_orders` | Registro `id = 43`, `slug = 'destaques'`, `modulo_id = 55` |
| `resources` | Registro `id = 75`, `slug = 'destaques'`, `modulo_id = 55` |

## 7. Como Testar

1. Criar um destaque com imagem → conferir arquivo em `storage/highlights/<id>/` e linha em
   `archives` com `highlight_id` preenchido.
2. Alterar a `position` → conferir o deslocamento das demais.
3. Publicar (`status`) → abrir a home do portal e ver o carrossel.
4. Despublicar → o portal deve voltar ao carrossel de notícias.
5. Acessar `/cms/datatable/highlight` → HTTP 200 com `titulo`/`posicao` (vindos da view `highlight`).

## 8. Migração para Laravel Moderno

Modelo `Highlight` enxuto com casts (`status`, `status_button`, `is_blank` → boolean;
`position` → integer), `FormRequest` com `Rule::image()->max('20mb')`, `Policy` para
autorização, `Storage::disk('public')` para as imagens, `ApiResource` para leitura e
testes Pest/PHPUnit para o CRUD, ordenação e a renderização do carrossel.

## 9. Resumo Geral

O módulo "Destaques" é uma funcionalidade de comunicação visual do topo do portal:
cadastrados na tabela `highlights`, com imagem na tabela `archives` (via
`highlight_id`) e arquivo em `storage/highlights/`. A ordem de exibição é definida pelo
campo inteiro `position`, rebalanceada automaticamente em create/update. O portal
carrega apenas destaques com `status = true` e, se não houver nenhum, exibe o
carrossel de notícias como fallback. O módulo foi criado em março de 2025 e hoje está
**inoperante no menu do CMS** por dois motivos: o slug cadastrado em `modulos` é
`detaques` (typo) e o seu `status` é `0`; além disso, o datatable do módulo consulta a
view SQL `highlight` (criada por `v6/database/migrations/2025_03_31_212620_create_view_highligh_table.php`). Trata-se, ainda, de um conceito diferente do campo
booleano `contents.highlights` ("marcar notícia como destaque") e de
`archives.highlight` ("imagem principal de um conteúdo"), distinção essencial para
qualquer refatoração.

---

## Índice do dossiê

| Arquivo | Conteúdo |
|---|---|
| `00-RESUMO.md` | Este documento |
| `01-ARQUITETURA.md` | Camadas, classes e o diagrama de fluxo |
| `02-MODELAGEM.md` | Estrutura de dados detalhada |
| `03-ROTAS-E-CONTROLADORES.md` | Rotas, controllers, requests, resources |
| `04-VIEWS-E-UX.md` | Telas, componentes, JS, assets |
| `05-REGRAS-E-PORTABILIDADE.md` | Particularidades e armadilhas |
| `06-MIGRACAO-MODERNA.md` | Plano de reconstrução em Laravel moderno |
| `07-TESTES.md` | Estratégia e casos de teste |
| `08-GAPS-E-DIVIDAS.md` | Pendências, riscos, comparativo v5 vs v6 |