# Manual do Sistema — Regras e Portabilidade > Regras de negócio não óbvias, acoplamentos e armadilhas do módulo. --- ## 1. Regras de negócio não óbvias ### 1.1 Um manual por módulo do sistema, mas sem vínculo formal O padrão de conteúdo é "um manual por módulo": "Manual de Notícias", "Manual de Licitações", "Manual do Diário Oficial"... Os títulos seguem os slugs dos módulos, mas **não existe** FK entre `manuals` e `modulos`. O vínculo é apenas convencional (humano). ### 1.2 O título é a chave de negócio Os seeders localizam manuais por título exato: ```php $manual_noticias = DB::table('manuals')->where('titulo', 'Manual de Notícias')->value('id'); ``` O `ManuaisSinergiaSeeder` ainda **renomeia** títulos (`$oldTitle => $newTitle`). Isso significa que renomear um manual no CMS **quebra** a associação feita pelos seeders — as áreas órfãs ficam sem manual. Não há `slug` estável. ### 1.3 A edição e a criação compartilham a mesma view `ManualController@edit()` renderiza `manual-usuario.create` com `$data`. Por isso o `form.blade.php` está cheio de ternários `isset($data) ? ... : ...`, e o bloco de áreas só aparece na edição. ### 1.4 A área é o "print" da funcionalidade Cada área guarda **uma imagem de destaque** (o `archive_id`) e uma **descrição** em HTML. A imagem é o print da tela que o manual documenta; a descrição explica o passo a passo. A imagem é opcional (`archive_id` é nullable), a descrição também. ### 1.5 Os links `url_portal` e `url_cms` são apenas atalhos São gravados e exibidos na tela de detalhe, mas **nada** no portal público lê a tabela `manuals`. O "Manual de Navegação" do portal é uma página estática, sem relação. ### 1.6 A exclusão de um manual é em cascata (no banco) `manuals` tem FK de `manual_areas.manual_id` **sem** `onDelete`. Ao excluir um manual (`Manual::destroy($id)` — soft delete), as áreas permanecem no banco, apontando para um manual "apagado" (soft deleted). Elas continuam invisíveis na listagem (que parte do manual), mas órfãs no banco. ### 1.7 O módulo não é auditado Nenhum `activity()` é chamado neste módulo. Criar, editar e excluir manuais **não** deixa rastro em `activity_log`. --- ## 2. Acoplamentos ### 2.1 Dependências de saída | Dependência | Tipo | Onde | |---|---|---| | `IManualUsuarioRepository` / `IManualAreaRepository` | interno | controllers | | `IArchiveRepository` | interno | `ManualAreaRepository` | | `AppTrait` / `FileTrait` | interno | repositories | | `check.route.permission` | interno | autorização | | `archives` | interno | imagem de destaque | | `resources` / `modulos` | interno | permissão (quebrada) | | Summernote, lightgallery | asset | descrição e zoom | ### 2.2 Dependências de entrada | Consumidor | Dependência | Risco | |---|---|---| | Menu do AdminLTE | `route('manual-usuario.index')` | item de menu para todos | | `resources` (ausente) | permissão `manual-usuario.*` | módulo inacessível a não-super-admin | | Nenhum consumidor do portal | — | — | > O módulo é **folha**: ninguém depende dele. Isso o torna seguro de > reescrever. --- ## 3. Armadilhas ### 3.1 [CRÍTICO] O recurso `manual-usuario` não existe em `resources` O seeder `v6/database/seeds/ManualDoSistemaResourceSeeder.php` criaria o recurso com `modulo_id = 8`, mas **a linha não está na base**. Como o catálogo `resources` é a fonte das permissões concedíveis, nenhuma chave `manual-usuario.*` pode ser atribuída a um perfil. Efeito combinado com o middleware: 1. `check.route.permission` avalia `hasAnyAccess(['manual-usuario.index', ...])`; 2. a chave não existe em nenhum perfil → **negado**; 3. apenas `super-admin` passa (bypass). Resultado: o módulo é **inoperante** para qualquer operador que não seja `super-admin`, embora o item de menu apareça no CMS. ### 3.2 [ALTO] `check.route.permission` libera `store`/`update`/`destroy` `v6/app/Http/Middleware/CheckRoutePermission.php:48-52,82-90` — o `in_array($value, $resourceRoutes)` compara com os **valores** do array (`update`, `store`, `destroy`). Como `$accessArr` são os segmentos do nome da rota, e toda rota de resource tem nome `xxx.store`/`xxx.update`/ `xxx.destroy`, o middleware retorna `true` **sem checar permissão**. Consequências específicas deste módulo: - `POST /cms/manual-usuario` (`manual-usuario.store`) — **liberado**; mas usa `ManualSistemaRequest` (valida) e o `filter_request`/`$fillable` limitam o que é gravado. - `PUT /cms/manual-usuario/{id}` (`manual-usuario.update`) — **liberado**; e **não valida** nada (`Request` genérico). Um usuário autenticado qualquer pode sobrescrever o objetivo de um manual. - `DELETE /cms/manual-area/{id}` (`manual-area.destroy`) — **liberado**; apaga a área (e deixa o arquivo órfão em disco). - `POST /cms/manual-area` (`manual-area.store`) — **liberado**; cria área. ### 3.3 [ALTO] `ManualController@update` não valida `v6/app/Http/Controllers/Prefecture/ManualController.php:110` recebe `Request $request` em vez de `ManualSistemaRequest`. Um `PUT` sem `titulo`/`objetivo` chega ao banco e viola `NOT NULL` — o `Repository::upInsert` captura o `Throwable` e chama **`dd($th)`** (`v6/app/Repositories/Repository.php:64-71`), **vazando a exceção** na página em vez de retornar um erro treated. ### 3.4 [ALTO] `Repository::upInsert` faz `dd($th)` ```php public function upInsert($request, int $id = null) { try { $data = DB::transaction(function () use ($request, $id) { return $this->structureUpInsert($this->dataTrait($request)); }); return $this->getModel()->updateOrCreate(['id' => $id], $data); } catch (\Throwable $th) { dd($th); } return false; } ``` `dd()` mata a requisição com um dump da exceção. Não há retorno de erro nem log. Isso afeta **todos** os módulos que usam o `Repository` abstrato (conteúdos, licitações, contratos, fornecedores, e-vacina, ...). ### 3.5 [MÉDIO] Exclusão por GET `GET /cms/manual/delete/{id}` executa `Manual::destroy($id)`. Uma operação destrutiva por GET é acionada por link, sem confirmação e sem proteção CSRF (o CSRF protege POST/PUT/DELETE). A view usa `bootstrap-confirmation` apenas para o botão de exclusão da área. ### 3.6 [MÉDIO] XSS armazenado na descrição da área `v6/resources/views/prefecture/configurations/manual-usuario/show.blade.php` renderiza: ```blade @php echo ($area->descricao) @endphp ``` O conteúdo vem do Summernote (HTML livre) e é impresso **sem escape**. Qualquer usuário com acesso à edição de área consegue injetar `