FinAI-RiskEngine

Обзор

FinAI-RiskEngine — гибридный детектор аномалий для мониторинга финансовых транзакций. Система сочетает кастомный движок правил с ИИ-анализом через Spring AI + OpenAI, обрабатывает события через Apache Kafka и хранит исторические кейсы в PostgreSQL с расширением pgvector для RAG.

Технологический стек

Компонент	Версия
Java (runtime)	JDK 25.0.3 (target: 21)
Spring Boot	3.3.5
Spring AI	1.0.0 GA
PostgreSQL + pgvector	15 (Docker: pgvector/pgvector:pg15)
Apache Kafka	KRaft-режим (Docker: apache/kafka:latest)
Lombok	1.18.46
Flyway	10.10.0
SpringDoc OpenAPI	2.6.0
Testcontainers	1.20.3
Pitest	1.19.0

Важно: Drools не используется. Движок правил реализован через интерфейс Rule с четырьмя имплементациями: AmountThresholdRule, CountryRiskRule, FrequencyRule, VelocityRule.

Архитектура

REST API / Kafka
      │
      ▼
TransactionProcessingService
      │
      ├── RulesEngineService  ──→  4 правила (Amount, Country, Frequency, Velocity)
      │
      ├── AIAgentService      ──→  ChatClient (OpenAI gpt-4o-mini) + pgvector RAG
      │
      ├── IdempotencyService  ──→  Дедупликация по idempotency_key
      │
      └── AuditService        ──→  audit_logs в PostgreSQL
              │
              ▼
        KafkaTemplate → topics: transactions.risk-assessed, transactions.dlq, transactions.audit

Поток обработки

1. Транзакция принимается через REST (POST /api/v1/transactions) или Kafka-топик transactions.inbound
2. Проверка идемпотентности (предотвращение дубликатов)
3. Параллельный запуск движка правил
4. ИИ-оценка с RAG (похожие исторические кейсы из pgvector)
5. Итоговый RiskLevel + riskScore, маршрутизация результата
6. Запись в audit_logs, публикация в Kafka

Жизненный цикл транзакции

ИИ-агент: RAG-пайплайн

Ключевые особенности

• 5k+ TPS через Virtual Threads (JDK 21, SimpleAsyncTaskExecutor с setVirtualThreads(true))
• Объяснимый ИИ — агент цитирует исторические кейсы из векторного хранилища
• Идемпотентность — повторные запросы с тем же transactionId возвращают кэшированный результат
• Dead-Letter Queue — необработанные сообщения уходят в transactions.dlq, статус REVIEW
• Fallback — при недоступности OpenAI система полностью переходит на движок правил
• Веб-дашборд — тёмный SPA на Bootstrap 5 + Chart.js: KPI, таблица транзакций, аналитика, ручная отправка
• Swagger UI — интерактивная документация API на /swagger-ui.html

Начало работы

Предварительные требования

• JDK 21+ (в системе: JDK 25.0.3)
• Docker Desktop (запущен)
• Ключ API OpenAI

Запуск

# 1. Запустить PostgreSQL (pgvector) и Kafka в Docker
docker compose up -d

# 2. Задать ключ OpenAI (или оставить placeholder — ИИ-анализ будет отключён)
set OPENAI_API_KEY=sk-...

# 3. Запустить приложение
mvn spring-boot:run

Примечание: На машинах с уже установленным локальным PostgreSQL порты 5432/5433 могут быть заняты. В этом случае в docker-compose.yml и application.yml используется порт 5434 для Docker-контейнера.

Конфигурация

Основные параметры в src/main/resources/application.yml:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5434/riskengine
    username: postgres
    password: 12345

  kafka:
    bootstrap-servers: localhost:9092

  ai:
    openai:
      api-key: ${OPENAI_API_KEY:sk-placeholder}
      chat.options.model: gpt-4o-mini

risk-engine:
  ai.enabled: true
  rules:
    amount-threshold-critical: 10000.0
    high-risk-countries: IR,KP,SY,CU,SD,LY,YE,SO,AF,MM

Docker Compose

# Запуск (PostgreSQL на 5434, Kafka на 9092)
docker compose up -d

# Статус
docker compose ps

# Остановка и удаление томов (сброс БД)
docker compose down -v

Предупреждение version is obsolete в выводе docker compose — безвредно, атрибут version устарел в Compose v2.

Веб-интерфейс

После запуска откройте http://localhost:8080.

Интерфейс построен на тёмной теме (Bootstrap 5 + Chart.js) и организован в четыре раздела:

Раздел	Что показывает
Дашборд	KPI-карточки (всего / одобрено / проверка / заблокировано), график активности за 7 дней, кольцевая диаграмма уровней риска, лента последних транзакций высокого риска
Транзакции	Таблица всех транзакций с пагинацией; фильтры по статусу и уровню риска; клик по строке открывает боковую панель с деталями: сумма, страна, risk score, причины риска и полный аудит-трек
Новая транзакция	Форма ручной отправки транзакции на оценку; кнопка генерации ID; справочная панель порогов риска
Аналитика	KPI по уровням риска, кольцевая диаграмма распределения, столбчатая диаграмма по статусам, линейный график активности за 7 дней

Дополнительно:

• Индикатор статуса API в шапке — зелёная точка при {"status":"UP"}, красная при недоступности
• Автообновление данных каждые 30 секунд (кнопка ручного обновления в сайдбаре)
• Swagger UI — ссылка в нижней части сайдбара → http://localhost:8080/swagger-ui.html

Healthcheck и мониторинг

Spring Boot Actuator доступен сразу после запуска:

Endpoint	Назначение
GET /actuator/health	Статус приложения — {"status":"UP"}
GET /actuator/metrics	Список доступных метрик JVM и приложения
GET /actuator/metrics/{name}	Значение конкретной метрики
GET /actuator/prometheus	Метрики в формате Prometheus (scrape endpoint)
GET /actuator/info	Информация о сборке

Пример быстрой проверки:

curl http://localhost:8080/actuator/health
# {"status":"UP"}

Все AI-вызовы и шаги пайплайна логируются на уровне INFO. Ошибки OpenAI → AiServiceException → 3 retry с экспоненциальным backoff → fallback-результат с пометкой [FALLBACK] в audit_logs.

Документация API

Основные endpoints:

• POST /api/v1/transactions — отправить транзакцию на оценку
• GET /api/v1/transactions/{id} — получить результат
• GET /api/v1/audit/{transactionId} — аудит-лог транзакции

Схема БД

Управляется через Flyway-миграции в src/main/resources/db/migration/:

• V1__init_schema.sql — таблицы transactions, audit_logs, idempotency_records, vector_store
• V2__insert_sample_fraud_cases.sql — тестовые кейсы для RAG

Ключевые типы колонок:

• amount → NUMERIC(19,4)
• risk_score → DOUBLE PRECISION (маппируется на Java Double)
• embedding → vector(1536) (OpenAI text-embedding-ada-002)

CI/CD Pipeline

GitHub Actions (.github/workflows/):

1. Компиляция и unit-тесты
2. Интеграционные тесты (Testcontainers: PostgreSQL + Kafka)
3. Мутационное тестирование (Pitest 1.19.0 + pitest-junit5-plugin 1.2.3)
4. Нагрузочное тестирование (k6)
5. Сборка и публикация Docker-образа

Известные ограничения среды

• Локальный PostgreSQL 17 занимает порт 5432, поэтому Docker-контейнер вынесен на 5434
• JDK 25 используется как runtime, хотя target-версия Java 21 (<release>21</release>)
• Spring AI 1.0.0 изменил artifact IDs стартеров по сравнению с milestone-версиями

Документация

Подробная документация в папке docs/:

• Обзор архитектуры
• Virtual Threads
• Стратегия верификации ИИ