---
id: MOD-INSTITUCIONAL-FALECONOSCO
tipo: modulo
onda: 4
status: concluido
unidades: [MOD-INSTITUCIONAL-FALECONOSCO]
fontes:
- V2/Modules/Institucional/FaleConosco/
depende_de: [CORE-BOOT, CORE-AUTH, CORE-CMS, CORE-RUNTIME, SVC-MAILSERVICE, SVC-SEO, SVC-ACTIVITYLOGGER]
consumidores: [SVC-DASHBOARD, SVC-MAILSERVICE, UI-CMS, UI-PORTAL, MOD-SUPPORT-STRUCTURALLANDINGEDITOR]
criticidade: alta
dono: InstitucionalA
---
# Institucional/FaleConosco
> Formulário público de contato + caixa de entrada no CMS. O visitante envia nome, e-mail,
> telefone, assunto e mensagem; a linha é gravada em `v2_mensagens_contato` e, **se houver
> configuração**, dois e-mails saem pelo `MailService` (notificação interna e auto-resposta).
> O operador lê (marcando como lida), responde por e-mail e arquiva. O módulo não tem tela
> de configuração: os dados exibidos em `/fale-conosco` vêm do Editor Estrutural (SLE) e as
> chaves de comportamento (`contato_*`) não têm formulário.
## 0. Ficha de identidade
| Campo | Valor |
|---|---|
| Efeito primário | Persiste a mensagem do formulário público e mostra/permite responder/arquivar essas mensagens no CMS; os e-mails são tentados, mas **nunca** alteram a resposta ao usuário (o retorno é ignorado). |
| Entrada | `GET|POST /fale-conosco` (público) e `GET /cms/fale-conosco`, `GET /cms/fale-conosco/{id}`, `POST /cms/fale-conosco/{id}/reply`, `POST /cms/fale-conosco/{id}/archive`; campos `name`, `email`, `phone`, `subject`, `message`, `g-recaptcha-response`, `reply_body`. |
| Saída | HTML `v2-faleconosco::portal.index` e `v2-faleconosco::cms.{inbox,show}`; `302` com flash; linhas em `v2_mensagens_contato`; tentativas em `v2_mail_logs`; `activity_log`; JSON-LD `ContactPage`. |
| Efeitos colaterais | `is_read` ao abrir a mensagem; `replied_at`/`reply_body` ao responder; `is_archived` ao arquivar; e-mails (notificação/auto-resposta/resposta) com template cru (`use_template=false`); logs de erro de mail; sem limpeza de cache (a rota é excluída do cache). |
| Particularidade central | O chamador ignora o `MailResult` e o `MailService` **não lança em falha de transporte/envio** (só propaga erros anteriores ao `try` interno, como falha de banco ao ler a config SMTP); portanto `Resposta enviada com sucesso!`/`Mensagem enviada com sucesso! Entraremos em contato em breve.` aparecem mesmo quando nenhum e-mail saiu. |
| Como se integra | View namespace `v2-faleconosco`; model `MensagemContato`; `MailService::send`; `SEOService`; `LayoutBaseConfig` (SLE) para os dados de contato; `activity_log`; Dashboard lê contagens. |
| Se removido, quebra | `/fale-conosco` cai no `BasicPage` semeado (HTML estático com formulário `action="#"`), o CMS perde a caixa de entrada, o Dashboard perde o card de não lidas e nenhuma mensagem nova é gravada. |
| Superfície pública | `MensagemContato` (scopes, `markAsRead`), `FaleConoscoPortalController@{index,store}`, `FaleConoscoCmsController@{inbox,show,reply,archive}`. |
## 1. Efeito
### 1.1 O que o usuário consegue fazer
- **Visitante**: abrir `/fale-conosco`, ver dados de contato do SLE (telefone, e-mail,
endereço, CEP, caixa postal, horário, mapa) e enviar uma mensagem
(`Views/portal/index.blade.php:45-219`).
- **Visitante**: receber a confirmação `Mensagem enviada com sucesso! Entraremos em contato em breve.`
e voltar ao formulário (`FaleConoscoPortalController.php:161-163`).
- **Operador CMS com `read`**: ver a caixa de entrada, buscar por nome/e-mail/assunto,
filtrar “Apenas não lidas” e abrir a mensagem (`FaleConoscoCmsController.php:44-87`).
- **Operador com `write`**: responder por e-mail e arquivar (`:94-153`).
- **Operador**: ver no topo o total e o badge de não lidas (`inbox.blade.php:22-31`).
### 1.2 O que muda no sistema
| Efeito | Onde é produzido | Fonte |
|---|---|---|
| INSERT em `v2_mensagens_contato` com `id=v2_uuid()`, `ip_address`, `user_agent`, `is_read=false`, `is_archived=false` | `store` | `FaleConoscoPortalController.php:105-114`; migration `:21-41` |
| Tentativa de e-mail interno `[Contato] {subject}` para `contato_recipient_email` (se não vazio) | `store` | `:116-135` |
| Tentativa de auto-resposta para o visitante se `contato_auto_reply_body` não vazio | `store` | `:137-159` |
| `is_read=true` (só se estava `false`) ao abrir `/cms/fale-conosco/{id}` | `show`/`markAsRead` | `FaleConoscoCmsController.php:73-78`; `MensagemContato.php:71-79` |
| `activity_log` `read` ao abrir, mesmo que já lida | `show` | `:80-84` |
| `reply_body` + `replied_at=now()` antes da tentativa de envio | `reply` | `:103-105` |
| Tentativa de e-mail `Re: {subject}` para o visitante com o corpo cru | `reply` | `:107-117` |
| `activity_log` `replied` | `reply` | `:122-126` |
| `is_archived=true` | `archive` | `:137-142` |
| `activity_log` `archived` | `archive` | `:144-148` |
| `v2_mail_logs` (`sent`/`failed`, corpo incluído) para cada tentativa | `MailService::logMail` | `MailService.php:360-380` |
| `activity_log` **não** é gerado no envio público | — | `FaleConoscoPortalController.php:70-164` |
### 1.3 Contrato observável (entrada → saída)
| Entrada | Resultado |
|---|---|
| `GET /fale-conosco` | `200` com formulário + cartão de informações; dados do SLE; SEO fixo; JSON-LD `ContactPage`. |
| `POST /fale-conosco` válido | INSERT; tenta e-mails; `302` para `v2.fale-conosco.portal.index` + flash `Mensagem enviada com sucesso! Entraremos em contato em breve.` |
| `POST` sem `name`/`email`/`subject`/`message` | `302` de volta com erros de validação exibidos como **chaves cruas** (`validation.required`, `validation.email`), pois não existe `resources/lang` e o translator devolve a própria chave. |
| `POST` com `phone` fora do formato | `302` de volta com `validation.regex`; nada é gravado. |
| `POST` com `message` > 10000 | `302` com `validation.max.string`. |
| `POST` com `g-recaptcha-response` presente e inválido | `302` back com input + flash `Falha na verificação do reCAPTCHA. Tente novamente.`; nada é gravado. |
| `POST` sem o campo `g-recaptcha-response` | reCAPTCHA **não** é verificado (bypass por omissão do campo). |
| `POST` com `contato_recipient_email` vazio/ausente | nenhum e-mail interno; mensagem gravada e sucesso exibido. |
| `POST` com `contato_auto_reply_body` vazio/ausente | nenhuma auto-resposta; sucesso exibido. |
| `POST` com SMTP inválido | mensagem gravada; `v2_mail_logs` com `status='failed'`; sucesso exibido (o erro não chega ao visitante). |
| `GET /cms/fale-conosco` | `200` com `$mensagens` (20/página, desc) e `$unreadCount`. |
| `GET /cms/fale-conosco?unread=1` | **`500`** `BadMethodCallException: Method boolean does not exist.` (Laravel 5.5 não tem `Request::boolean`) (`FaleConoscoCmsController.php:58`). |
| `GET /cms/fale-conosco/{id}` | `200`; marca lida; `activity_log read`. |
| `GET /cms/fale-conosco/{id}` inexistente | `404`. |
| `POST /cms/fale-conosco/{id}/reply` sem corpo | `302` back com `validation.required`. |
| `POST .../reply` com corpo > 10000 | `302` back com `validation.max.string`. |
| `POST .../reply` válido | grava `reply_body`/`replied_at`, tenta enviar, `302` back + `Resposta enviada com sucesso!` (mesmo se o envio falhou). |
| `POST .../archive` | `is_archived=true`, `302` para a inbox + `Mensagem arquivada com sucesso!`; a mensagem some da lista. |
| Acesso CMS sem sessão/papel | `302` login; `401` em AJAX (`CmsAuthenticate.php:21-44`). |
### 1.4 O que este módulo NÃO faz
- Não tem tela de configuração de contato: o comentário da rota aponta para o SLE
(`Routes/cms.php:13-15`).
- Não grava `contato_*` em lugar nenhum: são chaves somente-leitura para o módulo.
- Não tem caixa de saída, threads, anexos, encaminhamento, cópia ou template de e-mail.
- Não valida spam de forma efetiva: sem throttle, sem honeypot, sem captcha obrigatório.
- Não usa `created_by` (coluna existe, nunca é escrita).
- Não expõe mensagens arquivadas em nenhuma tela (sem filtro/aba).
- Não apaga mensagens fisicamente (só arquiva; soft delete não é usado no fluxo).
- Não notifica o remetente sobre o status (a resposta só existe se o operador responder).
- Não registra auditoria do envio público.
- Não limpa o cache de páginas (não é necessário; a rota está fora do cache).
## 2. Abordagem
### 2.1 Estratégia em uma página
Um CRUD de mensagens com dois atores: o público escreve (INSERT + tentativas de e-mail
best-effort) e o CMS lê/responde/arquiva. Toda a integração de e-mail é opcional e
silenciosa; a única configuração são três chaves em `v2_portal_configs` e os dados
exibidos, que vêm de outra tabela/editor (SLE).
```mermaid
flowchart LR
V[Visitante] -->|POST /fale-conosco| V1[validate + recaptcha condicional]
V1 --> DB[(v2_mensagens_contato)]
DB --> M1[MailService: notificacao]
DB --> M2[MailService: auto-resposta]
M1 --> LOG[(v2_mail_logs)]
M2 --> LOG
O[Operador CMS] -->|GET inbox/show| QB[(mensagens inbox)]
O -->|POST reply| DB
DB --> M3[MailService: Re:]
O -->|POST archive| DB
O --> AL[(activity_log)]
```
### 2.2 Mecânica passo a passo
1. **Boot**: rotas CMS sob `web` + `module.active:FaleConosco` (provider) e
`CmsAuthenticate` (arquivo); rotas web sob `web` + manutenção + `page.cache` +
`public.cache`, mas ambos os middlewares de cache excluem `fale-conosco`
(`V2ServiceProvider.php:215-219,299-306`; `PageCacheMiddleware.php:16-23`;
`PublicCacheMiddleware.php:31-36`).
2. **GET portal**: define SEO fixo (title/description/keywords), lê
`LayoutBaseConfig::where('key','contato')` e mapeia `payload[telefone_1|email|endereco|horario|map_link|zipcode|po_box]`,
depois mescla todas as chaves do grupo `CONTATO` de `v2_portal_configs`
(`FaleConoscoPortalController.php:34-64`).
3. **POST portal**: `validate` 5 campos; se existir `g-recaptcha-response`, chama
`siteverify` via cURL síncrono com `secret` (config inexistente → `''`), `response` e
`remoteip`; falha → flash de erro + back com input (`:72-103`).
4. Cria `MensagemContato`, preenche id/nome/e-mail/telefone/assunto/mensagem/IP/UA e salva
(`:105-114`).
5. Lê `contato_recipient_email`; se não vazio, monta corpo HTML escapado e chama
`MailService::send` em `try/catch` que, para falhas de SMTP, nunca captura (o serviço devolve `MailResult(false)`); falhas na leitura da config SMTP, por ocorrerem antes do `try` do serviço, ainda podem propagar
(`:116-135`).
6. Lê `contato_auto_reply_subject` e `contato_auto_reply_body`; se o corpo não for vazio,
envia a auto-resposta (`:137-159`).
7. Flash de sucesso e redirect à página (`:161-163`).
8. **Inbox**: `MensagemContato::inbox()` + busca opcional + filtro `unread` (bug) +
contagem de não lidas + `recent()->paginate(20)` (`FaleConoscoCmsController.php:44-66`).
9. **Show**: `findOrFail`, `markAsRead`, `activity_log read`, view (`:73-87`).
10. **Reply**: valida `reply_body`, grava campos, tenta `MailService::send` com
`Re: {subject}`, audita e faz `back()` (`:94-131`).
11. **Archive**: `is_archived=true`, audita, flash, redirect inbox (`:137-153`).
### 2.3 Decisões de design e por quê
- **E-mail como efeito best-effort**: a mensagem é o dado durável; e-mail é conveniência.
A ausência de transação entre INSERT e envio é coerente com isso `[C]`.
- **Configuração por chave, não por tabela**: `v2_portal_configs` evita schema novo; o custo
é não haver UI nem defaults `[C]` (`:116-142`).
- **Dados de exibição no SLE**: contato é dado institucional compartilhado com header/footer;
duplicar aqui criaria duas fontes `[C]` (`:40-53`; comentário em `Routes/cms.php:13-15`).
- **Captcha opcional**: só valida se o campo existir, permitindo que a página sem widget
funcione; na prática é um no-op `[C]` (`:80-103`).
- **Arquivar em vez de deletar**: preserva histórico; sem UI de restauração `[C]`
(`:137-142`).
- **Resposta inline (`reply_body` único)**: uma mensagem = no máximo uma resposta; o form
desaparece depois (`show.blade.php:92-116`), mas o endpoint continua aceitando novas
respostas e sobrescrevendo `reply_body`/`replied_at`.
### 2.4 Trechos de código pivô
```php
// V2/Modules/Institucional/FaleConosco/Controllers/FaleConoscoPortalController.php:72-78 — validação pública
$this->validate($request, [
'name' => 'required|string|max:255',
'email' => 'required|email|max:255',
'phone' => 'nullable|string|max:16|regex:/^\([0-9]{2}\)\s[0-9]{4,5}-[0-9]{4}$/',
'subject' => 'required|string|max:255',
'message' => 'required|string|max:10000',
]);
```
O telefone só aceita `(DD) 9999-9999` ou `(DD) 99999-9999` com **um espaço** após o DDD e
hífen antes dos 4 últimos dígitos; é opcional. A validação é inline (sem FormRequest).
```php
// V2/Modules/Institucional/FaleConosco/Controllers/FaleConoscoPortalController.php:80-102 — reCAPTCHA condicional
if ($request->has('g-recaptcha-response')) {
$recaptchaResponse = $request->input('g-recaptcha-response');
$secret = config('v2.recaptcha.secret', '');
$verifyUrl = 'https://www.google.com/recaptcha/api/siteverify';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $verifyUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'secret' => $secret,
'response' => $recaptchaResponse,
'remoteip' => $request->ip(),
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
if (!$result || !isset($result['success']) || !$result['success']) {
flash('Falha na verificação do reCAPTCHA. Tente novamente.')->error();
return redirect()->back()->withInput();
}
}
```
Não há `v2.recaptcha.secret` em `config/v2.php` (94 linhas, sem a chave), portanto o
`secret` enviado é `''`; se um cliente enviar o campo, o Google responde `success:false` e o
envio é bloqueado. Como a view do módulo não renderiza o widget, o caminho normal é o
bypass pelo campo ausente.
```php
// V2/Modules/Institucional/FaleConosco/Controllers/FaleConoscoPortalController.php:116-135 — notificação interna
$recipientEmail = DB::table('v2_portal_configs')
->where('config_key', 'contato_recipient_email')->value('config_value');
if (!empty($recipientEmail)) {
try {
$body = 'Nome: ' . $mensagem->name . '
' .
'Email: ' . $mensagem->email . '
' .
'Telefone: ' . ($mensagem->phone ?: '-') . '
' .
'Mensagem:
' . nl2br(e($mensagem->message));
$this->mailService->send($recipientEmail, '[Contato] ' . $mensagem->subject, $body, [
'to_name' => 'Administrador', 'use_template' => false, 'is_html' => true,
]);
} catch (\Exception $e) {
\Log::error('[FaleConosco] Falha ao enviar notificação admin: ' . $e->getMessage());
}
}
```
Assunto e corpo são literais; `name`/`email`/`phone` não são escapados no corpo (apenas a
mensagem). O retorno de `send()` é descartado. O `catch` só atua em falhas anteriores ao `try` do serviço (ex.: banco indisponível na leitura da config SMTP); falha de envio é convertida em `MailResult(false)` (próximo trecho).
```php
// V2/Services/MailService/MailService.php:126-133 — falha de envio vira MailResult false
} catch (\Exception $e) {
$errorMsg = $e->getMessage();
Log::error('[MailService] Erro ao enviar e-mail para ' . $to . ': ' . $errorMsg);
// Log de falha
$this->logMail($profile, isset($config) ? $config->from_address : null, $to, $subject, $body, 'failed', null, $errorMsg);
return $this->buildResult(false, 'Erro ao enviar e-mail.', null, $errorMsg);
}
```
O serviço captura a exceção e devolve `MailResult(false, 'Erro ao enviar e-mail.')`; os
`try/catch` dos chamadores não disparam para falhas de envio (apenas para falhas pré-`try`, como erro de banco). `logMail` grava a tentativa em `v2_mail_logs`
(inclusive o corpo) e também engole exceções (`MailService.php:360-380`).
```php
// V2/Modules/Institucional/FaleConosco/Controllers/FaleConoscoCmsController.php:94-130 — resposta do operador
$mensagem = MensagemContato::findOrFail($id);
$this->validate($request, ['reply_body' => 'required|string|max:10000']);
$mensagem->reply_body = $request->input('reply_body');
$mensagem->replied_at = now();
$mensagem->save();
try {
$this->mailService->send($mensagem->email, 'Re: ' . $mensagem->subject,
$request->input('reply_body'), [
'to_name' => $mensagem->name, 'use_template' => false, 'is_html' => true,
]);
} catch (\Exception $e) {
\Log::error('[FaleConosco] Falha ao enviar email de resposta: ' . $e->getMessage());
}
$this->activityLogger->log($mensagem, 'replied', [...]);
flash('Resposta enviada com sucesso!')->success();
return redirect()->back();
```
A ordem importa: `reply_body`/`replied_at` são persistidos **antes** do envio; se o envio
falhar, a UI continua mostrando a resposta como enviada e o formulário de resposta
desaparece (`show.blade.php:77-116`). O corpo é enviado sem escape (`is_html=true`), então
o operador pode inserir HTML.
```php
// V2/Modules/Institucional/FaleConosco/Controllers/FaleConoscoCmsController.php:44-64 — inbox e o filtro quebrado
$query = MensagemContato::inbox();
if ($request->has('search') && !empty($request->input('search'))) { /* name|email|subject ilike */ }
if ($request->has('unread') && $request->boolean('unread')) {
$query->unread();
}
$unreadCount = MensagemContato::inbox()->unread()->count();
$mensagens = $query->recent()->paginate(20);
```
`Request::boolean()` não existe no Laravel 5.5 (o framework é `5.5.*` no `composer.json`);
o `Request` usa `Macroable`, então a chamada lança `BadMethodCallException` — a inbox
quebra sempre que a query `unread` é enviada, embora o checkbox exista na tela
(`inbox.blade.php:39-45`).
```blade
{{-- V2/Modules/Institucional/FaleConosco/Views/portal/index.blade.php:57-120 — formulário --}}