# Feriados Municipais — Resumo Executivo

> **Versão analisada:** `v6` (módulo **idêntico** na `v5`, exceto o bloco de seed removido da migration)
> **Slug do módulo:** `feriados-municipais` (tabela `modulos`, id 51)
> **Natureza:** Ambos (CMS em `/cms` + Portal público)
> **Estado:** migrado v5 → v6 sem alteração de código (módulo já existia na v5)

---

## 1. Objetivo

O módulo mantém a **lista oficial de feriados municipais** do município — a data,
a descrição e o ícone (classe de Font Awesome) de cada feriado. O servidor da
prefeitura cadastra e edita esses registros no painel administrativo; o cidadão
consulta a página pública `/feriados-municipais`, que exibe os feriados do **ano
corrente** agrupados por mês em um acordeão, com o dia dentro de um selo
circular e o ícone ao lado.

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Consulta rápida dos feriados do ano, com data e descrição, agrupados mês a mês. |
| Prefeitura (CMS) | Cadastro, edição, exclusão individual e em lote dos feriados; listagem DataTable com exportação. |
| Transparência e legalidade | Mantém o calendário oficial de feriados em um único lugar, publicado no portal. |
| Operação técnica | Tabela simples (`feriados_municipais`) com soft delete, mais uma view SQL usada pelo DataTable do CMS. |

## 3. Comportamento

- O portal **só mostra o ano corrente**: `whereYear('date', date('Y'))`.
- Os registros são agrupados por mês (`mês` com dois dígitos, "01" a "12") e
  ordenados por data dentro do mês.
- Cada feriado exibe: **ícone**, **dia** (em selo circular) e **descrição**.
- O CMS exige, no formulário: `icon` (3 a 60 caracteres), `description`
  (obrigatório, máx. 200) e `date` (obrigatório).
- A data é enviada como `dd/mm/aaaa` e convertida para `Y-m-d` pelo repositório
  antes de gravar.
- A listagem do CMS usa a **view SQL `lista_feriados_municipais`**, que expõe
  `value`, `data` (texto `DD/MM/YYYY`), `descricao` e `id`.
- Exclusão é **lógica** (`SoftDeletes`); a view SQL filtra `deleted_at IS NULL`.
- O item de menu no CMS só aparece se `modulos.status = true` (nascimento:
  `status = 0`).

## 4. Como o Usuário Interage

**Cidadão (portal)**

1. Acessa `/feriados-municipais`.
2. Vê o cabeçalho "Feriados Municipais - {ano}" e um acordeão com um cartão
   por mês.
3. Cada cartão lista os feriados do mês: ícone + dia em selo + descrição.

**Operador (CMS)**

1. `/cms/feriados-municipais` → DataTable com colunas ID, Data, Descrição e Ações.
2. "Cadastrar Feriados Municipais" → formulário com Data do feriado (máscara
   `br-data`), Ícone (padrão `fab fa-500px`) e Descrição.
3. Edição via botão de pencil; exclusão individual via lixeira (DELETE ajax);
   exclusão em lote pelo botão "Excluir Registro(s)".

## 5. Detalhes e Particularidades Técnicas

- **Camadas (CMS):** `routes/basepro.php` → `Prefecture\FeriadosMunicipaisController`
  → `FeriadosMunicipaisRequest` → `FeriadosMunicipaisRepository` →
  `App\Http\Model\Prefecture\FeriadosMunicipais` → `feriados_municipais`.
- **Camadas (portal):** `routes/web.php` → `Portal\FeriadosMunicipaisController`
  → model `FeriadosMunicipais` → view `portal.layouts.{layout}.feriados-municipais.index`.
- **Camadas (DataTable):** `DatatableController@get_feriados` →
  `DB::table('lista_feriados_municipais')`.
- **Sem API Resource, sem Policy** — a autorização é feita pelo middleware
  textual `check.route.permission` e por `has_access()` nos Blade.
- **Sem cache, sem fila, sem storage**.

## 6. Estrutura de Dados

| Objeto | Tipo | Papel |
|---|---|---|
| `feriados_municipais` | tabela | Feriados (data, descrição, ícone) |
| `lista_feriados_municipais` | view SQL | Listagem plana consumida pelo DataTable do CMS |
| `modulos` | tabela | Registro do módulo (id 51) e seu `status` |
| `menu_orders` | tabela | Slug `feriados-municipais` → `modulo_id = 51`, contador `clicks` |
| `resources` | tabela | Permissões (`resources.modulo_id = 51`) |

## 7. Como Testar

- Portal: cadastrar um feriado no ano corrente → aparece no cartão do mês
  correspondente; feriado de outro ano **não** aparece.
- CMS: criar com data `25/12/2026` → gravada como `2026-12-25`; ícone com 2
  caracteres é recusado; descrição com 201 caracteres é recusada.
- Exclusão em lote: selecionar duas linhas → ambas com `deleted_at` preenchido
  e somem da view SQL.
- Permissões: usuário sem `feriados-municipais.create` não vê o botão de
  cadastro.

## 8. Migração para Laravel Moderno

Manter a tabela `feriados_municipais` (é simples e estável), mas: criar
`FeriadoMunicipal` com `$casts` (`date` → `date`), um `FormRequest` com
`Rule::date()` e validação de `icon` contra a lista de ícones permitidos,
`Policy` no lugar do middleware textual, `API Resource` para o portal (hoje a
página é renderizada no servidor), Livewire/Alpine para o acordeão, e
`paginate()` no lugar do `get()->groupBy()` (que carrega todos os registros do
ano em memória).

## 9. Resumo Geral

Feriados Municipais é um dos módulos mais simples da plataforma: uma tabela com
três campos úteis (`date`, `description`, `icon`), um CRUD no CMS com soft
delete, e uma página pública que agrupa os feriados do **ano corrente** por
mês em um acordeão. O código do módulo é **byte a byte idêntico entre a v5 e
a v6** — a única diferença é que a migration da v5 semeava também
`resources`, `menu_orders`, `links` e `menu_items`, blocos removidos na v6 em
favor do registro na tabela `modulos` (id 51). Os problemas a corrigir na v7
são: `dd()` dentro do `catch` do `upInsert` (vaza stack trace em produção),
`destroyAll` que sempre reporta sucesso, o botão "Voltar" apontando para
`/cms/servidor`, o script `deleteAll.js` carregado com capitalização errada
(404 em Linux) e a referência a um CSS inexistente no `modelo6`.

---

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