# Perguntas Frequentes — Gaps, Dívidas e Mapa v5 → v6

> Inventário do que está quebrado, morto ou divergente no módulo Perguntas Frequentes
> da `v6`, com o comparativo v5 → v6.

---

## 1. Bugs / erros conhecidos

| # | Severidade | Descrição | Evidência |
|---|---|---|---|
| B1 | Alta | **Itens desativados são publicados.** `getContentByCategory` não filtra `status`, então uma pergunta "desativada" no CMS continua visível ao cidadão | `v6/app/Http/Traits/GetInformationsPrefectureTrait.php:28-33` |
| B2 | Alta | **`CommonQuestionsController` está órfão**: sem rota em `v6/routes/` e apontando para a view inexistente `portal.layouts.default.pages.common-questions`. Se a rota for criada, a resposta é 500 | `v6/app/Http/Controllers/Portal/CommonQuestionsController.php:28` |
| B3 | Média | **`str_limit` no breadcrumb `pergunta`.** O helper foi removido no Laravel 6+; ao abrir a página do item (resultado da busca) a chamada falha | `v6/routes/breadcrumbs.php:259-261` |
| B4 | Média | **Resultado da busca quebra nos layouts `default` e `newsbit`**: `getViewToBeReturned` devolve `perguntas-frequentes.show`, view que só existe em modelo1..modelo6 | `v6/app/Http/Controllers/Portal/PortalController.php:401` |
| B5 | Média | **Duas implementações divergentes do filtro client-side** (modelo1..6 vs. layout `default`), com a versão do `default` usando `RegExp` não escapado e `closest('li').next()` | `v6/resources/views/portal/layouts/modelo1/informacoes-instituicao/acesso-rapido/perguntas-frequentes.blade.php:50-61` e `v6/resources/views/portal/layouts/default/pages/contents/perguntas-frequentes/index.blade.php:49-66` |
| B6 | Média | **A listagem do CMS não mostra a resposta** (a view SQL expõe apenas `value`, `titulo`, `id`) | `v6/database/migrations/2023_04_10_151038_create_view_to_perguntas_frequentes.php:16-25` |
| B7 | Baixa | **Variável global `currentName`** criada sem `var` no JS do filtro | view do modelo1, linha 53 |
| B8 | Baixa | **Botão da lupa sem handler**: apenas o `keyup` do input dispara o filtro | view do modelo1, linhas 21-24 |
| B9 | Baixa | **Resposta renderizada sem escape** (`{!!$content->text!!}`): risco de XSS via CMS | view do modelo1, linha 36 |
| B10 | Baixa | **`contentList` engole exceções** (`catch (\Throwable $th) {}`) | `v6/app/Http/Controllers/Portal/PortalController.php:367` |

## 2. Funcionalidades incompletas ou mortas

| # | Item | Situação |
|---|---|---|
| M1 | `Portal\CommonQuestionsController` | Código morto (sem rota, view inexistente). Presente também na v5 |
| M2 | `v6/resources/views/prefecture/contents/perguntas-frequentes/show.blade.php` | Arquivo morto no CMS: nenhuma rota renderiza essa view |
| M3 | `v6/resources/views/portal/layouts/default/pages/contents/perguntas-frequentes/index.blade.php` | View morta do portal: o layout `default` nem tem `home/index` (o que faz `getTemplateActived()` abortar com 404) |
| M4 | Controller público dedicado | Não existe: a rota canônica é a de "Acesso Rápido" |
| M5 | Agrupamento por tema | Não há categorias de FAQ: todas as perguntas ficam em uma lista única |
| M6 | Paginação | A listagem pública entrega todas as perguntas em uma requisição |
| M7 | Ordenação | Não há campo `order` no formulário: a ordem exibida é a do banco (`created_at`) |
| M8 | Exportação | Só os botões genéricos do DataTable (Excel/PDF client-side) |

## 3. Itens existentes na v5 e removidos na v6 (ou o contrário)

| Item | v5 | v6 | Observação |
|---|---|---|---|
| `Portal/QuickAccessController.php` | presente | presente | Estrutura equivalente; a v6 usa a pasta `informacoes-instituicao` (v5 usava `informacoes-prefeitura`) |
| `Portal/CommonQuestionsController.php` | presente (morto) | presente (morto) | Idêntico; nenhuma das versões o registra |
| View `portal.layouts.default.pages.common-questions` | **ausente** | **ausente** | O controller já apontava para uma view inexistente na v5 |
| `Prefecture/DatatableController::get_perguntas_frequentes` | presente | presente | Idêntico |
| Migration da view `perguntas_frequentes` | `v5/database/migrations/2023_04_10_151038_create_view_to_perguntas_frequentes.php` | `v6/database/migrations/2023_04_10_151038_create_view_to_perguntas_frequentes.php` | Mesmo SQL |
| JS do DataTable | `v5/public/assets/js/custom/contents/perguntas-frequentes/datatable.js` | `v6/public/assets/js/custom/contents/perguntas-frequentes/datatable.js` | Idêntico |
| Registry `modulos` / `resources` / `menu_orders` | inexistente | criado (módulo id 25) | Novo na v6 |

**Nenhum item funcional da FAQ foi removido na v6.** As diferenças são de nomenclatura
de pastas do portal e a adição da camada de registry.

## 4. Riscos de dados

| Risco | Descrição | Mitigação na v7 |
|---|---|---|
| DR1 | Migrar `contents` (categoria 12) para `faq_questions` exige mapear `title`->`question` e `text`->`answer` | Teste de migração com contagem e amostra |
| DR2 | A busca global e `getViewToBeReturned` referenciam o **id** 12 | Resolver por slug |
| DR3 | Permissões indexadas pelo slug `perguntas-frequentes` | Preservar o slug |
| DR4 | O link do bloco Acesso Rápido está gravado em `links` (`/acesso-rapido/perguntas-frequentes`) e em `menu_items` | Manter a URL (redirect interno se necessário) |
| DR5 | Soft delete: perguntas excluídas permanecem na base | Manter `SoftDeletes` |
| DR6 | O seed de demonstração usa `updateOrCreate` por `slug`: sem o seed, o município perde as 8 perguntas da LAI | Replicar no seeder da v7 |

## 5. Dívidas técnicas

| Dívida | Onde | Impacto |
|---|---|---|
| D1 | Reaproveitamento do CRUD genérico de `contents` (dezenas de colunas irrelevantes) | Acoplamento e confusão de modelo |
| D2 | Sete cópias da listagem no portal, com dois filtros diferentes | Correções replicadas |
| D3 | Controller genérico (`QuickAccessController`) decide a view pelo slug | Rota real do módulo invisível na tabela de rotas |
| D4 | Filtro client-side sem normalização de acentos e sem debounce | Resultado diferente do esperado pelo usuário |
| D5 | Sem cache nem paginação | Custo por requisição e payload cresce com o FAQ |
| D6 | `has_access()` chamado por linha no `struct_views` | N+1 de verificações de permissão |

## 6. Perguntas em aberto para o negócio

1. Perguntas devem poder ficar **inativas** (rascunho)? Hoje o campo existe no banco mas não no formulário e não filtra a exibição.
2. Deve haver **categorias de FAQ** (por exemplo, "Acesso à Informação", "Serviços", "Documentos")?
3. A FAQ deve ter **ordem** manual de exibição?
4. O citizens deve ver as perguntas em **accordion** (recolhível) em vez de lista aberta?
5. Deve existir um **mecanismo de "pergunta não encontrada"** apontando para a Ouvidoria?
6. Quem atualiza as perguntas da LAI periodicamente?

## 7. Mapa v5 → v6

```mermaid
graph LR
  subgraph V5["v5"]
    A1["QuickAccessController<br/>(rota /acesso-rapido/{slug})"]
    A2["CommonQuestionsController (MORTO, sem rota)"]
    A3["view SQL perguntas_frequentes"]
    A4["views: informacoes-prefeitura/acesso-rapido/perguntas-frequentes<br/>modelo1..modelo6/perguntas-frequentes/show"]
    A5["CMS: prefecture/contents/perguntas-frequentes/{index,create,edit,form,show}"]
    A6["JS datatable + seed de 8 perguntas (LAI)"]
  end
  subgraph V6["v6"]
    B1["QuickAccessController<br/>(mesma rota)"]
    B2["CommonQuestionsController (MORTO, sem rota)"]
    B3["view SQL perguntas_frequentes (mesma SQL)"]
    B4["views renomeadas: informacoes-instituicao/acesso-rapido/perguntas-frequentes<br/>modelo1..modelo6/perguntas-frequentes/show"]
    B5["CMS: mesmas views (+ show orfã)"]
    B6["NOVO: modulos (id 25), resources, menu_orders"]
    B7["NOVO: registro em links do bloco Acesso Rápido"]
  end
  A1 --> B1
  A2 --> B2
  A3 --> B3
  A4 --> B4
  A5 --> B5
  A6 --> B6
  B6 --> B7
```

**Resumo do mapa:** a FAQ é **funcionalmente idêntica** entre v5 e v6. As diferenças são
(1) a renomeação da pasta do portal de `informacoes-prefeitura` para
`informacoes-instituicao` e (2) a introdução da camada de registry de módulos
(`modulos`, `resources`, `menu_orders`) na v6. Os bugs B1–B10 e o código morto
(`CommonQuestionsController`) existem nas duas versões.

### Detalhamento das diferenças

| Dimensão | v5 | v6 |
|---|---|---|
| Rota pública | `/acesso-rapido/{slug}` -> `QuickAccessController@index` | idem |
| Pasta das views do portal | `informacoes-prefeitura/acesso-rapido/` | `informacoes-instituicao/acesso-rapido/` |
| Controller dedicado | inexistente | inexistente |
| Código morto | `CommonQuestionsController` | `CommonQuestionsController` |
| Listagem no CMS | view SQL `perguntas_frequentes` | idem |
| Permissões | por categoria de conteúdo | por módulo `perguntas-frequentes` (id 25) + recurso homônimo |
| Atalho no menu do portal | gravado em `links`/`menu_items` | idem, com seed `AcessoRapidoSeeder` |
| Busca global | [NÃO VERIFICADO] na v5 | `perguntas-frequentes` incluído nos slugs buscáveis |
| API | inexistente | inexistente |
| Testes | inexistentes | inexistentes |