# PLATAFORMA — Resumo Executivo

> **Versão analisada:** `v6` (referência atual) e `v5` (versão anterior)
> **Natureza:** este dossiê **não é um módulo** — é a visão geral que sustenta todos os dossiês de módulo
> **Slug:** não aplicável (a plataforma em si não está na tabela `modulos`)
> **Estado:** v6 = sistema em produção; v5 = base histórica, ainda restaurável

---

## 1. Objetivo

A plataforma é o **portal institucional de transparência municipal** da Máxima
Tecnologia. Entrega, em um único produto, três coisas que o município normalmente
precisa contratar separadamente:

1. **Um portal público** (`/`) para o cidadão consultar notícias, legislação,
   licitações, contratos, transparência fiscal, diário oficial, ouvidoria,
   agenda da Câmara, carta de serviços e demais informações públicas.
2. **Um CMS administrativo** (`/cms`) para o operador da prefeitura publicar
   conteúdo, modularizar o portal e administer usuários, permissões e menus.
3. **Uma API de dados abertos** (`/api/v1`) para o consumo programático das
   informações do portal (Notícias, Publicações, Legislação, Órgãos, Secretarias).

O problema que a plataforma resolve é o de **centralizar, publicar e controlar
a informação pública do município**, com trilhas de auditoria (log de
atividades), controle de acesso por permissão/módulo e um mecanismo de layout
configurável pelo próprio município, sem depender de desenvolvedor.

---

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Portal responsivo com 6 temas visuais (`modelo1`..`modelo6`), busca, mapa do site, e-SIC, ouvidoria on-line, carta de serviços com PDF, diário oficial com busca dentro do PDF. |
| Prefeitura (CMS) | Publicação de conteúdo com categorias, galeria de arquivos, destaque, carrossel, ordenação visual de widgets e banners por módulo, dashboard com 16 widgets e perfil de layout por usuário. |
| Transparência e legalidade | `resources` (permissões) tied a `modulos`; todo acesso ao CMS é registrado em `activity_log` com IP e User-Agent; solicitações LAI têm status, prazo e resposta formal. |
| Operação técnica | Uma única aplicação com 928 rotas registradas, 138 tabelas e 75 views SQL; deploy por CI GitLab; container Docker com `app`, `postgres`, `redis`, `mailhog`. |

---

## 3. Comportamento (visão das 3 camadas)

### 3.1 Portal público (`v6/routes/web.php`)

- 228 rotas servidas sob o grupo `web` + `check.site.manutention`.
- A home é montada por `Portal\PortalController@index`, que resolve o tema ativo
  (`getTemplateActived()`) e monta a página com notícias, destaques, banners
  "super banner", transparência fiscal, agenda e blocos de acesso rápido.
- Toda listagem com filtro de período, ordenação ou paginação tem um par
  **Ajax** (ex.: `noticias-ajax/{categorySlug}`, `legislacao/filtro`,
  `diario-oficial/filtro`).
- Exportação happens por rotas de planilha (`publicacoes/export`,
  `legislacao/export`, `emendas-parlamentares/export`, `viap/export`).

### 3.2 CMS (`v6/routes/basepro.php`)

- 695 rotas sob o prefixo `/cms`, agrupadas em 12 `Route::group` e 58
  `Route::resource`.
- O menu lateral é montado dinamicamente pelo `MenuServiceProvider`, que escuta
  o evento `BuildingMenu` do AdminLTE e filtra por `has_access()` + status do
  módulo.
- Todo controller de `Prefecture\` herda de `Prefecture\Controller`, que aplica
  `check.route.permission` no construtor.
- O dashboard é um grid de widgets arrastáveis, persistido por usuário em
  `dashboard_widget_instances`.

### 3.3 API (`v6/routes/api.php`)

- 5 endpoints sob `/api/v1` (`noticias`, `publicacoes`, `legislacoes`, `orgaos`,
  `secretarias`), sem autenticação, documentados por anotações OpenAPI
  (`@OA\Get`) e gerados por `php artisan swagger:generate` para
  `public/swagger.yml`.
- Saída via `App\Http\Resources\Swagger\V1\Portal\*Resource`.

---

## 4. Como o Usuário Interage

| Papel | Onde entra | O que faz |
|---|---|---|
| Cidadão | `https://<prefeitura>/` | Lê notícias, baixa diário oficial, protocola e-SIC/ouvidoria, consulta licitações e contratos, agenda sessões. |
| Operador do CMS | `https://<prefeitura>/cms` (login Sentinel) | Publica conteúdo, organiza menus, ajusta o layout do portal, responde ouvidoria e LAI, gera PDFs da carta de serviços. |
| Desenvolvedor / civic hacker | `https://<prefeitura>/api/v1/...` | Consome JSON de dados abertos. |

---

## 5. Detalhes e Particularidades Técnicas (visão geral)

- **Stack:** Laravel 5.5.50, PHP 7.2.34, PostgreSQL 10 + PostGIS, Redis, APCu.
- **Autoload híbrido:** PSR-4 `App\` → `app/` **e** classmap de `app/`, o que
  permite que models em `app/Http/Model/Prefecture/` usem o namespace
  `App\Prefecture\...` (veja `01-ARQUITETURA.md`).
- **Banco:** tabelas no plural `snake_case`; **75 views SQL** substituem joins
  complexos e são consumidas como tabelas (`DB::table('noticias')`).
- **Views do portal:** 6 temas (`modelo1`..`modelo6`) + `default` legado;
  1.069 arquivos Blade só no portal.
- **Dívida técnica:** 35 `whereRaw`, 8 `selectRaw`, 9 `DB::raw`, 12 `dd(` de
  depuração, 23 queries dentro de `foreach` (números reais via `grep`).

---

## 6. Estrutura de Dados (resumo)

| Grupo | Tabelas/views representativas |
|---|---|
| Conteúdo | `contents`, `category_contents`, `archives`, `highlights`, `static_pages` |
| Transparência | `transparencia_fiscal` (view), `licitacao` (view), `contratos`, `propostas`, `proponentes` |
| Ouvidoria / LAI | `ombudsman_requests`, `ombudsman_answers`, `informations_requests`, `answers` |
| Diário oficial | `diarios`, `diario_areas`, `diario_sub_areas`, `diario_has_areas` |
| Câmara | `councilmen`, `councilmen_mandates`, `mandates`, `sessoes`, `atas_e_pontos` |
| CMS / acesso | `users`, `roles`, `permissions`, `resources`, `modulos`, `menu_orders`, `activity_log` |
| Configuração | `configurations`, `layouts`, `menus`, `menu_items` |

---

## 7. Como Testar (resumo)

- `v6/tests/` — 30 arquivos PHPUnit (Feature + Unit), concentrados no dashboard.
- `v6/tests-e2e/` — suíte Playwright isolada para o Diário Oficial, com gate
  visual por `sniffCSS`.
- Comandos: `php artisan test` e `cd tests-e2e && npm test`.

---

## 8. Migração para Laravel Moderno (resumo)

Reconstrução em **PHP 8.x + Laravel 11/12**, mantendo **equivalência funcional
observável** (mesmas URLs públicas, mesmo JSON da API, mesmo conteúdo do CMS).
Pilares: Sanctum no lugar do Sentinel, Form Requests, Policies, API Resources,
enums PHP 8.1, Casts, filas assíncronas para geração de PDF, Pest para testes.

---

## 9. Resumo Geral

Este dossiê descreve a **plataforma** que dá sustentação a todos os demais
dossiês de módulo. A leitura obrigatória para qualquer engenharia da v7 é:
`v6/routes/basepro.php` (695 rotas do CMS) e `v6/routes/web.php` (228 rotas do
portal) definem o contrato público do sistema; `v6/app/Http/Model/` e
`v6/app/Repositories/` definem o contrato de dados; `v6/resources/views/portal/layouts/`
replica 6 temas visuais completos (1.069 Blades) que precisam ser reimplementados
como **componentes**; e a tabela `modulos` (56 slugs na migration
`v6/database/migrations/2024_11_01_150206_create_modulos_table.php`, 58 linhas
no banco implantado) é o **catálogo oficial de módulos** — é ela que decide o
que existe, o que está desligado e o que precisa ser reconstruído. O
`10-INVENTARIO-DE-MODULOS.md` deste mesmo diretório é o índice mestre.

---

## Índice do dossiê

| Arquivo | Conteúdo |
|---|---|
| `00-RESUMO.md` | Este documento |
| `01-ARQUITETURA.md` | Camadas, autoload, providers, diagrama de fluxo |
| `02-MODELAGEM.md` | Convenção de nomes, views SQL, estratégia de migrations |
| `03-ROTAS-E-CONTROLADORES.md` | Rotas por arquivo, grupos, middleware, controllers |
| `04-VIEWS-E-UX.md` | Temas do portal (`default` + `modelo1`..`modelo6`), escolha em runtime |
| `05-REGRAS-E-PORTABILIDADE.md` | Dívida técnica com contagens reais via `grep` |
| `06-MIGRACAO-MODERNA.md` | Plano de reconstrução, tabela de equivalência, ordem e esforço |
| `07-TESTES.md` | Situação atual dos testes e estratégia proposta |
| `08-GAPS-E-DIVIDAS.md` | Bugs conhecidos, funcionalidades mortas, itens v5→v6 |
| `09-MAPAS-DE-TABELAS.md` | Mapa das 138 tabelas e 75 views por área (continuação de `02`) |
| `10-INVENTARIO-DE-MODULOS.md` | Tabela dos 56 módulos + 2 pós-migration + exclusivos da v5 |
| `11-API-E-BREADCRUMBS.md` | API de dados abertos, substituição do pacote de breadcrumbs, controllers (continuação de `03`) |
| `12-WIDGETS-E-CMS.md` | Tabela `layouts`, widgets/tags, AdminLTE, dashboard, exportações (continuação de `04`) |
| `13-DEPENDENCIAS-E-RISCOS.md` | Dependências abandonadas, acoplamentos estruturais, riscos de migração (continuação de `05`) |
| `14-RISCOS-E-PERGUNTAS.md` | Riscos de dados, riscos técnicos, perguntas em aberto, mapa v5→v6 (continuação de `08`) |
| `15-SEGURANCA-INJECAO-SQL.md` | **8 pontos de injeção de SQL confirmados em runtime** (v5 e v6), sem login |
| `16-AUTORIZACAO-ROTA-SEM-AUTENTICACAO.md` | **Rotas de escrita do CMS sem autenticação** + bug do `array_where` no middleware de permissão |
| `16b-IMPACTO-E-CORRECAO-AUTORIZACAO.md` | Impacto e plano de correção das falhas de autorização (continuação de `16`) |
| `06b-PLANO-DE-MIGRACAO-E-ESTIMATIVAS.md` | Ordem de migração, nomenclatura de pastas, estimativas e riscos (continuação de `06`) |
| `17-REGISTRO-DE-BUGS.md` | **Registro master de todos os bugs** consolidados por severidade e categoria |
| `18-BACKLOG-PRIORIZADO.md` | Backlog P0–P3 com esforço, riscos e sequenciamento em sprints |
| `17b-DETALHAMENTO-DE-BUGS.md` | Detalhamento item a item dos bugs (severidade, onde, impacto, correção) |
| `17c-DETALHAMENTO-DE-BUGS-CONTINUACAO.md` | Continuação do detalhamento dos bugs |
| `18b-ESTIMATIVAS-POR-MODULO.md` | Estimativa de esforço por módulo e decisões que exigem o negócio |
| `06b-PLANO-DE-MIGRACAO-E-ESTIMATIVAS.md` | Ordem de migração, nomenclatura de pastas, estimativas e riscos (continuação de `06`) |