# Troubleshooting: Formulário de Associados — Imagens não persistem / Modal não abre
## Cronologia
1. **Problema reportado:** Áreas de input de imagem (logo, cover, galeria) no form de Associados estavam quebradas.
2. **Investigação:** Mapeamento do fluxo completo — view `_form.blade.php` → controller `InstituicaoCmsController` → modelo `AssociadoInstituicao`.
3. **Correções aplicadas:** 5 bugs corrigidos em 3 arquivos.
4. **Problema residual:** Modal de crop da galeria não aparecia na viewport.
5. **Correção final:** Modal movido para `` via JS + backdrop removido.
---
## Bugs encontrados e corrigidos
### 1. `dd()` esquecido em `handleLogoFromGallery`
**Arquivo:** `V2/Modules/Institucional/Associados/Controllers/InstituicaoCmsController.php`
**Problema:** Um `dd([...])` de debug foi commitado na primeira linha do método `handleLogoFromGallery()`. Como este método é chamando **incondicionalmente** tanto em `store()` quanto em `update()`, **qualquer tentativa de salvar** uma instituição morria ali — independente de ter logo ou não.
**Correção:** Remover o `dd()`.
```diff
- dd([
- 'method_called' => true,
- 'logo_id_raw' => $logoId,
- ...
- ]);
```
---
### 2. `create()` não passava `$instituicao` para a view
**Arquivo:** `InstituicaoCmsController.php`
**Problema:** O método `create()` retornava a view com apenas `$allTags` e `$unidadesRegionais`. A view `_form.blade.php` acessava `$inst->metadata`, `$inst->name`, etc. — com `$inst` nulo, lançava **fatal error** (`Call to a member function metadata on null`), impedindo a página de criar de renderizar.
**Correção:** Passar uma instância vazia do modelo para a view.
```diff
public function create()
{
$allTags = AssociadoTag::orderBy('name')->get();
$unidadesRegionais = UnidadeRegional::active()->ordered()->get();
+ $instituicao = new AssociadoInstituicao();
return view('v2-associados::cms.instituicoes.create', compact('instituicao', 'allTags', 'unidadesRegionais'));
}
```
---
### 3. `handleCoverFromGallery` não persistia `metadata['cover_image_id']`
**Arquivo:** `InstituicaoCmsController.php`
**Problema:** O método `handleLogoFromGallery` salvava corretamente `metadata['logo_id']`, mas `handleCoverFromGallery` salvava apenas `cover_image` (coluna) sem atualizar `metadata['cover_image_id']`. Isso fazia o campo hidden `cover_image_id_sync` ficar sempre vazio no form de edição.
**Correção:** Adicionar persistência do ID no metadata.
```diff
if ($media) {
$instituicao->cover_image = $media->file_path;
+ $metadata = $instituicao->metadata ?? [];
+ $metadata['cover_image_id'] = $coverId;
+ $instituicao->metadata = $metadata;
}
```
---
### 4. Galeria (`media-group-input`) fora do `` fechava na linha 141, e a galeria começava na linha 143. Os hidden inputs `convenios_gallery_ids[]` nunca eram submetidos, e o método `syncGalleryMediaIds()` recebia array vazio, **deletando todas as imagens** a cada atualização.
**Correção:** Mover o bloco da galeria para dentro do `
Depois:
```
---
### 5. Modal de crop da galeria fora da viewport
**Arquivo:** `V2/Services/Media/Views/components/media-group-input.blade.php`
**Problema:** O modal de crop estava aninhado dentro de elementos com `transform` (ou outro contexto de empilhamento), fazendo com que `position: fixed` do Bootstrap não posicionasse corretamente o modal na viewport. O modal aparecia "no meio da página" mas fora da área visível, atrás do backdrop escuro.
**Causa técnica:** `position: fixed` é relativo à viewport **apenas** quando nenhum ancestral possui `transform`, `filter` ou `perspective` não-`none`. Quando um ancestral tem essas propriedades, o elemento fixed passa a ser relativo àquele ancestral.
**Correções:**
1. **Remover backdrop** — `backdrop: false` elimina a sobreposição escura que escondia o modal.
```diff
- cropModal = new bootstrap.Modal($cropModal[0], { backdrop: 'static' });
+ cropModal = new bootstrap.Modal($cropModal[0], { backdrop: false, keyboard: false });
```
2. **Mover modal para `` ao abrir** — Garante que nenhum ancestral interfira no `position: fixed`.
```javascript
if ($cropModal.parent()[0] !== document.body) {
$(document.body).append($cropModal);
}
```
3. Adicionado antes de `cropModal.show()`.
---
## Fluxo de salvamento (pós-correção)
```
Usuário preenche form
→ submit POST /nova ou PUT /editar/{id}
→ InstituicaoCmsController@store / @update
→ validate() ← valida campos, incluindo logo_id e cover_image_id
→ preenche $instituicao com dados do request
→ handleLogoFromGallery()
→ busca GalleryMedia::find($logoId)
→ seta $instituicao->logo = media->file_path
→ seta $instituicao->metadata['logo_id'] = $logoId
→ handleCoverFromGallery()
→ mesmo fluxo para cover_image_id
→ $instituicao->save() ← persiste tudo (incluindo metadata JSON)
→ syncTagsFromArray(), syncUnidadeRegional(), syncGalleryMediaIds()
→ activityLogger->log()
→ redirect com flash message
```
---
## Verificação Horizontal: Outros Módulos V2
Realizada em 30/07/2026. Foram inspecionados os módulos abaixo contra os 5 padrões de bug identificados no Associados.
### Legenda
- ✅ **OK** — Padrão não encontrado ou devidamente tratado
- ⚠️ **ATENÇÃO** — Padrão encontrado, requer correção
- 🔘 **N/A** — Não se aplica (módulo não possui o recurso)
### Resumo por Bug
| Bug | SobreNós | Unid.Regional | Notícias | Parceiros | Agenda | LndSctEditor |
|-----|----------|---------------|----------|-----------|--------|--------------|
| #1 dd() esquecido | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| #2 create() sem model | ✅ | ✅ | ✅ | ✅ | ✅ | 🔘 |
| #3 metadata inconsistente | ✅ | ✅ | ✅ | ✅ | ✅ | 🔘 |
| #4 galeria fora do form | 🔘 | ⚠️ | ✅ | 🔘 | 🔘 | 🔘 |
| #5 modal de crop | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
### Detalhamento
#### 1. Sobre Nós (`V2/Modules/Institucional/SobreNos/`)
- **Controllers:** `SobreNosCmsController` (editor de seções), `BoardMemberController` (CRUD membros)
- **Bug #1:** Nenhum `dd()`, `dump()`, `var_dump()` ou `print_r()` encontrado. ✅
- **Bug #2:** `BoardMemberController@create()` passa apenas `$bienniums`. A view `_form.blade.php` faz `$member = isset($member) ? $member : null;` e `$isEdit = !is_null($member);`, usando `$isEdit ? $member->name : ''` — **null-safe**. ✅
- **Bug #3:** `BoardMemberController::fillMember()` chama `resolvePhotoFromMedia()` que salva `$member->photo = $media->file_path` e `$member->photo_id` já é o ID vindo do request. Não usa metadata para isso. Relação direta com `GalleryMedia`. ✅
- **Bug #4:** Não possui galeria. Apenas campo `photo_id` (media-input). 🔘
- **Bug #5:** O `media-group-input` (usado em outros módulos) já tem o fix aplicado. Modal de crop movido para ``. ✅
#### 2. Unidades Regionais (`V2/Modules/Institucional/UnidadeRegional/`)
- **Controller:** `UnidadeRegionalCmsController`
- **Bug #1:** Nenhum `dd()` encontrado. ✅
- **Bug #2:** `create()` retorna view sem `$unidade`. Mas `_form.blade.php` usa `$unidade = $unidade ?? null` e `$unidade->name ?? ''` — **null-safe** em todos os acessos. ✅
- **Bug #3:** `handleLogoFromGallery()` e `handleCoverFromGallery()` **ambos** persistem corretamente no metadata. ✅
- **Bug #4:** ⚠️ **GALERIA FORA DO `