# ANCHOR: Project_README
# Семантика: Документация, описывающая проект, его структуру и способ использования.

# Парсер цен для ElixirPeptide

Это структурированное Python-приложение для парсинга каталога товаров с сайта `elixirpeptide.ru`, сбора информации о вариантах товаров и их ценах.

## 🚀 Новые возможности (v2.0)

### ✅ Исправленные критические проблемы:
- **Устранено дублирование кода** в `engine.py` и `database.py`
- **Дополнены зависимости** в `requirements.txt` (pydantic, lxml, python-dotenv)
- **Улучшена обработка ошибок** с детальной диагностикой и retry механизмом
- **Добавлена валидация данных** на всех уровнях приложения

### 🎯 Новые функции:
- **Retry стратегия** для HTTP запросов с экспоненциальной задержкой
- **Детальная статистика** выполнения парсинга
- **Валидация конфигурации** при запуске
- **Поддержка переменных окружения** через `.env` файл
- **Graceful degradation** - продолжение работы при частичных сбоях
- **Улучшенное логирование** с категоризацией ошибок

### 🔧 Улучшения производительности:
- **Адаптивные таймауты** для HTTP запросов
- **Проверка на блокировку/капчу** в ответах сервера
- **Оптимизированная обработка данных** с пропуском некорректных записей

## Структура Проекта

Проект организован по принципу семантического разделения ответственности для удобства поддержки и дальнейшей разработки.

- `src/`: Основная директория с исходным кодом.
  - `config.py`: Все настройки (URL, селекторы, флаги сохранения).
  - `main.py`: Точка входа в приложение, оркестратор процесса.
  - `core/`: Пакет с ядром приложения.
    - `database.py`: Логика работы с базой данных SQLite.
    - `logging_config.py`: Настройка системы логирования.
    - **`models.py`: [NEW FILE] Pydantic модели данных (ProductVariant, LogRecordModel).**
    - **`settings.py`: [ENHANCED] Конфигурация с валидацией и поддержкой .env**
  - `scraper/`: Пакет с логикой парсинга.
    - **`engine.py`: [ENHANCED] Класс Scraper с retry механизмом и улучшенной обработкой ошибок**
  - `utils/`: Пакет со вспомогательными утилитами.
    - **`exporters.py`: [ENHANCED] Функции для сохранения данных с валидацией**
- `requirements.txt`: Список зависимостей проекта.
- `price_data_final/`: Директория для хранения результатов (создается автоматически).
- **`.env.example`: [NEW] Пример файла с переменными окружения**

## Установка и Запуск

### 1. Клонирование и настройка окружения

```bash
git clone <your-repo-url>
cd peptide_parser_project

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

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

### 2. Настройка конфигурации

#### Вариант A: Через переменные окружения
```bash
# Создайте файл .env на основе .env.example
cp .env.example .env

# Отредактируйте .env файл под ваши нужды
nano .env
```

#### Вариант B: Прямое редактирование настроек
Отредактируйте `src/core/settings.py` для изменения настроек по умолчанию.

### 3. Запуск парсера

```bash
python src/main.py
```

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

### Переменные окружения (.env файл)

| Переменная | Описание | По умолчанию |
|------------|----------|--------------|
| `PARSER_BASE_URL` | Базовый URL сайта | `https://elixirpeptide.ru` |
| `PARSER_CATALOG_URL` | URL каталога товаров | `https://elixirpeptide.ru/catalog/` |
| `PARSER_SAVE_TO_CSV` | Сохранять в CSV | `true` |
| `PARSER_SAVE_TO_DB` | Сохранять в базу данных | `true` |
| `PARSER_LOG_TO_DB` | Логировать в базу данных | `true` |
| `PARSER_TIMEOUT` | Таймаут HTTP запросов (сек) | `30` |
| `PARSER_DELAY` | Задержка между запросами (сек) | `1.0` |
| `PARSER_RETRIES` | Максимум попыток для запросов | `3` |

### Настройки производительности

- **Таймаут запросов**: 30 секунд (настраивается)
- **Задержка между запросами**: 1 секунда (настраивается)
- **Retry стратегия**: 3 попытки с экспоненциальной задержкой
- **Graceful degradation**: Продолжение работы при ошибках отдельных запросов

## Результаты

### Файлы результатов

- **CSV файл**: `price_data_final/prices_full_catalog_YYYY-MM-DD_HHMMSS.csv`
- **База данных**: `price_data_final/parser_data.db` (SQLite)

### Структура данных

```csv
name,volume,price
"Peptide X","30ml",1500
"Peptide Y","50ml",2500
```

### Логирование

- **Консольные логи**: Детальная информация о процессе парсинга
- **Логи в БД**: Если `PARSER_LOG_TO_DB=true`, все логи сохраняются в таблицу `logs`

## Обработка ошибок

### Типы обрабатываемых ошибок

1. **Сетевые ошибки**: Timeout, ConnectionError, HTTPError
2. **Ошибки парсинга**: Отсутствующие элементы, некорректные данные
3. **Ошибки файловой системы**: Права доступа, отсутствие директорий
4. **Ошибки базы данных**: SQLite ошибки, проблемы с подключением

### Стратегия восстановления

- **Retry механизм**: Автоматические повторные попытки для сетевых ошибок
- **Graceful degradation**: Пропуск проблемных записей с продолжением работы
- **Детальная диагностика**: Подробные логи для анализа проблем

## Мониторинг и статистика

### Статистика выполнения

Приложение выводит детальную статистику:

```
[FINAL_STATS] Время выполнения: 45.23 секунд
[FINAL_STATS] Успешность: 95/100 (95.0%)
[STATS] Успешно: 95, Ошибок: 5
```

### Метрики

- Общее количество URL для парсинга
- Количество успешно обработанных записей
- Количество ошибок
- Время выполнения
- Процент успешности

## Разработка

### Архитектурные принципы

1. **Разделение ответственности**: Каждый модуль отвечает за свою область
2. **Типизация**: Использование Pydantic для валидации данных
3. **Обработка ошибок**: Graceful handling с детальной диагностикой
4. **Конфигурируемость**: Гибкие настройки через переменные окружения
5. **Логирование**: Структурированное логирование на всех уровнях

### Добавление новых функций

1. **Новые форматы экспорта**: Добавьте функции в `src/utils/exporters.py`
2. **Новые селекторы**: Обновите `ScraperSelectors` в `src/core/settings.py`
3. **Новые поля данных**: Расширьте модель `ProductVariant` в `src/core/models.py`

## Устранение неполадок

### Частые проблемы

1. **"Не удается подключиться к базовому URL"**
   - Проверьте интернет-соединение
   - Убедитесь, что сайт доступен
   - Проверьте настройки прокси

2. **"Не найдено ни одной ссылки на товар"**
   - Проверьте CSS селекторы в настройках
   - Убедитесь, что структура сайта не изменилась

3. **"Ошибка при сохранении в БД"**
   - Проверьте права доступа к директории
   - Убедитесь, что SQLite поддерживается

### Логи для диагностики

Все ошибки логируются с детальной информацией. Проверьте:
- Консольные логи при запуске
- Логи в базе данных (если включено)
- Файлы результатов для проверки данных