Alertas

A ideia do produto: quando a análise percebe um risco numa conversa, o responsável recebe um alerta com o trecho mínimo e um caminho do que fazer. Ele não navega pelas conversas, e push, e-mail e SSE nunca levam o trecho (regras P1 a P4 do api-map.md).

O ciclo completo está na main: a análise abre o alerta, o responsável é avisado por severidade, lê o alerta, vê o trecho só quando pede e resolve, dispensa ou reabre. A tela Alertas do app chega com a onda 4; hoje o alerta aparece em Início (GET /accounts/{uid}/home) e no sino.

Do achado ao alertaCopy Anchor Link

flowchart TD
  msgs[("Mensagens guardadas<br/>cifradas por vaga")] --> win["Janela de análise fecha<br/>analysis-scheduler, a cada 30 s"]
  win --> model["Modelo lê e cita mensagens<br/>m1…mN"]
  model --> tx{{"Uma transação"}}
  tx --> findings[("risk_findings<br/>imutável")]
  tx --> alerts[("risk_alerts")]
  tx --> history[("risk_alert_events")]
  tx --> events[("events<br/>alert.opened / alert.updated")]
  tx -->|depois do commit| sse["Stream da conta<br/>SSE pro app"]
  tx -->|depois do commit| notifier["Notificador de risco<br/>risk.critical · warning · info"]
  notifier --> dispatch["notification-dispatcher<br/>app, e-mail, push"]
  sse --> guardian(["Responsável"])
  dispatch --> guardian
  guardian -->|"lê, pede o trecho, resolve,<br/>dispensa ou reabre"| act["POST /alerts/{uid}/…"]
  act --> history
  act --> sse
  act -.->|"resolve ou dispensa:<br/>trecho apagado em 30 dias"| purger["excerpt-purger"]

• Achado (risk_findings): a saída do modelo, imutável. Cita de 1 a 3 mensagens guardadas (message_refs) em vez de escrever uma citação, então não existe trecho inventado. Traz kind, subtype (golpes, só pra adultos), severity (critical, warning ou info) e signals de um vocabulário fechado.
• Alerta (risk_alerts): o que o responsável vê. Agrupa achados da mesma vaga, mesma contraparte (ou conversa) e mesmo tipo: group_key = seat:(contraparte ou conversa):kind.
• Histórico (risk_alert_events): append-only. A análise grava opened, finding_added e severity_raised; o notificador, notified; o responsável, excerpt_viewed, resolved, dismissed, reopened e follow_up ("ainda estou preocupado"); a retenção, purged. shared espera o G-30.

Se qualquer passo falhar, tudo volta (nem achado, nem alerta, nem evento) e a tarefa tenta de novo.

O que a análise procuraCopy Anchor Link

O perfil vem de dependents.kind.

Regras de agrupamentoCopy Anchor Link

• Um achado entra no alerta aberto do grupo se aconteceu até ALERT_GROUP_WINDOW_HOURS (padrão 72 h) do intervalo do alerta. Passada a janela, o alerta antigo é marcado como substituído (superseded_at, continua aberto pro responsável) e um novo abre, apontando pro anterior.
• Existe um alerta coletando por grupo (índice único parcial).
• Um alerta fechado (resolved ou dismissed) nunca é reaberto por um achado novo. Abre-se outro.
• A severidade só sobe enquanto o alerta está aberto.
• Pausa e parada: vaga pausada não é analisada. Uma pausa no meio da chamada ao modelo descarta os achados e devolve a tarefa. Parada pela pessoa ou vaga arquivada: a tarefa é pulada e nada é guardado. Veja Pausar e parar.
• Há um gancho de contato confiável (silencedByTrust), que hoje sempre responde "não". self_harm e sexual_content nunca seriam silenciados.

O trechoCopy Anchor Link

O trecho vem das mensagens guardadas, montado no servidor e mascarado: telefones, CPF/CNPJ, cartões e chaves Pix viram •••• 1234, e e-mails viram •••• @domínio.

• GET /alerts/{uid} não traz o trecho, só excerptAvailable.
• POST /alerts/{uid}/excerpt devolve de 1 a 3 mensagens, grava excerpt_viewed com quem viu e publica alert.updated (change: excerpt_viewed). Limite de 30 por minuto por responsável (429).
• Resolver ou dispensar agenda o apagamento pra 30 dias depois (ALERT_EXCERPT_RETENTION_DAYS). O worker excerpt-purger apaga trecho, justificativa e notas e grava purged; depois disso a rota responde 410 EXCERPT_PURGED. Se a vaga perdeu a chave (parada pela pessoa), também é 410.

Ler e agirCopy Anchor Link

Qualquer membro da família lê e age; quem é de fora recebe 404 ALERT_NOT_FOUND. Fechar avisa os outros responsáveis no app (alert.resolved_by_other).

EventosCopy Anchor Link

Um evento por alerta por lote, e o mais forte vence: opened, depois severity_raised, depois grouped.

source.addEventListener("event", (e) => {
  const ev = JSON.parse(e.data);
  if (ev.type === "alert.opened" && ev.payload.severity === "critical") {
    showBanner({ seatUid: ev.seatUid, kind: ev.payload.kind }); // sem trecho: ele só vem pela rota autenticada
  }
});

NotificaçõesCopy Anchor Link

raise() grava a notificação e enfileira uma entrega por responsável por canal; o worker notification-dispatcher envia, e uma dedupeKey evita repetição.

Risco (G-06). O notificador é instalado no boot da api e dos workers (installRiskNotifier):

O payload é fechado: { alertUid, seatUid, kind, subtype, severity, firstName }, e qualquer outra chave é recusada. Nunca o trecho nem a contraparte. A deduplicação é risk:{alertUid}:{severity}: se piorar, avisa de novo. O e-mail de autolesão traz o CVV 188.

Categorias (G-07): risks, protection, billing e summary.

• risks no app é fixo (locked), e o e-mail ou o push precisa ficar ligado (422 CATEGORY_LOCKED, RISKS_CHANNEL_REQUIRED). Riscos e resumo são instant ou off (422 MODE_NOT_OFFERED).
• Caixa de entrada: GET /notifications?category=&cursor=&limit= com unreadByCategory e alertUid.
• Horário de silêncio: GET e PUT /notifications/quiet-hours (from, to, timezone IANA). O que espera sai no fim da janela.

FontesCopy Anchor Link

• backend/src/domains/alerts/** (open-or-attach.ts, act-on-alert.ts, reveal-excerpt.ts, notify-risk.ts, alerts-reader.ts, playbooks/pt-BR.ts)
• backend/src/http/routes/alerts/*.route.ts, backend/migrations/0047_alert_actions.ts
• backend/src/domains/analysis/vocabulary.ts, use-cases/analyze.ts, excerpt.ts, mask.ts
• backend/migrations/0044_risk_alerts.ts, backend/apps/workers/analysis-scheduler.ts
• backend/src/domains/notifications/catalog.ts, use-cases/raise.ts, use-cases/dispatch.ts
• backend/src/domains/protection/ports/alerts.ts
• backend/src/http/routes/notifications/*.route.ts
• Notas das frentes k-alert-core e k-alert-api
• .specs/features/redesign/api-gaps.md (G-02 a G-07), api-map.md (§0.2, §7)