feat: Sistema de transacciones con validación anti-fraude mediante Kafka

[victor-soto]

📋 Resumen

Implementación de un sistema completo de gestión de transacciones con validación anti-fraude asíncrona utilizando Apache Kafka. El sistema permite crear transacciones que son procesadas y
validadas en segundo plano, garantizando idempotencia y trazabilidad completa.

✨ Características Principales

🔄 Sistema de Transacciones

• API GraphQL para crear y consultar transacciones
• Estados de transacción: PENDING → APPROVED/REJECTED
• Consulta por ID con información detallada
• Listado completo de transacciones ordenadas por fecha

🛡️ Sistema Anti-Fraude

• Procesamiento asíncrono mediante Kafka
• Validación automática de transacciones
• Reglas de negocio:
  • Rechazo si valor > 1000
  • Rechazo si cuenta débito = cuenta crédito
  • Aprobación automática en casos válidos

🔐 Idempotencia

• Claves de idempotencia para prevenir duplicados
• Generación automática mediante SHA-256 de datos transaccionales
• Protección contra reenvíos y reintentos de Kafka

🏗️ Arquitectura

• NestJS como framework principal
• Prisma ORM para gestión de base de datos PostgreSQL
• GraphQL con Apollo Server
• KafkaJS para mensajería asíncrona
• Docker Compose para orquestación de servicios

📦 Componentes Agregados

Módulos y Servicios

• TransactionModule: Módulo principal de transacciones
• TransactionService: Lógica de negocio de transacciones
• TransactionResolver: Resolvers GraphQL (mutations y queries)
• TransactionConsumerService: Consumidor Kafka para validación anti-fraude
• KafkaService: Servicio centralizado de Kafka con productor y consumidor
• AntiFraudService: Servicio de validación anti-fraude
• PrismaService: Cliente Prisma para base de datos

DTOs y Models

• CreateTransactionInput: Input para crear transacciones
• UpdateTransactionInput: Input para actualizar transacciones
• FindTransactionOutput: Output con información detallada
• Transaction: Modelo GraphQL de transacción

Base de Datos

• Migraciones Prisma con esquema completo
• Índices optimizados en idempotencyKey y status
• Campos: id, accountExternalIdDebit, accountExternalIdCredit, transferTypeId, value, status, idempotencyKey, timestamps

🧪 Pruebas Unitarias

Cobertura Completa

• ✅ TransactionService: 100% cobertura
  • Creación con/sin idempotency key
  • Manejo de duplicados
  • Envío a Kafka
  • Consultas y actualizaciones
• ✅ TransactionResolver: 100% cobertura
  • Mutations (createTransaction)
  • Queries (transactions, transaction)
  • Manejo de casos null
• ✅ AppController: Health check endpoint

🚀 Plan de Pruebas

Pruebas Manuales Recomendadas

# 1. Crear transacción válida
mutation {
  createTransaction(createTransactionInput: {
    accountExternalIdDebit: "ACC-001"
    accountExternalIdCredit: "ACC-002"
    transferTypeId: 1
    value: 500
  }) {
    id
    status
    idempotencyKey
  }
}

# 2. Verificar procesamiento anti-fraude
query {
  transaction(id: "transaction-id") {
    transaction { status }
  }
}

# 3. Probar idempotencia (enviar misma transacción 2 veces)
# 4. Verificar rechazo por valor > 1000
# 5. Verificar rechazo por cuenta origen = destino

📚 Documentación

- SETUP_AND_DEVELOPMENT.md: Guía completa de configuración y desarrollo
  - Instalación y requisitos
  - Comandos disponibles
  - Arquitectura del sistema
  - Guía de desarrollo
  - Troubleshooting

🔧 Configuración

Variables de Entorno Requeridas

DATABASE_URL="postgresql://user:password@localhost:5432/db"
KAFKA_BROKERS="localhost:9092"

Servicios Docker

- PostgreSQL (puerto 5432)
- Kafka (puerto 9092)
- Zookeeper (puerto 2181)
- Kafka UI (puerto 8080)

🏃 Cómo Ejecutar

# 1. Instalar dependencias
pnpm install

# 2. Levantar servicios Docker
docker-compose up -d

# 3. Ejecutar migraciones
pnpm prisma:migrate

# 4. Iniciar servidor
pnpm start:dev

# 5. Acceder a GraphQL Playground
http://localhost:3000/graphql