fraudshield/specs/001-fraud-detection-engine/spec.md

Feature Specification: Motor de Detecção de Fraudes Bancárias

Feature Branch: 001-fraud-detection-engine Created: 2026-05-11 Status: Draft Input: User description: "App para detectar fraudes bancárias - motor de detecção com regras, explicações auditáveis e painel de alertas"

User Scenarios & Testing (mandatory)

User Story 1 - Analista avalia alerta de fraude e toma decisão (Priority: P1)

Um analista de fraude recebe um alerta gerado pelo sistema, revisa a explicação detalhada do motivo pelo qual a transação foi sinalizada, investiga o contexto da transação e toma uma decisão: confirmar como fraude, marcar como falso positivo, ou escalar para revisão sênior. O analista precisa entender o motivo da sinalização em menos de 30 segundos.

Why this priority: Este é o core loop do produto. Sem a capacidade de revisar e decidir sobre alertas, o sistema não entrega valor. Todo o pipeline de detecção existe para alimentar esta tela.

Independent Test: Pode ser testado com alertas pré-carregados no sistema — um analista faz login, vê a fila de alertas pendentes, abre um alerta, revisa a explicação e toma uma decisão. O fluxo completo é testável sem o pipeline de ingestão.

Acceptance Scenarios:

1. Given que um alerta de fraude foi gerado para uma transação de R$ 5.000,00 em local incomum, When o analista abre o alerta, Then ele vê: valor da transação, estabelecimento, local, horário, regras que dispararam (ex: "Valor 5x acima da média do cliente"), score de risco (ex: 87/100), e uma explicação em linguagem natural do porquê a transação foi sinalizada.

2. Given que o analista está revisando um alerta, When ele decide "Confirmar Fraude", Then o sistema registra a decisão com timestamp, analista responsável, e dispara as ações configuradas (ex: bloquear cartão, notificar cliente). O alerta sai da fila de pendentes.

3. Given que o analista está revisando um alerta, When ele decide "Falso Positivo", Then o sistema registra a justificativa, libera a transação (se estava bloqueada), e opcionalmente ajusta o score da regra que gerou o falso positivo para reduzir alertas futuros similares.

4. Given que o analista não tem certeza sobre um alerta, When ele decide "Escalar", Then o alerta é enviado para a fila de revisão sênior com as notas do analista, e ele pode voltar para a fila principal.

---

User Story 2 - Sistema ingere transações e aplica regras de detecção (Priority: P1)

Transações financeiras chegam ao sistema via API. O motor de detecção aplica todas as regras ativas, calcula um score de risco composto, gera uma explicação detalhada para cada regra que disparou, e cria um alerta quando o score ultrapassa o threshold configurado. Transações abaixo do threshold são registradas no audit log mas não geram alerta.

Why this priority: Sem ingestão e detecção, não existem alertas para os analistas revisarem. É o pipeline que alimenta o User Story 1. Ambos são P1 porque um não funciona sem o outro.

Independent Test: Enviar uma transação de teste via API e verificar se: (a) todas as regras aplicáveis foram executadas, (b) o score foi calculado corretamente, (c) a explicação foi gerada, (d) o alerta foi criado (se acima do threshold) ou apenas logado (se abaixo).

Acceptance Scenarios:

1. Given que uma transação de R$ 200,00 em um estabelecimento habitual do cliente chega ao sistema, When o motor processa a transação, Then as regras são avaliadas, o score fica abaixo do threshold (ex: 15/100), e a transação é registrada no audit log sem gerar alerta.

2. Given que uma transação de R$ 15.000,00 em outro estado, às 3h da manhã, chega ao sistema, When o motor processa, Then múltiplas regras disparam (valor atípico, local incomum, horário suspeito), o score ultrapassa o threshold (ex: 92/100), e um alerta é criado com explicação composta listando cada regra que contribuiu.

3. Given que o sistema está processando transações, When uma transação chega com dados incompletos (ex: sem geolocalização), Then o motor aplica as regras que consegue avaliar, marca campos ausentes no log, e calcula o score com os dados disponíveis — não rejeita a transação.

4. Given que 1000 transações chegam simultaneamente, When o motor processa o lote, Then todas as transações são processadas sem perda de dados e sem degradação significativa de latência.

---

User Story 3 - Administrador gerencia regras de detecção (Priority: P2)

Um administrador de fraude cria, edita, ativa, desativa e testa regras de detecção. Cada regra tem: nome, descrição, condições (ex: "valor > 3x média do cliente"), peso no score (0-100), e threshold individual. O administrador pode testar uma regra contra dados históricos para ver quantos alertas ela geraria antes de ativá-la em produção.

Why this priority: Regras são o coração do motor, mas o sistema pode começar com um conjunto inicial de regras pré-configuradas. A interface de gestão é essencial para evolução contínua, mas não bloqueia o MVP.

Independent Test: Um administrador faz login, cria uma nova regra ("Transação noturna acima de R$ 1.000"), define peso 30, testa contra 90 dias de dados históricos, revisa a estimativa de alertas gerados, e ativa a regra.

Acceptance Scenarios:

1. Given que o administrador acessa a tela de regras, When ele clica "Nova Regra", Then ele pode definir: nome, descrição, condições (com builder visual ou expressão), peso (0-100), e threshold. Ao salvar, a regra fica com status "Inativa" por padrão.

2. Given que uma regra está inativa, When o administrador clica "Testar", Then o sistema executa a regra contra os últimos 90 dias de transações e mostra: número de transações que disparariam, distribuição de scores, e estimativa de falsos positivos baseada em decisões anteriores de analistas.

3. Given que o administrador revisou os resultados do teste, When ele clica "Ativar", Then a regra passa a ser aplicada em todas as novas transações imediatamente, e um registro de auditoria é criado (quem ativou, quando, resultado do teste).

4. Given que uma regra está gerando muitos falsos positivos, When o administrador ajusta o peso de 40 para 20, Then a alteração entra em vigor imediatamente e um registro de auditoria é criado com o valor anterior e o novo.

---

User Story 4 - Dashboard e relatórios de fraude (Priority: P3)

Gestores e líderes de fraude acessam um dashboard com métricas em tempo real: volume de transações, taxa de fraude, distribuição de scores, tempo médio de decisão dos analistas, taxa de falsos positivos, e regras que mais geram alertas. Relatórios podem ser exportados em PDF/CSV para compliance e auditoria.

Why this priority: O dashboard é importante para gestão e compliance, mas o sistema entrega valor sem ele — analistas podem trabalhar diretamente na fila de alertas (US1) e o motor processa transações (US2). É a camada de visibilidade que fecha o ciclo de melhoria contínua.

Independent Test: Com dados de transações e alertas no sistema, um gestor acessa o dashboard e vê métricas atualizadas. Pode filtrar por período (7d, 30d, 90d), exportar um relatório em PDF e verificar se os números batem com os dados brutos.

Acceptance Scenarios:

1. Given que existem transações e alertas processados no sistema, When o gestor acessa o dashboard, Then ele vê cards com: total de transações (24h), alertas gerados (24h), taxa de fraude confirmada, tempo médio de decisão, e falsos positivos (24h).

2. Given que o gestor quer analisar um período específico, When ele seleciona "Últimos 30 dias", Then todos os gráficos e métricas são recalculados para o período, e ele pode ver tendências (ex: aumento de fraude em horários noturnos).

3. Given que o gestor precisa de um relatório para auditoria, When ele clica "Exportar Relatório", Then um PDF é gerado com: período, métricas principais, top 5 regras que mais dispararam, distribuição de decisões (fraude/falso positivo/escalado), e lista de alterações em regras no período.

---

Edge Cases

• O que acontece quando uma transação chega sem dados de geolocalização? O motor aplica as regras disponíveis e marca campos ausentes no log.
• O que acontece quando duas regras contraditórias disparam (uma sugere fraude, outra sugere transação legítima)? O score é calculado como soma ponderada — regras conflitantes se anulam parcialmente, e a explicação lista ambas.
• Como o sistema lida com picos de volume (Black Friday, pagamento de salários)? Deve manter latência sem perda de transações — usar backpressure e filas.
• O que acontece se um analista aprovar uma transação que depois se confirma como fraude? O sistema registra a decisão original no audit log imutável. Cabe ao processo de revisão identificar e corrigir.
• O que acontece quando uma regra é desativada enquanto transações estão em processamento? Transações já em fila usam o snapshot de regras do momento da ingestão.
• Como o sistema lida com clientes que têm padrões atípicos legítimos (ex: viajante frequente)? O motor deve aprender com decisões de falsos positivos para ajustar scores ao longo do tempo.

Requirements (mandatory)

Functional Requirements

• FR-001: Sistema MUST receber transações via API REST com payload JSON contendo: ID da transação, valor, estabelecimento, categoria, localização (opcional), timestamp, e ID do cliente (tokenizado).
• FR-002: Sistema MUST aplicar todas as regras ativas a cada transação e calcular um score de risco composto (0-100) como soma ponderada dos scores de regras que dispararam.
• FR-003: Sistema MUST gerar uma explicação em linguagem natural para cada regra que disparou, incluindo: nome da regra, condição que disparou, valor encontrado vs esperado, e contribuição para o score.
• FR-004: Sistema MUST criar um alerta de fraude quando o score composto ultrapassar o threshold configurável (default: 70/100).
• FR-005: Sistema MUST registrar todas as transações e decisões do motor em audit log imutável com trace ID, timestamp, e versão do conjunto de regras.
• FR-006: Analistas MUST poder visualizar a fila de alertas pendentes, filtrar por score, data, valor, e regra disparada.
• FR-007: Analistas MUST poder abrir um alerta, revisar a explicação completa, e tomar uma das três decisões: Confirmar Fraude, Falso Positivo, ou Escalar.
• FR-008: Sistema MUST registrar todas as decisões de analistas com: analista, timestamp, decisão, justificativa (obrigatória para falso positivo e escalamento).
• FR-009: Administradores MUST poder criar, editar, ativar, desativar e testar regras de detecção.
• FR-010: Cada regra MUST ter: nome, descrição, condições, peso no score (0-100), threshold individual, e status (ativa/inativa).
• FR-011: Sistema MUST permitir testar uma regra inativa contra dados históricos (até 90 dias) mostrando: total de transações que disparariam, distribuição de scores, e estimativa de impacto.
• FR-012: Dashboard MUST exibir em tempo real: volume de transações (24h), alertas gerados (24h), taxa de fraude confirmada, tempo médio de decisão, e taxa de falsos positivos.
• FR-013: Dashboard MUST permitir filtro por período (24h, 7d, 30d, 90d, personalizado) e exportação de relatório em PDF e CSV.
• FR-014: Sistema MUST suportar autenticação e autorização com perfis: analista (leitura de alertas + decisão), administrador (gestão de regras + dashboard), e sênior (fila de escalados).
• FR-015: Sistema MUST mascarar dados sensíveis em logs e na interface (ex: mostrar últimos 4 dígitos do cartão, não o número completo).
• FR-016: Toda alteração em regras (criação, edição, ativação, desativação) MUST ser registrada em audit log com: usuário, timestamp, regra afetada, valores antes/depois.

Key Entities

• Transaction: Transação financeira recebida. Atributos: ID, valor, estabelecimento, categoria, localização (opcional), timestamp, ID do cliente (tokenizado), canal (web, mobile, POS).
• DetectionRule: Regra de detecção de fraude. Atributos: ID, nome, descrição, condições, peso (0-100), threshold individual, status (ativa/inativa), versão, data de criação, data de última modificação.
• FraudAlert: Alerta gerado quando score > threshold. Atributos: ID, transação associada, score composto, regras que dispararam (lista), explicação composta, status (pendente/confirmado/falso_positivo/escalado), analista, decisão, timestamp de criação, timestamp de decisão.
• InvestigationResult: Decisão do analista sobre um alerta. Atributos: alerta, analista, decisão (confirmado/falso_positivo/escalado), justificativa, timestamp, notas.
• AuditLog: Registro imutável de eventos. Atributos: ID, trace ID, tipo de evento (transacao_recebida, regra_disparada, alerta_criado, decisao_analista, regra_alterada), timestamp, payload JSON, versão do conjunto de regras.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Transações são processadas e o score de risco é calculado em até 2 segundos após a ingestão para 95% das transações (p95).
• SC-002: Analistas conseguem revisar um alerta e tomar uma decisão em até 2 minutos (tempo médio), desde a abertura do alerta até a decisão registrada.
• SC-003: Taxa de falsos positivos (alertas marcados como falso positivo / total de alertas decididos) é monitorada e mantida abaixo de 15% após 30 dias de operação.
• SC-004: Explicações de fraude são compreensíveis: 90% dos analistas conseguem identificar o motivo principal da sinalização em até 30 segundos de leitura (validado em teste de usabilidade).
• SC-005: Sistema processa pelo menos 500 transações por minuto sem degradação de latência além do p95 estabelecido.
• SC-006: Dashboard reflete métricas com no máximo 60 segundos de atraso em relação aos dados reais (near real-time).
• SC-007: 100% das alterações em regras e decisões de analistas são rastreáveis no audit log com todos os campos obrigatórios preenchidos.

Assumptions

• As transações chegam ao sistema já tokenizadas (dados sensíveis do cliente são substituídos por tokens pelo sistema de origem antes da ingestão).
• O sistema de origem (core banking) é responsável por enviar as transações; o FraudShield não faz pull de dados.
• O volume inicial esperado é de até 10.000 transações/dia, com picos sazonais de até 5x.
• Os analistas de fraude trabalham em horário comercial (8h-20h) com sobreaviso para alertas críticos fora de horário.
• A autenticação será delegada a um identity provider existente (OAuth2/OIDC) — o FraudShield não gerencia credenciais.
• As regras iniciais serão configuradas manualmente pela equipe; o motor não inclui ML/AI na v1.
• Conformidade LGPD é obrigatória desde o dia 1 (dados de clientes brasileiros).
• O sistema será web-based (acessível via navegador) com API REST para integrações.
• Relatórios para compliance incluem: registro de todas as decisões, alterações em regras, e métricas de performance do motor.