130 lines
3.9 KiB
Text
130 lines
3.9 KiB
Text
---
|
|
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)
|