busya/peptide-parcer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readme update

Browse Source
This commit is contained in:
busya
2025-07-21 10:37:12 +03:00
parent 69e90bd4f2
commit ae6d81f6f2
1 changed files with 81 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

236
README.md
View File

@@ -1,58 +1,55 @@
# ANCHOR: Project_README
# Семантика: Документация, описывающая проект, его структуру и способ использования.
# Парсер цен для ElixirPeptide
# Сервис мониторинга цен ElixirPeptide (v3.0)
Это структурированное Python-приложение для парсинга каталога товаров с сайта `elixirpeptide.ru`, сбора информации о вариантах товаров и их ценах.
Это распределенное Python-приложение для мониторинга каталога товаров с сайта `elixirpeptide.ru`. Сервис автоматически отслеживает изменения в ценах и наличии товаров, и отправляет отчеты в Telegram.
## 🚀 Новые возможности (v2.0)
## 🚀 Архитектура (v3.0)
### ✅ Исправленные критические проблемы:
- **Устранено дублирование кода** в `engine.py` и `database.py`
- **Дополнены зависимости** в `requirements.txt` (pydantic, lxml, python-dotenv)
- **Улучшена обработка ошибок** с детальной диагностикой и retry механизмом
- **Добавлена валидация данных** на всех уровнях приложения
Проект перешел от простого парсера к полноценному сервису мониторинга с асинхронной обработкой данных.
### 🎯 Новые функции:
- **Retry стратегия** для HTTP запросов с экспоненциальной задержкой
- **Детальная статистика** выполнения парсинга
- **Валидация конфигурации** при запуске
- **Поддержка переменных окружения** через `.env` файл
- **Graceful degradation** - продолжение работы при частичных сбоях
- **Улучшенное логирование** с категоризацией ошибок
- **Точка входа**: `monitoring_service.py` — главный скрипт, запускаемый по расписанию (cron).
- **Оркестратор**: `src/orchestrator.py` управляет процессом парсинга.
- **Анализатор**: `src/analyzer.py` сравнивает данные последнего и предпоследнего запусков, выявляя изменения.
- **Уведомления**: `src/utils/telegram_sender.py` отправляет HTML-отчеты об изменениях в Telegram.
- **Очередь сообщений**: Интеграция с **RabbitMQ** для асинхронного экспорта данных о товарах и логах.
- **База данных**: **SQLite** используется для хранения истории парсинга и данных для анализа.
### 🔧 Улучшения производительности:
- **Адаптивные таймауты** для HTTP запросов
- **Проверка на блокировку/капчу** в ответах сервера
- **Оптимизированная обработка данных** с пропуском некорректных записей
## ✨ Ключевые возможности
- **Автоматический мониторинг**: Запуск по расписанию для непрерывного отслеживания.
- **Отчеты об изменениях**: Уведомления в Telegram о новых, удаленных товарах, а также изменениях цен и наличия.
- **Асинхронный экспорт**: Отправка данных в RabbitMQ для дальнейшей обработки другими системами.
- **Надежность**: Механизм retry-запросов, детальное логирование и отказоустойчивость.
- **Гибкая конфигурация**: Все параметры настраиваются через `.env` файл.
## Структура Проекта
Проект организован по принципу семантического разделения ответственности для удобства поддержки и дальнейшей разработки.
- `monitoring_service.py`: **[NEW]** Главная точка входа для запуска по расписанию.
- `src/`: Основная директория с исходным кодом.
- `config.py`: Все настройки (URL, селекторы, флаги сохранения).
- `main.py`: Точка входа в приложение, оркестратор процесса.
- `core/`: Пакет с ядром приложения.
- `orchestrator.py`: **[NEW]** Управляет всем процессом парсинга.
- `analyzer.py`: **[NEW]** Анализирует данные и формирует отчеты.
- `main.py`: Точка входа для ручного запуска парсинга.
- `core/`: Ядро приложения.
- `settings.py`: **[ENHANCED]** Pydantic-модели для конфигурации (включая Telegram, RabbitMQ).
- `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] Пример файла с переменными окружения**
- `rabbitmq.py`: **[NEW]** Клиент для работы с RabbitMQ.
- `scraper/`: Логика парсинга.
- `engine.py`: Улучшенный движок парсера.
- `utils/`: Вспомогательные утилиты.
- `telegram_sender.py`: **[NEW]** Отправка уведомлений в Telegram.
- `requirements.txt`: **[UPDATED]** Обновленный список зависимостей.
- `.env.example`: Пример файла с переменными окружения.
- `RABBITMQ_SETUP.md`: **[NEW]** Руководство по настройке RabbitMQ.
## Установка и Запуск
### 1. Клонирование и настройка окружения
```bash
git clone <your-repo-url>
cd peptide_parser_project
git clone https://gitea.bebesh.ru/busya/peptide-parcer.git
cd peptide-parcer
# Создание виртуального окружения
python -m venv venv
@@ -62,139 +59,68 @@ source venv/bin/activate # Для Windows: venv\Scripts\activate
pip install -r requirements.txt
```
### 2. Настройка конфигурации
### 2. Настройка RabbitMQ (Опционально)
#### Вариант A: Через переменные окружения
Для асинхронного экспорта данных требуется RabbitMQ. Рекомендуется запуск через Docker:
```bash
# Создайте файл .env на основе .env.example
cp .env.example .env
docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management
```
Подробности см. в `RABBITMQ_SETUP.md`.
# Отредактируйте .env файл под ваши нужды
nano .env
### 3. Настройка конфигурации
Скопируйте `.env.example` в `.env` и заполните необходимые параметры.
```bash
cp .env.example .env
nano .env # Отредактируйте файл
```
#### Вариант B: Прямое редактирование настроек
Отредактируйте `src/core/settings.py` для изменения настроек по умолчанию.
**Ключевые переменные окружения:**
- `TELEGRAM_BOT_TOKEN`: Токен вашего Telegram-бота.
- `TELEGRAM_CHAT_ID`: ID чата, куда будут приходить отчеты.
- `ENABLE_RABBITMQ_EXPORT`: `true` или `false` для включения/отключения экспорта в RabbitMQ.
- `RABBITMQ_HOST`, `RABBITMQ_PORT` и т.д.: Настройки подключения к RabbitMQ.
### 3. Запуск парсера
### 4. Запуск
#### Автоматический мониторинг (рекомендуется)
Настройте запуск `monitoring_service.py` через `cron` или планировщик задач.
```bash
# Пример для cron, запуск каждый час
# 0 * * * * /path/to/your/project/venv/bin/python /path/to/your/project/monitoring_service.py >> /path/to/your/project/logs/cron.log 2>&1
# Ручной запуск для проверки
python monitoring_service.py
```
#### Ручной запуск парсинга (без анализа и отчета)
```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**: Продолжение работы при ошибках отдельных запросов
## Результаты
### Файлы результатов
### Отчеты в Telegram
Сервис присылает в указанный чат отчет, если обнаруживает изменения:
- **💰 Изменились цены**: список товаров с новой и старой ценой.
- **📦 Изменилось наличие**: список товаров, которые появились или закончились.
- **✨ Новые товары**: список добавленных товаров.
- **🗑️ Удаленные товары**: список удаленных товаров.
- **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`
### Данные
- **База данных**: `price_data_final/parser_data.db` — хранит всю историю парсинга.
- **CSV файл**: `price_data_final/prices_full_catalog_*.csv` — создается при ручном запуске.
- **RabbitMQ**: Сообщения с данными о товарах и логах отправляются в очереди `price_parser.products` и `price_parser.logs`.
## Устранение неполадок
### Частые проблемы
1. **"Не удается подключиться к базовому URL"**
- Проверьте интернет-соединение
- Убедитесь, что сайт доступен
- Проверьте настройки прокси
2. **"Не найдено ни одной ссылки на товар"**
- Проверьте CSS селекторы в настройках
- Убедитесь, что структура сайта не изменилась
3. **"Ошибка при сохранении в БД"**
- Проверьте права доступа к директории
- Убедитесь, что SQLite поддерживается
### Логи для диагностики
Все ошибки логируются с детальной информацией. Проверьте:
- Консольные логи при запуске
- Логи в базе данных (если включено)
- Файлы результатов для проверки данных
1. **Не приходят сообщения в Telegram**:
- Проверьте правильность `TELEGRAM_BOT_TOKEN` и `TELEGRAM_CHAT_ID`.
- Убедитесь, что бот добавлен в чат с нужными правами.
2. **Ошибка подключения к RabbitMQ**:
- Проверьте, что RabbitMQ запущен и доступен.
- Убедитесь в корректности настроек в `.env`.
3. **Ошибки парсинга**:
- Проверьте доступность сайта `elixirpeptide.ru`.
- Возможно, изменилась структура HTML-страниц. В этом случае нужно обновить CSS-селекторы в `src/core/settings.py`.