# VIAP — Resumo Executivo

> **Versão analisada:** `v6`
> **Slug do módulo:** `viap` (tabela `modulos`, id 58)
> **Natureza:** Ambos (CMS em `/cms/viap` + Portal público em `/viap`)
> **Estado:** **novo na v6** — nenhum arquivo, rota, view ou migration do módulo
> existe na `v5` (busca negativa registrada em `08-GAPS-E-DIVIDAS.md`)

---

## 1. Objetivo

**VIAP = Verba Indenizatória de Apoio Parlamentar.** O módulo publica, no portal
público do município, os **valores repassados a gabinetes parlamentares e a
órgãos públicos** a título de indenização, vinculados a um mês/ano de
referência.

O nome oficial da sigla e a descrição do módulo vêm do próprio seed:

```php
// v6/database/seeds/ViapSeeder.php:46-49
Resource::updateOrCreate(['slug' => $slug], [
    'name' => 'VIAP',
    'description' => 'Verba Indenizatória de Apoio Parlamentar',
    'modulo_id' => $moduloId,
]);
```

O portal descreve a base normativa exibida ao cidadão:

> *"A Verba Indenizatória de Apoio Parlamentar (VIAP) está regulamentada na
> Resolução nº 1885/2020, alterada pelas Resoluções nº 2012/2022, 2057/2022 e
> 2108/2023."*
> — `v6/resources/views/portal/viap/index.blade.php:12`

O módulo tem **duas faces**:

| Face | Caminho | Quem usa | Finalidade |
|---|---|---|---|
| CMS | `/cms/viap` | Operador da prefeitura (Sentinel) | Cadastrar, editar, listar e excluir lançamentos de VIAP com anexos |
| Portal | `/viap` | Cidadão anônimo | Consultar e exportar os lançamentos com filtros por vínculo, parlamentar/órgão, mês e ano |

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Consulta pública dos lançamentos de VIAP com filtros e página de detalhe por registro; download de XLSX/PDF/CSV/TXT. |
| Prefeitura (CMS) | Registro de um lançamento por (mês, ano, vínculo), com data de publicação, descrição e anexos; listagem em DataTable alimentada por **view SQL** (`view_viap`). |
| Transparência e legalidade | Publica a destinação de recursos de indemnização parlamentar — dados de interesse público e de controle social. |
| Operação técnica | Depende de `contents` + `category_contents` (para a lista de órgãos), de `councilmen` (parlamentares) e de `archives` (anexos). Cria uma **view SQL** que precisa ser mantida por migration. |

## 3. Comportamento

- O módulo só aparece no menu lateral do CMS quando o registro em `modulos`
  (id 58) está com `status = true` **e** o operador tem a permissão
  `viap.index` (`v6/app/Providers/MenuServiceProvider.php:46` e `:412-413`).
- Cada lançamento pertence a **um** de dois vínculos (`link_type`):
  `gabinete` (aponta para `councilmen.id`) ou `outro_orgao` (aponta para
  `contents.id`).
- O CMS **não publica por data**: o que decide a exibição pública é a flag
  `status` (`scopeActive`), e não `publication_date`.
- A listagem do CMS é um **DataTable servidor-side-leve**: o endpoint
  `/cms/datatable/viap` lê a **view** `view_viap` inteira e devolve JSON para
  paginação no cliente (`v6/app/Http/Controllers/Prefecture/DatatableController.php:480-489`).
- O portal **só mostra registros filtrados**: sem nenhum parâmetro de filtro a
  view exibe uma tabela vazia (ver `05-REGRAS-E-PORTABILIDADE.md`, Gap G-01).
- A coluna `amount` (valor da verba) existe no schema mas **nunca é preenchida**:
  não há campo no formulário nem o atributo está no `$fillable` do model
  (Gap G-02).
- A descrição (`description`) é enviada pelo formulário mas **descartada** na
  gravação, por não constar do `$fillable` (Gap G-03).
- O slug público é gerado no repository como
  `{mês}-{ano}-gabinete-{parlamentar}` ou `{mês}-{ano}-orgao-{órgão}`
  (`v6/app/Repositories/Eloquent/Prefecture/Viap/ViapRepositoryDefaultImpl.php:41-69`).

## 4. Como o Usuário Interage

**Cidadão (portal)**

1. Acessa `/viap` → página com texto institucional (ou o texto da *static page*
   `slug = 'viap'`, quando cadastrada) e formulário de filtros.
2. Escolhe **Tipo de Vínculo** (Todos / Gabinete Parlamentar / Outros Órgãos);
   o seletor de Parlamentar ou de Órgão aparece dinamicamente via jQuery.
3. Escolhe **Mês** e **Ano** e clica em **Filtrar** (GET).
4. A tabela mostra Data de Publicação, Referência, Vínculo, Valor e Ações.
5. "Ver detalhes" abre `/viap/{slug}` com data, período, vínculo e arquivos anexos.
6. Exportação: `/viap/export?type=xls|pdf|csv` (sem `type`, exporta TXT).

**Operador (CMS)**

1. `/cms/viap` → DataTable com ID, Data Publicação, Referência, Vínculo e Ações;
   botão "Cadastrar VIAP" e botão "Excluir Registro(s)" em lote.
2. "Cadastrar VIAP" → formulário com data de publicação, mês/ano de referência,
   tipo de vínculo (com alternância gabinete/órgão), descrição e **multi-upload**
   de arquivos (cada arquivo com sua própria descrição).
3. Salvar → `flash('VIAP cadastrado com sucesso.')` e redirecionamento para a
   listagem.
4. Editar → mesmo formulário, com os anexos já enviados listados e removíveis por
   AJAX.
5. Excluir → botão individual na DataTable (DELETE) ou botão em lote
   (POST `viap/delete-por-lote`).

## 5. Particularidades Técnicas

| Item | Detalhe |
|---|---|
| Registro no menu | Criado por **seed** (`v6/database/seeds/ViapSeeder.php`), não por migration → um ambiente novo com apenas `migrate` **não tem** o módulo |
| Tabelas | `viap`, `viap_has_archives` (pivot com `archives`) |
| View SQL | `view_viap` — projeta `linked_name` resolvendo gabinete × orgão |
| Persistência | Repository pattern (`IViapRepository` / `ViapRepositoryDefaultImpl`) sobre `App\Http\Model\Prefecture\Viap` |
| Upload | `App\Http\Traits\FileTrait::getFileName()` + `App\Prefecture\Archive`; caminho `viap/{id}/arquivos/{nome}` |
| Auditoria | `spatie/laravel-activitylog` (`LogsActivity`) + `activity()->performedOn()` no `index` |
| Autorização | `check.route.permission` (Sentinel) + helper `has_access()` |
| Exportação | `maatwebsite/excel` (`ViapExport`, `FromView`) + `barryvdh/laravel-dompdf` |
| Front-end | DataTables (Yajra) + jQuery + Summernote (descrição) + jsPDF (PDF client-side) |

## 6. Estrutura de Dados (resumo)

```
councilmen ──┐
             ├──< viap >──┬── view_viap (CREATE VIEW)
contents ────┘            └──< viap_has_archives >── archives
```

`viap` — colunas: `id`, `publication_date`, `amount`, `reference_month`,
`reference_year`, `description`, `link_type`, `councilman_id`, `organ_id`,
`status`, `slug`, `created_at`, `updated_at`, `deleted_at`.

Detalhes em `02-MODELAGEM.md`.

## 7. Como Testar (resumo)

```bash
# listagem pública
curl -sk https://<host>/viap
curl -sk https://<host>/viap/export?type=csv

# CMS exige login (302 -> /login sem sessão)
curl -sk -o /dev/null -w "%{http_code}\n" https://<host>/cms/viap

# suíte
php artisan test --filter=Viap
```

Detalhe dos cenários em `07-TESTES.md`.

## 8. Migração para a v7 (resumo)

- `viap` e `viap_has_archives` → migrations Laravel 11/12 com FK e `softDeletes`.
- `view_viap` → **não portar**; substituir por `scopeComVinculo` / `withCount`
  no Eloquent (a view só existe para o DataTable do legado).
- `ViapRequest` → Form Requests `StoreViapRequest` / `UpdateViapRequest`.
- `check.route.permission` (por nome de rota) → **Policy** `ViapPolicy`
  (`viewAny`, `view`, `create`, `update`, `delete`, `deleteAny`).
- Controller único com `__construct` → controllers separados
  `ViapController` (CMS) e `ViapPortalController` (público), com
  `Authorize` + `Policy` e rota `viap.show` implementada (hoje inexistente).
- Exportação → endpoint `GET /api/v1/viap/export` com `Excel::download` /
  `dompdf` e **os mesmos nomes de arquivo**.

Plano detalhado em `06-MIGRACAO-MODERNA.md`.

## 9. Resumo Geral

O VIAP é um módulo **pequeno e autocontido**, criado do zero na v6 e já
operacional nas duas faces (CMS + Portal), mas com maturidade de código
**inexistente**: o valor e a descrição são campos "mortos" no schema, a listagem
pública só funciona com filtro aplicado, a rota `viap.show` do CMS aponta para
um método inexistente e o botão de exclusão em lote é bloqueado pelo próprio
middleware de permissão para o papel `administrador`. As correções e as
decisões de equivalência funcional estão detalhadas em
`05-REGRAS-E-PORTABILIDADE.md` e `08-GAPS-E-DIVIDAS.md`.

## 10. Índice dos arquivos deste dossiê

| Arquivo | Conteúdo |
|---|---|
| `00-RESUMO.md` | Objetivo, efeito, comportamento, interação, dados, testes e migração (este arquivo) |
| `01-ARQUITETURA.md` | Fluxo da requisição (CMS, DataTable e Portal), classes envolvidas, diagrama Mermaid, dependências composer |
| `02-MODELAGEM.md` | Tabelas `viap` e `viap_has_archives`, view `view_viap`, migrations, seed e regras de integridade |
| `03-ROTAS-E-CONTROLADORES.md` | Tabelas de rotas (CMS e Portal), Form Requests, autorização e matriz de permissões verificada em runtime |
| `04-VIEWS-E-UX.md` | Views do CMS e do portal (modelo1..6), JavaScript/Ajax, exportações e o que cada ator vê |
| `05-REGRAS-E-PORTABILIDADE.md` | Regras de negócio, acoplamentos, armadilhas de código, duplicações e decisões de equivalência funcional |
| `06-MIGRACAO-MODERNA.md` | Plano de reconstrução: schema, model, Form Requests, Policy, endpoints, Resource, views, riscos |
| `07-TESTES.md` | Estratégia, casos concretos (Feature/Unit), fixtures, comandos e checklist de regressão |
| `08-GAPS-E-DIVIDAS.md` | Mapa v5 → v6, gaps G-01..G-19, riscos de segurança, perguntas em aberto e riscos de dados |