# Manual do Sistema — Resumo Executivo

> **Versão analisada:** `v6` (módulo **novo** na v6; não existe na v5)
> **Slug do módulo:** `manual-do-sistema` (tabela `modulos`, id 8, `status = true`)
> **Natureza:** CMS (painel administrativo)
> **Estado:** novo na v6

---

## 1. Objetivo

Manter a **documentação interna do CMS**: para cada módulo do sistema
(Notícias, Licitações, Diário Oficial, Ouvidoria...), um registro de manual
com título, objetivo, links para a tela equivalente no portal e no CMS, e
**áreas** — subseções com imagem de destaque e descrição, que funcionam
como um tutorial visual da funcionalidade.

O objetivo final é reduzir a curva de aprendizado dos operadores do painel
e servir de referência de migração para os clientes.

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Nenhum efeito direto. |
| Prefeitura (CMS) | Dá ao operador uma referência interna por módulo, com telas ilustradas. |
| Transparência e legalidade | Não se aplica diretamente. |
| Operação técnica | Documenta o próprio sistema, serve de referência para a reconstrução da v7. |

## 3. Comportamento

- Um **manual** tem: `titulo` (obrigatório), `objetivo` (obrigatório),
  `url_portal` (opcional) e `url_cms` (opcional).
- Um manual tem **n áreas** (`manual_areas`), cada uma com `titulo`,
  `descricao` (HTML do Summernote) e um **arquivo de destaque**
  (`archive_id` -> tabela `archives`), exibido como imagem ampliada
  (lightgallery) na tela de detalhe.
- A listagem (`/cms/manual-usuario`) mostra os manuais em um **índice**
  ordenado alfabeticamente por título.
- A edição acontece na **mesma** view de criação (`create.blade.php`): o
  controller `edit()` renderiza `manual-usuario.create` com o registro.
- As áreas são gerenciadas por **AJAX**: `GET /cms/manual/get/{id}` lista,
  `POST|PUT /cms/manual-area` grava, `DELETE /cms/manual-area/{id}` exclui.
- A exclusão do manual inteiro é feita por `GET /cms/manual/delete/{id}`
  (operação destrutiva por GET).
- **O módulo está inacessível para operadores comuns**: o recurso
  `manual-usuario` **não existe** na tabela `resources`, logo a permissão
  `manual-usuario.index` não pode ser concedida e o middleware
  `check.route.permission` só libera `super-admin`.

## 4. Como o Usuário Interage

- Menu do AdminLTE (menu de engrenagem): item **"Manual do Sistema"**
  (`v6/resources/views/vendor/adminlte/page.blade.php:294-301`).
  O item **não** tem guarda de módulo nem de permissão — aparece para
  qualquer usuário autenticado (e leva a um redirect de "sem autorização"
  para quem não tem a permissão).
- `/cms/manual-usuario`: índice com os manuais cadastrados.
- Botão "Cadastrar Manual do Sistema" — só aparece com
  `has_access('manual-usuario.create')` (na prática, só para
  `super-admin`).
- Formulário: Título, URL no Portal, URL no CMS, Objetivo do Módulo.
  Ao editar, a mesma tela carrega a lista de **Áreas**.
- Modal "Cadastrar Nova Área": Título, descrição (Summernote) e upload de
  imagem de destaque.
- Tela de detalhe (`/cms/manual-usuario/{id}`): objetivo, links e as áreas
  com as imagens em lightgallery.

## 5. Detalhes e Particularidades Técnicas

- Camadas: `Route` -> `check.route.permission` ->
  `Prefecture\ManualController` / `Prefecture\ManualAreaController` ->
  `IManualUsuarioRepository` / `IManualAreaRepository` ->
  `App\Http\Model\Prefecture\Manual` / `ManualArea` -> `manuals` /
  `manual_areas` / `archives`.
- O `ManualAreaController` usa `IArchiveRepository` para registrar o
  arquivo de destaque egravá-lo em
  `storage/app/public/manual-usuario/area/{id}/destaque/`.
- A listagem de manuais é feita por Eloquent
  (`$this->table->orderBy('created_at')->get(['id','titulo'])`) — a ordenação
  por `created_at` é **invertida** na view, que reordena por título.
- Não há auditoria (`activity()`) neste módulo.
- Dependências: `laravelcollective/html`, Summernote, lightgallery,
  Yajra DataTables (apenas para a tabela de áreas, montada à mão no JS).

## 6. Estrutura de Dados

| Tabela | Papel |
|---|---|
| `manuals` | Um manual por módulo do sistema |
| `manual_areas` | Áreas (subseções) de um manual |
| `archives` | Arquivo de destaque da área (imagem) |
| `resources` | Deveria ter o recurso `manual-usuario` (modulo_id 8) — **ausente na base** |
| `modulos` | Registro de módulos (id 8 = `manual-do-sistema`) |

Views SQL: nenhuma.

Seeds: a migration `v6/database/migrations/2023_02_01_083626_add_itens_to_archives.php`
**cria os manuais** (20+ registros) dentro de uma migration; os seeders
`UpdateManualAreas.php`, `UpdateManualAreasDiarioSeeder.php` e
`ManuaisSinergiaSeeder.php` ajustam títulos e criam áreas.

## 7. Como Testar

- `super-admin` em `/cms/manual-usuario` deve ver o índice.
- `super-admin` em `/cms/manual-usuario/create` deve poder criar um manual
  com título e objetivo; sem título, erro de validação.
- Após criar, o sistema redireciona para
  `manual-usuario.edit/{id}` (mesma tela de create).
- Adicionar uma área via modal deve fazer `POST /cms/manual-area` e
  recarregar a tabela de áreas.
- Um operador **sem** `manual-usuario.index` deve ser redirecionado com
  "Você não tem autorização para acessar esta funcionalidade!".

## 8. Migração para Laravel Moderno

- Modelos `Manual` e `ManualArea` enxutos, com `casts` para `descricao`
  (HTML) e relacionamentos `hasMany`/`hasOne`.
- `StoreManualRequest` / `UpdateManualRequest` com regras
  (`titulo` required, `objetivo` required, `url_portal`/`url_cms` nullable
  url).
- `ManualPolicy` (view/create/update/delete) no lugar do middleware.
- `ManualAreaController` como API REST (`/api/manuals/{manual}/areas`) com
  `POST` multipart para o upload.
- `Storage` com disk `public` e `UploadedFile::storeAs`.
- Componente Blade `<x-manual-areas>` com Alpine/Livewire, dispensando o
  JS imperativo atual.

## 9. Resumo Geral

"Manual do Sistema" é a documentação interna do CMS: cada módulo do
sistema tem um manual com objetivo, links para o portal e para o CMS, e
subseções ("áreas") com imagem de destaque e descrição. A implementação
segue o padrão Repository do legado (`IManualUsuarioRepository`,
`IManualAreaRepository`) e usa `check.route.permission` como única
proteção. O principal problema do módulo é de **acesso**: o recurso
`manual-usuario` (modulo_id 8) não existe na tabela `resources`, o que
impede a concessão da permissão `manual-usuario.index` e deixa o módulo
restrito ao `super-admin` — apesar de o item de menu aparecer para todos.
Somam-se a isso a ausência de validação no `update` (que usa `Request` em
vez de `ManualSistemaRequest`), a exclusão por GET
(`/cms/manual/delete/{id}`), duas rotas de resource geradas sem método
correspondente (`manual-area.create` e `manual-area.show`) e a criação dos
manuais dentro de uma *migration*, o que mistura schema e dado.

---

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