# Perguntas Frequentes — Resumo Executivo

> **Versão analisada:** `v6` (módulo idêntico em `v5`)
> **Slug do módulo:** `perguntas-frequentes` (tabela `modulos`, id 25) — categoria de conteúdo
> `category_contents.slug = 'perguntas-frequentes'` (id 12)
> **Natureza:** CMS (painel administrativo) + Portal (público)
> **Estado:** OK v6 com feature morta (`CommonQuestionsController` sem rota)

---

## 1. Objetivo

O módulo publica as **Perguntas Frequentes** do município: um conjunto curado de
perguntas e respostas (na instalação de demonstração, perguntas sobre a Lei de
Acesso à Informação) que o cidadão consulta para resolver dúvidas comuns sem
protocolar requerimento. O operador mantém cada pergunta/Resposta no CMS, na
categoria `perguntas-frequentes`, e o portal as exibe na página de **Acesso Rápido**
(`/acesso-rapido/perguntas-frequentes`).

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Página `/acesso-rapido/perguntas-frequentes` com lista de perguntas e respostas, campo de filtro instantâneo (client-side) e link permanente no bloco "Acesso Rápido". |
| Prefeitura (CMS) | Menu "Perguntas Frequentes" (`/cms/conteudos/perguntas-frequentes`) com DataTable, cadastro e edição de itens (Título = pergunta, Texto = resposta). |
| Transparência e legalidade | FAQ é conteúdo institucional público e participates da busca global do portal (`/buscar`). |
| Operação técnica | Não há controller público dedicado: a página é servida pelo `QuickAccessController` (rotas de "acesso rápido"). O `CommonQuestionsController` existe mas é código morto. |

## 3. Comportamento

- O portal resolve `/acesso-rapido/{slug}` -> `Portal\QuickAccessController@index`
  (`v6/routes/web.php:88-89`).
- `QuickAccessController@index` busca os conteúdos da categoria pelo slug **sem filtro de
  status**: `getContentByCategory($slug1)` -> `Content::whereHas('categoryContents', fn ($q) => $q->where('slug', $param))->get()`
  (`v6/app/Http/Traits/GetInformationsPrefectureTrait.php:28-33`).
- Se não houver nenhum conteúdo na categoria, o controller cai no **fallback de página
  estática** (`getIndexStatic`), que procura um registro em `static_pages` com o mesmo slug.
- Cada item renderiza `title` como pergunta e `text` como resposta (HTML), prefixado por
  "**R.**" na view.
- O filtro de texto é feito no navegador, sobre o `<li>` já renderizado.
- O CMS lista os itens pela **view SQL `perguntas_frequentes`** (`value`, `titulo`, `id`).
- O formulário do CMS expõe apenas **Título** e **Resposta**; não há status, ordem ou
  data de publicação.

## 4. Como o Usuário Interage

**Operador (CMS)**

| Tela | Rota | Ação |
|---|---|---|
| Lista | `/cms/conteudos/perguntas-frequentes` | DataTable `#tabela_perguntas_frequentes`; botão "Cadastrar Pergunta"; exclusão em lote |
| Cadastro | `/cms/conteudos/cadastrar/perguntas-frequentes` | Título + Resposta |
| Edição | `/cms/conteudos/editar/perguntas-frequentes/{id}` | Idem, via `Form::model` |

**Cidadão (portal)**

- `/acesso-rapido/perguntas-frequentes`: cartão "Perguntas Frequentes", campo "Digite para
  filtrar:", lista de perguntas com respostas.
- Busca global: a categoria `perguntas-frequentes` é um dos filtros da página `/buscar`.

## 5. Detalhes e Particularidades Técnicas

- Camadas: `Route (web.php)` -> `QuickAccessController@index` -> `GetInformationsPrefectureTrait::getContentByCategory`
  -> `App\Prefecture\Content` -> `contents`.
- CMS: `Route (basepro.php)` -> `ContentController@genericIndex/genericGenerate` ->
  `ContentRequest` -> `Content`; listagem via `DatatableController@get_perguntas_frequentes`
  -> view SQL `perguntas_frequentes`.
- Dependências: `yajra/laravel-datatables-oracle`, jQuery, `laravelcollective/html`,
  `cartalyst/sentinel` (permissões `perguntas-frequentes.*`).
- **Código morto**: `v6/app/Http/Controllers/Portal/CommonQuestionsController.php` não tem
  rota registrada e a view que ele renderiza (`portal.layouts.default.pages.common-questions`)
  não existe na `v6`.

## 6. Estrutura de Dados

| Objeto | Detalhe |
|---|---|
| `contents` | Pergunta em `title`, resposta em `text`, `category_contents_id = 12` |
| `category_contents` | id 12, `name = 'Perguntas Frequentes'`, `slug = 'perguntas-frequentes'` |
| view `perguntas_frequentes` | `value` (row_number), `titulo`, `id` — usada só pelo CMS |
| `modulos` | id 25, `status = 1` |
| `resources` | `slug = 'perguntas-frequentes'`, `modulo_id = 25` |
| `links` | seed do "Acesso Rápido" apontando para `/acesso-rapido/perguntas-frequentes` |

## 7. Como Testar

- CMS: cadastrar pergunta, listar, editar, excluir.
- Portal: abrir `/acesso-rapido/perguntas-frequentes`, filtrar por texto, conferir que a
  pergunta aparece no card e que o breadcrumb está correto.
- Fallback: esvaziar a categoria e confirmar que a página estática assume.
- Busca: pesquisar um trecho da resposta em `/buscar`.

## 8. Migração para Laravel Moderno

Criar `FaqQuestion`/`FaqAnswer` (ou `FaqItem` com `question`/`answer`), `FormRequest` com
`question` e `answer` obrigatórios, `FaqPolicy`, `GET /api/v1/perguntas-frequentes`,
componente Blade único `<x-faq.lista>` (hoje duplicado em 7 arquivos) e um controller
dedicado `FaqController@index` no lugar do `QuickAccessController` genérico.

## 9. Resumo Geral

As Perguntas Frequentes são conteúdo genérico (`contents`) na categoria
`category_contents.id = 12`. Ao contrário do Glossário, **não existe rota nem controller
público próprio**: a página é montada pelo `QuickAccessController`, que lista os itens da
categoria e, se não houver nenhum, delega a uma página estática. A listagem do CMS usa a
view SQL `perguntas_frequentes` e o formulário só expõe "Título" (pergunta) e "Texto"
(resposta). O `CommonQuestionsController` é código morto (sem rota e sem view), e a
filtração da lista acontece no navegador, sobre o HTML já entregue.

---

## Í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, resources |
| `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 |