app+docs: wire brevo outbox worker and describe flow

Author: AmaLS367

app/main.py

@@ -10,6 +10,7 @@
 from db.connection import database_connection_scope
 from logging_config.logger import configure_logging
 from brevo.api_client import BrevoApiClient
+from brevo.sync_worker import BrevoSyncWorker
 from funnels.sync_service import FunnelSyncService
 from funnels.purchase_sync_service import PurchaseSyncService
 
@@ -103,6 +104,15 @@ def main() -> None:
 
             purchase_sync_service.sync(max_rows=100)
 
+            if not settings.application.dry_run:
+                brevo_sync_worker = BrevoSyncWorker(
+                    connection=connection,
+                    brevo_client=brevo_client,
+                )
+                brevo_sync_worker.run_once(limit=100)
+            else:
+                logger.info("Dry run mode: BrevoSyncWorker is not executed.")
+
         logger.info("Job finished")
 
     except KeyboardInterrupt:

docs/en/operations_guide.md

@@ -82,6 +82,26 @@ This will:
 * record funnel entry in the `funnel_entries` table (or log dry-run message, depending on `APP_DRY_RUN`);
 * sync certificate purchases with MODX tables and update `funnel_entries` (or log dry-run message, depending on `APP_DRY_RUN`).
 
+### 2.2.1. End-to-End Flow
+
+The main task follows an outbox pattern for reliable Brevo synchronization:
+
+1. **Funnel Sync and Purchase Sync** write state into:
+   * `funnel_entries` (main analytics table)
+   * `brevo_sync_outbox` (outbox table for Brevo operations)
+
+2. **BrevoSyncWorker** reads pending jobs from `brevo_sync_outbox` and applies them to Brevo by calling the Brevo API.
+
+This decouples database writes from external API calls, ensuring that:
+* Database operations and outbox job creation happen atomically within transactions
+* Brevo API calls can be retried independently if they fail
+* The system can recover from temporary Brevo API outages without losing work
+
+**In dry-run mode:**
+* Only read queries are executed
+* `funnel_entries` and `brevo_sync_outbox` are not modified
+* The worker is not executed
+
 ### 2.3. Running Conversion Report
 
 ```powershell

docs/ru/operations_guide.md

@@ -87,6 +87,26 @@ python -m app.main
 * записывает вход в воронку в таблицу `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. Запуск отчета по конверсии
 
 ```powershell