# Manual do Sistema — Gaps, Dívidas e Divergências v5 → v6

> Módulo **novo na v6**. O levantamento abaixo cobre os problemas
> introduzidos na criação do módulo.

---

## 1. Bugs e erros conhecidos

| Sev. | Item | Arquivo / linha |
|---|---|---|
| **CRÍTICO** | O recurso `manual-usuario` **não existe** em `resources` → o módulo é inacessível a qualquer perfil que não seja `super-admin` | `v6/database/seeds/ManualDoSistemaResourceSeeder.php` (não executado) |
| **ALTO** | `check.route.permission` libera `store`/`update`/`destroy` → qualquer usuário autenticado pode alterar manuais e áreas | `v6/app/Http/Middleware/CheckRoutePermission.php:48-52,82-90` |
| **ALTO** | `ManualController@update` usa `Request` genérico → **nenhuma validação** na edição | `v6/app/Http/Controllers/Prefecture/ManualController.php:110` |
| **ALTO** | `Repository::upInsert` faz `dd($th)` → vaza a exceção na tela em vez de retornar erro | `v6/app/Repositories/Repository.php:64-71` |
| **ALTO** | XSS armazenado: a descrição da área é impressa com `echo` sem escape | `v6/resources/views/prefecture/configurations/manual-usuario/show.blade.php:57` |
| **MÉDIO** | Exclusão de manual por **GET** (`/cms/manual/delete/{id}`) | `v6/routes/basepro.php:227` |
| **MÉDIO** | `manual-usuario.destroy` (rota gerada) aponta para método inexistente → 500 | `v6/routes/basepro.php:211` |
| **MÉDIO** | `manual-area.create` e `manual-area.show` (rotas geradas) não têm método → 500 | `v6/routes/basepro.php:212` |
| **MÉDIO** | Excluir uma área **não** remove o arquivo em disco nem o registro em `archives` | `v6/app/Http/Controllers/Prefecture/ManualAreaController.php:85-93` |
| **MÉDIO** | `ManualAreaController@index` devolve **todas** as áreas do sistema (sem filtro por manual) | `v6/app/Http/Controllers/Prefecture/ManualAreaController.php:25-28` |
| **MÉDIO** | `manual_areas` sem `onDelete` nas FKs → áreas órfãs | `v6/database/migrations/2023_01_20_163012_create_manual_areas_table.php` |
| **MÉDIO** | Item de menu aparece mesmo com o módulo desativado (sem guarda `$modulos[...]`) | `v6/resources/views/vendor/adminlte/page.blade.php:294-301` |
| **MÉDIO** | Nenhum registro em `activity_log` para as operações do módulo | `v6/app/Http/Controllers/Prefecture/ManualController.php` |
| **BAIXO** | `ManualAreaRepository::upInsert` tem retornos inconsistentes (`true`/`null`/`false`) | `v6/app/Repositories/Eloquent/Prefecture/ManualArea/ManualAreaRepository.php:47-79` |
| **BAIXO** | `str_replace('storage', '', ...)` remove todas as ocorrências da substring | `v6/app/Repositories/Eloquent/Prefecture/Archive/ArchiveRepository.php:23` |
| **BAIXO** | `ManualAreaController` devolve Eloquent cru (sem API Resource), expondo `deleted_at` e `manual_id` | `v6/app/Http/Controllers/Prefecture/ManualAreaController.php:25-60` |
| **BAIXO** | Factories apontam para `App\Manual` / `App\ManualArea` (classes inexistentes) e não definem atributos | `v6/database/factories/ManualFactory.php`, `ManualAreaFactory.php` |
| **BAIXO** | Migration com nome enganoso: `2023_01_27_104631_add_area_to_manual_areas.php` altera `diario_areas` | `v6/database/migrations/2023_01_27_104631_add_area_to_manual_areas.php` |
| **BAIXO** | Dados (20+ manuais) criados dentro de uma **migration** | `v6/database/migrations/2023_02_01_083626_add_itens_to_archives.php` |
| **BAIXO** | `index()` ordena por `created_at` e a view reordena por título (ordem do controller inútil) | `v6/app/Http/Controllers/Prefecture/ManualController.php:38` |
| **BAIXO** | Títulos são a chave de negócio; `ManuaisSinergiaSeeder` renomeia e quebra a associação dos seeders | `v6/database/seeds/ManuaisSinergiaSeeder.php:49-53` |
| **BAIXO** | O item de menu do AdminLTE não tem guarda de permissão (aparece para todos) | `v6/resources/views/vendor/adminlte/page.blade.php:294-301` |

---

## 2. Funcionalidades incompletas ou mortas

| Item | Situação |
|---|---|
| `ManualController@destroy` | Não existe; a rota gerada aponta para ele |
| `ManualAreaController@create` / `@show` | Não existem; as rotas geradas apontam para eles |
| `manuals.url_portal` | Gravado e exibido, mas **nada no portal** consome a tabela `manuals` |
| `manuals.url_cms` | idem |
| `ManualDoSistemaResourceSeeder` | Seeder escrito, **nunca executado** na base |
| Auditoria (`activity()`) | Nenhuma operação do módulo é registrada |
| Versão/histórico do manual | Inexistente; editar sobrescreve |
| Remoção do arquivo ao substituir a imagem | Inexistente (o arquivo antigo fica no disco) |

---

## 3. Mapa v5 → v6

O módulo **não existe na v5**. Tudo abaixo é novidade da v6.

| Aspecto | v5 | v6 |
|---|---|---|
| Controller | inexistente | `Prefecture\ManualController` (140 linhas) |
| Controller de áreas | inexistente | `Prefecture\ManualAreaController` (94 linhas) |
| Models | inexistentes | `App\Http\Model\Prefecture\Manual`, `ManualArea` |
| Repositories | inexistentes | `IManualUsuarioRepository`/`ManualUsuarioRepository`, `IManualAreaRepository`/`ManualAreaRepository` |
| Request | inexistente | `ManualSistemaRequest` (só no `store`) |
| Tabelas | inexistentes | `manuals`, `manual_areas` (migrations de 2023-01-20) |
| Views | inexistentes | `prefecture/configurations/manual-usuario/**` (6 arquivos) |
| JS | inexistente | `public/assets/js/custom/contents/manual-sistema/areas.js` |
| Seeds | inexistentes | `UpdateManualAreas`, `UpdateManualAreasDiarioSeeder`, `ManuaisSinergiaSeeder`, `ManualDoSistemaResourceSeeder` |
| Registro de módulos | inexistente | `modulos` (id 8) — o módulo passa a ser "ligável/desligável" |
| Recurso em `resources` | inexistente | deveria existir (`manual-usuario`, modulo_id 8) — **ausente** |

**Conclusão:** módulo novo, com arquitetura coerente com o restante do
CMS (Repository + Model), mas entregue **incompleto**: falta o recurso que
habilita a autorização por perfil, falta validação na edição, e a
exclusão foi implementada por `GET`.

---

## 4. Riscos de dados (migração de schema)

| Risco | Detalhe | Mitigação |
|---|---|---|
| Títulos como identificador | `ManuaisSinergiaSeeder` renomeia títulos | adicionar `slug` e migrar as áreas por id |
| Áreas órfãs | soft delete do manual não remove as áreas | FK com `onDelete('cascade')` + limpeza periódica |
| Arquivos órfãos | exclusão de área não apaga o arquivo | deletar o arquivo no `destroy` + job de varredura |
| `archives` órfãos | idem | deletar o registro junto |
| HTML não sanitizado | conteúdo atual pode conter `<script>` | re-sanitizar no backfill |
| Dados em migration | `migrate:fresh` recria os manuis com títulos antigos | mover para seeder versionado |
| Slug duplicado em `manuals` | `Str::slug` pode colidir ("Manual de A Cidade" x "Manual da Cidade") | índice único com desempate por id |

---

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

1. **O manual deve ser publicado no portal?** As colunas `url_portal` e
   `url_cms` indicam a intenção, mas não há implementação. Se for SIM, é
   um escopo adicional (página pública, busca, índice por módulo).
2. **Quem é o responsável por manter os manuais?** Hoje, na prática,
   apenas `super-admin`.
3. **Deve existir versioning?** Um manual que muda de layout invalidate
   as capturas de tela antigas.
4. **O "Manual de Navegação" do portal deve migrar para esta estrutura?**
   Hoje é uma página estática independente — unificar evitaria duas fontes
   de verdade.
5. **A exclusão deve ser definitiva?** Hoje é soft delete, mas as áreas
   e os arquivos permanecem.
6. **O texto do objetivo é suficiente ou deve haverrich text?** Hoje é um
   `textarea` simples; as áreas aceitam HTML.
7. **É preciso um vínculo oficial com `modulos`?** Se sim, uma FK
   `module_id` e a desduplicação automática de títulos.

---

## 6. Checklist de correção (priorizado)

| Prioridade | Item | Arquivo |
|---|---|---|
| P0 | Executar/garantir o recurso `manual-usuario` (seeder idempotente) | `v6/database/seeds/ManualDoSistemaResourceSeeder.php` |
| P0 | Corrigir o middleware `check.route.permission` | `v6/app/Http/Middleware/CheckRoutePermission.php:48-52` |
| P0 | Sanitizar a descrição da área (escrita e leitura) | `v6/resources/views/prefecture/configurations/manual-usuario/show.blade.php:57` |
| P0 | Trocar `Repository::upInsert` para logar e retornar erro em vez de `dd($th)` | `v6/app/Repositories/Repository.php:64-71` |
| P1 | Usar `ManualSistemaRequest` no `update` | `v6/app/Http/Controllers/Prefecture/ManualController.php:110` |
| P1 | Trocar a exclusão de GET para DELETE | `v6/routes/basepro.php:227` |
| P1 | Adicionar `StoreManualAreaRequest` com validação | `v6/app/Http/Controllers/Prefecture/ManualAreaController.php:36` |
| P1 | Remover o arquivo e o `archives` ao excluir uma área | `v6/app/Http/Controllers/Prefecture/ManualAreaController.php:85` |
| P2 | Filtrar `manual-area.index` por manual (ou remover a rota) | `v6/app/Http/Controllers/Prefecture/ManualAreaController.php:25` |
| P2 | Implementar `destroy` no `ManualController` ou remover a rota | `v6/app/Http/Controllers/Prefecture/ManualController.php` |
| P2 | Implementar `create`/`show` no `ManualAreaController` ou remover as rotas | `v6/app/Http/Controllers/Prefecture/ManualAreaController.php` |
| P2 | Adicionar guarda `$modulos['manual-do-sistema']` no menu | `v6/resources/views/vendor/adminlte/page.blade.php:294` |
| P2 | Registrar auditoria (`activity()`) nas operações | ambos os controllers |
| P3 | Reescrever as factories | `v6/database/factories/ManualFactory.php`, `ManualAreaFactory.php` |
| P3 | Mover os dados da migration para um seeder | `v6/database/migrations/2023_02_01_083626_add_itens_to_archives.php` |
| P3 | Renomear a migration enganosa | `v6/database/migrations/2023_01_27_104631_add_area_to_manual_areas.php` |
| P3 | Adicionar `slug`/`module_id` a `manuals` | nova migration |