# Acesso Rápido — Resumo Executivo

> **Versão analisada:** `v6` (o módulo existe também na `v5`, com diferenças — ver `08-GAPS-E-DIVIDAS.md`)
> **Slug do módulo:** `acesso-rapido` (tabela `modulos`) — id `49`, nome "Seção de links rápidos"
> **Natureza:** Ambos (CMS para gerenciar os atalhos + Portal público para consumi-los)
> **Estado:** migrado v5 -> v6 (com renomeação de rotas/pastas de views)

---

## 1. Objetivo

O módulo "Acesso Rápido" é a seção de atalhos do portal municipal: um conjunto de
cartões/links de destaque que o cidadão clica para chegar rapidamente a serviços
informativos (Perguntas Frequentes, Central de Licitações, Ouvidoria, Manual de
Navegação, Solicitação de Informação, Acompanhe sua Solicitação). Ele serve de
**porta de entrada de alto tráfego** para as páginas de serviço do portal.

Do lado do CMS, o módulo é uma tela de CRUD de `contents` da categoria
`category_contents.slug = 'acesso-rapido'`, com ordenação por arrastar-e-soltar,
ativação/desativação e vínculo com um `link` (URL de destino).

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Atalhos visíveis na home do portal levam a serviços em 1 clique; o cidadão também acessa "Solicitar Informação" (e-SIC) e "Acompanhe sua solicitação" a partir do mesmo bloco. |
| Prefeitura (CMS) | operador cadastra/edita/ordena/ativa/desativa os atalhos; o texto exibido no card e o destino são editáveis sem deploy. |
| Transparência e legalidade | O atalho "Ouvidoria" redireciona para o fluxo de e-SIC (`/acessos-rapido/solicitar-informacao`), garantindo o canal de acesso à informação. |
| Operação técnica | O módulo depende do *layout ativo* (`Configuration.key = 'layout'`) e da existência de views por layout (`modelo1..modelo6` + `newsbit`); trocar de layout sem replicar as views quebra as rotas. |

## 3. Comportamento

- A home do portal só exibe o bloco se **duas** condições forem verdadeiras:
  `modulos['acesso-rapido']` estiver habilitado (tabela `modulos.status`) **e**
  `configurations.key = 'links_rapidos'` valer `'1'`
  (`v6/resources/views/portal/layouts/modelo1/home/acesso-rapido.blade.php`).
- Os itens exibidos são os `contents` da categoria `acesso-rapido` com
  `status = true`, ordenados por `contents.order` ascendente
  (`v6/app/Providers/ConfigHeaderServiceProvider.php:86-100`).
- O card renderiza `contents.title`, `contents.text`, `contents.icon` e o destino
  `links.link` (relacionamento 1-1 via `contents.linksUnique`).
- Duas famílias de URL pública existem, com prefixos diferentes:
  - `/acesso-rapido/{slug}` -> `QuickAccessController@index` (conteúdo de categoria);
  - `/acessos-rapido/{slug}` -> `QuickAccessController@getIndexStatic` (página estática).
- `index()` com slug `ouvidoria` **redireciona** para
  `url('/acessos-rapido/solicitar-informacao')`.
- `index()` com slug que não encontra nenhum `content` **cai** em
  `getIndexStatic()` (fallback automático conteúdo -> página estática).
- Páginas estáticas incrementam `static_pages.clicks` a cada acesso.
- O CMS lista os itens via DataTable server-side em `/cms/datatable/acesso_rapido`
  (view SQL `acesso_rapido`) e persiste a nova ordem via `POST /cms/ajax/ajust-banners`.

## 4. Como o Usuário Interage

**Cidadão (portal)**

1. Abre a home do portal e vê o bloco "Acesso Rápido" (cartões com ícone, título, descrição e botão "VEJA MAIS").
2. Clica no cartão -> navega para `links.link` (interno ou externo; `links.isBlank` define se abre em nova aba).
3. Ou digita diretamente `/acesso-rapido/perguntas-frequentes` e recebe a lista de perguntas com filtro client-side por digitação.
4. Em "Solicitar Informação" preenche o formulário (PF/PJ, contato, endereço, reCAPTCHA) e recebe um protocolo; em "Acompanhe sua solicitação" consulta o protocolo e recebe status, prazo e respostas.
5. "Manual de Navegação" exibe o texto da página e embute um `iframe` com `links.link`.

**Operador (CMS)**

1. `/cms/conteudos/acesso-rapido` -> listagem em DataTable (ID, Título, Ações).
2. Botão "Cadastrar Acesso Rápido" -> `/cms/conteudos/cadastrar/acesso-rapido` -> form (Título, Descrição, Ícone, URL, "Ativar no portal", "Abrir em nova guia").
3. Na listagem: botão de arrastar (reordena), botão liga/desliga (status), botão editar, botão excluir.
4. A exclusão é definitiva (`DELETE /cms/conteudo/delete/{id}`).

## 5. Detalhes e Particularidades Técnicas

- **Camadas:** `routes/web.php` -> `Portal\QuickAccessController` (traits `NewsTrait` + `GetInformationsPrefectureTrait`) -> `App\Prefecture\Content` / `StaticPage` / `Archive` / `Link` -> view Blade por layout.
- **Sem Repository/Service:** o controller do portal fala direto com os Models Eloquent. O CMS reaproveita o `Prefecture\ContentController` genérico (`genericIndex`/`genericCreate`/`genericEdit`) e o `Prefecture\DatatableController`.
- **Views SQL:** a listagem do CMS lê a view `acesso_rapido` (criada por migrations), que já aplica o filtro `cc.slug = 'acesso-rapido'` e o `row_number()`.
- **Acoplamento forte ao layout:** o prefixo de view `portal.layouts.{layout}.informacoes-instituicao.acesso-rapido.` é montado no construtor do controller.
- **Layout `newsbit` hardcoded:** o slug `solicitar-informacao` renderiza sempre `portal.layouts.newsbit.informacoes-instituicao.acesso-rapido.solicitar-informacao`, ignorando o layout ativo.
- **Dependência externa:** o bloco da home usa `Recaptcha::render()` (`v6/resources/views/portal/layouts/modelo1/informacoes-instituicao/acesso-rapido/solicitacao-form.blade.php`).

## 6. Estrutura de Dados

| Objeto | Natureza | Chave do módulo |
|---|---|---|
| `modulos` | tabela | `id = 49`, `slug = 'acesso-rapido'`, `status = true` |
| `resources` | tabela | `id = 69`, `slug = 'acesso-rapido'`, `modulo_id = 49` (permissoes `acesso-rapido.*`) |
| `menu_orders` | tabela | `id = 38`, `slug = 'acesso-rapido'`, `modulo_id = 49` (contador de cliques do CMS) |
| `category_contents` | tabela | `slug = 'acesso-rapido'` (categoria pai dos atalhos) |
| `contents` | tabela | `category_contents_id` -> categoria acima; colunas `title`, `text`, `icon`, `order`, `status`, `slug` |
| `links` | tabela | `contents_id` -> `contents.id`; colunas `link`, `isBlank`, `title` |
| `static_pages` | tabela | `slug` (`manual-de-navegacao`, `solicitar-informacao`, `acompanhe-sua-solicitacao`, `ouvidoria`) |
| `archives` | tabela | `static_pages_id` -> `static_pages.id` (arquivos para download) |
| view `acesso_rapido` | view SQL | `value`, `titulo`, `id`, `status_name`, `status` |

## 7. Como Testar

- Portal: abrir `/acesso-rapido/perguntas-frequentes` (deve listar perguntas),
  `/acesso-rapido/solicitar-informacao` (formulário e-SIC),
  `/acesso-rapido/ouvidoria` (deve redirecionar para `/acessos-rapido/solicitar-informacao`),
  `/acessos-rapido/manual-de-navegacao` (página estática).
- CMS: `/cms/conteudos/acesso-rapido` (listagem), criar item, arrastar para reordenar,
  alternar status, editar e excluir.
- Verificar no banco que `static_pages.clicks` incrementa a cada visita de página estática.

## 8. Migração para Laravel Moderno

Modelar `QuickLink` como model próprio (não reaproveitar `contents`), com `title`,
`description`, `icon`, `url`, `is_blank`, `position`, `is_active`; tabela de
`CategoryContent` deixa de ser necessária. Endpoints REST `/api/quick-links` com
`ApiResource`, `FormRequest` para validação, `Policy` para `acesso-rapido.*`
(traduzindo `has_access` para `Gate::allows`), e componentes Blade
`<x-portal.quick-links />` com cache por layout. A resolução de layout deve passar a
ser injetada (container/`ViewFactory`) em vez de lida do banco dentro do controller.

## 9. Resumo Geral

O módulo "Acesso Rápido" é um conjunto de atalhos configuráveis pelo CMS e renderizado
na home do portal. O dado mora em `contents` (categoria `acesso-rapido`) + `links`
(URL de destino); a listagem do CMS usa a view SQL `acesso_rapido` e um DataTable
server-side com ordenação por drag-and-drop. O portal expõe duas rotas de prefixos
diferentes (`/acesso-rapido` para conteúdo e `/acessos-rapido` para página estática),
com fallback automático da primeira para a segunda. Os maiores riscos técnicos são o
acoplamento ao nome do layout ativo, o uso do layout `newsbit` fixo no fluxo de
solicitação de informação, o `Route::any` permissivo nas rotas e a checagem de
"conteúdo não encontrado" feita **depois** do uso da variável. Ao reconstruir,
o módulo deve virar um CRUD dedicado com policy, resource JSON e cache de leitura,
preservando os destinos `/acesso-rapido/*` e `/acessos-rapido/*` por compatibilidade
de links externos.

---

## Í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 |