# Temas e Cores — Resumo Executivo

> **Versão analisada:** `v6` (Laravel 5.5.50 / PHP 7.2.34 / PostgreSQL 10 + PostGIS)
> **Slug do módulo:** `temas-e-cores` (tabela `modulos`, id 2, nome "Temas e Cores", `status = 1`)
> **Natureza:** CMS (painel administrativo) + Portal (público)
> **Estado:** migrado v5 → v6 (com acréscimos no modelo 5 personalizável)

---

## 1. Objetivo

O módulo "Temas e Cores" é a tela de **identidade visual do portal municipal**: define o
*template* (modelo 1 a 6) que renderiza o portal público, as quatro cores institucionais
aplicadas via CSS, o plano de fundo do site e a skin (tema) do próprio CMS (AdminLTE).
Ele existe para que a prefeitura troque a identidade visual do portal sem deploy de código.
Serve ao operador do CMS (prefeitura) e, indiretamente, ao cidadão que navega pelo portal.

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Portal com template, cores e plano de fundo escolhido pela prefeitura; o conteúdo não muda, apenas a apresentação. |
| Prefeitura (CMS) | Uma tela (`/cms/configuracoes/editar/temas`) edita template, cores, plano de fundo e skin do CMS. |
| Transparência e legalidade | Troca de cores pode quebrar contraste (ex.: `cor_4` usado como fundo de datas em listagens). |
| Operação técnica | `cor_cms` é lido **a cada render** do AdminLTE (query por página); o template ativo é lido do banco em cada requisição do portal. |

## 3. Comportamento

- O módulo **não tem controller, model ou tabela própria**. Reaproveita
  `v6/app/Http/Controllers/Prefecture/ConfigurationController.php`, o model
  `App\Prefecture\Configuration` e a tabela `configurations`, filtrando pela categoria
  `category_configurations.slug = 'temas'` (9 configurações ativas).
- A leitura da tela exige a permissão `tema-do-portal.edit`; a gravação passa por
  `updateByCategory`, cuja guarda é `has_access(['configuracoes.edit'])` — **assimetria de
  permissão** (ver `08-GAPS-E-DIVIDAS.md`).
- O template ativo é a chave `layout` (`modelo1`..`modelo6`). Valor fora dessa lista é
  rejeitado com flash "Por favor, selecione um layout entre as opções exibidas.".
- As cores `cor_1`..`cor_4` são **texto livre** validadas apenas por `required|max:50|min:3`;
  não há validação de formato hex nem FK para uma tabela de cores.
- `cor_cms` escolhe uma skin do AdminLTE; a lista válida de skins existe **apenas** no array
  `$temas_lte` do controller.
- O modelo 5 (Personalizável) é a única parte com estrutura própria: tabela `layouts` +
  `v6/app/Http/Controllers/Prefecture/LayoutController.php`.

## 4. Como o Usuário Interage

| Passo | Tela / ação |
|---|---|
| 1 | Menu lateral do CMS → "Temas & Cores" (visível apenas se `has_access(['tema-do-portal.index'])` **e** `$modulos['temas-e-cores']`). |
| 2 | Grade com 6 miniaturas (`modelo1`..`modelo6`); clique abre modal de pré-visualização; o "check" verde marca o selecionado. O bloco só aparece com `has_access(['layouts'])`. |
| 3 | Botão de caneta no card do **Modelo 5** abre `/cms/editar/modelo-personalizavel` (exige `modelo-personalizavel.*`). |
| 4 | Campos: 4 seletores de cor (bootstrap-colorpicker), `<select>` de skin do CMS, upload de plano de fundo, checkboxes "Fixar"/"Repetir" plano de fundo. |
| 5 | "Salvar" → `POST /cms/update/configuration` → flash "Configurações salvas com sucesso". |
| 6 | Cidadão: recarrega o portal; o `<head>` recebe `:root { --cor-1..--cor-4 }` e o `<body>` recebe o `background-image`. |

## 5. Detalhes e Particularidades Técnicas

- `v6/app/Http/Controllers/Prefecture/ConfigurationController.php` — `editByCategory('temas')`
  (linhas ~484-491) monta `$temas_lte` (11 skins) e `$templatesPortal` (6 modelos).
- `v6/app/Http/Requests/ConfigurationRequest.php` — regras geradas **dinamicamente** a partir de
  `notnull`/`max_input`/`min_input` de cada chave; uma query ao banco **por campo enviado**.
- `v6/app/Http/Traits/GetInformationsPrefectureTrait.php` — `getConfiguration('temas')`.
- `v6/app/Http/Traits/FileTrait.php` — `getFileName()` gera nome do upload de plano de fundo.
- `v6/app/Helpers/functions.php:1130` — `getActualLayout()`.
- `v6/app/Http/Controllers/Admin/Controller.php:39` — `getTemplateActived()` (grava
  `pagina_em_manutencao = 1` e aborta 404 se a view do template não existir).
- `v6/app/Http/Controllers/Prefecture/LayoutController.php` — CRUD do modelo 5 (tabela `layouts`).
- Dependências: `intervention/image` (resize do plano de fundo), `bootstrap-colorpicker`
  (front), `tinycolor` (ajuste de contraste no JS do portal).

## 6. Estrutura de Dados

| Objeto | Descrição |
|---|---|
| `configurations` (categoria `temas`) | 9 chaves: `layout`, `cor_1`..`cor_4`, `cor_cms`, `background`, `background_fixed`, `background_repeat`. |
| `category_configurations` | Categoria `temas` (id 3, "Temas"). |
| `layouts` | 41 linhas: seções e elementos do modelo 5, `preview`/`tags` (HTML ~77 KB cada). **Sem relação com `configurations`.** |
| `view configuracoes` | View SQL que lista todas as configurações de todas as categorias (sem filtro). |
| Seed | `v6/database/seeds/ConfigurationsTableSeeder.php` (bloco "Temas e cores"), `v6/database/seeds/CategoryConfigurationsTableSeeder.php`. |

## 7. Como Testar

- Trocar o template e recarregar o portal → view `portal.layouts.{modelo}.home.index`.
- Alterar `cor_1` e verificar `--cor-1` no `<head>` e a cor de fundo dos títulos.
- `GET /getColors` deve devolver as 4 cores em JSON.
- Salvar com `layout` inválido → flash de erro e redirect back.
- No modelo 5: reordenar elementos e salvar → conferir `layouts.order`/`section`/`status`.

## 8. Migração para Laravel Moderno

Extrair `tema` para entidade própria (`themes`) com `slug`, `colors` (JSON), `cms_skin`,
`background_path`; manter a resolução do template ativo em um `Setting`/`Theme` singleton
cacheado; tipar as cores com um value object validado por regex hex; criar `ThemeController`
do CMS e `ThemeResource` para o portal; mover a lista de skins para um enum.

## 9. Resumo Geral

Temas e Cores é um módulo de configuração visual sem código próprio: ele grava 9 linhas na
tabela `configurations` (categoria `temas`) e o portal as consome em cada renderização.
Duas dessas linhas — `layout` e `cor_cms` — são estruturais (template e skin do CMS) e as
outras sete são de aparência (4 cores, 1 imagem de fundo, 2 flags do fundo). A troca do
template reescreve a home do portal, o número de notícias exibido, as classes CSS dos cards
e a quantidade de slides. O Modelo 5 (Personalizável) é a exceção: tem estrutura de dados
própria (`layouts`), controller próprio (`LayoutController`) epermite reordenação de blocos via
AJAX. Na reconstrução, o essencial é separar "configuração de aparência" (dados) de
"apresentação" (views), tipar as cores e cachear a resolução do template ativo.

---

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