Troubleshooting

Guia para resolução dos problemas mais comuns encontrados ao usar ou desenvolver o SystemClinic.

Problemas de Autenticação

Não consigo fazer login

Sintomas: A tela de login não avança, aparece mensagem de credenciais inválidas.

Verificações:

1. Confirme que está usando o e-mail correto (ex: com ou sem acento)
2. Verifique se o Caps Lock está ativado
3. Tente "Esqueci minha senha" para redefinir
4. Se o problema persistir, peça ao administrador verificar se sua conta está ativa

Erro técnico esperado:

{ "error": "INVALID_CREDENTIALS" }

---

Fui deslogado de repente

Causa mais comum: O refresh token expirou (após 30 dias sem uso) ou foi revogado pelo administrador.

Solução: Faça login novamente. Se acontecer frequentemente, verifique se seu papel foi alterado recentemente.

---

"Sua sessão expirou. Faça login novamente."

Causa: O refresh token foi revogado (logout remoto, alteração de papel, inativação da conta).

Solução: Faça login novamente. Contate o administrador se o acesso continuar sendo negado.

---

Problemas de Agendamento

Não consigo criar um agendamento — "Horário indisponível"

Causas possíveis:

1. O profissional já tem um agendamento no horário (conflito)
2. O horário está fora da grade de disponibilidade configurada para o profissional
3. A sala selecionada já está em uso no horário

Solução:

• Tente um horário diferente
• Verifique a grade de disponibilidade do profissional em Configurações → Profissionais
• Se precisar do horário específico, cancele o agendamento conflitante primeiro

---

O paciente não recebeu o e-mail de confirmação

Verificações:

1. Confirme se o paciente tem e-mail cadastrado (vá em Pacientes → Detalhe)
2. Peça para verificar a caixa de spam
3. Verifique se a integração com Resend está configurada em Configurações → Integrações

Se o e-mail não foi para spam e a integração está configurada:

No painel do Hangfire (http://localhost:5032/hangfire em dev), verifique se o job de notificação falhou e está na fila "Failed" ou "Dead Letter".

---

O calendário não atualiza em tempo real

Causa: Conexão SignalR desconectada.

Verificações:

1. Verifique a conexão com a internet
2. Recarregue a página (o SignalR tentará reconectar automaticamente em até 30s)
3. Se o banner offline estiver visível, aguarde a reconexão

---

Problemas Financeiros

O status da fatura não atualizou após pagamento via gateway

Causa: O webhook do PagarMe não chegou ou falhou na validação.

Verificações:

1. Verifique no painel do PagarMe se o pagamento foi confirmado
2. Verifique no Hangfire se o job de webhook está na fila "Failed"
3. Confirme se o WebhookSecret está correto nas configurações

Solução temporária: Registre o pagamento manualmente na fatura enquanto o problema é investigado.

---

NFS-e não foi emitida após pagamento

Causa: Falha na integração com NFE.io ou dados incompletos.

Verificações:

1. Acesse a fatura e verifique se o campo NFS-e mostra "Pendente"
2. Verifique no Hangfire se o job EmitNfseJob está na fila "Failed"
3. Confirme os dados de CNPJ e configurações fiscais em Configurações → Clínica

O sistema tentará reemitir automaticamente até 5 vezes. Após isso, será necessário emitir manualmente no portal NFE.io.

---

Problemas de Upload de Arquivo

"Arquivo muito grande" ao fazer upload

O limite é de 20 MB por arquivo. Comprima o PDF ou reduza a resolução da imagem antes de tentar novamente.

---

"Tipo de arquivo não suportado"

Formatos aceitos: PDF, JPG, JPEG, PNG, HEIC.

Arquivos Word (.docx), Excel (.xlsx) e outros formatos não são suportados — converta para PDF antes do upload.

---

Upload travado ou sem resposta

Verificações:

1. Verifique a conexão com a internet (uploads grandes precisam de conexão estável)
2. Verifique se as credenciais do Firebase Storage estão configuradas corretamente
3. Verifique se o bucket do Firebase Storage está ativo e sem problemas de cobrança

---

Problemas de Desenvolvimento

A API não inicia — "Connection refused" para o banco de dados

Verificação:

docker compose ps

Se o container do PostgreSQL não estiver rodando:

docker compose up -d db

Aguarde 10–15 segundos para o PostgreSQL inicializar completamente antes de iniciar a API.

---

Erro de migrations ao iniciar a API

Sintoma: Cannot find migration 'InitialCreate' ou similar.

Solução:

cd api
dotnet ef database drop --force
dotnet ef database update

---

Frontend não conecta à API ("ERR_CONNECTION_REFUSED")

Verificação:

1. Confirme que a API está rodando em http://localhost:5032
2. Verifique o apiUrl em web/src/environments/environment.ts
3. Verifique se há algum proxy ou VPN interferindo na porta 5032

---

"CORS policy error" no browser

Causa: A origem do frontend não está na lista de origens permitidas da API.

Solução: Verifique se http://localhost:4200 está configurado no CORS da API em Program.cs.

---

Testes de integração falhando — "Docker not available"

Causa: Testcontainers requer Docker em execução.

Solução:

# Verifique se o Docker está rodando
docker info

# Se não estiver, inicie o Docker Desktop
# ou, no Linux:
sudo systemctl start docker

---

Erros Comuns da API

Código	Mensagem	Causa e Solução
401	UNAUTHORIZED	Token ausente ou expirado. Faça login novamente.
403	FORBIDDEN	Papel insuficiente. Contate o administrador.
409	CPF_ALREADY_EXISTS	CPF já cadastrado. Use o merge de pacientes.
409	SLOT_NOT_AVAILABLE	Horário ocupado. Escolha outro horário.
413	FILE_TOO_LARGE	Arquivo acima de 20 MB. Reduza o tamanho.
422	MINOR_REQUIRES_RESPONSIBLE	Paciente menor de 18 anos precisa de responsável.
429	RATE_LIMIT_EXCEEDED	Muitas requisições. Aguarde e tente novamente.
500	INTERNAL_ERROR	Erro inesperado. Verifique os logs e reporte.

---

Como Reportar um Bug

Se encontrar um problema não listado aqui:

1. Anote o comportamento esperado e o comportamento observado
2. Capture a mensagem de erro completa (incluindo código de erro)
3. Anote a URL da página e os passos para reproduzir
4. Abra uma issue em github.com/fastgivr/system-clinic/issues

Para problemas em produção com impacto crítico, contate o suporte diretamente pelo e-mail de suporte do plano de assinatura.