# Secretarias — Resumo Executivo

> **Versão analisada:** `v6` (Laravel 5.5.50 / PHP 7.2.34) com comparação `v5`
> **Slug do módulo:** `secretarias` (tabela `modulos`, id = 18) — `status = false` no banco
> **Categoria de conteúdo:** `category_contents` id = 7, `name = "Secretarias"`, `slug = secretarias`, `category_contents_id = NULL`
> **Natureza:** Ambos (CMS `/cms/...` + Portal público `/a-instituicao/...` + API `/api/v1/...`)
> **Estado:** migrado v5 -> v6 com regressões de rota (ver `08-GAPS-E-DIVIDAS.md`)

---

## 1. Objetivo

O módulo **Secretarias** organiza o organograma municipal em duas camadas: as
**secretarias** (conteúdos da categoria `secretarias`, ex.: "Secretaria de Saúde")
e, dentro de cada secretaria, os **departamentos** (`categorias_secretarias`) e as
suas **páginas institucionais** (`paginas_secretarias`, com texto, imagem de
destaque e arquivos para download).

Serve ao **cidadão**, que consulta a página de uma secretaria no portal
(`/a-instituicao/secretarias/{slug}`) e navega por um menu em acordeão com
departamentos e páginas; e ao **operador do CMS**, que cadastra secretarias,
monta o menu de cada uma e vincula notícias a elas.

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Página institucional por secretaria com destaque, texto, vídeo, galeria e bloco "Notícias de {secretaria}"; subpáginas de departamento com arquivos para download. |
| Prefeitura (CMS) | CRUD de secretarias (via `ContentController` genérico), CRUD de departamentos e páginas, ordenação do menu por drag-and-drop (`Sortable`), vínculo notícia ↔ secretaria. |
| Transparência e legalidade | Contatos, competências e documentos de cada secretaria ficam públicos; a API `/api/v1/secretarias` publica título, descrição, slug, interações e arquivos. |
| Operação técnica | O módulo está **desabilitado** (`modulos.status = false`): o menu lateral do CMS não exibe "Secretarias" e o select "Secretaria" do formulário de notícias não aparece. |

## 3. Comportamento

- Uma **secretaria** é um registro de `contents` com `category_contents_id = 7`;
  ganha `slug` automático (`Str::slug` do título) com desempate `-<maxid+1>`.
- O **departamento** (`categorias_secretarias`) pertence a uma secretaria
  (`secretarias_id` → `contents.id`) e agrupa **páginas** (`paginas_secretarias.categoria_id`).
- A **página** tem título, texto HTML (Summernote), imagem de destaque e N arquivos;
  cada upload gera linha em `archives` (`reference_id` = id da página, `highlight` true/false)
  e grava o arquivo em `storage/app/public/content/secretarias_paginas/<id>/{destaque,arquivos}`.
- A **ordenação** do menu (coluna `order` de `categorias_secretarias`) é reescrita de
  1..N a cada drag-and-drop (`POST /cms/order_categorias/secretarias`).
- O portal exibe o menu **inline** (sem `pub-nav`, ao contrário de `publicacoes`,
  `atas-e-pontos`, `comite-de-investimentos` e `requerimentos`): cada secretaria tem
  sua própria navegação em acordeão dentro de `portal/components/secretarias/show.blade.php`.
- O bloco **"Notícias de {título}"** lista os conteúdos cujo campo `contents.secretaria`
  (string) é igual ao `slug` da secretaria; o corte para 12 itens é feito **em Blade**
  (`->sortByDesc('created_at')->splice(0, 12)`), sem limite no SQL.
- O módulo está **desligado no banco** (`modulos.status = false`), logo: o operador
  não vê a entrada "Secretarias" no menu do CMS, o select "Secretaria" do formulário
  de notícias fica oculto, `contents.secretaria` está 100% NULL e o bloco de notícias
  do portal sai vazio. As tabelas `categorias_secretarias` e `paginas_secretarias`
  também estão **vazias** (0 linhas).

## 4. Como o Usuário Interage

**Operador (CMS, AdminLTE 1.22 / Bootstrap 3)**

| Tela | Rota | Ação principal |
|---|---|---|
| Lista de Secretarias | `GET /cms/conteudos/secretarias` | Grade DataTable (Yajra) com colunas ID/Título/Ações |
| Formulário de secretaria | `GET /cms/conteudos/cadastrar/secretarias` | Título, Sigla (`contents.acronym`), Link Permanente, texto Summernote, vídeo YouTube, destaque com tamanho, galeria |
| Menus da secretaria | `GET /cms/conteudo/secretarias/menus/{id}` | Criar departamento, criar página, arrastar para reordenar |
| Departamentos | `GET /cms/conteudo/secretarias/secretarias-categorias` | Grade com nome, secretaria e ações |
| Páginas de secretaria | `GET /cms/conteudo/secretarias/secretarias-paginas` | Grade com título, departamento e secretaria |

Ações da grade de secretarias: "Acessar secretaria" (abre `/a-instituicao/secretarias/{slug}`
em nova aba), galeria, "Menus das secretarias" (abre `/cms/conteudo/secretarias/menus/{id}`),
editar e excluir. Exportações **Excel** e **PDF** do cliente DataTable
(`v6/public/assets/js/custom/utilities/table.js`).

**Cidadão (portal, Bootstrap 4)**

- `/a-instituicao/secretarias/{slug}`: menu lateral de departamentos (acordeão) +
  agenda de eventos da secretaria + destaque + texto + galeria + vídeo + notícias.
- `/a-instituicao/secretarias/paginas/{slug}/{id}`: menu lateral + conteúdo da página +
  "Arquivos para Download".

## 5. Detalhes e Particularidades Técnicas

- Camadas: `Route` → `Middleware check.route.permission` → `Controller` →
  `FormRequest` → `Repository` (contrato vazio) → `Model` → `DB`.
- O CRUD de secretarias **não tem controller próprio**: é o `ContentController` genérico
  (`v6/app/Http/Controllers/Prefecture/ContentController.php:96` e `:168`), que mapeia
  o slug `secretarias` para a view `prefecture.contents.secretarias.*`.
- As subfuncionalidades (departamentos, páginas, menu) têm controllers próprios:
  `CategorySecretaryController`, `PagesSecretaryController`, `MenuSecretaryController`.
- Os contratos `ICategorySecretaryRepository` e `IPagesSecretaryRepository` são
  **interfaces vazias** — a API real vem da classe base abstrata `App\Repositories\Repository`.
- As listagens do CMS usam **views SQL** (`secretarias`, `secretarias_categorias`,
  `secretarias_paginas`) carregadas com `DB::table(...)->get()` — sem `LIMIT` no SQL.
- Dependências: `yajra/laravel-datatables-oracle` (grades), `cartalyst/sentinel` (permissões),
  `laravelcollective/html` (helper `Form::`), `intervention/image` (compressão de imagens
  via `FileTrait::saveUpload`).

## 6. Estrutura de Dados

| Objeto | Tipo | Observação |
|---|---|---|
| `contents` (cat. 7) | tabela | 13 secretarias cadastradas; colunas usadas: `id`, `title`, `slug`, `acronym`, `text`, `galery`, `category_contents_id`, `secretaria`, `clicks`, `publication_date` |
| `contents.secretaria` | coluna `text` (string) | slug da secretaria dona da notícia; **100% NULL** no banco |
| `categorias_secretarias` | tabela | `id`, `name`, `secretarias_id` (FK `contents.id`), `order`, soft delete; **0 linhas** |
| `paginas_secretarias` | tabela | `id`, `title`, `text`, `categoria_id` (FK), `order`, soft delete; **0 linhas** |
| `archives` | tabela (compartilhada) | `reference_id` = `paginas_secretarias.id`; `highlight` true = imagem de destaque |
| `secretarias` | view SQL | `value`, `titulo`, `id`, `galeria`, `slug` |
| `secretarias_categorias` | view SQL | `value`, `name`, `id`, `nome_secretaria` |
| `secretarias_paginas` | view SQL | `value`, `title`, `texto`, `categoria`, `id`, `nome_secretaria` |
| `modulos` | tabela | id 18 = `secretarias`, `status = false` |
| `resources` | tabela | ids 15/16/17 = `secretarias`, `secretarias-categorias`, `secretarias-paginas`, `modulo_id = 18` |
| `menu_items` | tabela | id 15 (agrupador "Secretarias"), ids 18–29 (12 secretarias em `menus_id = 1`), ids 81–92 (mesmas em `menus_id = 2`) |

Detalhamento em `02-MODELAGEM.md`.

## 7. Como Testar

| Cenário | Como verificar |
|---|---|
| Página da secretaria no portal | `GET /a-instituicao/secretarias/saude` → 200, título e bloco "Notícias de Secretaria da Saúde" |
| Subpágina | `GET /a-instituicao/secretarias/paginas/saude/1` (exige página cadastrada) |
| CRUD de departamento | `POST /cms/conteudo/secretarias/secretarias-categorias` com `name` + `secretarias_id` |
| CRUD de página | `POST /cms/conteudo/secretarias/secretarias-paginas` com `title`, `categoria_id`, `text` |
| Reordenação | `POST /cms/order_categorias/secretarias` com `ids[]` |
| Grades do CMS | `GET /cms/datatable/secretarias`, `/cms/datatable/secretarias_categorias`, `/cms/datatable/secretarias_paginas` |
| API | `GET /api/v1/secretarias` → JSON com `data[]` |

Plano detalhado em `07-TESTES.md`.

## 8. Migração para Laravel Moderno

Reconstruir com: `Secretaria` (model, `category_contents_id = 7`), `Department`
(`SecretariaDepartment`), `DepartmentPage`, Policies por `resource` + `action`
(o middleware `check.route.permission` deve virar Policy), Resources de API,
`paginate()` em todas as grades (eliminar `DB::table(...)->get()`), ordenação por
`order` explícita em índice, e o menu de departamentos como componente Blade único
(`<x-secretaria-menu>`). Detalhes em `06-MIGRACAO-MODERNA.md`.

## 9. Resumo Geral

O módulo Secretarias é um organograma em duas camadas: secretarias (conteúdos da
categoria 7) e, dentro delas, departamentos e páginas institucionais com anexos.
O CRUD de secretarias é reaproveitado do `ContentController` genérico; departamentos,
páginas e a ordenação do menu têm controllers e repositórios próprios, com contratos
de repositório vazios herdando de `App\Repositories\Repository`. O portal exibe um menu
inline em acordeão (não existe `pub-nav` para este módulo) e a listagem de notícias da
secretaria, que é paginada na view do layout mas recortada em memória na view da
secretaria. O módulo está desabilitado no banco (`modulos.status = false`): o menu do
CMS não o exibe, o select "Secretaria" do formulário de notícias some e
`contents.secretaria` fica NULL, o que esvazia o bloco de notícias do portal; as tabelas
de departamentos e páginas também nunca foram populadas. Há bugs abertos: a rota
`a-instituicao-secretarias.index` não existe na v6 (erro 500 em `/portal/secretarias/...`),
o nome `a-instituicao.index` está duplicado em `v6/routes/web.php:79-80`, o `whereRaw`
da API é descartado sem reatribuição, e `PaginasSecretaria::categoria()` concatena
`'teste'` no id da relaçã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 |