# 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.