refatoração dos agents

This commit is contained in:
Luiz Silva 2026-08-10 16:08:03 -03:00
parent 97acfb07df
commit 1177e31e56
104 changed files with 1068 additions and 3995 deletions

View file

@ -24,9 +24,9 @@ Todo evento relevante (erro, aviso, conclusão de processo, falha de validação
| Camada | Responsável | Como |
|--------|-------------|------|
| **Frontend** | `@ag-front` + `@ag-ux` | Toast, banner, mensagem inline, estado de erro visível |
| **Backend** | `@ag-back` | `console.error()` / `console.warn()` com contexto suficiente |
| **Log de fila** | `@ag-back` + `@ag-deploy` | Registrar falha no job com payload + stack trace |
| **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 |
---
@ -89,7 +89,7 @@ processor.on('failed', (job, erro) => {
## Camadas e responsabilidades detalhadas
### Frontend (`@ag-front` + `@ag-ux`)
### 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
@ -97,7 +97,7 @@ processor.on('failed', (job, erro) => {
- 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 (`@ag-back`)
### 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
@ -105,7 +105,7 @@ processor.on('failed', (job, erro) => {
- 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 (`@ag-back` + `@ag-deploy`)
### 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
@ -125,6 +125,6 @@ processor.on('failed', (job, erro) => {
## Referências
- Rule: `global/rules/mensagens-usuario` (vocabulário para mensagens ao usuário)
- Persona: `agents/ag-front/persona` (estados de UI)
- Persona: `agents/ag-back/persona` (tratamento de erros)
- Persona: `agents/ag-ux/persona` (feedback imediato como princípio)
- Persona: `agents/front/persona` (estados de UI)
- Persona: `agents/back/persona` (tratamento de erros)
- Persona: `agents/ux/persona` (feedback imediato como princípio)