# Banners — Resumo Executivo

> **Versão analisada:** `v6` (com pequenas diferenças em relação à `v5`)
> **Slug do módulo:** `banners` (tabela `modulos`, `id = 22`, `status = 1`)
> **Natureza:** CMS (painel administrativo) + Portal (público)
> **Estado:** migrado v5 -> v6 (funcionalidade em uso; 4 banners e 2 super banners cadastrados)

---

## 1. Objetivo

O módulo "Banners" dá à prefeitura o controle das peças publicitárias/imagens
institucionais exibidas no portal: os **banners laterais** (faixas de 267x95 px exibidas
na coluna lateral direita das páginas) e os **super banners** (faixas de 772x90 px
exibidas em posições no topo, na lateral do cabeçalho ou em carrossel, conforme o
modelo de layout ativo).

Não existe uma tabela "banners": ambos os tipos são **conteúdos** (`contents`)
vinculados a categorias da tabela `category_contents` — `banners` (id 27) e
`super-banners` (id 33). O CMS é, portanto, o CRUD genérico de conteúdos
(`ContentController`) dirigido pelo *slug* da categoria.

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Vê faixas institucionais (e-SIC, Portal da Transparência, Licitações) na lateral das páginas e, nos modelos 1/2/5, super banners no topo e no rodapé da home. |
| Prefeitura (CMS) | Publica, ordena (drag & drop), ativa/desativa e troca a imagem dos banners; a posição do super banner depende do layout escolhido para o portal. |
| Transparência e legalidade | Os super banners são o espaço institucional por excelência; a implementação atual tem **inconsistência de nomes de campo** que impede a edição pela tela de super banners (ver `08-GAPS-E-DIVIDAS.md`). |
| Operação técnica | Duas views SQL (`banners`, `super_banners`) exponham os dados ao grid do CMS; a view `super_banners` embute uma subconsulta em `configurations`. |

## 3. Comportamento

- **Banner comum** (`category_contents.slug = 'banners'`): título, URL, imagem
  (`archives.highlight = 1`), ordem (`contents.order`) e status. Renderizado na coluna
  lateral das páginas internas do layout `default` e na sidebar do `modelo1`.
- **Super banner** (`category_contents.slug = 'super-banners'`): mesmos campos, mas
  `order` tem **semântica dupla**: `order = 1` = "topo"/"esquerda";
  `order = 2` = "base"/"direita" (o rótulo exato depende do layout ativo).
- **Ativação**: apenas um super banner por posição pode estar ativo — ao ativar um, o
  controller desativa o anterior da mesma posição.
- **Ordenação**: drag & drop na lista do CMS, persistida via `POST /cms/ajust-banners`
  (rota `ajust.banners`).
- **Status**: visível no grid como "Ativado"/"Desativado" (view SQL) e alternável pelo
  botão de status do DataTable.

### Tabela comparativa: banner comum x super banner

| Aspecto | Banner comum | Super banner |
|---|---|---|
| Categoria | `banners` (id 27) | `super-banners` (id 33) |
| View SQL | `banners` | `super_banners` |
| Tamanho sugerido | 267x95 | 772x90 |
| Posição no portal | Lateral direita | Topo / lateral do logo / rodapé / carrossel |
| Rótulos de posição | — | `Esquerda`/`Direita` (modelo5) ou `Em cima`/`Em baixo` (demais) |
| Renderização | `default/side-banners.blade.php`, `modelo1/layout/sidebar/banners.blade.php` | `modelo1/home/elementos.blade.php`, `modelo2/home/elementos.blade.php`, `modelo2/layout/nav.blade.php`, `modelo5/home/super-banners/*` |

## 4. Como o Usuário Interage

**Operador (CMS):**

- Menu "Banners" → submenu "Banners Laterais" (`/cms/conteudos/banners`) e
  "Super Banners" (`/cms/conteudos/super-banners`), este último visível apenas com a
  permissão `super-banners.index`.
- Lista com ID, Título, Status e Ações; a coluna do botão de arraste habilita a
  reordenação por drag & drop.
- Formulário: Status, Título, **Posição** (select com os rótulos dependentes do layout),
  Imagem (upload ou "Criar banner personalizado"), URL e "Abrir em nova guia".
- Exclusão em lote via `ajax.generic.content.deleteAll`.

**Cidadão (portal):** clique no banner navega para a URL cadastrada; com
"Abrir em nova guia" (`links.isBlank = 1`) abre em nova aba.

## 5. Detalhes e Particularidades Técnicas

- O CRUD é o **genérico** de conteúdos: `ContentController@genericIndex`,
  `genericCreate`, `genericEdit`, `store`, `update`, `destroy`, todos dirigidos por
  `slug`.
- A view SQL `super_banners` decide a coluna `posicao` lendo
  `configurations.key = 'layout'` **dentro do SQL**; o mesmo dado é reproduzido no PHP
  pelo helper `objBanner($template)` (`v6/app/Helpers/functions.php:921`).
- O caminho do arquivo do super banner na view de upload é
  `storage/content/super-banners/<id>/destaque/<nome>`, enquanto o `updateSuperBanner`
  grava em `storage/content/super-banner/` (singular) — divergência real de caminho.
- O `super.blade.php` do CMS envia campos `check_<slug>` / `url_<slug>` /
  `<slug>` (arquivo) e o controller `updateSuperBanner` espera
  `check_super_banner_1`, `check_super_banner_2`, `url_super_banner_1`,
  `url_super_banner_2`, `super_banner_1`, `super_banner_2`. Com o seed atual
  (slugs `super_banner_1`/`super_banner_2`) os nomes coincidem, mas a tela é
  **órfã**: nenhum controller renderiza `prefecture.contents.banners.super`, de
  modo que a rota `update.super.banner` fica sem uso.

## 6. Estrutura de Dados

| Objeto | Descrição |
|---|---|
| `category_contents` | Categorias `banners` (27) e `super-banners` (33) |
| `contents` | Os banners propriamente ditos (título, `order`, `status`, `slug`) |
| `archives` | Imagem do banner (`highlight = 1`) |
| `links` | URL do banner (`links.contents_id`, `isBlank`, `alt`) |
| View `banners` | Projeção para o DataTable do CMS |
| View `super_banners` | Projeção com a coluna `posicao` calculada |
| `configurations` | Chave `layout` (ex.: `modelo5`) lida pela view `super_banners` |
| `modulos` | `id = 22`, `slug = 'banners'`, `status = 1` |
| `resources` | `banners` (id 25) e `super-banners` (id 26), ambos `modulo_id = 22` |

## 7. Como Testar

1. Ativar/desativar um banner lateral → conferir `contents.status`.
2. Arrastar um banner na lista → conferir `contents.order`.
3. Trocar o layout ativo (Configurações) → conferir os rótulos de posição de super
   banner e a view `super_banners.posicao`.
4. Conferir no portal: lateral (banners) e topo/rodapé (super banners).
5. Verificar a tela "Super Banners" (botão da home) — atualmente quebrada.

## 8. Migração para Laravel Moderno

Modelos `Content`/`Banner` enxutos com `Category` dedicada, `Media` para imagens,
`BannerPosition` enum, `Policy` por módulo (`banners.*`, `super-banners.*`), API
Resources para a listagem pública de banners, cache curto do payload do portal e
componentes Blade únicos (`<x-portal.banner-strip>`, `<x-portal.super-banner>`) no lugar
das cópias por modelo de layout.

## 9. Resumo Geral

Banners e super banners são, internamente, **conteúdos** do CMS genérico: a
distinção vem apenas da categoria (`banners` vs `super-banners`) e do significado do
campo `order` — no super banner, `order` indica a posição na tela, e o rótulo dessa
posição ("Esquerda"/"Direita" no modelo5; "Em cima"/"Em baixo" nos demais) é calculado
em tempo de consulta pela view SQL `super_banners`, que lê a configuração `layout` do
portal. O portal os exibe em pontos fixos de cada modelo (lateral, topo do conteúdo,
lateral do logo, carrossel do modelo5), injetados por view composers de
`v6/app/Providers/BannerServiceProvider.php`. O módulo está em produção (4 banners e 2
super banners cadastrados) e habilitado no menu, mas apresenta inconsistências
relevantes: a tela de edição rápida de super banners usa nomes de campos diferentes
dos lidos pelo controller, e o caminho de upload do super banner diverge entre a view
e o controller.

---

## Í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 |