# Estagiários — Resumo Executivo

> **Versão analisada:** `v5` (o módulo **não existe** na `v6`)
> **Slug do módulo:** `estagiario` (tabela `resources`, id 15) — singular, apesar do nome das rotas
> **Natureza:** Ambos (CMS administrativo + Portal público)
> **Estado:** apenas v5 — funcionalidade removida na v6

---

## 1. Objetivo

O módulo **Estagiários** publica e administra a relação de estagiários
contratados pela Prefeitura: nome, período do contrato (início/fim), lotação
(secretaria ou órgão) e situação (Ativo, Encerrado, Rescindido). Ele atende a
duas audiências com objetivos distintos: o **operador do CMS**, que cadastra,
edita, exclui e anexa documentos (PDFs) de cada estagiário; e o **cidadão**,
que consulta a relação no portal, filtra por nome/lotação/situação, abre a ficha
individual e exporta o resultado em XLSX, PDF, CSV ou TXT.

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Passa a ver a lista de estagiários, o período do contrato e a lotação de cada um, e pode baixar os documentos anexados. Nome e lotação são dados pessoais expostos publicamente, sem aviso de privacidade na tela. |
| Prefeitura (CMS) | Centraliza o cadastro em uma tabela com soft delete, upload de PDFs e listagem em DataTable com permissões por recurso. |
| Transparência e legalidade | Serve de evidência de ocupação de vagas de estágio e de uso de mão de obra temporária pelo município. A remoção do módulo na v6 significa que a prefeitura deixou de publicar esse registro. |
| Operação técnica | Exige `resources.slug = 'estagiario'` e um item em `menu_orders` para o menu do AdminLTE; sem permissão Sentinel correspondente, apenas `super-admin` enxerga a funcionalidade. |

## 3. Comportamento

- O cadastro é **obrigatório** em `nome`, `periodo_inicio`, `periodo_fim`,
  `lotacao` e `situacao`; os arquivos são opcionais, mas quando enviados devem
  ser PDF de até 20 MB (`v5/app/Http/Requests/EstagiarioRequest.php`).
- A `situacao` é string livre no banco (`varchar(50)`, default `'Ativo'`), mas o
  formulário só oferece `Ativo`, `Encerrado` e `Rescindido`.
- A `lotacao` guarda o **título** da secretaria (texto), não o id — a lista de
  secretarias vem da view `secretarias`, derivada de `contents`.
- O `slug` é gerado no `boot()` do model como `str_slug(nome-id)` e é
  recalculado a cada `update`.
- Arquivos enviados são gravados em `storage/app/public/docs`; o campo `arquivo`
  guarda um **JSON** com a lista `{path, description}`.
- A listagem pública pagina em 15 registros e aceita os filtros `busca`
  (nome), `lotacao` e `situacao`.
- A exportação respeita os filtros aplicados, mas **ignora a paginação**:
  exporta todos os registros que casam com o filtro.
- A exclusão no CMS é **soft delete** (coluna `deleted_at`); a view
  `estagiarios_view` já filtra `deleted_at IS NULL`.

## 4. Como o Usuário Interage

**Operador (CMS, `/cms/estagiarios`)**

1. Menu lateral "Estagiários" (AdminLTE, ícone `id-card-o`), visível apenas
   para quem tem `estagiario.index`.
2. Listagem em DataTable server-side (`/cms/datatable/estagiario`) com colunas
   ID, Nome, Período Início, Período Fim, Lotação, Situação e Ações; botões de
   Excel/PDF/CSV/TXT do próprio DataTable.
3. Botão "Cadastrar" (visível com `estagiario.create`) abre o formulário com
   máscara de data `dd/mm/aaaa`, select de lotação e de situação e um
   construtor dinâmico de linhas de arquivo (input file + descrição).
4. Ao editar, os arquivos já enviados aparecem com download/visualização e botão
   de remoção via `DELETE /cms/estagiarios/{id}/arquivo/{index}`.

**Cidadão (portal, `/estagiarios`)**

1. Formulário de filtros (busca por nome, secretaria/órgão, situação) com botões
   "Limpar campos" e "Consultar".
2. Tabela paginada (componente compartilhado
   `portal/components/estagiarios/table.blade.php`) com link "Detalhes" para a
   ficha individual `/estagiario/{slug}`.
3. Botões "Salvar como: xls | pdf | csv | txt" que reenviam a requisição ao
   controller com o parâmetro `type`.

## 5. Detalhes e Particularidades Técnicas

- **Camadas:** `Route` → middleware (`check.logged` na rota + `check.route.permission`
  no construtor do controller) → `Prefecture\EstagiarioController` /
  `Portal\EstagiariosController` → `EstagiarioRequest` → model `Estagiario`
  (Eloquent + SoftDeletes) → tabela `estagiarios` / view `estagiarios_view`.
- **Sem repositório/serviço:** o módulo usa o model Eloquent direto nos
  controllers (padrão do legado).
- **Dependências:** `secretarias` (view sobre `contents`), `menu_orders`,
  `resources`, permissões Sentinel (`cartalyst/sentinel`), `FileTrait`
  (upload), `laracasts/flash` + `laralabs/toaster` (mensagens),
  `maatwebsite/excel` (XLSX/CSV), `barryvdh/laravel-dompdf` (PDF),
  `yajra/laravel-datatables` (JSON do DataTable).
- **Armadilhas confirmadas:** SQL concatenado no filtro de busca
  (`whereRaw` com `translate(...)`), IDs relativos montados por JS na listagem,
  rota `datatable.*` liberada para qualquer usuário logado, `store`/`update`/
  `destroy` sem verificação granular de permissão, coluna `value` da view que
  não é o `id` real, datas inválidas virando `1970-01-01` e ausência de trilha
  de auditoria (`activity()` não é usado no módulo).

## 6. Estrutura de Dados

| Objeto | Tipo | Observação |
|---|---|---|
| `estagiarios` | tabela | 11 colunas, `softDeletes`, `slug` unique |
| `estagiarios_view` | view SQL | `row_number()` + colunas da tabela, filtra `deleted_at IS NULL` |
| `resources` (id 15) | registro | slug `estagiario`, name `Estagiários` |
| `menu_orders` (id 35) | registro | slug `estagiario`, `clicks` = 0 |
| `secretarias` | view | fonte da lista de lotações (13 secretarias) |

Sem seeds e sem factories para `estagiarios` na v5.

## 7. Como Testar

- Criar estagiário no CMS com e sem PDF; conferir a listagem e a ficha pública.
- Filtrar no portal por nome (com acento), lotação e situação; validar a
  exportação nos quatro formatos.
- Excluir um registro e confirmar que ele some da listagem (soft delete) e que
  a view `estagiarios_view` não o retorna.
- Validar a ausência do módulo na v6 (nenhuma rota, controller ou resource).

## 8. Migração para Laravel Moderno

Reconstruir com migration equivalente (`estagiarios` + view de leitura), model
`Estagiario` com `casts` de data e `HasFactory`, rotas de API restritas e
`Policy` por status do estagiário; trocar o `whereRaw` por busca parametrizada
com índice funcional; mover o JSON de arquivos para a tabela
`estagiario_arquivos` (relacionamento 1:N) e para disco privado quando houver
dado pessoal; expor o portal como resource JSON paginado e manter o `slug`
estável. Detalhes em `06-MIGRACAO-MODERNA.md`.

## 9. Resumo Geral

Estagiários é um módulo pequeno e autocontido que existe **apenas na v5**. Ele
cadastra, na tabela `estagiarios`, o nome do estagiário, o período do contrato,
a lotação (texto da secretaria), a situação e uma lista de PDFs em JSON; expõe
esses dados em dois lugares — uma listagem DataTable no CMS (`/cms/estagiarios`)
e uma página pública com filtros e exportações (`/estagiarios`). A leitura do
CMS passa pela view `estagiarios_view`, alimentada pela migration
`2026_05_26_200001`; o menu do AdminLTE e a permissão `resources.id = 15`
(`estagiario`) vêm da migration `2026_05_26_200002`. A v6 removeu o módulo
inteiro: não há controller, model, request, export, view, rota, view SQL nem
resource com o slug `estagiario`. Ao reconstruir, é preciso preservar o
comportamento observável (filtros, quatro formatos de exportação, anexos
publicamente baixáveis) e corrigir as armadilhas do legado: SQL concatenado na
busca, ausência de auditoria, permissões de escrita liberadas, "ID" exibido que
não é o `id` real e exposição de dados pessoais sem base legal declarada.

---

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