Tratamento de Erros

Para garantir uma experiência de usuário fluida e facilitar o debug, seguimos um padrão rigoroso de tratamento de erros.

1. Categorias de Erro

Para um guia detalhado sobre como implementar classes de erro e o fluxo de propagação, consulte o Guia Técnico de Tratamento de Erros.

• Erro de Rede: Falha de conexão ou timeout.
• Erro de API (4xx): Erros de validação, autenticação ou recursos não encontrados.
• Erro de Servidor (5xx): Falhas internas no backend.
• Erro de Domínio: Erros na lógica de negócio (ex: cálculo matematicamente impossível).

2. Camada de Actions (Application)

As actions, localizadas na camada de aplicação (Application), devem lançar erros de forma que o TanStack Query possa capturá-los. Para mais detalhes sobre as camadas, veja o documento de Arquitetura de Camadas.

// src/actions/example.action.ts
export const myAction = async () => {
    try {
        const response = await api.get("/path");
        return response.data;
    } catch (error) {
        // A action apenas relança o erro, sem feedback visual
        throw error;
    }
};

3. Responsabilidade de Exibição (Camada Screen)

Regra de Ouro: A exibição de mensagens de erro ao usuário é de responsabilidade EXCLUSIVA da camada de tela (screen).

• Sources/Actions: Nunca exibem Toasts, Alerts ou Modais. Elas apenas capturam, formatam e relançam o erro.
• Rules: Nunca disparam feedbacks visuais. Elas validam a lógica e retornam estados de erro ou lançam exceções de domínio.
• Screen: Captura o erro (via TanStack Query ou Try/Catch) e decide a melhor forma de apresentar ao usuário (Inline, Toast ou Modal), utilizando os componentes do @ptm/design-system.

4. Feedback ao Usuário

• Toast/Alert: Para erros globais, de rede ou inesperados, disparados pela Screen.
• Inline Validation: Para erros de formulário, controlados pelo estado da Screen.
• Haptics: A Screen deve disparar feedback tátil em caso de erro, conforme definido nas regras de UI/UX.

5. Padrão de Resposta da API

Esperamos que o backend siga este formato para erros de validação:

{
    "code": "VALIDATION_ERROR",
    "message": "Dados inválidos",
    "errors": [{ "field": "email", "message": "E-mail já cadastrado" }]
}

5. Logging

Em produção, erros críticos devem ser logados em serviços como Sentry para monitoramento.