# Banners — Gaps, Dívidas e Mapa v5 → v6

## 1. Bugs e erros conhecidos

| # | Severidade | Descrição | Evidência |
|---|---|---|---|
| B1 | Média | A tela de edição rápida de super banners (`banners/super.blade.php`) monta os nomes dos campos a partir de `contents.slug` (`check_<slug>`, `url_<slug>`, `<slug>`), enquanto `updateSuperBanner` fixa `check_super_banner_1/2`, `url_super_banner_1/2` e `super_banner_1/2`. Com o seed atual (slugs `super_banner_1` e `super_banner_2`) os nomes coincidem, mas a dependência é implícita: renomear o slug de um super banner faz o controller deixar de ler o campo, zerar o `status` e gravar `link` nula. | `v6/resources/views/prefecture/contents/banners/super.blade.php` × `v6/app/Http/Controllers/Prefecture/ContentController.php:1440-1452` |
| B2 | **Alta** | `updateSuperBanner` assume exatamente dois super banners; com menos de dois, `$banner1`/`$banner2` são `null` → erro fatal em `->id`. | `…/ContentController.php:1431-1438` |
| B3 | **Alta** | Caminho de upload divergente: o preview da view aponta para `storage/content/super-banners/<id>/destaque/<nome>` (sem o segmento do slug do conteúdo), enquanto o upload genérico grava em `storage/content/<slug-do-conteudo>/<id>/destaque/<nome>`; a rota `updateSuperBanner` grava em `storage/content/super-banner/<nome>` (singular). | `v6/resources/views/prefecture/contents/super-banners/form.blade.php` × `…/ContentController.php:1150` e `…/ContentController.php:1460` |
| B4 | Média | `returnData('Super Banners', 'super-banners', 'banners', ...)` popula `$banners` com os conteúdos da categoria `banners` (e não `super-banners`). | `…/ContentController.php:175` |
| B5 | Média | `ContentRequest` decide a obrigatoriedade da imagem lendo `Route::getCurrentRoute()->getName() == "conteudo.store"` — renomear a rota quebra a regra. | `v6/app/Http/Requests/ContentRequest.php:127` |
| B6 | Média | A view SQL `super_banners` depende de uma subconsulta escalar em `configurations`; qualquer alteração do schema de `configurations` quebra a view. | `v6/database/migrations/2023_04_10_132524_create_view_to_super_banners.php` |
| B7 | Média | A ordem de `super_banners` é `(status IS TRUE) DESC, created_at DESC`, ignorando `c.order` — enquanto o portal usa `order` para posicionar. Grid e portal podem discordar. | mesma migration |
| B8 | Média | `super-banners` não valida o campo `link`, embora o formulário o exija. | `v6/app/Http/Requests/ContentRequest.php:151-163` |
| B9 | Média | `banners` limita `title` a 45 caracteres na UI e a 120 no request — inconsistência. | `v6/resources/views/prefecture/contents/banners/form.blade.php` × `v6/app/Http/Requests/ContentRequest.php:124` |
| B10 | Média | O formulário de banner define `maxlen => 200` e `maxlength => 2999` no mesmo input de URL. | `v6/resources/views/prefecture/contents/banners/form.blade.php` |
| B11 | Baixa | O botão "Cadastrar Banner" usa URL relativa (`cadastrar/banners`), dependente do contexto da URL. | `v6/resources/views/prefecture/contents/banners/index.blade.php` |
| B12 | Baixa | Imagem padrão com typo no nome do arquivo: `supper-banner-sem-imagem.png`. | `v6/resources/views/prefecture/contents/super-banners/form.blade.php` |
| B13 | Baixa | O botão de arraste do grid usa `createDragglabeButton(data.edit)` (sem `id`), diferente do padrão dos demais grids. | `v6/public/assets/js/custom/contents/super-banners/datatable.js` |
| B14 | Baixa | `@inject` + query dentro do Blade executa a consulta de banners **a cada renderização**, ignorando o composer. | `v6/resources/views/portal/layouts/default/side-banners.blade.php` |
| B15 | Baixa | A view do layout `default` mantém uma linha `<img>` comentada (código morto). | `v6/resources/views/portal/layouts/default/side-banners.blade.php` |

## 2. Funcionalidades incompletas ou mortas

| Item | Situação |
|---|---|
| `banners/super.blade.php` | Não é alcançada por nenhuma rota — resíduo de versão anterior |
| `objBanner()` | Devolve rótulos por layout, mas só é usado no formulário de super banner; a view SQL recalcula o mesmo valor em SQL (duplicação) |
| `fileSuperBannerExist()` | Definido em `v6/app/Helpers/functions.php:397`, mas **não usado** pelas views do portal atuais |
| `fileBannerExist()` | Usado apenas no `modelo1`; o layout `default` faz o fallback inline |
| `super-banners-2` (layout) | Está ativo no banco, mas depende de `superBanners[1]` existir |
| Import de `acronym` no `BannerServiceProvider` da v5 | Removido na v6 sem substituição |
| API pública de banners | Não existe endpoint JSON para o portal consumir |

## 3. Acoplamentos frágeis

| Acoplamento | Risco |
|---|---|
| View SQL ← `configurations.layout` | Alterar o schema de `configurations` quebra a view `super_banners` |
| `contents.order` com semântica dupla | Banner comum (ordem na lista) vs super banner (posição na tela) |
| Grid (`banners`/`super_banners`) × portal | Os dois usam `order`, mas a view `super_banners` **não** ordena por ele |
| `MenuServiceProvider` + `modulos` | O submenu "Super Banners" depende de `has_access('super-banners.index')` **e** de `modulos.status` |
| JS do grid + prefixo `/cms` | Rotas do AJAX construídas por convenção no front |
| `layouts` (modelo5) | A composição dos super banners do modelo5 depende da tabela `layouts` |

## 4. Riscos de dados (migração de schema)

| Risco | Detalhe | Mitigação |
|---|---|---|
| Views SQL com `row_number()` | `CREATE OR REPLACE VIEW` falha se a assinatura de colunas mudar | Versionar as views como migrations e recriá-las (`DROP` + `CREATE`) quando necessário |
| Dependência de seed para a view | `v6/database/seeds/UpdateSuperBannersViewFixEmBaixo.php` reescreve a view; seeds não rodam em `migrate` | Converter em migration |
| Migration ausente na v6 | `v5/database/migrations/2025_09_30_215142_update_view_to_super_banners.php` não existe na v6 | Portar a migration ou unificar as duas versões da view |
| `order` sem unicidade | Vários banners podem sharear a mesma posição | Índice único por `(categoria, order)` para super banners |
| Regras de ativação em `UPDATE` massivo | `Content::where(...)->update(['status' => false])` afeta todas as posições iguais | Manter dentro de transação e auditar |
| Arquivos órfãos | A exclusão de conteúdo não apaga a imagem em `storage/content/banners/...` | Limpeza por job |

## 5. Perguntas em aberto para o negócio

1. Quantos super banners devem existir? O código assume **dois** (posições 1 e 2).
2. O modelo5 deve permitir mais de dois super banners por posição (carrossel)? A v5
   agrupava por posição (`superBannersPosition1/2`), sugerindo que sim.
3. O rótulo da posição ("Esquerda"/"Direita" no modelo5) é autoexplicativo para o
   operador? Talvez "Header"/"Sidebar" seja mais claro.
4. Deve ser permitido mais de um banner lateral ativo? Hoje sim, todos aparecem.
5. Os tamanhos 267x95 e 772x90 devem ser validados?
6. A tela de edição rápida de super banners (`super.blade.php`) deve ser recuperada
   (com os nomes de campo corrigidos) ou removida?

## 6. Mapa v5 → v6

| Aspecto | v5 | v6 | Impacto |
|---|---|---|---|
| Categorias `banners` / `super-banners` | Presentes | Presentes | Sem mudança |
| View `banners` | `2023_04_10_112025` + `2023_04_18_132413` | Idênticas | Sem mudança |
| View `super_banners` | `2023_04_10_132524` + **`2025_09_30_215142_update_view_to_super_banners.php`** | Só a `2023_04_10_132524`; a atualização virou seed (`v6/database/seeds/UpdateSuperBannersViewFixEmBaixo.php`) | **Divergência**: a v6 depende de executar o seed |
| `BannerServiceProvider` | Agrupa super banners por `order` e expõe `superBannersPosition1/2`; seleciona `acronym`; `whereHas('archiveHighlight')` | Sem agrupamento, sem `acronym`, sem filtro de imagem | **Regressão**: a v6 voltou a uma versão mais simples |
| `MenuServiceProvider` | `MenuOrder::orderBy(...)` sem `with('modulo')`; menu sem o gate `modulos.status` | `with('modulo')` + gate `modulos.status` | Mudança de arquitetura do menu |
| `ContentController` | Versão anterior do CRUD genérico | Versão nova: `display_type`, `custom_icon`, `description`, API de categorias, `setStatus` com a regra de ativação do super banner | Evolução do CMS |
| `CategoryContentController` | Versão anterior | Versão nova com `ApiStoreRequest`/`ApiUpdateRequest`/`ApiDestroyRequest` e `ShowResource` | Evolução do CMS |
| `DatatableController` | Versão anterior | Versão nova com `get_banners`/`get_super_banners` equivalentes | Sem mudança funcional |
| `banners/index.blade.php` | Versão anterior | Versão nova | Sem mudança funcional relevante |
| `super-banners/index.blade.php` | — | **Idêntico** (`diff` sem diferenças) | Sem mudança |
| `banners/form.blade.php` | Verificar | Inclui `components.inputs.select` com `objBanner($isModel5)` no super banner | Evolução no super banner |
| Tabela `modulos` | Não existe na v5 | `banners` (id 22, `status = 1`), `super-banners` (id 26) | Novo registry |
| `resources` | `banners` e `super-banners` | `banners` (25), `super-banners` (26), `modulo_id = 22` | Equivalente |

**Resumo do mapa**: o módulo de banners é estruturalmente o mesmo nas duas versões
(os dados vivem em `contents`/`category_contents`, com as mesmas views SQL). A v6
evoluiu o CMS genérico em volta (registry de módulos, API de categorias, novos campos
de categoria) e **perdeu** a agrupagem de super banners por posição que a v5 já tinha.
O único ponto que exige atenção na migração de ambientes é a **view `super_banners`**:
a v5 a atualiza por migration e a v6 por seed.

## 7. Checklist de correção rápida

- [ ] Alinhar os nomes de campo de `banners/super.blade.php` com `updateSuperBanner`
      (ou remover a tela)
- [ ] Tornar `updateSuperBanner` tolerante a menos de dois super banners
- [ ] Unificar o caminho de upload (`super-banners` × `super-banner`)
- [ ] Corrigir `returnData` de super banners para usar a categoria correta
- [ ] Trocar `Route::getCurrentRoute()->getName()` por uma regra de request
- [ ] Validar `link` em `super-banners`
- [ ] Unificar o limite de `title` (45 × 120)
- [ ] Portar a migration `2025_09_30_215142_update_view_to_super_banners.php` para a v6
- [ ] Recuperar o agrupamento por posição do `BannerServiceProvider` (v5)
- [ ] Mover as queries das views para composers/cached components
- [ ] Escrever testes (ver `07-TESTES.md`)

## 8. Verificação realizada

| Item | Resultado |
|---|---|
| `ls dossie_modules/banners/` | 9 arquivos presentes |
| Caminhos citados (`grep -ohE '(v5\|v6)/...'`) | 0 inexistentes |
| Marcadores de placeholder | 0 ocorrências |
| Dados no banco | 4 banners + 2 super banners ativos; view `super_banners` retornando `Em cima`/`Em baixo` (layout ≠ modelo5) |