# Relatório Estatístico da Ouvidoria — Resumo Executivo

> **Versão analisada:** `v5` (Laravel 5.5 / PHP 7.2) — módulo **existente apenas na v5**
> **Slug do módulo:** `relatorio-estatistico-ouvidoria` (não existe linha correspondente em `resources.modulo_id` da v6)
> **Natureza:** CMS (painel administrativo) + Portal (público)
> **Estado:** apenas v5 — a v6 mantém **apenas a face pública**, com implementação diferente e sem o cadastro de relatórios PDF

---

## 1. Objetivo

Publicar, no portal público da prefeitura, o **relatório estatístico da Ouvidoria**: a
quantidade de manifestações recebidas, o prazo de atendimento (dentro/fora do prazo), a
distribuição por tipo de manifestação, por assunto e por gênero do solicitante, além da
**listagem completa das solicitações** com dados mascarados (protocolo e nome).

Paralelamente, o CMS oferece o **cadastro dos relatórios oficiais em PDF** por ano de
gestão (ano, descrição e arquivo). Esses relatórios são exibidos no topo da mesma página
pública, como uma tabela "Ano / Descrição / Documento" com link de leitura e download do PDF.

O módulo serve à **Ouvidoria municipal** (transparência ativa e Art. 30, III, da Lei
12.527/2011) e ao **cidadão**, que pode consultar, filtrar por ano e exportar a listagem.

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Consulta o volume de manifestações e o desempenho do atendimento da Ouvidoria por ano; exporta a listagem em XLSX, CSV, PDF ou TXT; abre o PDF oficial do relatório de cada ano de gestão. |
| Prefeitura (CMS) | Operador mantém o cadastro anual dos relatórios em PDF (upload de arquivo, até 20 MB, PDF) e a listagem de documentos no DataTable do CMS. |
| Transparência e legalidade | Publica métricas de atendimento (dentro/fora do prazo) e dados agregados por tipo, assunto e gênero, atendendo ao Art. 30, III, da LAI. |
| Operação técnica | Requer `artisan storage:link` (o link do PDF é `/storage/docs/<arquivo>`), fila Redis e PostgreSQL com `EXTRACT(DAY FROM ...)` nos agregados de prazo. |

## 3. Comportamento

- O portal monta a página em `/relatorio-estatistico-ouvidoria` (`v5/routes/web.php:32`).
- O filtro **Ano de Gestão** é opcional: vazio = todos os anos; preenchido = apenas
  solicitações criadas dentro do ano e os relatórios PDF com `ano` igual ao filtro.
- Os **agregados de prazo** (em tramitação / atendido / indeferido / prorrogado, dentro e
  fora do prazo) são calculados no banco por `OmbudsmanRequest::getByBetweenDate()` e
  `OmbudsmanRequest::getByBetweenDateWithAnswer()` (20 dias = prazo legal).
- As **distribuições por tipo, assunto e gênero** são três consultas agregadas com
  `DB::raw('count(*) as total')` e `groupBy`.
- A **listagem completa** só aparece se a configuração `full_list_requests_disabled` não
  estiver ligada; nesse caso, apenas os cartões de resumo e os gráficos permanecem.
- No CMS, o CRUD é completo (listar, cadastrar, editar, excluir) com upload de PDF
  opcional, `SoftDeletes` no banco e permissões por linha do DataTable.

## 4. Como o Usuário Interage

**Portal (cidadão).** Abre a página em Transparência Fiscal → "Ouvidoria - Relatório
Estatístico". Vê (a) a tabela de relatórios PDF por ano de gestão, (b) o texto da página
estática, (c) o seletor de Ano de Gestão com botão "Filtrar", (d) três cartões
(Recebidos / Atendidos / Indeferidos), (e) três gráficos de pizza (Status, Tipo de
Manifestação, Gênero), (f) os botões de exportação (xls, pdf, csv, txt) e (g) a tabela
"Listagem completa das solicitações", recolhida por um acordeão, com botão "Solicitação"
que abre modal Ajax com o protocolo, a descrição e as respostas.

**CMS (operador).** Menu *Ouvidoria → Relatório Estatístico* (`/cms/relatorios-estatisticos-ouvidoria`).
Vê um DataTable (Ano, Descrição, Documento, Ações) com botões de Excel/PDF/CSV/TXT,
botão "Cadastrar" e, por linha, botões de editar/excluir conforme permissão. O formulário
pede Ano (4 dígitos, filtrado por JS), Descrição (255) e Arquivo PDF (opcional, até 20 MB).

## 5. Detalhes e Particularidades Técnicas

- **Camadas:** `Route` → `check.site.manutention` (portal) / `check.logged` (CMS) →
  Controller → Form Request (`RelatorioEstatisticoOuvidoriaRequest`) → Model
  (`RelatorioEstatisticoOuvidoria`) → PostgreSQL → Blade.
- O relatório público **não usa o model do CMS**: as estatísticas vêm de
  `ombudsman_requests`/`ombudsman_answers`; o model `RelatorioEstatisticoOuvidoria` é usado
  apenas para a lista de PDFs (`$relatorios`).
- **Acoplamento forte:** a página pública depende do módulo de Ouvidoria
  (`OmbudsmanRequest`), do módulo de Transparência Fiscal (componentes
  `relatorio-estatistico/table` e `relatorio-estatistico-export-button`) e do template ativo
  do portal (`modelo1..modelo6`).
- **Armadilhas:** agregação de prazos com `whereRaw` montando SQL a partir de parâmetros;
  carga de **todas** as solicitações em memória para montar a lista de anos;
  `ano` gravado como texto (ordem lexicográfica); botão "Limpar filtro" da página da
  Ouvidoria apontando para a rota do relatório de LAI (`relatorio-estatistico`).
- **Dependências:** `yajra/laravel-datatables`, `maatwebsite/excel`, `barryvdh/laravel-dompdf`,
  `laracasts/flash`, `cartalyst/sentinel`, `google charts` (CDN) no portal.

## 6. Estrutura de Dados

| Item | Descrição |
|---|---|
| Tabela própria | `relatorios_estatisticos_ouvidoria` (`id`, `ano`, `descricao`, `arquivo`, `created_at`, `updated_at`, `deleted_at`) |
| Migration | `v5/database/migrations/2026_05_27_135849_create_relatorios_estatisticos_ouvidoria_table.php` |
| Origem dos dados | `ombudsman_requests`, `ombudsman_answers`, `ombudsman_manifestation_types`, `ombudsman_subjects`, `statuses` |
| Apoio | `static_pages` (slug `relatorio-estatistico-ouvidoria`), `archives`, `configurations` (`layout`, `full_list_requests_disabled`) |
| Views SQL | nenhuma específica deste módulo |
| Seeds | `v5/database/seeds/OuvidoriaPaginasLinksSeeder.php` cria a página estática e os banners do relatório |

## 7. Como Testar

- **CMS:** cadastrar/editar/excluir relatório; validar upload de PDF > 20 MB (rejeitado);
  validar arquivo não-PDF (rejeitado); validar `ano` com letras (o JS limita a dígitos,
  o servidor aceita até 10 caracteres).
- **Portal:** abrir `/relatorio-estatistico-ouvidoria`; filtrar por ano; conferir os
  cartões e os três gráficos; exportar em xls/csv/pdf/txt; abrir o modal de uma
  solicitação; verificar o download do PDF oficial cadastrado no CMS.

## 8. Migração para Laravel Moderno

Reconstruir como um único módulo com: model `RelatorioEstatisticoOuvidoria` (casts, soft
deletes), Form Request com regras equivalentes (PDF, 20 MB), Policy para
`create/edit/delete`, um `OmbudsmanReportService` que concentrate os agregados de prazo e
as distribuições (hoje misturados no controller do portal), `API Resource` para o JSON dos
gráficos (evitando embutir JSON no Blade), e views Blade com componentes. Preservar
obrigatoriamente: a máscara de protocolo/nome, o limiar de 20 dias, a lista de anos, o
comportamento de `full_list_requests_disabled` e o download público do PDF.

## 9. Resumo Geral

O módulo **Relatório Estatístico da Ouvidoria** da v5 tem duas partes: uma **base de
relatórios oficiais em PDF**, cadastrada no CMS e listada no topo da página pública; e um
**painel de estatísticas calculadas em tempo real** a partir das manifestações registradas na
Ouvidoria (volume, prazo de resposta, tipo, assunto e gênero), com exportação em quatro
formatos e listagem completa das solicitações com dados mascarados. O painel público
sobreviveu à v6, mas **perdeu** o cadastro de PDFs, os cartões de resumo, os gráficos por
tipo/gênero, a rota dedicada de exportação e o item de menu no CMS. A reconstrução em
Laravel moderno deve reaproveitar a lógica de agregação (migrando os `whereRaw` para
consultas parametrizadas), separar serviço de apresentação e recriar a gestão anual dos
relatórios em PDF, hoje existente apenas na v5.

---

## Í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, permissões |
| `04-VIEWS-E-UX.md` | Telas, componentes, JS, assets, exportações |
| `05-REGRAS-E-PORTABILIDADE.md` | Regras de negócio, agregações 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 e comparativo v5 -> v6 |