# Requerimento de Diárias — Resumo Executivo

> **Versão analisada:** `v6` (o módulo existe e é **idêntico** na `v5`)
> **Slug do módulo:** `requerimento-de-diarias` (tabela `modulos`, id **36**, `status = false`)
> **Natureza:** Ambos (CMS administrativo + Portal público)
> **Estado:** OK v6 — sem divergência funcional em relação à v5

---

## 1. Objetivo

O módulo **Requerimento de Diárias** formaliza e publica os pedidos de diárias
de viagem dos servidores públicos municipais. No CMS o operador cadastra cada
requerimento (servidor, destino, datas, quantidade e valor das diárias,
fundamentação legal) e anexa a lei/regulamentação que fundamenta o pedido; no
Portal o cidadão consulta publicamente esses pedidos, filtra por CPF, nome,
número da diária e período, e visualiza o requerimento em PDF.

Atende ao servidor público que se desloca em viagem e ao cidadão que exerce o
controle social sobre a despesa com diárias.

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Consulta pública de requerimentos de diárias, com dados sensíveis mascarados (CPF/RG) no PDF do portal |
| Prefeitura (CMS) | Registro padronizado das diárias, com numeração sequencial sugerida e arquivo de lei padrão reutilizável |
| Transparência e legalidade | Publicação do PDF do requerimento no Portal, expondo nome, cargo, secretaria, banco, agência e conta do servidor (ver `08-GAPS-E-DIVIDAS.md`) |
| Operação técnica | Módulo isolado: 2 tabelas próprias, 1 view SQL (`req_diarias`) e 1 arquivo anexado |

## 3. Comportamento

- **Numeração:** ao abrir o formulário de cadastro, o CMS sugere
  `max(codigo_diarias) + 1` (`RequerimentoDiariasController@create`).
- **Código é inteiro:** a coluna `codigo_diarias` foi convertida de `varchar`
  para `int` em `2023_01_30_093017_alter_codigo_diarias_to_requerimento_diarias.php`.
- **Datas:** `data_saida` e `data_entrada` são gravadas como `date`; o
  repositório normaliza `dd/mm/aaaa` → `Y-m-d` via `str_replace('/', '-')` +
  `strtotime`.
- **Arquivo padrão:** em Configurações de Requerimento o operador informa a
  "Lei padrão" (texto) e anexa um arquivo (`pdf|doc|docx`). O arquivo fica
  gravado em `storage/app/public/leis_de_requerimentos/`.
- **Reuso da lei padrão:** no cadastro, o checkbox "Usar Arquivo de Lei Padrão"
  cria, para o requerimento, um registro em `archives` apontando para o mesmo
  arquivo de configuração.
- **PDF:** `RequerimentoRepository@generatePDF` monta um PDF com DomPDF
  (`barryvdh/laravel-dompdf`) a partir de
  `prefecture.contents.requerimento-diarias.pdf.index`. No CMS os dados são
  completos; no Portal (`$hiddendados = true`) CPF e identidade são mascarados.
- **Filtros do Portal:** CPF, nome do requerente, nº da diária, data de saída
  (>=) e "data de retorno" (<=) — o filtro de retorno compara contra
  `data_saida`, não contra `data_entrada` (ver `05-REGRAS-E-PORTABILIDADE.md`).
- **Paginação:** 10 registros por página no Portal.
- **Exclusão em lote:** checkbox master + `POST requerimento-diarias/destroyAll`
  (`toDelete[]`), com confirmação via SweetAlert.

## 4. Como o Usuário Interage

**Operador (CMS, `/cms/requerimento-diarias`)**

| Tela | Endereço | Ações |
|---|---|---|
| Listagem | `/cms/requerimento-diarias` | DataTable (Yajra) com colunas Número, Requerente, Objetivo, Fundamentos; botões Editar/Excluir/Download; exclusão em lote; botões "Configurações" e "Cadastrar" |
| Cadastro/Edição | `/cms/requerimento-diarias/create` · `/cms/requerimento-diarias/{id}/edit` | Formulário único (create/edit), upload de arquivo, checkbox de lei padrão |
| Configurações | `/requerimento-diarias/configuracoes` | Lei padrão + arquivo da lei; botão excluir arquivo |
| Preview do PDF | `/cms/requerimento-diarias/{id}` | PDF do requerimento completo (sem máscara) |

**Cidadão (Portal, `/requerimento-de-diarias`)**

- Formulário de filtros (CPF com máscara `000.000.000-00`, data de saída, data
  de retorno, nº da diária, nome do requerente) + botão "Limpar campos".
- Tabela com nº da diária, nome, RG (mascarado no HTML) e CPF (mascarado no
  HTML).
- Dois ícones por linha: "Visualizar Regulamentação" (abre o PDF da lei) e
  "Visualizar Requerimento" (abre o PDF do requerimento em nova aba).
- Paginação e breadcrumb "Home > Requerimento Diárias".

## 5. Detalhes e Particularidades Técnicas

- Camadas: `Route` → `Controller` → `FormRequest` → `Repository` → `Model` → `DB`.
- O CMS usa `Prefecture\RequerimentoDiariasController`; o Portal usa
  `Portal\BuscaDiariasController`. Os dois compartilham
  `RequerimentoRepository`.
- A listagem do CMS **não** consulta a tabela: ela lê a view SQL `req_diarias`
  (`DB::table('req_diarias')`), que já faz o `JOIN` com `servidor` e filtra
  `deleted_at IS NULL`.
- O Portal **não** usa a view: consulta `RequerimentoDiarias` via Eloquent com
  `with('servidor','archives')`.
- Busca textual com `whereRaw` + `translate()`/`ilike` (SQL montado por
  concatenação de string).
- Dependências: `barryvdh/laravel-dompdf` (alias global `PDF`), `yajra/laravel-datatables`,
  `cartalyst/sentinel`, `laravelcollective/html`.

## 6. Estrutura de Dados

| Objeto | Tipo | Papel |
|---|---|---|
| `requerimento_diarias` | tabela | Requerimentos de diárias (soft delete) |
| `requerimento_diarias_configs` | tabela | Configuração singleton (lei padrão + arquivo) |
| `archives` | tabela (compartilhada) | Arquivo anexado, ligado por `requerimento_id` |
| `servidor` | tabela (compartilhada) | Servidor requerente |
| `states` | tabela (compartilhada) | UF de destino |
| `req_diarias` | view SQL | Projeção para o DataTable do CMS |
| `requerimentos` | view SQL | **Não pertence a este módulo** — ver `02-MODELAGEM.md` |

## 7. Como Testar

1. CMS: cadastrar um requerimento com arquivo; conferir listagem, edição e PDF.
2. CMS: marcar "Usar Arquivo de Lei Padrão"; conferir que a lei aparece no Portal.
3. Portal: filtrar por CPF, nome, nº de diária e período; conferir paginação.
4. Portal: abrir o PDF e conferir o mascaramento de CPF/identidade.
5. Exclusão em lote e exclusão de arquivo padrão.

Detalhe em `07-TESTES.md`.

## 8. Migração para Laravel Moderno

- `FormRequest` único com `Rule::exists` para `id_servidor`/`estado_destino`.
- `casts` de data em `RequerimentoDiarias` (`data_saida`, `data_entrada` como
  `immutable_date`).
- Eliminar a view SQL `req_diarias` (substituir por `JOIN`/eager loading) e a
  view `requerimentos` (substituir por query builder sobre `contents`).
- Remover `whereRaw` com concatenação → `whereRaw` com bindings ou
  `ilike` parametrizado.
- API Resources (`RequerimentoDiariasResource`) + endpoints JSON paginados.
- Storage via `Storage::disk('public')->putFileAs()` e `assert` de MIME.

## 9. Resumo Geral

O módulo Requerimento de Diárias é o cadastro e a vitrine pública dos pedidos
de diárias de viagem dos servidores. No CMS, o operador cria requerimentos
numerados sequencialmente, anexa a lei que os fundamenta (ou reutiliza a lei
padrão configurada no módulo) e gera um PDF institucional. No Portal, o
cidadão filtra os requerimentos por CPF, nome, número e período, e abre o PDF
com CPF e identidade mascarados. Os dados vivem em `requerimento_diarias` e
`requerimento_diarias_configs`, com arquivos em `archives`; o CMS lista através
da view SQL `req_diarias`. O código é praticamente idêntico entre `v5` e `v6`:
a v6 apenas introduuiu a tabela `modulos` (id 36) e reescreveu as views SQL
`requerimentos` — que pertencem a outro módulo. O principal passivo do legado
é a busca textual montada por concatenação de strings e a existence de colunas
inexistentes (`padrao_arquivo_config`) em trechos do controller.

---

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