Readme - master - Sano_Enger/SberBench

Readme
413 строк13 KB
Sano_Enger
update Readme
23 ноя 2025, 03:27
23 ноя 2025, 03:2758fd43a
# 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": ["ставка", "срок"]
}'
```