plan: add implementation plan for fraud detection engine

Stack: Python 3.12/FastAPI + React 19/TypeScript + PostgreSQL + Redis.
6 artifacts: plan.md, research.md, data-model.md, api.yaml (OpenAPI),
quickstart.md, updated AGENTS.md. Constitution check: 6/6 PASS.

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

@@ -0,0 +1,127 @@
+# Research: Motor de Detecção de Fraudes Bancárias
+
+**Feature**: 001-fraud-detection-engine
+**Date**: 2026-05-11
+**Status**: Complete
+
+## 1. Backend Runtime & Framework
+
+**Decision**: Python 3.12 + FastAPI
+
+**Rationale**:
+- Python é a linguagem dominante em data science e financial services — facilita contratação e evolução futura para ML.
+- FastAPI oferece async nativo, validação automática via Pydantic, OpenAPI auto-generated, e performance comparável a Node.js.
+- Ecossistema rico para processamento de dados (pandas, numpy) útil para análise de transações e backtesting de regras.
+- Tipagem estática com mypy alinha-se com o princípio de Test-First da constituição.
+
+**Alternatives considered**:
+- **Node.js + Express**: Bom para I/O, mas ecossistema de data processing inferior. Regras complexas seriam mais verbosas.
+- **Go**: Performance superior, mas ecossistema de dados limitado e curva de aprendizado maior para analistas que contribuem com regras.
+- **Java + Spring Boot**: Maduro para banking, mas verboso e lento para iteração. Overkill para MVP.
+
+## 2. Frontend Framework
+
+**Decision**: React 19 + TypeScript + Tailwind CSS
+
+**Rationale**:
+- Dashboard com múltiplos gráficos e filtros se beneficia do modelo de componentes React.
+- TypeScript alinha-se com a tipagem do backend (Pydantic → TypeScript types via OpenAPI codegen).
+- Tailwind CSS para velocidade de desenvolvimento e consistência visual sem CSS complexo.
+- Recharts ou Tremor para gráficos de dashboard (nativos React, bem mantidos).
+
+**Alternatives considered**:
+- **HTMX + templates Jinja2**: Mais simples, mas dashboard interativo com filtros dinâmicos e real-time updates seria complexo.
+- **Vue 3 + Nuxt**: Excelente framework, mas React tem ecossistema maior de componentes de dashboard.
+- **Svelte**: Performance superior, mas ecossistema de componentes para dashboard ainda imaturo comparado a React.
+
+## 3. Database
+
+**Decision**: PostgreSQL 16
+
+**Rationale**:
+- Audit log imutável: PostgreSQL com triggers ou particionamento por mês atende sem complexidade adicional.
+- JSONB para payload flexível das transações e regras.
+- Full-text search nativo para busca em explicações.
+- Window functions para cálculos de médias móveis (baseline do cliente).
+- `pgAudit` extension para camada extra de auditoria a nível de banco.
+- Row-Level Security como defesa em profundidade.
+
+**Alternatives considered**:
+- **MongoDB**: Schema flexível para transações, mas audit log imutável é mais natural em relacional. Transações ACID são essenciais para dados financeiros.
+- **SQLite**: Ótimo para dev/local, insuficiente para concorrência em produção.
+- **TimescaleDB (extensão PostgreSQL)**: Considerar para hypertables de transações se volume crescer além de 100k/dia. Não necessário para MVP.
+
+## 4. Cache & Real-Time
+
+**Decision**: Redis 7
+
+**Rationale**:
+- Contadores em tempo real do dashboard (transações/minuto, alertas/24h) via Redis `INCR` + TTL.
+- Cache de médias do cliente (gasto médio, localização habitual) para o motor de regras (evita JOIN pesado a cada transação).
+- Rate limiting da API de ingestão.
+- Pub/Sub para notificações de novos alertas no dashboard (SSE ou WebSocket).
+
+**Alternatives considered**:
+- **Sem cache (query direta no PostgreSQL)**: Viável para MVP com <10k transações/dia, mas dashboard near real-time sofreria.
+- **Memcached**: Mais simples, mas sem Pub/Sub e estruturas de dados avançadas.
+
+## 5. Message Queue (Picos de Volume)
+
+**Decision**: Redis Streams (MVP) → RabbitMQ (scale)
+
+**Rationale**:
+- Para MVP, Redis Streams oferece consumer groups, acknowledgments, e já está na stack.
+- Se volume crescer, migrar para RabbitMQ que oferece dead letter queues, retry policies, e routing complexo.
+- Padrão: API de ingestão → Redis Streams → Workers de processamento → PostgreSQL.
+- Desacopla ingestão do processamento, essencial para os picos de 5x mencionados na spec.
+
+**Alternatives considered**:
+- **Kafka**: Overkill para MVP. Operação complexa.
+- **Processamento síncrono**: Violaria SC-001 (2s p95) durante picos.
+
+## 6. Rule Engine Architecture
+
+**Decision**: Python rules engine built on Pydantic models + expression evaluator
+
+**Rationale**:
+- Regras são condições booleanas com peso. Exemplo: `transaction.amount > customer.avg_amount * 3` → score 30.
+- Pydantic models definem o schema da regra, validação automática.
+- `simpleeval` ou `lark-parser` para avaliar expressões de forma segura (sem `eval()` nativo).
+- Cada regra é uma classe Python que implementa `evaluate(transaction, context) -> RuleResult`.
+- Conjunto de regras é carregado do PostgreSQL no boot e cacheado em memória. Reload via endpoint admin.
+- Snapshot versionado: cada transação registra qual versão do ruleset foi usada (rastreabilidade → FR-005).
+
+**Alternatives considered**:
+- **Drools (Java)**: Maduro mas exige JVM, complexidade desnecessária.
+- **Django Rules**: Acoplado ao Django ORM, não adequado para FastAPI.
+- **JSONLogic**: Bom para regras simples, limitado para expressões aritméticas complexas.
+
+## 7. Testing Strategy
+
+**Decision**: pytest + pytest-asyncio (backend), Vitest + React Testing Library (frontend)
+
+**Rationale**:
+- TDD mandatório por constituição.
+- Testes de regra: dataset de transações com fraudes conhecidas → assert score, assert explicação, assert alerta.
+- Testes de contrato: OpenAPI schema validation, garantir que API não quebra entre versões.
+- Testes de integração: pipeline completo (API → rules → alerta → decisão).
+- Testes E2E: Playwright para fluxos do analista (login → fila → avalia alerta → decide).
+
+## 8. Authentication & Authorization
+
+**Decision**: JWT + OAuth2/OIDC via external IdP (Keycloak ou Auth0)
+
+**Rationale**:
+- Spec assume identity provider externo. FastAPI tem suporte nativo a OAuth2 + JWT.
+- Perfis (analista, admin, sênior) mapeados para claims no token.
+- Middleware de autorização por rota verifica claims.
+- Sem senhas armazenadas no FraudShield — compliance LGPD simplificada.
+
+## 9. Deployment
+
+**Decision**: Docker Compose (dev/local) → Kubernetes ou cloud PaaS (produção)
+
+**Rationale**:
+- Docker Compose para ambiente dev: PostgreSQL + Redis + API + Frontend em containers.
+- Simplicidade para MVP: um `docker compose up` resolve.
+- Produção depende de onde hospedar (AWS ECS, GCP Cloud Run, Railway, etc.). Fora do escopo do MVP decidir.