200 lines
10 KiB
Markdown
200 lines
10 KiB
Markdown
# 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 поддерживается
|
||
|
||
### Логи для диагностики
|
||
|
||
Все ошибки логируются с детальной информацией. Проверьте:
|
||
- Консольные логи при запуске
|
||
- Логи в базе данных (если включено)
|
||
- Файлы результатов для проверки данных |