# Fila de Espera SUS — Resumo Executivo

> **Versão analisada:** `v5` (Laravel 5.5 / PHP 7.2) — o módulo **não existe** na `v6`
> **Slug do módulo:** `fila-espera-sus` (registro em `resources.id = 17`; não há tabela `modulos` na v5)
> **Natureza:** Ambos (CMS administrativo + Portal público)
> **Estado:** apenas v5 — funcionalidade removida na v6

---

## 1. Objetivo

O módulo **Fila de Espera SUS** publica e administra a relação de pacientes
na fila de espera por consultas, exames e procedimentos da rede municipal de
saúde. Cada registro liga um **cartão SUS** a uma **especialidade**, um
**procedimento**, o **número de pacientes** em fila, o **tempo médio de
espera** em dias, o **critério de priorização**, um **contato** e o
**status da fila**. No CMS o servidor municipal cadastra e mantém esses
registros (inclusive anexos em PDF); no portal o cidadão consulta a fila,
filtra por especialidade/prioridade/texto e baixa a lista em XLSX, PDF, CSV
ou TXT.

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Consulta a fila de espera por especialidade e procedimento, vê o tempo médio de espera e o critério de priorização, e baixa a relação completa. O cartão SUS é sempre exibido mascarado. |
| Prefeitura (CMS) | Cadastra, edita, anexa PDFs, publica (`is_show = true`) e exclui (lógica) registros da fila; toda ação gera log de atividade e contador de cliques no menu. |
| Transparência e legalidade | Publica dados de saúde **vinculados a um indivíduo** (cartão SUS) em espaço público, o que exige mascaramento rigoroso, base legal (LGPD) e controle de acesso aos anexos. |
| Operação técnica | Módulo isolado (uma tabela, um model, dois controllers), mas dependente do bloco de permissões `resources`/`permissions` do Sentinel, do `activity_log` (spatie) e do gerador de PDF/Excel. |

## 3. Comportamento

- **Publicação implícita:** todo registro criado ou editado pelo CMS é gravado
  com `is_show = true`; o operador **não tem tela para despublicar** um item.
  A única forma de sumir do portal é excluir o registro.
- **Máscara do cartão SUS:** o portal, o DataTable do CMS e as exportações
  substituem os 3 primeiros e os 2 últimos dígitos do cartão por caracteres
  `X` (prefixo de três `X`, o miolo intacto e sufixo de dois `X`); para
  cartões com 5 dígitos ou menos o valor sai sem máscara.
- **Busca textual:** o filtro `busca` do portal procura, com `ilike`, em
  `sus_card`, `specialty` e `procedure` — ou seja, **o cartão SUS completo é
  pesquisável** por qualquer visitante.
- **Ordenação padrão do portal:** `update_date` descendente e depois
  `specialty` ascendente; paginação de **15 registros** por página.
- **Filtros do portal:** são gerados a partir de valores distintos
  existentes em registros publicados (`specialty` e `priority_criteria`),
  coletados com `pluck`.
- **Exportação:** disparada pelo parâmetro `type` na mesma URL do portal
  (`xls`, `pdf`, `csv` e qualquer outro valor cai no formato TXT). A
  exportação **não pagina**: carrega todos os registros filtrados em memória.
- **Exclusão:** `delete` do Eloquent (soft delete); a exclusão em lote
  (`destroyAll`) usa `whereIn('id', ...)`.
- **Slug:** gerado como `str_slug(especialidade-procedimento-id)`. No
  `update` o slug é recalculado **a partir dos valores antigos do registro**,
  não dos valores enviados — logo, renomear especialidade/procedimento não
  altera a URL pública.
- **Anexos:** PDFs gravados em `public_path('storage/fila-espera-sus')` com
  nome aleatório de 16 caracteres; o caminho e a descrição ficam serializados
  em JSON na coluna `file_path`.

## 4. Como o Usuário Interage

**Operador (CMS, `/cms/fila-espera-sus`)**

1. Tela "Lista de Fila de Espera SUS": DataTable server-side alimentado por
   `GET /cms/datatable/fila-espera-sus`, com colunas ID, Cartão SUS
   (mascarado), Especialidade, Procedimento, Nº Pacientes, Tempo Médio e
   Status; botões de editar/excluir conforme permissão; botão de exclusão
   em lote; botões de exportação do próprio DataTables (Excel/PDF/CSV/TXT).
2. "Cadastrar Registro": formulário com 9 campos obrigatórios + telefone
   opcional + adição dinâmica de anexos PDF com descrição.
3. "Editar": mesmo formulário, com listagem dos anexos já enviados e
   ações de download, visualizar e remover arquivo.

**Cidadão (Portal, `/fila-espera-sus`)**

1. Formulário de filtros (Especialidade, Critério de Prioridade, busca livre)
   com botões "Consultar" e "Limpar campos".
2. Tabela paginada com os dados da fila e um botão de lupa que abre o
   detalhe em `/fila-espera-sus/{slug}`.
3. Botões de exportação (xls, pdf, csv, txt) que respeitam os filtros
   ativos da URL.
4. Página de detalhe: tabela de atributos + bloco "Arquivos para Download".

## 5. Detalhes e Particularidades Técnicas

- **Camadas:** rota CMS → `check.logged` + `check.route.permission` →
  `Prefecture\FilaEsperaSusController` → `FilaEsperaSusRequest` →
  `App\Prefecture\FilaEsperaSus` → tabela `fila_espera_sus`.
  Rota portal → `check.site.manutention` → `Portal\FilaEsperaSusController` →
  `App\Http\Filter\FilterFilaEsperaSus` → model → view do layout ativo.
- **Listagem do CMS não usa o model:** `DatatableController@get_fila_espera_sus`
  consulta `DB::table('fila_espera_sus')` e aplica a máscara em PHP.
- **Armadilhas reais:** slug desatualizado no `update`; `destroyAll` lê
  `$request->ids` enquanto o JS envia `toDelete` (exclusão em lote inoperante);
  `indexShow` combina `orWhere` com `where('is_show')` de forma que registros
  não publicados continuam acessíveis por slug; o PDF recebe `$pdf`
  indefinido via `compact()`; extensão do arquivo anexado usa
  `getClientOriginalExtension()` sem sanitização; cartão SUS completo fica
  pesquisável e gravado em log.
- **Dependências:** `maatwebsite/excel` 3.1, `barryvdh/laravel-dompdf` 0.8,
  `yajra/laravel-datatables` 1.5, `spatie/laravel-activitylog` 2.8,
  `laracasts/flash` 3.0, `cartalyst/sentinel`.

## 6. Estrutura de Dados

- Tabela única `fila_espera_sus` (ver `02-MODELAGEM.md`), 14 colunas de
  negócio, `softDeletes`, índice único em `slug`.
- **Sem view SQL** associada ao módulo (verificado em `pg_views`).
- Tabelas do entorno: `resources` (id 17, slug `fila-espera-sus`),
  `menu_orders` (id 37, slug `fila-espera-sus`), `permissions` (verbos
  `index`, `create`, `edit`, `delete`, `inactive`, `inactivate`, `restore`,
  `show`) e `activity_log` (`log_name = 'fila-espera-sus'`).

## 7. Como Testar

Cenário mínimo: cadastrar um registro no CMS, conferir `is_show = true` e o
slug gerado; abrir o portal e validar a linha mascarada; filtrar por
especialidade e por busca; exportar em xls/pdf/csv/txt; editar o registro e
verificar que o slug não muda; remover um anexo; excluir em lote e observar
que nada é removido (bug conhecido).

## 8. Migração para Laravel Moderno

Reconstruir com: migration equivalente, model `FilaEsperaSus` com casts
(`date`, `boolean`, `integer`), `FileTrait` substituído por storage
dedicado, Form Request com as mesmas 11 regras, `Policy` por ação
(`viewAny`, `create`, `update`, `delete`), API Resource JSON para o portal,
enum para `queue_status` e `priority_criteria`, tabela de anexos
normalizada e rota REST `GET /api/v1/fila-espera-sus`. A migração dos dados
deve incluir mascaramento em repouso ou, no mínimo, controle de acesso por
papel.

## 9. Resumo Geral

A Fila de Espera SUS é um módulo de **transparência de saúde** com dois
perfis: o operador cadastra e publica a relação no CMS; o cidadão consulta,
filtra e baixa no portal. O núcleo técnico é pequeno — uma tabela, um model
com soft delete e log de atividade, dois controllers e um filtro de consulta
— mas o módulo carrega riscos relevantes: **dado pessoal de saúde
identificável** (cartão SUS) exposto em busca pública, **anexos servidos
diretamente do `public/`**, e **bugs de comportamento** (slug congelado no
update, exclusão em lote sem efeito, acesso a registro despublicado por
slug). Na `v6` **todo o módulo desapareceu**: rotas, controllers, model,
request, export, views de CMS e de portal, e o próprio registro de
permissão `resources.id = 17`.

---

## Í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, filtros |
| `04-VIEWS-E-UX.md` | Telas, componentes, JS, assets |
| `05-REGRAS-E-PORTABILIDADE.md` | Particularidades 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, comparativo v5 vs v6 |