Política de Incidentes

Definição formal do que é um incidente, como classificar e como adicionar novos — Última atualização: 2026-03-24

---

1. Definição

Incidente = evento técnico anômalo que requer atenção operacional.

Log de auditoria = registro de ação normal do sistema para rastreabilidade.

Incidentes aparecem no painel de Incidentes (/admin → Incidentes). Logs aparecem apenas na aba Logs.

---

2. O que É um incidente

Categoria	Exemplos	Ação típica
Falha de infraestrutura	Edge function 500, timeout, probe falho	edge.erro_500, healthcheck.falha
Falha de CRON	Job não executou, erro durante execução	<job>.erro, <job>.alerta
Falha de integração externa	Mensagem WhatsApp não enviada, webhook rejeitado, pagamento com erro	sms.falha_cobranca, faturamento.erro
Bloqueio de segurança	Rate-limit atingido, IP bloqueado, lockout, RBAC negado	portal.rate_limit_bloqueado, permissao.acesso_negado
Health check degradado	Probe respondeu mas com latência alta ou erro parcial	healthcheck.degradado

---

3. O que NÃO é incidente

Situação	Motivo	Onde aparece
Matrícula errada, CPF não encontrado	Erro de input do usuário, não técnico	Log de auditoria
OTP expirado ou inválido	Fluxo normal de segurança	Log de auditoria
Verificações de rotina OK (ex: sessão WhatsApp OK)	Rotina bem-sucedida	Nem log (ou log info)
Operações CRUD normais	Fluxo operacional padrão	Log de auditoria
Reads / consultas	Nunca logados	Nenhum

Regra de ouro: Se o erro é causado pelo input do usuário → log. Se é causado por falha técnica/infra/integração → incidente.

---

4. Convenção de nomes de ações

Ações de incidente (monitoradas automaticamente)

<modulo>.erro              → Erro técnico genérico do módulo
<modulo>.falha_<operacao>  → Falha em operação específica
<modulo>.critico           → Situação crítica que requer ação imediata
<modulo>.alerta            → Alerta que pode escalar
<modulo>.bloqueado         → Bloqueio de segurança ativado

Ações normais (apenas log de auditoria)

<modulo>.<operacao>        → Ação CRUD normal (escola.create, usuario.update)
<modulo>.login             → Login bem-sucedido
<modulo>.logout            → Logout

Exemplos

Ação	Tipo	Monitorada?
escola.create	Log normal	❌
escola.update	Log normal	❌
sms.falha_cobranca	Incidente	✅
sms.enviado	Log normal	❌
healthcheck.falha	Incidente	✅
faturamento.erro	Incidente	✅
portal.rate_limit_bloqueado	Incidente	✅
auth.bloqueio_escola_status	Incidente	✅
manutencao.check_whatsapp_session	NÃO é incidente	❌ (rotina)

---

5. Classificação de severidade

Derivada automaticamente pelo sufixo/conteúdo da ação:

Severidade	Palavras-chave na ação	Cor no painel
Crítico	erro, falha, critico, 500	🔴 Vermelho
Alerta	alerta, bloqueio, bloqueado, degradado	🟡 Amarelo
Info	Demais (ex: permissao.acesso_negado)	🔵 Azul

---

6. Regra para novas features

Ao criar uma nova Edge Function:

1. Toda operação CUD deve chamar registrarLog() com req
2. Se a operação pode falhar por motivo técnico (não por input do usuário):
   • Criar ação com sufixo .erro ou .falha_<operacao>
   • Adicionar à lista de ações monitoradas (ver seção 7)
3. Se é um job CRON novo:
   • Adicionar errorActions no CRON_JOBS_REGISTRY em _shared/cron-jobs.ts
4. Se é integração externa (SMS, pagamento, webhook):
   • Sempre ter ação .erro ou .falha_* para falhas de comunicação

Ao atualizar uma feature existente:

• Verificar se novos modos de falha técnica foram introduzidos
• Se sim, adicionar ação de incidente correspondente

---

7. Onde registrar ações monitoradas

Jobs CRON → CRON_JOBS_REGISTRY

// supabase/functions/_shared/cron-jobs.ts
{
  jobName: 'meu-novo-job',
  errorActions: ['meu_modulo.erro', 'meu_modulo.falha_operacao'],
  // ...
}

Outras ações (segurança, integrações) → acoesExtras

// supabase/functions/admin-cron-monitor/index.ts
// Na lista acoesExtras dentro da função de incidentes
'meu_modulo.erro',
'meu_modulo.falha_operacao',

---

8. Extração de erro (extrairErroIncidente)

A função extrairErroIncidente(acao, detalhes) no admin-cron-monitor extrai a mensagem de erro legível do JSONB detalhes. Ao criar novas ações de incidente, garantir que o campo de erro está acessível:

Padrão recomendado	Campo no detalhes
Erro genérico	{ erro: "mensagem" }
Erro com motivo	{ motivo: "razão" }
Erro com message	{ message: "texto" }
RBAC	{ recurso, papel_usuario, papel_requerido }
Rate limit	{ tipo_bloqueio, acao_bloqueada, falhas_acumuladas }

Se usar um campo diferente, atualizar extrairErroIncidente para mapeá-lo.

---

Referências

• supabase/functions/admin-cron-monitor/index.ts — Painel de incidentes e função extrairErroIncidente
• supabase/functions/_shared/cron-jobs.ts — Registry de jobs CRON
• supabase/functions/_shared/logging-helper.ts — Helper de logging
• docs/security/AUDIT_LOG.md — Catálogo de ações de log
• docs/operations/CRON_JOBS.md — Documentação de jobs CRON