HackChange-Alpha

Платформа управления клиентами с ML-скорингом для банковской сферы. Система предоставляет функциональность для анализа клиентов, предсказания доходов с использованием машинного обучения, управления кредитными лимитами и импорта данных.

Команда: мамалыга2013

• Федосеев Дмитрий - Backend-developer
• Аристакесян Мелания - Data-scientist
• Петрова Екатерина - Backend-developer
• Насибуллин Никита - Data-analyst
• Карпов Роман - Frontend-developer

🎥 Демонстрация

Видео демонстрация проекта

---

📁 Структура проекта

HackChange-Alpha/
├── backend/                   # Backend сервис (Go)
│   ├── cmd/
│   │   └── server/
│   │       └── main.go        
│   ├── configs/
│   │   ├── config.example.yaml
│   │   └── config.yaml        # Конфигурация сервера
│   ├── internal/
│   │   ├── application/       # Бизнес-логика
│   │   │   └── services/      # Сервисы приложения
│   │   ├── domain/            # Доменная модель
│   │   │   ├── dto/           # Data Transfer Objects
│   │   │   ├── models/        # Модели данных
│   │   │   └── interfaces/    # Интерфейсы
│   │   └── infrastructure/    # Инфраструктура
│   │       ├── http/          # HTTP слой
│   │       ├── storage/       # Работа с БД
│   │       └── ml/            # Интеграция с ML-сервисом
│   ├── docs/                  # Swagger документация
│   ├── Dockerfile
│   └── go.mod                 # Зависимости Go
│
├── frontend/                  # Frontend приложение (Angular)
│   ├── src/
│   │   ├── app/
│   │   │   ├── core/          # Основные сервисы и модели
│   │   │   ├── features/      # Функциональные модули
│   │   │   │   ├── clients/   # Управление клиентами
│   │   │   │   └── client-metrics/ # Метрики клиентов
│   │   │   └── shared/        # Общие компоненты
│   │   └── environments/      # Конфигурация окружений
│   ├── Dockerfile
│   ├── package.json           # Зависимости Node.js
│   └── angular.json           # Конфигурация Angular
│
├── ml-service/               # ML сервис (Python/FastAPI)
│   ├── app/
│   │   ├── main.py           # Точка входа FastAPI
│   │   ├── endpoints.py      # API endpoints
│   │   ├── preprocessor.py   # Препроцессинг данных
│   │   ├── inference.py      # Предсказания и объяснения
│   │   ├── schemas.py        # Pydantic схемы
│   │   └── loader.py         # Загрузка модели
│   ├── models/               # Обученные модели
│   │   └── pipeline.pkl      # XGBoost pipeline
│   ├── train_and_save.py     # Скрипт обучения модели
│   ├── requirements.txt      # Зависимости Python
│   └── Dockerfile
│
├── docker-compose.yml        # Оркестрация сервисов
└── README.md                 # Документация проекта

---

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

Backend

• Язык: Go 1.24.0
• Фреймворк: Chi v5.2.3 (HTTP router)
• ORM: GORM v1.31.1
• База данных: PostgreSQL 15
• Документация API: Swagger/OpenAPI

Frontend

• Фреймворк: Angular 21.0.1
• UI библиотека: ng-zorro-antd 20.4.3
• Визуализация: @swimlane/ngx-charts 23.1.0, D3.js 7.9.0
• SSR: Angular SSR
• Язык: TypeScript 5.9.3

ML Service

• Язык: Python 3.x
• Фреймворк: FastAPI 0.115.6
• ML библиотеки:
  • XGBoost 3.1.2
  • scikit-learn 1.6.1
  • pandas 2.2.3
  • numpy 2.0.2
  • SHAP 0.50.0
• Сериализация: dill 0.3.9

Infrastructure

• Контейнеризация: Docker, Docker Compose
• Веб-сервер: Uvicorn 0.34.0
• База данных: PostgreSQL 15-alpine

---

🚀 Быстрый старт

Требования

• Docker версии 20.10 или выше
• Docker Compose версии 2.0 или выше
• Минимум 4 GB оперативной памяти
• Свободные порты: 4000, 5432, 8000, 8080

Запуск проекта

1. Клонируйте репозиторий:

   git clone https://github.com/Godrik0/HackChange-Alpha.git
   cd HackChange-Alpha

2. Запустите все сервисы:

   docker-compose up -d --build

   Эта команда:

   • Соберёт Docker образы для всех сервисов
   • Запустит PostgreSQL базу данных
   • Запустит ML-сервис на порту 8000
   • Запустит Backend API на порту 8080
   • Запустит Frontend на порту 4000

3. Проверьте статус сервисов:

   docker-compose ps

Доступ к сервисам

После успешного запуска доступны следующие сервисы:

• Frontend приложение: http://localhost:4000
• Backend API: http://localhost:8080
• API Documentation (Swagger): http://localhost:8080/swagger/index.html
• ML Service: http://localhost:8000
• ML Service Health: http://localhost:8000/health
• PostgreSQL: localhost:5432
  • User: postgres
  • Password: postgres
  • Database: hackchange

Проверка работоспособности

# Проверка ML сервиса
curl http://localhost:8000/health

# Проверка Backend API
curl http://localhost:8080/swagger/index.html

# Проверка Frontend
curl http://localhost:4000

---

🔧 Локальная разработка

Backend (Go)

cd backend

# Установка зависимостей
go mod download

# Запуск
go run cmd/server/main.go

Переменные окружения:

HACKCHANGE_SERVER_ADDR=0.0.0.0
HACKCHANGE_SERVER_PORT=8080
HACKCHANGE_DATABASE_HOST=localhost
HACKCHANGE_DATABASE_PORT=5432
HACKCHANGE_DATABASE_USER=postgres
HACKCHANGE_DATABASE_PASSWORD=postgres
HACKCHANGE_DATABASE_DBNAME=hackchange
HACKCHANGE_ML_BASE_URL=http://localhost:8000

Frontend (Angular)

cd frontend

# Установка зависимостей
npm install

# Запуск dev сервера
npm start

# Сборка для продакшена
npm run build

ML Service (Python)

cd ml-service

# Создание виртуального окружения
python -m venv .venv
source .venv/bin/activate

# Установка зависимостей
pip install -r requirements.txt

# Запуск сервиса
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

📊 API Endpoints

Backend API (Port 8080)

Клиенты

• POST /api/clients - Создание клиента
• GET /api/clients - Список клиентов
• GET /api/clients/:id - Получение клиента
• PUT /api/clients/:id - Обновление клиента
• DELETE /api/clients/:id - Удаление клиента

Скоринг

• POST /api/scoring/predict - Предсказание дохода клиента

Импорт

• POST /api/import/clients - Импорт клиентов из CSV
• POST /api/import/full-features - Импорт полных данных с фичами

ML Service API (Port 8000)

• POST /predict - Предсказание дохода
• GET /health - Проверка состояния сервиса
• GET /model-info - Информация о модели
• POST /reload-model - Перезагрузка модели

---

🗃 База данных

Схема PostgreSQL

Таблица clients:

• id - UUID (Primary Key)
• name - VARCHAR
• age - INTEGER
• income - DECIMAL
• credit_limit - DECIMAL
• features - JSONB (фичи для ML-модели)
• created_at - TIMESTAMP
• updated_at - TIMESTAMP

Миграции

База данных автоматически инициализируется при первом запуске через GORM AutoMigrate.

---

📝 Лицензия

MIT License - см. файл LICENSE

---

👥 Контакты

По вопросам и предложениям обращайтесь к команде разработки.