fraudshield/specs/001-fraud-detection-engine/data-model.md

Data Model: Motor de Detecção de Fraudes Bancárias

Feature: 001-fraud-detection-engine Date: 2026-05-11

Entity Relationship Diagram

┌─────────────┐       ┌──────────────────┐       ┌─────────────┐
│ Transaction  │──────▶│   FraudAlert     │◀──────│ DetectionRule│
└─────────────┘  1:N  └──────────────────┘  N:M  └─────────────┘
                              │
                              │ 1:1
                              ▼
                     ┌──────────────────┐
                     │InvestigationResult│
                     └──────────────────┘
                              │
                              ▼
                     ┌──────────────────┐
                     │    AuditLog      │ (todos os eventos)
                     └──────────────────┘

Entities

Transaction

Field	Type	Constraints	Description
id	UUID	PK, NOT NULL	Identificador único da transação
external_id	VARCHAR(255)	NOT NULL, UNIQUE	ID original do sistema bancário
amount	DECIMAL(15,2)	NOT NULL, CHECK > 0	Valor da transação em reais
merchant_name	VARCHAR(255)	NOT NULL	Nome do estabelecimento
merchant_category	VARCHAR(100)	NOT NULL	Categoria (ex: "alimentação", "eletrônicos")
latitude	DECIMAL(10,7)	NULLABLE	Latitude do estabelecimento
longitude	DECIMAL(10,7)	NULLABLE	Longitude do estabelecimento
customer_id	VARCHAR(128)	NOT NULL, INDEX	ID do cliente tokenizado
channel	VARCHAR(20)	NOT NULL, CHECK (web, mobile, pos)	Canal da transação
transaction_at	TIMESTAMPTZ	NOT NULL, INDEX	Timestamp original da transação
ingested_at	TIMESTAMPTZ	NOT NULL, DEFAULT NOW()	Timestamp de ingestão no FraudShield
ruleset_version	VARCHAR(20)	NOT NULL	Versão do conjunto de regras usado
raw_payload	JSONB	NOT NULL	Payload original completo para auditoria

Indexes:

• idx_transactions_customer_id on customer_id
• idx_transactions_transaction_at on transaction_at
• idx_transactions_ingested_at on ingested_at

DetectionRule

Field	Type	Constraints	Description
id	UUID	PK, NOT NULL	Identificador único da regra
name	VARCHAR(255)	NOT NULL, UNIQUE	Nome da regra
description	TEXT	NOT NULL	Descrição do que a regra detecta
condition	TEXT	NOT NULL	Expressão da condição (ex: amount > customer.avg_amount * 3)
weight	INTEGER	NOT NULL, CHECK 0-100, DEFAULT 0	Peso da regra no score composto
threshold	INTEGER	NOT NULL, CHECK 0-100, DEFAULT 0	Score mínimo individual para disparar
is_active	BOOLEAN	NOT NULL, DEFAULT FALSE	Se a regra está ativa em produção
version	INTEGER	NOT NULL, DEFAULT 1	Versão incremental
created_by	VARCHAR(255)	NOT NULL	Usuário que criou
created_at	TIMESTAMPTZ	NOT NULL, DEFAULT NOW()	Data de criação
updated_at	TIMESTAMPTZ	NOT NULL, DEFAULT NOW()	Data da última modificação

FraudAlert

Field	Type	Constraints	Description
id	UUID	PK, NOT NULL	Identificador único do alerta
transaction_id	UUID	FK → Transaction.id, NOT NULL	Transação associada
score	INTEGER	NOT NULL, CHECK 0-100	Score de risco composto
triggered_rules	JSONB	NOT NULL	Array de objetos: [{rule_id, rule_name, score, explanation}]
explanation	TEXT	NOT NULL	Explicação composta em linguagem natural
status	VARCHAR(20)	NOT NULL, DEFAULT 'pending', CHECK (pending, confirmed, false_positive, escalated)	Status do alerta
assigned_to	VARCHAR(255)	NULLABLE	Analista designado
decision	VARCHAR(20)	NULLABLE, CHECK (confirmed, false_positive, escalated)	Decisão tomada
decided_by	VARCHAR(255)	NULLABLE	Analista que decidiu
decided_at	TIMESTAMPTZ	NULLABLE	Timestamp da decisão
justification	TEXT	NULLABLE	Justificativa (obrigatória para false_positive e escalated)
created_at	TIMESTAMPTZ	NOT NULL, DEFAULT NOW()	Timestamp de criação do alerta
ruleset_version	VARCHAR(20)	NOT NULL	Versão do ruleset que gerou o alerta

Indexes:

• idx_alerts_status on status
• idx_alerts_created_at on created_at
• idx_alerts_transaction_id on transaction_id

AuditLog

Field	Type	Constraints	Description
id	UUID	PK, NOT NULL	Identificador único
trace_id	UUID	NOT NULL, INDEX	Trace ID para correlação
event_type	VARCHAR(50)	NOT NULL, INDEX	Tipo de evento (transaction_received, rule_evaluated, alert_created, decision_made, rule_updated)
event_at	TIMESTAMPTZ	NOT NULL, INDEX	Timestamp do evento
actor	VARCHAR(255)	NULLABLE	Usuário ou sistema que gerou o evento
payload	JSONB	NOT NULL	Dados completos do evento
ruleset_version	VARCHAR(20)	NULLABLE	Versão do ruleset no momento do evento

Partitioning: Por mês via event_at para facilitar retenção e performance.

Imutabilidade: Tabela configurada com triggers que rejeitam UPDATE e DELETE. Apenas INSERT permitido.

RuleSnapshot

Field	Type	Constraints	Description
version	VARCHAR(20)	PK, NOT NULL	Versão do conjunto de regras (ex: "20260511-001")
rules_json	JSONB	NOT NULL	Snapshot completo de todas as regras ativas na versão
created_at	TIMESTAMPTZ	NOT NULL, DEFAULT NOW()	Quando o snapshot foi criado
created_by	VARCHAR(255)	NOT NULL	Quem gerou o snapshot

CustomerProfile (Cache / Materialized View)

Field	Type	Source	Description
customer_id	VARCHAR(128)	Derived	ID do cliente tokenizado
avg_amount_30d	DECIMAL(15,2)	AVG(amount) 30d	Média de gasto 30 dias
avg_amount_90d	DECIMAL(15,2)	AVG(amount) 90d	Média de gasto 90 dias
common_categories	JSONB	Top 5 categorias 90d	Categorias mais frequentes
common_locations	JSONB	Cluster de coordenadas	Regiões habituais de transação
night_transactions_pct	DECIMAL(5,2)	% transações 22h-06h	Percentual noturno
last_updated_at	TIMESTAMPTZ	NOW()	Última atualização

Implementation: Materialized view no PostgreSQL, refresh a cada 5 minutos. Cache em Redis com TTL de 5 minutos para acesso rápido pelo motor de regras.

State Transitions

Alert Lifecycle

                    ┌──────────────┐
                    │   pending    │ ◀── Alerta criado (score > threshold)
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
       ┌──────────┐ ┌──────────┐ ┌───────────┐
       │confirmed │ │  false_  │ │ escalated │
       │          │ │ positive │ │           │
       └──────────┘ └──────────┘ └─────┬─────┘
                                       │
                                 Revisão sênior
                                       │
                              ┌────────┼────────┐
                              ▼                 ▼
                       ┌──────────┐      ┌──────────┐
                       │confirmed │      │  false_  │
                       │          │      │ positive │
                       └──────────┘      └──────────┘

Estados finais: confirmed, false_positive (não transicionam mais)

Rule Lifecycle

  ┌────────┐    activate    ┌────────┐
  │inactive│───────────────▶│ active │
  └────────┘                └────────┘
       ▲                          │
       │      deactivate          │
       └──────────────────────────┘

Validation Rules

• Transaction.amount > 0
• Transaction.channel ∈ {web, mobile, pos}
• DetectionRule.weight ∈ [0, 100]
• DetectionRule.threshold ∈ [0, 100]
• FraudAlert.score ∈ [0, 100]
• FraudAlert.justification required when decision ∈ {false_positive, escalated}
• FraudAlert.status transitions only: pending → {confirmed, false_positive, escalated}; escalated → {confirmed, false_positive}