Skip to content

operations_guide.md

Latest commit

 

History

History
243 lines (130 loc) · 8.75 KB

operations_guide.md

File metadata and controls

243 lines (130 loc) · 8.75 KB

Testizer email funnels · Operations guide

Этот документ описывает, как запускать и сопровождать Python скрипт воронок для сайта Testizer.

1. Environment variables

Основные переменные в файле .env:

  • APP_ENV

    Значение: development или production.

  • APP_DRY_RUN

    Значение: true или false.

    При APP_DRY_RUN=true:

    • выполняются только чтения из базы MODX;
    • таблица funnel_entries не изменяется;
    • реальные запросы в Brevo не отправляются, пишутся только логи.

    При APP_DRY_RUN=false выполняется полный боевой цикл с реальными записями в базу данных и вызовами API Brevo.

    Режим dry run предназначен для безопасной проверки на продакшн-данных без изменения состояния. Это позволяет операторам проверить логику запросов, выборку данных и ожидаемые операции перед включением реальных записей.

    Для боевого режима установить false.

  • APP_LOG_LEVEL

    Возможные значения: DEBUG, INFO, WARNING, ERROR.

    Рекомендуемое значение для продакшена: INFO.

  • DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME, DB_CHARSET

    Параметры подключения к базе данных MODX.

  • BREVO_API_KEY

    Ключ API из кабинета Brevo.

  • BREVO_BASE_URL

    Базовый URL API Brevo. По умолчанию https://api.brevo.com/v3.

  • BREVO_LANGUAGE_LIST_ID

    ID списка Brevo для языковых тестов.

  • BREVO_NON_LANGUAGE_LIST_ID

    ID списка Brevo для неязыковых тестов.

Перед включением боевого режима важно проверить, что:

  1. Подключение к базе данных работает.
  2. В Brevo существуют корректные списки и их ID записаны в .env.
  3. APP_DRY_RUN временно установлен в true для тестовых прогонов.

2. Ручной запуск задачи

Работа выполняется из корня проекта в активированном виртуальном окружении.

2.1. Активация окружения

cd C:\Users\user\Desktop\testizer_email_funnels

.\.venv\Scripts\Activate.ps1

2.2. Запуск основной задачи

python -m app.main

При этом:

  • скрипт выбирает кандидатов по языковым и неязыковым тестам;
  • отправляет контакты в Brevo (или логирует сообщение dry run, в зависимости от APP_DRY_RUN);
  • записывает вход в воронку в таблицу funnel_entries (или логирует сообщение dry run, в зависимости от APP_DRY_RUN);
  • синхронизирует покупки сертификатов с таблицами MODX и обновляет funnel_entries (или логирует сообщение dry run, в зависимости от APP_DRY_RUN).

2.2.1. Сквозной поток выполнения

Основная задача использует паттерн outbox для надежной синхронизации с Brevo:

  1. Модуль синхронизации воронок и покупок записывает состояние в:

    • funnel_entries (основная аналитическая таблица)
    • brevo_sync_outbox (таблица outbox для операций Brevo)

  2. BrevoSyncWorker забирает задания из brevo_sync_outbox и применяет их к Brevo, вызывая API Brevo.

Это разделяет запись в базу данных и внешние вызовы API, обеспечивая:

  • Атомарность операций с базой данных и создания заданий в outbox в рамках транзакций
  • Возможность повторных попыток вызовов API Brevo при сбоях
  • Восстановление системы после временных сбоев API Brevo без потери работы

В режиме dry-run:

  • Выполняются только запросы на чтение
  • Таблицы funnel_entries и brevo_sync_outbox не изменяются
  • Воркер не запускается

2.3. Запуск отчета по конверсии

python -m app.report_conversions

или с указанием периода:

python -m app.report_conversions --from-date 2024-01-01 --to-date 2025-01-01

Даты задаются в формате YYYY-MM-DD.

Если --to-date не указана, учитываются записи до текущего момента.

3. Переход из режима dry run в боевой режим

Рекомендуемая последовательность:

  1. Оставить APP_DRY_RUN=true.

  2. Несколько раз запустить:

    python -m app.main

    и проверить логи в logs/app.log, а также логи в Brevo, что запросы формируются корректно.

  3. Убедиться, что в логах отображается то, что было бы записано в таблицу funnel_entries, и выглядит все ожидаемо. Примечание: В режиме dry run записи в базу данных фактически не выполняются.

  4. Изменить в .env:

    
APP_ENV=production

APP_DRY_RUN=false

  5. Перезапустить задачу вручную и убедиться, что:

    • в Brevo появляются реальные контакты в нужных списках;
    • таблица funnel_entries заполняется;
    • отчет app.report_conversions возвращает данные по воронкам.

4. Настройка периодического запуска на Windows (Task Scheduler)

Этот раздел описывает настройку расписания на Windows для тестового стенда или локального окружения.

  1. Открыть "Планировщик заданий" (Task Scheduler).

  2. Создать новую задачу:

    • "Создать задачу".

    • Задать имя, например: Testizer email funnels job.

  3. Вкладка "Триггеры":

    • "Создать".

    • Выбрать расписание, например "По расписанию" → "Ежечасно" или нужный интервал.

    • Сохранить триггер.

  4. Вкладка "Действия":

    • "Создать".

    • Действие: "Запуск программы".

    • В поле "Программа или сценарий" указать путь к powershell.exe, например:

      
C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe

    • В поле "Добавить аргументы" указать:

      
-ExecutionPolicy Bypass -File "C:\Users\user\Desktop\testizer_email_funnels\run_job.ps1"

  5. Вкладка "Условия" и "Параметры":

    • Настроить по требованиям (можно оставить значения по умолчанию).

  6. Сохранить задачу.

5. Скрипт run_job.ps1

Для удобства можно вынести запуск Python в отдельный PowerShell скрипт run_job.ps1 в корне проекта:

$projectPath = "C:\Users\user\Desktop\testizer_email_funnels"

Set-Location $projectPath

.\.venv\Scripts\Activate.ps1

python -m app.main

Именно этот файл указывать в аргументах планировщика.

6. Рекомендации по мониторингу

  • Проверять файл logs/app.log на наличие ошибок.

  • Периодически запускать:

    python -m app.report_conversions

    чтобы отслеживать эффективность воронок для языковых и неязыковых тестов.