# Obras Paralisadas — Regras e Portabilidade > Módulo **existente apenas na v5**. --- ## 1. Regras de negócio observáveis | # | Regra | Onde está implementada | |---|---|---| | R1 | Os quatro campos de texto são **obrigatórios**; os anexos são opcionais. | `v5/app/Http/Requests/ObraParalisadaRequest.php` | | R2 | Anexos devem ser **PDF** com no máximo **10 MB** cada. | regra `file\|mimes:pdf\|max:10240` | | R3 | Anexos são **múltiplos** e cada um pode ter uma descrição de até 255 caracteres. | campos `arquivo[]` e `arquivo_desc[]` | | R4 | A exclusão do registro é **lógica**; o registro some do CMS e do portal mas permanece no banco. | `SoftDeletes` no model | | R5 | O anexo pode ser removido **individualmente**, por posição. | `destroyArquivo($id, $index)` | | R6 | Ao editar, os anexos **novos são somados** aos existentes; os existentes são preservados na ordem original. | `update()` do controller | | R7 | A listagem pública é **ordenada alfabeticamente** por `identificacao`. | `buildQuery()` | | R8 | A paginação pública é de **15 registros** por página. | `$query->paginate(15)` | | R9 | A busca cobre `identificacao` **ou** `motivo_paralisacao` (OR). | `buildQuery()` | | R10 | A exportação usa **todos** os registros filtrados, sem paginação. | `$allData` | | R11 | Somente `csv`, `xls` e `txt` são aceitos como `type`; qualquer outro valor devolve 404. | `exportar()` | | R12 | O PDF é gerado no **navegador** e cobre todos os registros filtrados. | `gerar-pdf-obras-paralisadas.js` | | R13 | O portal só mostra os botões de exportação quando há ao menos um registro. | `$result->isNotEmpty()` | | R14 | O slug público é `str_slug(identificacao . '-' . id)` e é **recalculado** a cada edição. | hooks `created`/`updating` do model | | R15 | O botão "Cadastrar" e os botões por linha dependem de permissões (`obra-paralisada.create/edit/delete`, resolvidas para `obras.*`). | `has_access()` + `struct_views()` | ## 2. Regras implícitas e efeitos colaterais ### 2.1 Slug dependente do identificador ```php static::updating(function ($model) { $model->slug = str_slug($model->identificacao . '-' . $model->id); }); ``` - Editar "Obra da Praça Central" para "Obra da Praça Central - Fase 2" troca a URL pública de `/obra-paralisada/obra-da-praca-central-12` para `/obra-paralisada/obra-da-praca-central-fase-2-12`. - Links já diffusionados (imprensa, redes sociais) passam a responder **404**, porque `show()` faz `where('slug', $slug)->firstOrFail()`. - Como o `id` entra no slug, dois registros com a mesma `identificacao` coexistem sem colisão. Não há, porém, **índice único** em `slug`: a unicidade é apenas convenção do código. ### 2.2 `created` com `save()` dentro do evento ```php static::created(function ($model) { $model->slug = str_slug($model->identificacao . '-' . $model->id); $model->save(); }); ``` - Cada criação dispara **um INSERT + dois UPDATE** (o `save()` dentro de `created` dispara `updating`, que recalcula o mesmo slug, e persiste). - O segundo `save()` também **reescreve `updated_at`**, então `updated_at` fica praticamente igual a `created_at` no momento da criação. - Se `identificacao` for alterado para vazio após a criação, o slug passa a ser apenas `"-{id}"` → `str_slug` remove o hífen inicial e devolve `"12"`. ### 2.3 Normalização dupla da busca ```php $inner->whereRaw("translate(lower(identificacao), ' ''àáâãäéèëêíìïîóòõöôúùüûçÇ', '--aaaaaeeeeiiiiooooouuuucc') ilike ?", ['%' . clean_slug($busca) . '%']) ->orWhereRaw("lower(motivo_paralisacao) ilike ?", ['%' . mb_strtolower($busca) . '%']); ``` - `clean_slug()` (`v5/app/Helpers/functions.php:780-806`) remove acentos e remove **todo caractere** que não seja `[A-Za-z0-9. ]` — inclusive o hífen. O termo buscado é, portanto, apenas letras, dígitos, ponto e espaço. - O `translate(...)` converte, na coluna, espaço e apóstrofo em hífen e acentos em ASCII. O resultado é que **palavras compostas não são localizáveis**: "obras publicas" (com espaço) não casa com "obras-publicas" no banco, e "obras-publicas" (com hífen) perde o hífen no `clean_slug` e também não casa. - Em `motivo_paralisacao` não há `translate`: apenas `lower()`. Termos com acento ("paralisação") **não** encontram "paralisacao". - `mb_strtolower` é aplicado ao termo, mas o `lower()` do PostgreSQL é locale-dependent; com o cluster em `C` locale o `lower()` só trata ASCII. ### 2.4 Exclusão de anexo por índice ```php array_splice($arquivos, $index, 1); $obra->arquivo = !empty($arquivos) ? json_encode(array_values($arquivos)) : null; ``` - A posição é reindexada (`array_values`) após a remoção; os índices exibidos na tela são recalculados no próximo render. - Se o índice informado não existir, devolve 404 com `{"erro":"Arquivo não encontrado."}`. - **O arquivo físico não é apagado** do storage: o PDF continua acessível em `/storage/docs/` se alguém tiver a URL. Isso é um vazamento de arquivo e um acúmulo de espaço em disco. - A mesma lacuna existe no `store` e no `update`: se o `insert`/`update` falhar depois do upload, o arquivo já gravado no storage fica órfão. ## 3. Armadilhas técnicas | # | Armadilha | Onde | Impacto | |---|---|---|---| | A1 | `Route::any` na rota pública do índice | `v5/routes/web.php:211` | A mesma URI aceita POST/PUT/DELETE; o controller ignora o verbo. | | A2 | `$allData = (clone $query)->get()` executado **sempre**, mesmo sem `type` | `Portal\ObrasParalisadasController@index` | Carrega a tabela inteira na memória a cada visita ao portal e injeta **todos** os registros no HTML (`json_encode($allData)`), mesmo com paginação de 15. | | A3 | `json_encode($allData)` dentro do `