---
type: rule
name: feedback-visivel
description: Feedbacks importantes nunca ficam ocultos — devem ser visíveis no front, no console e no log de fila.
scope: global
trigger: always_on
updatedAt: "2026-06-18"
---

# Regra: Feedback Visível em Todas as Camadas

## Contexto

Erros silenciosos e feedback oculto são as piores formas de falha em um sistema.
O usuário fica sem saber o que aconteceu, o desenvolvedor não consegue diagnosticar, e o operador não vê nada nos logs.

Esta regra exige que todo feedback relevante seja surfaceado na camada apropriada — sem exceção.

---

## Regra

Todo evento relevante (erro, aviso, conclusão de processo, falha de validação) deve aparecer em **pelo menos uma** das camadas abaixo, e nas **todas as camadas que tiverem acesso**:

| Camada | Responsável | Como |
|--------|-------------|------|
| **Frontend** | `@front` + `@ux` | Toast, banner, mensagem inline, estado de erro visível |
| **Backend** | `@back` | `console.error()` / `console.warn()` com contexto suficiente |
| **Log de fila** | `@back` + `@deploy` | Registrar falha no job com payload + stack trace |

---

## Exemplos

### ✅ Correto — frontend mostra, backend registra

```ts
// backend
try {
  await processarLicenca(dados)
} catch (erro) {
  console.error('[licenca] Falha ao processar', { licencaId: dados.id, erro })
  throw new ErroOperacional('Não foi possível processar a licença')
}
```

```ts
// frontend
catch (erro) {
  mensagem.value = extrairMensagemErro(erro) // nunca silenciar
  mostrarFeedback('erro', mensagem.value)
}
```

### ❌ Errado — engolir o erro silenciosamente

```ts
try {
  await processarLicenca(dados)
} catch (_) {
  // silêncio — o usuário não sabe, o log não sabe
}
```

### ❌ Errado — mostrar erro técnico ao usuário

```ts
// frontend
catch (erro) {
  alert(erro.stack) // nunca expor stack trace ao usuário
}
```

### ✅ Correto — log de fila (BullMQ)

```ts
// processador de fila
processor.on('failed', (job, erro) => {
  console.error('[fila] Job falhou', {
    jobId: job.id,
    nome: job.name,
    tentativas: job.attemptsMade,
    erro: erro.message,
  })
})
```

---

## Camadas e responsabilidades detalhadas

### Frontend (`@front` + `@ux`)

- Todo `catch` deve resultar em feedback visível ao usuário
- Nunca usar `catch (_) {}` sem ao menos logar no console do browser
- Mensagens de erro para o usuário: linguagem do domínio, sem stack trace, sem IDs técnicos
- Estados de carregamento e erro devem ser explícitos na UI (não apenas esconder o spinner)
- Usar o padrão: `loading → sucesso | erro`, nunca ficar preso em "loading" silencioso

### Backend (`@back`)

- Toda exceção capturada deve ser logada com contexto: qual operação, qual entidade, qual erro
- `console.error()` para erros operacionais; `console.warn()` para situações de atenção
- Nunca logar senhas, tokens ou dados pessoais
- O log deve incluir o suficiente para reproduzir o problema: IDs, parâmetros relevantes
- Erros internos não devem vazar para o cliente — traduzir para `ErroOperacional` ou equivalente

### Fila (`@back` + `@deploy`)

- Se o sistema usa BullMQ, Redis ou similar: configurar handler de `failed` e `error`
- Jobs que falham devem ser registrados com: jobId, nome, tentativas, payload relevante, erro
- Falhas repetidas devem gerar alerta (monitoramento de `job.failedReason`)
- Nunca deixar um job falhar silenciosamente sem registro

---

## Impacto

- **Diagnóstico:** sem log, nenhum problema pode ser investigado
- **Confiança do usuário:** feedback ausente = sistema parece travado ou bugado
- **Operação:** sem log de fila, jobs perdidos são invisíveis

---

## Referências

- Rule: `global/rules/mensagens-usuario` (vocabulário para mensagens ao usuário)
- Persona: `agents/front/persona` (estados de UI)
- Persona: `agents/back/persona` (tratamento de erros)
- Persona: `agents/ux/persona` (feedback imediato como princípio)