# Fila de Espera SUS — Arquitetura

> Versão analisada: `v5` (Laravel 5.5.50 / PHP 7.2.34 / PostgreSQL 10).

## 1. Visão geral das camadas

O módulo é **duplo**: um par CMS (autenticado) e um par Portal (público).
Não há service layer, repository ou API Resource: o model Eloquent é
acessado direto pelos controllers.

```text
CMS  (/cms/...)                         PORTAL (/)
   │                                       │
   ▼                                       ▼
v5/routes/basepro.php                 v5/routes/web.php
   │                                       │
   ▼                                       ▼
Prefecture\FilaEsperaSusController   Portal\FilaEsperaSusController
   │                                       │
   ├─ check.logged                        ├─ check.site.manutention
   ├─ check.route.permission              │
   ▼                                       ▼
FilaEsperaSusRequest                 FilterFilaEsperaSus
   │                                       │
   ▼                                       ▼
App\Prefecture\FilaEsperaSus  ◄───────  App\Prefecture\FilaEsperaSus
   │                                       │
   ▼                                       ▼
tabela fila_espera_sus                 views portal (modelo1..modelo6)
   │
   ├─► view prefecture.fila-espera-sus.*
   ├─► /cms/datatable/fila-espera-sus (yajra DataTables)
   └─► App\Exports\FilaEsperaSusExport (xls/csv) + dompdf (pdf)
```

## 2. Classes envolvidas

| Classe | Caminho | Papel |
|---|---|---|
| `Prefecture\FilaEsperaSusController` | `v5/app/Http/Controllers/Prefecture/FilaEsperaSusController.php` | CRUD do CMS, upload de anexos, remoção de arquivo, log de atividade, contador de menu. |
| `Portal\FilaEsperaSusController` | `v5/app/Http/Controllers/Portal/FilaEsperaSusController.php` | Listagem pública, filtros, paginação, detalhe e exportações. |
| `App\Prefecture\FilaEsperaSus` | `v5/app/Http/Model/Prefecture/FilaEsperaSus.php` | Model Eloquent, soft delete, log de atividade (spatie). |
| `App\Http\Requests\FilaEsperaSusRequest` | `v5/app/Http/Requests/FilaEsperaSusRequest.php` | Validação do formulário de cadastro/edição. |
| `App\Http\Filter\FilterFilaEsperaSus` | `v5/app/Http/Filter/FilterFilaEsperaSus.php` | Construtor de query do portal (filtros). |
| `App\Exports\FilaEsperaSusExport` | `v5/app/Exports/FilaEsperaSusExport.php` | Exportação XLSX/CSV a partir de uma view Blade (`FromView`). |
| `Prefecture\DatatableController` | `v5/app/Http/Controllers/Prefecture/DatatableController.php` | Endpoint JSON do DataTable do CMS (método `get_fila_espera_sus`). |
| `Admin\Controller` | `v5/app/Http/Controllers/Admin/Controller.php` | Base do controller do portal; resolve o layout ativo (`getTemplateActived`). |
| `App\Http\Middleware\CheckRoutePermission` | `v5/app/Http/Middleware/CheckRoutePermission.php` | Autorização por rota/permissão no CMS. |
| `App\Http\Middleware\CheckLogged` | `v5/app/Http/Middleware/CheckLogged.php` | Exige sessão iniciada no CMS. |
| `App\Http\Traits\AppTrait` | `v5/app/Http/Traits/AppTrait.php` | Trait genérico do model (validações de documentos). |
| `App\Http\Traits\FileTrait` | `v5/app/Http/Traits/FileTrait.php` | Trait de arquivos importado pelo controller (nenhum método dele é usado neste módulo). |
| `App\Admin\Resource` | `v5/app/Http/Model/Admin/Resource.php` | Model da tabela `resources` (permissões por recurso). |
| `App\Library\Helper\appHelpers.php` | `v5/app/Library/Helper/appHelpers.php` | Funções `has_access()` e `resolve_permission_aliases()`. |
| `App\Helpers\functions.php` | `v5/app/Helpers/functions.php` | Função `menuClicks()` (contador de acessos ao menu). |
| `App\Providers\MenuServiceProvider` | `v5/app/Providers/MenuServiceProvider.php` | Injeta o item "Fila de Espera SUS" no menu do CMS. |

## 3. Fluxo de requisição (detalhado)

### 3.1 CMS — listagem

1. `GET /cms/fila-espera-sus` → `fila-espera-sus.index`.
2. Middleware do grupo `cms` (`before => csrf`) + `check.logged` +
   `check.route.permission` (registrado no construtor do controller).
3. O controller grava a atividade e o contador de cliques:

```php
activity()->performedOn(new FilaEsperaSus())
    ->causedBy(Sentinel::getUser())
    ->withProperty('Detalhe', 'Listado por: ' . Sentinel::getUser()->name)
    ->log('Listou Fila de Espera SUS');

menuClicks('fila-espera-sus');
```

4. Devolve a view `prefecture.fila-espera-sus.index`, que apenas monta o
   esqueleto da tabela; os dados chegam depois por AJAX.

### 3.2 CMS — tabela (AJAX)

1. `GET /cms/datatable/fila-espera-sus` → `Prefecture\DatatableController@get_fila_espera_sus`.
2. A consulta é feita **pelo query builder, fora do model**:

```php
$items = DB::table('fila_espera_sus')->whereNull('deleted_at')->get();
```

3. A máscara do cartão é aplicada em PHP e as flags de permissão por linha
   são injetadas por `struct_views($data, 'fila-espera-sus')`
   (`edit`, `delete`, `active`, `inactivate`).

### 3.3 CMS — cadastro/edição

1. `POST /cms/fila-espera-sus` ou `PUT /cms/fila-espera-sus/atualizar/{id}`.
2. `FilaEsperaSusRequest` valida 11 campos (ver `03-ROTAS-E-CONTROLADORES.md`).
3. O controller grava os anexos, monta o `file_path` (JSON) e faz
   `FilaEsperaSus::create($data)` / `$item->update($data)`.
4. O model, por `LogsActivity` com `$logFillable = true`, grava uma linha em
   `activity_log` com `log_name = 'fila-espera-sus'`.

### 3.4 Portal — listagem e exportações

1. `GET /fila-espera-sus` → `portal.fila-espera-sus.index`.
2. `FilterFilaEsperaSus::filter($request)` devolve a query já filtrada e
   restrita a `is_show = true`.
3. Se o parâmetro `type` existir, o controller exporta (xls, pdf, csv ou txt);
   caso contrário pagina 15 registros e monta os selects de filtro.
4. A view é escolhida dinamicamente:

```php
return view(
    'portal.layouts.' . $this->getTemplateActived() . '.fila-espera-sus.index',
    compact('title', 'items', 'specialties', 'priorities', 'request')
);
```

`getTemplateActived()` lê `configurations.key = 'layout'` (no banco v5 o valor
é `modelo1`) e, se a view inicial do layout não existir, coloca o portal em
manutenção e aborta com 404.

## 4. Diagrama de fluxo

```mermaid
flowchart TD
    A[Cidadão GET /fila-espera-sus] --> B{Route::get type?}
    B -- não --> C[FilterFilaEsperaSus::filter]
    C --> D[orderBy update_date desc, specialty asc]
    D --> E[paginate 15]
    E --> F[pluck specialties e priorities]
    F --> G[view portal.layouts.ACTIVE.fila-espera-sus.index]
    B -- sim --> H[get sem paginação]
    H --> I{type}
    I -- xls --> J[Excel::download FilaEsperaSusExport]
    I -- csv --> J
    I -- pdf --> K[dompdf loadView exports.fila-espera-sus]
    I -- outros --> L[exportTxt Response::make]
```

```mermaid
sequenceDiagram
    participant O as Operador (CMS)
    participant C as Prefecture\FilaEsperaSusController
    participant R as FilaEsperaSusRequest
    participant M as App\Prefecture\FilaEsperaSus
    participant D as PostgreSQL
    O->>C: POST /cms/fila-espera-sus (multipart)
    C->>R: valida campos e anexos
    R-->>C: regras aprovadas
    C->>C: grava PDFs em public_path storage
    C->>M: create com file_path em JSON
    M->>D: INSERT fila_espera_sus
    M->>D: INSERT activity_log (spatie)
    C-->>O: redirect fila-espera-sus.index + flash success
```

## 5. Dependências externas (composer)

| Pacote | Versão em `v5/composer.json` | Uso no módulo |
|---|---|---|
| `maatwebsite/excel` | `^3.1` | `Excel::download()` com `FilaEsperaSusExport` (XLSX/CSV). |
| `barryvdh/laravel-dompdf` | `^0.8.7` | Geração do PDF a partir da view de exportação. |
| `yajra/laravel-datatables` | `^1.5` | Endpoint do DataTable do CMS. |
| `spatie/laravel-activitylog` | `^2.8` | `LogsActivity` no model + helper `activity()`. |
| `laracasts/flash` | `3.0.*` | Mensagens `flash(...)->success()/error()`. |
| `cartalyst/sentinel` | (auth do portal) | `Sentinel::getUser()`, `hasAnyAccess()`, `inRole()`. |

## 6. Onde o módulo está acoplado ao resto da v5

- `v5/app/Providers/MenuServiceProvider.php:380-382` — item de menu do CMS.
- `v5/app/Http/Controllers/Prefecture/DatatableController.php:106-119` — dado
  da tabela do CMS.
- `v5/app/Http/Middleware/CheckRoutePermission.php` — autorização por nome de
  rota.
- `v5/app/Library/Helper/appHelpers.php:22-45` — `has_access()`.
- `v5/app/Helpers/functions.php:822-830` — `menuClicks()`.
- `v5/routes/breadcrumbs.php:225-234` — trilha de navegação do portal.
- `v5/database/migrations/2026_05_28_200000_create_fila_espera_sus_table.php` —
  tabela, `menu_orders` e `resources`.