# TRANSPARÊNCIA FISCAL — Resumo Executivo

> **Versão analisada:** `v6` (Laravel 5.5.50 / PHP 7.2.34 / PostgreSQL 10)
> **Slug do módulo:** `transparencia-fiscal` — tabela `modulos`, `id = 23`, nome `Transparência Fiscal`
> **Natureza:** Ambos (CMS em `/cms/...` + Portal público)
> **Estado:** OK v6 (módulo já existia na v5 com o mesmo desenho — ver `08-GAPS-E-DIVIDAS.md`)

---

## 1. Objetivo

O módulo entrega ao cidadão a **página de Transparência Fiscal** do portal: um mosaico de
atalhos (ícones + títulos) agrupados em categorias, cada um apontando para um **link externo**
(ou para uma página interna) onde o município publica despesas, contratos, folha de
pagamento, licitações e demais dados fiscais. Ao lado disso, o módulo publica o
**Relatório Estatístico do e-SIC (LAI)**, com o índice de solicitações de informação,
gráfico de status/prazo e exportação em XLS/PDF/CSV/TXT.

O módulo **não armazena dados fiscais**: não há tabelas de despesas, credores ou orçamento.
A "transparência fiscal" do legado é um **catálogo de links** gerenciado no CMS
(`contents` + `category_contents` + `links`). Os dados financeiros reais ficam em sistemas
externos (Sicon/Elmar, TCE, portal do fornecedor) e são acessados por link.

Público-alvo: cidadão que consulta a transparência do município; operador do CMS que
mantém os atalhos, as categorias e o relatório.

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Acesso em um clique aos serviços de transparência; relatório estatístico público do e-SIC com protocolos e solicitantes mascarados (LGPD) |
| Prefeitura (CMS) | Cadastro de links, ícones, ordem, referência legal e status de cada item de transparência, sem sair do painel |
| Transparência e legalidade | Publicação de itens com referência (ex.: "2.1 a 2.5") atendendo listas de acesso; relatório de LAI comprova atendimento e prazos |
| Operação técnica | View SQL `transparencia_fiscal` alimenta o DataTable do CMS; 4 URIs de índice e 5 de detalhe mantêm URLs históricas |

## 3. Comportamento

- A raiz da transparência é a `category_contents` com `slug = 'transparencia-fiscal'` (**id 25** no banco); todo controller usa fallback literal `25` quando o slug não é encontrado.
- A listagem do portal mostra **duas camadas**: itens cuja `category_contents_id` é a própria raiz (seção "Geral") e, abaixo, uma seção por subcategoria, na ordem de `category_contents.order`.
- Itens aparecem somente com `contents.status = true`; a posição vem de `contents.order` (1-based, o CMS reordena incrementando os seguintes).
- Cada item tem **um** `links` (relação `hasOne` por `contents_id`): se `links.isBlank` é verdadeiro o link abre em nova aba; caso contrário abre a página interna `transparencia.show/{slug}`.
- A página interna (`show`) renderiza o item dentro de um `<iframe>` com a URL do `links.link`.
- O **Relatório Estatístico** filtra por ano (`?ano=YYYY`); com `?type=xls|csv|pdf|txt` devolve o arquivo em vez do HTML.
- As 8 fatias do gráfico (status × dentro/fora do prazo) vêm de `InformationsRequest::getByBetweenDate` e `getByBetweenDateWithAnswer`; o prazo legal é de **20 dias** (comparação `> 20` / `<= 20`).
- O Ajax `POST /AjaxGetanswers` devolve, para um pedido de informação, o protocolo mascarado, o texto mascarado da solicitação, o `status_id` e a lista de respostas com anexos.
- A listagem completa de solicitações pode ser desligada pela configuração `full_list_requests_disabled`.

## 4. Como o Usuário Interage

**Cidadão (portal)**

| Ação | Resultado |
|---|---|
| Abre `/transparencia-fiscal` (ou `/transparencia`, `/portal-da-transparencia`, `/portal-transparencia`) | Grade de ícones por categoria |
| Clica em um item com `isBlank` | Abre o sistema externo em nova aba |
| Clica em um item sem `isBlank` | Abre `/transparencia/{slug}`, que embute a URL em `iframe` |
| Abre `/relatorio-estatistico` | Gráfico de pizza, filtro de ano, tabela de solicitações, botões xls/pdf/csv/txt |
| Clica em "Solicitação" na tabela | Modal Ajax com a resposta e os anexos |

**Operador (CMS)**

| Tela | Rota | O que faz |
|---|---|---|
| Lista de itens | `/cms/conteudos/transparencia-fiscal` | DataTable alimentado pela view `transparencia_fiscal`; ativa/desativa, edita, exclui em lote, arrasta para reordenar |
| Formulário | `/cms/conteudos/cadastrar/transparencia-fiscal` | Título, ícone, posição, URL, referência, "abrir em nova janela" |
| Categorias | `/cms/categorias/transparencia-fiscal` | CRUD das subpastas (com `description` exibida no portal) |

## 5. Detalhes e Particularidades Técnicas

- **Fluxo portal:** `routes/web.php` → `Portal\TransparencyController` → Eloquent (`CategoryContent`, `Content`, `Link`) → Blade `portal.layouts.{template}.transparencia-fiscal.*`.
- **Fluxo CMS:** `routes/basepro.php` → `Prefecture\ContentController` / `CategoryContentController` / `DatatableController` → `ContentRequest` → Eloquent + `ActivityLog`.
- **View SQL:** a view PostgreSQL `transparencia_fiscal` é lida por `Prefecture\DatatableController@get_transparencia_fiscal` via `DB::table('transparencia_fiscal')`.
- **Sem service/repository dedicado:** ao contrário do Diário Oficial, este módulo usa Eloquent direto do controller.
- **Dependências:** `maatwebsite/excel` (xls/csv), `barryvdh/laravel-dompdf` (pdf), `yajra/laravel-datatables` (CMS), `cartalyst/sentinel` (permissões), `laracasts/presenter`.
- **Mascaramento LGPD** via `App\Http\Traits\DataMaskTrait` (`maskProtocol`, `maskName`).

## 6. Estrutura de Dados

| Objeto | Tipo | Papel |
|---|---|---|
| `transparencia_fiscal` | view SQL | Listing do CMS sobre `contents` + `category_contents` |
| `contents` | tabela | Um item de transparência (título, ícone, ordem, URL via `links`, `referencia`, `status`) |
| `category_contents` | tabela | Categorias (pastas) da transparência; raiz `slug = 'transparencia-fiscal'` |
| `links` | tabela | URL e `isBlank` do item (1:1 com `contents`) |
| `informations_requests` | tabela | Pedidos de informação (e-SIC) exibidos no relatório |
| `answers` / `answer_archives` | tabelas | Respostas do e-SIC e anexos |
| `configurations` | tabela | `layout`, `full_list_requests_disabled`, `portal_transparencia_*` |
| `layouts` | tabela | `transparencia-fiscal` e `transparencia-fiscal-grid` (grid da home) |

## 7. Como Testar

1. `GET /transparencia-fiscal` → grade renderizada com os itens ativos.
2. `GET /cms/conteudos/transparencia-fiscal` (logado) → DataTable com as colunas `titulo`, `category_name`, `status_name`.
3. `GET /relatorio-estatistico?ano=2024` → gráfico + tabela; `?type=csv` → download.
4. `POST /AjaxGetanswers` com `id` válido → JSON com `request` e `answers`.
5. Criar/editar item no CMS e conferir `contents.order`, `links.link` e a posição no portal.

## 8. Migração para Laravel Moderno

Substituir a view SQL por uma query Eloquent (ou `Content` com `scope`), trocar as 4 URIs
alias por redirecionamentos 301 para uma URI canônica, mover o relatório para um
`ReportController` com `FormRequest` (`ano` obrigatório, `type` em enum), tipar o catálogo
externo do `PortalTransparenciaService` em uma tabela de configuração dedicada e criar
`Policy` para as ações `transparencia-fiscal.*` no lugar do `has_access` por string.

## 9. Resumo Geral

A "Transparência Fiscal" do portal é um **catálogo de links** curado no CMS, não um
repositório de dados orçamentários. O operador cria categorias e itens (título, ícone,
posição, URL, referência legal) e o cidadão recebe uma grade de atalhos que abre sistemas
fiscais externos ou páginas internas em `iframe`. O mesmo módulo hospeda o **Relatório
Estatístico do e-SIC**, com filtro por ano, gráfico de status/prazo sobre 20 dias,
listagem de protocolos com dados mascarados por LGPD e exportação em XLS/PDF/CSV/TXT.
No CMS, a listagem é alimentada por uma **view SQL** (`transparencia_fiscal`) criada e
substituída por quatro migrations sucessivas desde abril/2023 — a versão vigente ordena
por `contents.order` e expõe `value`, `titulo`, `id`, `status_name`, `category_name` e
`status`. O portal mantém **9 URIs** para o mesmo conteúdo (4 de índice, 5 de detalhe,
com uma duplicação literal), existindo para preservar links publicados; isso é dívida
técnica de SEO e deve virar redirect 301 para uma URI canônica na v7. O módulo não usa
repository nem service próprio: lê e escreve Eloquent direto dos controllers.

---

## Í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, view SQL transcrita, migrations, seeds |
| `03-ROTAS-E-CONTROLADORES.md` | Rotas CMS e Portal, controllers, requests, permissões |
| `04-VIEWS-E-UX.md` | Blades por template, componentes, JS/Ajax, exportações |
| `05-REGRAS-E-PORTABILIDADE.md` | Regras de negócio, armadilhas, acoplamentos, v5 vs v6 |
| `06-MIGRACAO-MODERNA.md` | Plano de reconstrução em Laravel 11/12 |
| `07-TESTES.md` | Estratégia e casos de teste |
| `08-GAPS-E-DIVIDAS.md` | Pendências, bugs, riscos, comparativo v5 vs v6 |