# SberBench - Banking Benchmark Platform
**SberBench** — это комплексная платформа для бенчмаркинга банковских продуктов с интеграцией искусственного интеллекта для анализа и рекомендаций. Система позволяет сравнивать предложения различных банков и получать AI-powered инсайты на базе анализа данных.
## 📋 Содержание
- [Описание проекта](#описание-проекта)
- [Основные возможности](#основные-возможности)
- [Архитектура](#архитектура)
- [Технологический стек](#технологический-стек)
- [Структура проекта](#структура-проекта)
- [Установка и запуск](#установка-и-запуск)
- [API Документация](#api-документация)
- [Переменные окружения](#переменные-окружения)
- [Разработка](#разработка)
## 📝 Описание проекта
**SberBench** предоставляет инструменты для:
- **Сравнения банковских продуктов** (вклады, кредиты, тарифы)
- **Анализа конкурентных предложений** через веб-скрейпинг
- **AI-анализа данных** с использованием OpenRouter API
- **Рекомендаций** для улучшения позиции Сбербанка на рынке
## ⭐ Основные возможности
### Backend (FastAPI + Python)
- ✅ RESTful API для управления банками и продуктами
- ✅ Автоматический сбор данных о банковских предложениях
- ✅ AI-анализ и рекомендации через DeepSeek (OpenRouter)
- ✅ Интерактивный чат с AI для обсуждения результатов
- ✅ Асинхронная обработка данных с BackgroundTasks
- ✅ SQLite БД для хранения запросов и результатов
### Frontend (React + Vite)
- ✅ Интерактивный интерфейс для создания запросов бенчмаркинга
- ✅ Таблицы сравнения банков по различным критериям
- ✅ Визуализация результатов анализа
- ✅ Интеграция с AI-чатом для уточнений
- ✅ Отзывчивый дизайн (responsive)
## 🏗️ Архитектура
```
SberBench/
├── backend/ # FastAPI приложение
│ ├── app/ # Основной код приложения
│ │ ├── services/ # Бизнес-логика (AI, сбор данных)
│ │ ├── main.py # API endpoints
│ │ ├── crud.py # Операции с БД
│ │ ├── database.py # Конфигурация SQLAlchemy
│ │ └── models.py # SQLAlchemy models
│ ├── requirements.txt # Зависимости Python
│ ├── run.py # Точка входа
│ └── .env.example # Шаблон переменных окружения
│
└── frontend/ # React приложение (Vite)
├── src/
│ ├── pages/ # Страницы приложения
│ ├── components/ # React компоненты
│ ├── services/ # API клиент
│ ├── store/ # State management
│ ├── hooks/ # Custom React hooks
│ ├── utils/ # Утилиты
│ └── styles/ # CSS стили
├── public/ # Статические файлы
└── package.json # Зависимости Node.js
```
## 🛠️ Технологический стек
### Backend
- **FastAPI** - современный веб-фреймворк
- **Python 3.8+** - язык программирования
- **SQLAlchemy** - ORM для работы с БД
- **SQLite** - легковесная БД
- **Uvicorn** - ASGI сервер
- **BeautifulSoup4** - парсинг HTML
- **aiohttp/requests** - HTTP клиент для веб-запросов
- **Pydantic** - валидация данных
- **python-dotenv** - управление переменными окружения
**API с интеграцией:**
- OpenRouter API (DeepSeek LLM) - для AI анализа
### Frontend
- **React 18.2** - UI библиотека
- **Vite 4.4** - быстрый bundler
- **React Router 6.15** - маршрутизация
- **Axios 1.5** - HTTP клиент
- **ESLint** - линтер кода
## 📂 Структура проекта
### Backend структура
#### `/backend/app/main.py` - Основной API
Содержит:
- `POST /benchmark/` - создание запроса бенчмаркинга
- `GET /banks/` - получение списка банков
- `GET /products/` - получение списка продуктов
- `POST /ai/analyze/` - AI анализ готовых данных
- `POST /ai/chat/` - интерактивный чат с AI
- `GET /benchmark/{request_id}/ai-analysis/` - получение AI анализа
#### `/backend/app/services/`
- **ai_analyzer.py** - сервис AI анализа (интеграция с OpenRouter)
- **data_collector.py** - сбор данных о банках и продуктах
- **deepseek_client.py** - клиент для взаимодействия с DeepSeek LLM
#### `/backend/app/database.py`
- Конфигурация SQLAlchemy
- Определение сессии БД
- Подключение к SQLite
#### `/backend/app/crud.py`
- Create, Read, Update, Delete операции
- Функции для работы с банками, продуктами и запросами
#### `/backend/app/models.py`
SQLAlchemy модели:
- `Bank` - информация о банках
- `Product` - банковские продукты
- `BenchmarkRequest` - запросы пользователей
### Frontend структура
#### `/frontend/src/pages/`
- Основные страницы приложения
#### `/frontend/src/components/`
- Переиспользуемые React компоненты
- UI элементы
#### `/frontend/src/services/`
- API клиент (`apiClient.js`)
- Запросы к backend
#### `/frontend/src/store/`
- State management (Zustand/Redux)
- Глобальное состояние приложения
#### `/frontend/src/hooks/`
- Custom React hooks для бизнес-логики
#### `/frontend/src/utils/`
- Вспомогательные функции
- Форматирование данных
## 🚀 Установка и запуск
### Требования
- Python 3.8+
- Node.js 16+
- npm или yarn
### Backend установка
1. **Перейти в папку backend:**
```
cd backend
```
2. **Создать виртуальное окружение:**
```
python -m venv venv
source venv/bin/activate # Linux/Mac
или
venv\Scripts\activate # Windows
```
3. **Установить зависимости:**
```
pip install -r requirements.txt
```
4. **Настроить переменные окружения:**
```
cp .env.example .env
```
Отредактировать .env и добавить:
- OPENROUTER_API_KEY (для AI анализа)
- Другие параметры по необходимости
text
5. **Запустить backend:**
```
python run.py
или
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
Backend будет доступен по адресу: `http://localhost:8000`
### Frontend установка
1. **Перейти в папку frontend:**
```
cd frontend
```
2. **Установить зависимости:**
```
npm install
```
3. **Запустить dev сервер:**
```
npm run dev
```
Frontend будет доступен по адресу: `http://localhost:5173` (Vite default)
### Docker (опционально)
Для развертывания в Docker:
```
Backend
docker build -t sberbench-backend ./backend
docker run -p 8000:8000 sberbench-backend
Frontend
docker build -t sberbench-frontend ./frontend
docker run -p 3000:3000 sberbench-frontend
```
## 📡 API Документация
### Interactive API Docs
После запуска backend откройте:
- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
### Основные endpoints
#### 1. Получить список банков
```
GET /banks/?skip=0&limit=100
```
#### 2. Получить список продуктов
```
GET /products/?skip=0&limit=100
```
#### 3. Создать запрос бенчмаркинга
```
POST /benchmark/
Content-Type: application/json
{
"product_name": "Вклады",
"competitors": ["Альфа-Банк", "ВТБ"],
"criteria": ["процентная_ставка", "минимальный_взнос", "срок"]
}
```
**Ответ:**
```
{
"request_id": 1,
"product_name": "Вклады",
"comparison_table": [...],
"summary": {...},
"best_bank": "Сбер",
"sber_advantages": [...],
"improvement_areas": [...],
"ai_suggestions": {...},
"ai_analysis": {...},
"strategic_recommendations": {...}
}
```
#### 4. AI анализ данных
```
POST /ai/analyze/
Content-Type: application/json
{
"comparison_data": {...},
"product_type": "Вклады",
"criteria": ["ставка", "условия"]
}
```
#### 5. AI чат
```
POST /ai/chat/
Content-Type: application/json
{
"message": "Почему Сбер лучше чем конкуренты по вкладам?"
}
```
#### 6. Проверка здоровья приложения
```
GET /health/
```
## 🔐 Переменные окружения
Создайте файл `.env` в папке `backend` на основе `.env.example`:
```
OpenRouter API Configuration
OPENROUTER_API_KEY=sk-your-api-key-here
Database
DATABASE_URL=sqlite:///./benchmark.db
Application Settings
DEBUG=True
HOST=0.0.0.0
PORT=8000
Project Info
PROJECT_NAME=Banking Benchmark AI
PROJECT_REPOSITORY=https://gitverse.ru/banking-benchmark
```
### Получение API ключей
**OpenRouter API:**
1. Перейти на https://openrouter.ai/
2. Зарегистрироваться
3. Скопировать API ключ
4. Добавить в переменную окружения `OPENROUTER_API_KEY`
## 👨💻 Разработка
### Структура кода
**Backend:**
- Все API endpoints в `app/main.py`
- Бизнес-логика в `app/services/`
- Работа с БД в `app/crud.py`
- Модели данных в `app/models.py`
**Frontend:**
- Компоненты в `src/components/`
- Страницы в `src/pages/`
- API запросы в `src/services/`
### Запуск с режимом разработки
Backend с hot reload
```
uvicorn app.main:app --reload
```
Frontend с hot reload
```
npm run dev
```
### Линтинг и форматирование
**Backend (Python):**
```
pip install pylint black
black app/
pylint app/
```
**Frontend (JavaScript):**
```
npm run lint
npm run lint -- --fix
```
### Тестирование
**Backend (при наличии тестов):**
```
pytest
```
**Frontend (при наличии тестов):**
```
npm test
```
## 🔄 Workflow бенчмаркинга
1. **Пользователь** создает запрос бенчмаркинга (выбирает продукт, конкурентов, критерии)
2. **Backend** собирает данные о предложениях банков
3. **AI Service** анализирует собранные данные через OpenRouter
4. **Backend** формирует таблицу сравнения и рекомендации
5. **Frontend** отображает результаты пользователю
6. **Пользователь** может уточнить результаты через AI чат
## 📊 Примеры использования
### Пример 1: Анализ вкладов
```
curl -X POST http://localhost:8000/benchmark/
-H "Content-Type: application/json"
-d '{
"product_name": "Вклады",
"competitors": ["Альфа", "ВТБ", "Газпром"],
"criteria": ["ставка", "минимум", "условия"]
}'
```
### Пример 2: AI рекомендации
```
curl -X POST http://localhost:8000/ai/analyze/
-H "Content-Type: application/json"
-d '{
"product_type": "Кредиты",
"criteria": ["ставка", "срок"]
}'
```