spec: add fraud detection engine specification (001)

4 user stories: alert investigation (P1), transaction ingestion
+ rule engine (P1), rule management (P2), dashboard (P3).
16 functional requirements, 7 success criteria, 5 entities.
Quality checklist: all 16 items passed.

.specify/feature.json

@@ -0,0 +1 @@
+{"feature_directory":"specs/001-fraud-detection-engine"}

specs/001-fraud-detection-engine/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Motor de Detecção de Fraudes Bancárias
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-11
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All items pass. Spec is ready for `/speckit.clarify` or `/speckit.plan`.
+- No [NEEDS CLARIFICATION] markers were needed — all design decisions had reasonable defaults based on industry standards for fraud detection systems.
+- Key assumptions documented: tokenized transactions, OAuth2/OIDC auth delegation, rules-based v1 (no ML), LGPD compliance, web-based delivery.

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

@@ -0,0 +1,148 @@
+# 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.