Ord Ozon Manager

Ord Ozon Manager — это инструмент для автоматизации процесса формирования и отправки статистики рекламных интеграций в ОРД. Проект разработан с использованием фреймворка NestJS и интегрирован с API ОРД Озон, что позволяет автоматически синхронизировать данные с данной платформой.

Описание проекта

Этот проект разработан для автоматизации работы с рекламными интеграциями и платформами в системе ОРД Озон. Основной функционал включает в себя получение списка креативов, сопоставление их с интеграциями в базе данных, расчет и генерацию статистики по просмотрам, затратам, и автоматическую отправку этой информации в ОРД. Приложение также поддерживает создание, хранение и управление данными о рекламных интеграциях и платформах, с возможностью автоматической синхронизации с ОРД Озон.

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

Основные функции

1. Получение списка креативов из ОРД Озон и сопоставление с интеграциями в базе данных.

   • Этот процесс основан на сопоставлении Erid Token, который используется как уникальный идентификатор интеграции в системе.

2. Синхронизация рекламных платформ между базой данных и ОРД Озон.

   • Перед отправкой статистики приложение автоматически синхронизирует данные о платформах, сравнивая их с локальной базой данных.

3. Автоматическое добавление недостающих рекламных платформ в базу данных.

   • Если платформа канала отсутствует в базе данных, она автоматически создается и синхронизируется с ОРД Озон.

4. Расчет и генерация статистики по недостающим месяцам для интеграций.

   • Метод анализирует, какие месяцы отсутствуют в статистике и создает данные для этих периодов, основываясь на дате выхода интеграции.

5. Расчет затрат и стоимости интеграций.

   • Определение затрат на рекламные интеграции, включая расчеты для каждого месяца на основе стоимости приложения.

6. Расчет просмотров для интеграций.

   • Приложение рассчитывает количество просмотров за каждый месяц, включая сложные сценарии, когда статистика просмотров была недоступна в предыдущие месяцы.

7. Создание и отправка статистики интеграций в ОРД Озон.

   • После всех расчетов данные отправляются в ОРД Озон, и сохраняются в локальной базе данных для дальнейшего анализа и отчетности.

8. Планирование задач с помощью Cron для регулярного выполнения операций.

   • Процессы синхронизации и отправки данных автоматизируются и запускаются по расписанию, что позволяет поддерживать актуальность данных без участия пользователя.

9. Использование сидов для тестирования и работы с проектом.

   • Генерация мок-данных для базы данных, включая каналы, интеграции и оплаты, что позволяет быстро приступить к тестированию проекта.

   Особенности проекта

• Мок-данные: Для облегчения старта работы с приложением и тестовых запросов, в проекте реализована "имитация" получения данных о креативах из ОРД Озон. Используется файл mock-creatives.ts, содержащий данные, идентичные креативам в ОРД Озон.

• Связь с базой данных: При генерации сидов в базу данных будут созданы интеграции с Erid токенами, взятыми из файла mock-creatives.ts (используются поля markers).

• Обновление платформ: Сервис автоматически синхронизирует рекламные платформы между локальной базой данных и ОРД Озон. Для этого используется метод processUpdateChannelPlatforms, который также может быть вызван вручную через соответствующий эндпоинт.

• Связь платформ: Основная связь рекламных площадок (платформ) из ОРД с локальной базой данных осуществляется через поле channel.link, которое служит уникальным ключом для связи. Перед началом работы сервис запрашивает рекламные платформы из ОРД Озон и сравнивает их с данными в локальной базе для определения, какие платформы необходимо обновить или добавить.

• Поля сущности Channel: Поля ordPlatformId и ordExternalPlatformId в сущности Channel указывают, была ли уже создана рекламная платформа канала в ОРД Озон. Если они равны null, платформа еще не была создана, и сервис создаст ее. В противном случае, сервис использует уже существующую платформу.

Генерация статистики

Особенность метода генерации статистики заключается в том, что он автоматически создает объекты статистики для всех недостающих месяцев с момента выхода интеграции. Например, если интеграция вышла 1 января 2024 года, а сейчас 1 августа 2024 года, метод создаст 7 недостающих объектов статистики.

• Сущность OrdIntegration: Для определения, для каких месяцев нужно генерировать статистику, используется сущность OrdIntegration, в которую заносятся данные о созданной статистике.

• Расчет затрат: Поля moneySpent и unitCost равны по значению и указываются только в первый месяц выхода интеграции. В последующие месяцы они принимают значение 0, что соответствует тому, что оплата за интеграцию была произведена единожды в первый месяц.

Расчет просмотров

Один из сложных аспектов проекта — расчет просмотров интеграций за каждый месяц. Например, если интеграция вышла более месяца назад и не имеет данных в сущности OrdIntegration за прошлый месяц, в первый месяц указывается полная сумма просмотров, а в последующие — 0.

• Динамика просмотров: Если интеграция вышла в прошлом месяце, метод записывает актуальные просмотры и в следующем месяце рассчитывает разницу, вычитая прошлые данные из текущих. Поле ordIntegration.viewsSum содержит сумму просмотров за текущий месяц.
• Поля просмотров: Поля viewsCountByInvoice и viewsCountByFact равны по значению и каждый месяц содержат разницу просмотров, накопленную за текущий месяц.

Дополнительные замечания

• Код проекта содержит подробные комментарии и закомментированные участки с "return...", чтобы упростить проверку работы методов.
• Для упрощения работы с API ОРД Озон в проекте реализован отдельный сервис ordOzon.service, который отвечает за отправку запросов.

Стек проекта

Проект разработан с использованием NestJS, прогрессивного фреймворка для создания серверных приложений на Node.js.

Установка и запуск

Для быстрого развертывания проекта используйте Docker. Выполните следующую команду в корневой директории проекта:

docker-compose up --build

Для запуска Backend части приложения на NestJS без использования Docker нужно установить все зависимости выполните команду(также должна быть установлена база данных MySQL):

В директории проекта:

npm ci
npm run start:dev

Порты и переменные окружения

• Backend: http://localhost:3500
• MySQL Database: http://localhost:3306
• PhpMyAdmin: http://localhost:8080
• MYSQL_HOST: 'localhost' (по умолчанию)
• MYSQL_USERNAME: 'root'
• MYSQL_PASSWORD: 'root'
• MYSQL_DATABASE: 'ord-manager'

Основные возможности

1. Автоматизация:

   • Полный цикл автоматизации процесса отправки статистики в ОРД Озон, включая все необходимые шаги от получения данных до их отправки.

2. Получение списка креативов и сопоставление с интеграциями в БД:

   • Имитация получения данных через mock-creatives.ts.
   • Сопоставление Erid токенов с маркерами из БД.

3. Синхронизация платформ каналов между БД и ОРД Озон:

   • Автоматическая проверка и обновление рекламных платформ.

4. Автоматическое добавление недостающих платформ каналов в БД:

   • Уникальный ключ для связи — channel.link.

5. Расчет недостающих месяцев для статистики интеграций:

   • Генерация статистики за все месяцы с момента выхода интеграции.

6. Расчет затрат и стоимости за интеграции:

   • Учет затрат только в первый месяц выхода интеграции.

7. Расчет просмотров за интеграции:

   • Разница просмотров рассчитывается на основе данных ordIntegration.viewsSum.

8. Создание и отправка статистики интеграций в ОРД Озон:

   • Отправка данных в ОРД через сервис ordOzon.service.

9. Планирование задач с помощью Cron:

   • Регулярное выполнение операций через Cron.

10. Использование сидов:

    • Генерация готовых данных для БД и поддержка их удаления через отдельные методы.

11. Документация:

    • Встроенная документация API через Swagger, доступная по адресу http://localhost:3500/api.

Будущие доработки

В планах на будущее:

• Улучшение генерации статистики просмотров: Разработка более сложного алгоритма распределения просмотров по месяцам, чтобы обеспечить более точное отображение динамики.
• Расширение функционала: Добавление новых возможностей для работы с другими API и интеграциями.
• Добавление новой ОРД помимо ОЗОН.

Лицензия

Проект распространяется под лицензией MIT.