1. Общие сведения
- Цель разработки: Создание Python-скрипта для автоматизации задач, связанных с управлением Telegram-ботом, выполнением SEO оптимизации, взаимодействием с OpenCart API, и предоставлением REST API на базе Flask.
- Среда выполнения: Сервер Ubuntu 20.04.
- Используемые технологии: Python, Flask, Gunicorn, aiogram, OpenAI API, OpenCart API, SQL, PHP.
2. Описание функциональных модулей
2.1 Telegram-бот
Файлы: `bot.py`, `app.py`
- Основные задачи:
- Инициализация и конфигурация:
- Бот загружает конфигурационные параметры из файла `config.py`, включая параметры подключения к Telegram API, базу данных, и ключи API для внешних сервисов.
- Используется библиотека `aiogram` для асинхронного взаимодействия с Telegram API, что позволяет боту эффективно обрабатывать несколько запросов одновременно.
- Обработка команд:
- Поддержка команд:
- `/start`: Отправка приветственного сообщения и инструкций по использованию бота.
- `/help`: Предоставление списка всех доступных команд с кратким описанием их функциональности.
- `/update_seo`: Запуск процесса обновления SEO данных для продуктов или категорий в OpenCart.
- Бот предлагает команды для выбора всех товаров или категорий для обновления.
- Пользователь может выбрать один из двух режимов обновления:
1. Массовое обновление — обновление SEO данных для всех выбранных продуктов или категорий.
2. Обновление по URL — обновление SEO данных для конкретного продукта или категории, указанных по URL.
- В обоих случаях данные загружаются из XML ссылки и проверяются через базу данных, чтобы определить, были ли они обработаны ранее.
- Предусмотрена настройка для учета или игнорирования истории обработки (например, обработанные данные могут быть обновлены или пропущены в зависимости от настройки).
- Введенные пользователем данные (например, URL или параметры для массового обновления) должны быть предварительно проверены (валидированы) перед началом обработки.
- `/get_product_info [ID]`: Запрос информации о продукте по его уникальному идентификатору из OpenCart.
- Логика обработки команды `/update_seo`:
1. Пользователь выбирает, обновлять все товары или категории.
2. Скрипт предлагает пользователю выбрать режим обновления: массовое обновление или обновление по URL.
3. В случае массового обновления, скрипт загружает данные из XML ссылки и проверяет их в базе данных.
4. В случае обновления по URL, введенный URL проверяется на корректность и соответствие нужным параметрам.
5. Данные проверяются на наличие в базе данных, чтобы определить, были ли они обработаны ранее.
6. В зависимости от настройки (учитывать историю обработки или нет), данные либо обновляются, либо пропускаются.
7. Результаты обновления сохраняются в базе данных, и пользователь уведомляется о завершении процесса.
- Взаимодействие с внешними сервисами:
- OpenAI API:
- Генерация текстов, таких как SEO-описания продуктов, на основе данных, предоставленных пользователем или полученных из базы данных.
- Формирование запроса к API с необходимым промптом (например, описание продукта) и обработка полученного ответа для дальнейшего использования в других модулях скрипта.
- OpenCart API:
- Получение данных о продуктах, таких как название, описание, цена, количество на складе и других характеристик, по запросу пользователя.
- Обновление информации о продуктах на основе данных, предоставленных пользователем или сгенерированных с помощью других модулей (например, генератором SEO).
2.2 Веб-приложение на Flask
Файлы: `app.py`, `wsgi.py`, `gunicorn_conf.py`
- Основные задачи:
- Инициализация и настройка:
- Веб-приложение инициализируется с использованием Flask и настроено на работу с Gunicorn для обеспечения многопоточности и масштабируемости.
- Настройка конфигурационных файлов, таких как `gunicorn_conf.py`, для оптимизации производительности и управления ресурсами сервера.
- Маршрутизация:
- Приложение поддерживает несколько маршрутов для обработки HTTP-запросов, например:
- `/api/product/<product_id>`: Получение информации о продукте по его ID.
- `/api/update_seo`: Запуск процесса обновления SEO данных для всех продуктов.
- Каждый маршрут корректно обрабатывает запросы, проверяя параметры и выполняя необходимые действия, такие как взаимодействие с базой данных или вызов внешних API.
- Обработка данных:
- Веб-приложение интегрируется с базой данных через `db_manager.py` для выполнения операций чтения, записи, обновления и удаления данных.
- Обработка данных включает валидацию входных данных и применение бизнес-логики перед выполнением операций.
- Возврат ответов:
- Приложение формирует и возвращает ответы в формате JSON, включая информацию о статусе выполнения запроса, данные о продуктах, результаты обновления SEO данных и другие релевантные данные.
- В случае ошибок или некорректных данных, приложение возвращает подробные сообщения об ошибках с указанием причин и возможных решений.
2.3 Работа с базой данных
Файлы: `db_manager.py`
- Основные задачи:
- Управление базой данных:
- Скрипт обеспечивает создание, чтение, обновление и удаление (CRUD) данных о продуктах, пользователях, SEO параметрах и других связанных сущностях.
- Реализация взаимодействия с базой данных через ORM (если используется) или прямые SQL-запросы для повышения производительности.
- Оптимизация запросов:
- SQL-запросы оптимизированы для минимизации нагрузки на базу данных и быстрого выполнения.
- Предусмотрена индексация полей, часто используемых в запросах, для повышения скорости выборки данных.
- Интеграция с другими модулями:
- Работа с базой данных интегрирована с модулями Telegram-бота и веб-приложения, чтобы обеспечить синхронизацию данных между различными компонентами системы.
- Модули взаимодействуют с базой данных через API или напрямую для выполнения необходимых операций, таких как обновление данных о продуктах или сохранение сгенерированных SEO описаний.
2.4 SEO генератор
Файлы: `seo_generator.py`, `update_seo.php`
- Основные задачи:
- Генерация SEO данных:
- Использование OpenAI API для генерации SEO-описаний, мета-тегов и других элементов SEO на основе данных о продуктах.
- Генерация многоязычных описаний для поддержки мультинациональных магазинов, если это требуется.
- Сценарии генерации учитывают уникальные особенности продуктов, такие как их категория, целевая аудитория и конкурентное окружение.
- Анализ и обновление данных:
- Парсинг существующего контента на страницах для выявления id товара или категории в теге <body>.
- Модуль обновляет существующие SEO данные в базе данных на основе анализа и сгенерированных описаний.
- После обновления данных в базе, скрипт автоматически отправляет обновленные SEO данные в OpenCart через соответствующий API.
- Интеграция с OpenCart API:
- Скрипт обеспечивает тесную интеграцию с OpenCart для автоматического обновления SEO данных продуктов через API.
- Модуль поддерживает как автоматические, так и ручные запуски обновления SEO данных через интерфейсы Telegram-бота, веб-приложения Flask или скрипта `update_seo.php`.
2.5 Интеграция с OpenCart API
Файлы: `opencart_api.py`
- Основные задачи:
- Получение данных о продуктах:
- Модуль обеспечивает получение информации о продуктах из OpenCart API по уникальному идентификатору (ID) или другим параметрам.
- Полученные данные включают все необходимые атрибуты продукта, такие как название, описание, цена, наличие на складе, категория и другие.
- Модуль интегрирован с другими компонентами системы, такими как SEO генератор и Telegram-бот, для предоставления пользователям актуальной информации.
- Обновление данных:
- Модуль поддерживает обновление данных о продуктах в OpenCart через API, включая изменение цен, описание, количества на складе и других параметров.
- Для обновления данных используются методы POST или PUT, с обязательной проверкой успешности выполнения операции.
- Авторизация и безопасность:
- Все взаимодействия с OpenCart API защищены с использованием токенов авторизации и других мер безопасности для предотвращения несанкционированного доступа.
- Модуль поддерживает обновление и управление токенами API, включая их автоматическое обновление по мере необходимости.
- Отправка уведомлений:
- Модуль отправляет уведомления пользователям (например, через Telegram-бота) о результатах выполнения операций с продуктами, таких как успешное обновление данных или возникновение ошибок.
3. Дополнительные модули
3.1 Логирование
Файлы: `requirements_logging.py`
- Основные задачи:
- Логирование операций:
- Все значимые события в системе логируются, включая ошибки, взаимодействия с внешними API, изменения в базе данных и другие критические операции.
- Логи включают информацию о времени события, источнике (например, модуль, вызвавший событие), статусе операции и подробности выполнения.
- Настройка логирования:
- Логирование поддерживает разные уровни детализации (debug, info, error) в зависимости от текущей среды (разработка, тестирование, продакшн).
- Логи хранятся в определенном формате и месте (например, на локальном сервере или в облачном хранилище), с возможностью дальнейшего анализа и мониторинга.
3.2 Валидация данных
Файлы: `validators.py`
- Основные задачи:
- Валидация входных данных:
- Модуль реализует функции для валидации всех данных, поступающих от пользователей Telegram-бота, через веб-приложение или из внешних API.
- Валидация включает проверку формата данных (например, числовые ID, текстовые поля), допустимых значений, наличия обязательных полей и других параметров.
- Модуль интегрирован с другими компонентами системы для обеспечения корректности данных на всех этапах обработки.
- Обработка ошибок валидации:
- В случае некорректных данных, модуль возвращает соответствующие сообщения об ошибках пользователям или клиентам API, с указанием причин ошибки и рекомендаций по исправлению.
4. Скрипт для обновления SEO данных
Файлы: `update_seo.php`
- Основные задачи:
- Запуск процесса обновления:
- PHP скрипт запускает процесс обновления SEO данных для всех продуктов в базе данных.
- Скрипт интегрирован с другими модулями системы, такими как `seo_generator.py`, для выполнения обновления на основании сгенерированных данных.
- Интеграция с базой данных и OpenCart:
- Скрипт взаимодействует с базой данных для получения текущих данных о продуктах и сохранения новых SEO параметров.
- Обновленные данные автоматически передаются в OpenCart через API для обновления страниц продуктов.
- Автоматизация процесса:
- Скрипт поддерживает возможность автоматического запуска по расписанию (например, с использованием cron задач), чтобы обеспечить регулярное обновление SEO данных.
- В случае ошибок или сбоев, скрипт логирует соответствующую информацию для последующего анализа и устранения.
