Troubleshooting (erros comuns)
Este guia lista problemas recorrentes, causa provável e resolução prática.
1) Importação falha com mensagem genérica
Mensagem:
`Não foi possível importar o arquivo. Verifique se é JSON ou CSV no formato do modelo.`
Causas prováveis:
- JSON inválido (vírgula, aspas ou estrutura).
- JSON não é array (`[]`), mas objeto (`{}`).
- CSV fora do cabeçalho esperado.
- Excel com formatação inesperada.
Como resolver:
- Use o modelo da página (`download modelo`).
- Para JSON, valide se começa com `[` e termina com `]`.
- Para CSV, mantenha cabeçalho do sistema.
- Abra o console do navegador (F12) e verifique o erro técnico.
2) Plano de Ação não abre (erro de float parsing)
Exemplo de erro:
```json
{
"detail": [{
"type": "float_parsing",
"loc": ["query", "financeiro_valor_pago"],
"input": ""
}]
}
```
Causa:
- Parâmetro numérico enviado vazio (`""`) para API.
Status atual do sistema:
- Front foi ajustado para enviar `financeiro_valor_pago` e `score_risco` somente quando válidos.
Se reaparecer:
- Verificar construção da URL no `centro-alertas.html`.
- Confirmar no Network (F12) se query não contém `financeiro_valor_pago=`.
3) PDF de relatório não gera
Sintoma:
- API retorna erro 500 em `/api/reports/export/pdf`.
Causa provável:
- Dependência `reportlab` ausente no backend.
Correção:
- Instalar no ambiente backend: `pip install reportlab`.
4) Recomendações da IA indisponíveis
Sintoma:
- Recomendação “genérica” aparece sempre.
Causa provável:
- API/modelo externo indisponível.
Comportamento esperado:
- Sistema cai para fallback local (heurístico) sem interromper operação.
Verificações:
- Health do backend.
- Logs da rota `/api/recomendacoes/gerar`.
- Configuração do serviço de recomendação.
5) Mapa sem coordenadas
Sintoma:
- Mapa não posiciona estudantes.
Causa provável:
- Base sem `latitude/longitude` e CEP ausente/inválido.
Correção:
- Informar coordenadas no arquivo.
- Ou preencher CEP válido para enriquecimento geográfico.
6) Alertas não aparecem
Causas possíveis:
- Filtros ativos ocultando registros.
- Critérios muito restritivos.
- Base sem estudantes em `pesaEstudantes`.
Checklist:
- Limpar filtros na tela.
- Verificar importação e conteúdo em `pesaEstudantes`.
- Revisar critérios em `pesaCriterios`.
7) Regras contextuais não surtindo efeito
Causas comuns:
- Nome de curso/turno/campus não casa exatamente com os dados do estudante.
- JSON de regras inválido.
Correção:
- Copiar nomes exatamente como aparecem nos estudantes.
- Validar JSON na edição de regras da `trajetoria-estudante.html`.
- Recarregar a página após salvar regras.
8) Exportação CSV com caracteres estranhos
Causa:
- Ferramenta de abertura usando encoding diferente.
Correção:
- Abrir CSV com UTF-8 (BOM) no Excel/importador.
9) Backend indisponível no front
Sintoma:
- Botões que dependem de API não funcionam.
Verificação:
- `API_BASE` (localStorage `pesaApiBase` ou origem da página).
- Endpoint `/health`.
- CORS e porta do backend.
Coleta rápida para suporte
Quando abrir chamado, incluir:
- Página onde ocorreu erro.
- Ação executada (ex.: importar CSV, abrir plano).
- Mensagem exibida.
- Erro do console (F12) e status/response da aba Network.
- Exemplo mínimo de dado que reproduz o problema.
