Мини-проект: события в BackendStart (LessonCompleted → Achievements/Email/Analytics)

Мини-проект: события в BackendStart (LessonCompleted → Achievements/Email/Analytics)

В этом уроке мы соберём всё, что изучили за трек, в работающую систему. Возьмём реальный сценарий BackendStart: пользователь завершает урок, и это порождает цепочку побочных эффектов - проверку ачивок, запись аналитики, отправку уведомления. Каждый эффект реализован отдельным подписчиком. Ни один из них не знает о существовании остальных. Добавление нового подписчика - это один файл и одна строка регистрации. Брокера здесь намеренно нет: всё in-process, чтобы инфраструктура не прятала логику. Тот же сценарий, но уже с RabbitMQ и Kafka в docker-compose, собран в мини-проекте трека Message Brokers.

Мы реализуем: доменное событие, EventBus (in-process), outbox-таблицу, три подписчика, wiring в main.go и unit-тесты на подставной шине (раздел «Тестирование: FakeEventBus» в конце урока). Теория по каждому куску осталась в уроках выше - здесь только сборка.

Архитектура мини-проекта: use-case CompleteLesson пишет данные и outbox в одной транзакции; poller досылает в EventBus; три подписчика - Achievement, Analytics, Notification - читают параллельно

Структура проекта

backend/
├── internal/
│   ├── domain/
│   │   └── events.go              # Доменные события
│   ├── eventbus/
│   │   ├── bus.go                  # EventBus interface + in-process реализация
│   │   └── bus_test.go             # Тесты EventBus
│   ├── outbox/
│   │   ├── repository.go           # Outbox-таблица (запись + чтение)
│   │   └── poller.go               # Outbox poller (горутина-отправитель)
│   ├── usecase/
│   │   └── complete_lesson.go      # Use-case: завершение урока
│   └── subscribers/
│       ├── achievement_checker.go   # Подписчик: проверка ачивок
│       ├── analytics_recorder.go    # Подписчик: запись аналитики
│       └── notification_sender.go   # Подписчик: отправка уведомления
└── cmd/
    └── server/
        └── main.go                  # Wiring: bus + subscribers + use-case

Domain Event: LessonCompleted

Доменное событие - это факт, который произошёл в системе. Имя в прошедшем времени, неизменяемые поля, event_id как натуральный ключ дедупликации - все правила разобраны в уроке про доменные события. Неизменяемая структура с временной меткой:

// domain/events.go

// LessonCompleted - доменное событие: пользователь завершил урок.
type LessonCompleted struct {
    EventID       string    `json:"event_id"`
    Type          string    `json:"type"`            // всегда "lesson.completed"
    CorrelationID string    `json:"correlation_id"`
    OccurredAt    time.Time `json:"occurred_at"`
    UserID        int64     `json:"user_id"`
    LessonID      int64     `json:"lesson_id"`
    TrackSlug     string    `json:"track_slug"`
    LessonSlug    string    `json:"lesson_slug"`
}

// NewLessonCompleted создаёт событие с автоматическим event_id и timestamp.
func NewLessonCompleted(correlationID string, userID, lessonID int64, trackSlug, lessonSlug string) LessonCompleted {
    return LessonCompleted{
        EventID:       ulid.Make().String(),
        Type:          "lesson.completed",
        CorrelationID: correlationID,
        OccurredAt:    time.Now().UTC(),
        UserID:        userID,
        LessonID:      lessonID,
        TrackSlug:     trackSlug,
        LessonSlug:    lessonSlug,
    }
}

// EventType реализует интерфейс eventbus.Event. Метод объявляется здесь,
// в пакете domain: Go не позволяет добавлять методы к типу из другого пакета.
func (e LessonCompleted) EventType() string { return e.Type }
<?php
// src/Domain/Event/LessonCompleted.php
declare(strict_types=1);

namespace App\Domain\Event;

use Symfony\Component\Uid\Uuid;
use DateTimeImmutable;
use DateTimeZone;

// final readonly - событие immutable по определению.
final readonly class LessonCompleted implements DomainEvent
{
    public function __construct(
        public string $eventId,
        public string $correlationId,
        public DateTimeImmutable $occurredAt,
        public int $userId,
        public int $lessonId,
        public string $trackSlug,
        public string $lessonSlug,
    ) {}

    public static function create(
        string $correlationId,
        int $userId,
        int $lessonId,
        string $trackSlug,
        string $lessonSlug,
    ): self {
        return new self(
            eventId: Uuid::v4()->toRfc4122(),
            correlationId: $correlationId,
            occurredAt: new DateTimeImmutable('now', new DateTimeZone('UTC')),
            userId: $userId,
            lessonId: $lessonId,
            trackSlug: $trackSlug,
            lessonSlug: $lessonSlug,
        );
    }

    public function eventType(): string
    {
        return 'lesson.completed';
    }

    public function occurredAt(): DateTimeImmutable
    {
        return $this->occurredAt;
    }
}
# domain/events.py
from __future__ import annotations

import uuid
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Any


@dataclass(frozen=True, slots=True)
class LessonCompleted:
    """Доменное событие: пользователь завершил урок.

    frozen=True - событие immutable по определению.
    """

    event_id: str
    event_type: str  # всегда "lesson.completed"
    correlation_id: str
    occurred_at: datetime
    user_id: int
    lesson_id: int
    track_slug: str
    lesson_slug: str

    # to_dict/from_dict - аналог json-тегов в Go: ключи те же, что в payload outbox.
    def to_dict(self) -> dict[str, Any]:
        return {
            "event_id": self.event_id,
            "type": self.event_type,
            "correlation_id": self.correlation_id,
            "occurred_at": self.occurred_at.isoformat(),
            "user_id": self.user_id,
            "lesson_id": self.lesson_id,
            "track_slug": self.track_slug,
            "lesson_slug": self.lesson_slug,
        }

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> LessonCompleted:
        return cls(
            event_id=data["event_id"],
            event_type=data["type"],
            correlation_id=data["correlation_id"],
            occurred_at=datetime.fromisoformat(data["occurred_at"]),
            user_id=int(data["user_id"]),
            lesson_id=int(data["lesson_id"]),
            track_slug=data["track_slug"],
            lesson_slug=data["lesson_slug"],
        )


def new_lesson_completed(
    correlation_id: str,
    user_id: int,
    lesson_id: int,
    track_slug: str,
    lesson_slug: str,
) -> LessonCompleted:
    """Создаёт событие с автоматическим event_id и timestamp.

    В Go - ULID; здесь uuid4 из stdlib (пакет python-ulid даст сортируемые id).
    """
    return LessonCompleted(
        event_id=str(uuid.uuid4()),
        event_type="lesson.completed",
        correlation_id=correlation_id,
        occurred_at=datetime.now(timezone.utc),
        user_id=user_id,
        lesson_id=lesson_id,
        track_slug=track_slug,
        lesson_slug=lesson_slug,
    )

Поле Type - строковая константа. Подписчики фильтруют события по этому полю. CorrelationID приходит из HTTP-middleware (см. урок 09).

EventBus: интерфейс и in-process реализация

EventBus - это порт (interface) в терминах Hexagonal Architecture. Use-case зависит от интерфейса, а не от конкретной реализации - именно поэтому in-process шину потом можно заменить на Kafka или RabbitMQ, не трогая бизнес-код (что при этом меняется в гарантиях - в уроке Event Bus vs Message Broker):

// eventbus/bus.go

// Event - обобщённый интерфейс события.
type Event interface {
    EventType() string
}

// domain.LessonCompleted реализует Event методом EventType() в пакете domain.

// Handler - функция-обработчик события.
type Handler func(ctx context.Context, event Event) error

// EventBus - порт для публикации и подписки на события.
type EventBus interface {
    // Publish отправляет событие всем зарегистрированным подписчикам.
    Publish(ctx context.Context, event Event) error

    // Subscribe регистрирует обработчик для данного типа события.
    Subscribe(eventType string, handler Handler)
}
<?php
// src/Application/Port/EventBus.php
declare(strict_types=1);

namespace App\Application\Port;

use App\Domain\Event\DomainEvent;

// final НЕ ставится на interface.
interface EventBus
{
    public function publish(DomainEvent $event): void;

    public function subscribe(string $eventClass, callable $handler): void;
}
# eventbus/bus.py
from __future__ import annotations

from typing import Callable, Protocol


class Event(Protocol):
    """Обобщённый интерфейс события. Protocol сверяется структурно:
    LessonCompleted подходит за счёт поля event_type, отдельный метод не нужен.
    """

    @property
    def event_type(self) -> str: ...


# Handler - функция-обработчик события. context.Context в сигнатуре нет:
# correlation_id едет внутри события, отмена - через исключения.
Handler = Callable[[Event], None]


class EventBus(Protocol):
    """Порт для публикации и подписки на события."""

    def publish(self, event: Event) -> None:
        """Отправляет событие всем зарегистрированным подписчикам."""

    def subscribe(self, event_type: str, handler: Handler) -> None:
        """Регистрирует обработчик для данного типа события."""

In-process реализация - подходит для монолита и для начала разработки. Позже можно заменить на Kafka/NATS без изменения use-case:

// eventbus/bus.go

// InProcessBus - реализация EventBus через Go channels.
// Подписчики вызываются асинхронно в отдельных горутинах.
type InProcessBus struct {
    mu       sync.RWMutex
    handlers map[string][]Handler
}

// NewInProcessBus создаёт bus.
func NewInProcessBus() *InProcessBus {
    return &InProcessBus{
        handlers: make(map[string][]Handler),
    }
}

// Subscribe регистрирует обработчик для типа события.
func (b *InProcessBus) Subscribe(eventType string, handler Handler) {
    b.mu.Lock()
    defer b.mu.Unlock()
    b.handlers[eventType] = append(b.handlers[eventType], handler)
}

// Publish отправляет событие всем подписчикам данного типа.
// Каждый подписчик вызывается в отдельной горутине.
// Ошибка одного подписчика не останавливает остальных, но в конце все ошибки
// возвращаются вызывающему (errors.Join): иначе poller отметил бы событие
// опубликованным, и сбой подписчика тихо потерял бы эффект.
func (b *InProcessBus) Publish(ctx context.Context, event Event) error {
    b.mu.RLock()
    handlers := b.handlers[event.EventType()]
    b.mu.RUnlock()

    var (
        wg   sync.WaitGroup
        mu   sync.Mutex
        errs []error
    )
    for _, h := range handlers {
        wg.Add(1)
        go func(handler Handler) {
            defer wg.Done()
            if err := handler(ctx, event); err != nil {
                slog.ErrorContext(ctx, "subscriber failed",
                    slog.String("event_type", event.EventType()),
                    slog.String("err", err.Error()),
                )
                mu.Lock()
                errs = append(errs, err)
                mu.Unlock()
            }
        }(h)
    }
    wg.Wait()
    return errors.Join(errs...) // nil, если ошибок не было
}
<?php
// src/Infrastructure/EventBus/InProcessBus.php
declare(strict_types=1);

namespace App\Infrastructure\EventBus;

use App\Application\Port\EventBus;
use App\Domain\Event\DomainEvent;
use Psr\Log\LoggerInterface;
use Throwable;
use RuntimeException;

// PHP-FPM однопоточный per request - подписчики выполняются последовательно,
// без горутин. Для параллельной обработки используй Symfony Messenger
// с async-транспортом (Redis Streams/AMQP) и несколькими workers.
final class InProcessBus implements EventBus
{
    /** @var array<string, list<callable>> */
    private array $handlers = [];

    public function __construct(
        private readonly LoggerInterface $logger,
    ) {}

    public function subscribe(string $eventClass, callable $handler): void
    {
        $this->handlers[$eventClass][] = $handler;
    }

    // Ошибка одного подписчика не останавливает остальных, но в конце
    // бросаем исключение: иначе poller отметит событие опубликованным,
    // и сбой подписчика тихо потеряет эффект.
    public function publish(DomainEvent $event): void
    {
        $errors = [];
        foreach ($this->handlers[$event::class] ?? [] as $handler) {
            try {
                $handler($event);
            } catch (Throwable $e) {
                $this->logger->error('subscriber failed', [
                    'event_type' => $event->eventType(),
                    'err' => $e->getMessage(),
                ]);
                $errors[] = $e;
            }
        }

        if ($errors !== []) {
            throw new RuntimeException(
                sprintf('%d subscriber(s) failed for %s', count($errors), $event->eventType()),
                previous: $errors[0],
            );
        }
    }
}
# eventbus/bus.py (продолжение)
import logging
import threading
from collections import defaultdict
from concurrent.futures import ThreadPoolExecutor, wait

logger = logging.getLogger(__name__)


class InProcessBus:
    """Реализация EventBus на пуле потоков (аналог горутин + WaitGroup).

    Подписчики вызываются параллельно. Не asyncio, потому что подписчики
    ходят в БД синхронным psycopg.
    """

    def __init__(self, max_workers: int = 8) -> None:
        self._lock = threading.Lock()
        self._handlers: dict[str, list[Handler]] = defaultdict(list)
        self._pool = ThreadPoolExecutor(max_workers=max_workers, thread_name_prefix="eventbus")

    def subscribe(self, event_type: str, handler: Handler) -> None:
        """Регистрирует обработчик для типа события."""
        with self._lock:
            self._handlers[event_type].append(handler)

    def publish(self, event: Event) -> None:
        """Отправляет событие всем подписчикам данного типа.

        Каждый подписчик выполняется в отдельном потоке пула.
        Ошибка одного подписчика не останавливает остальных, но в конце все
        ошибки пробрасываются (ExceptionGroup): иначе poller отметит событие
        опубликованным, и сбой подписчика тихо потеряет эффект.
        """
        with self._lock:
            handlers = list(self._handlers.get(event.event_type, []))

        futures = [self._pool.submit(self._run, handler, event) for handler in handlers]
        wait(futures)  # аналог wg.Wait()

        errors = [exc for f in futures if (exc := f.exception()) is not None]
        if errors:
            raise ExceptionGroup(f"{len(errors)} subscriber(s) failed", errors)

    def _run(self, handler: Handler, event: Event) -> None:
        try:
            handler(event)
        except Exception as exc:
            logger.error(
                "subscriber failed",
                extra={"event_type": event.event_type, "err": str(exc)},
            )
            raise  # ошибка попадёт в future и вернётся из publish

Use-case: CompleteLesson с outbox

Use-case завершает урок, сохраняет прогресс и записывает событие в outbox - всё в одной транзакции. После коммита публикует событие в in-process bus для немедленной обработки и, если все подписчики отработали, сразу отмечает строку outbox опубликованной - иначе poller через полсекунды разослал бы то же событие второй раз. Зачем этот крюк через таблицу вместо прямого Publish - в разборе dual-write проблемы в уроке про outbox и inbox:

// usecase/complete_lesson.go

// CompleteLessonUseCase - завершение урока с публикацией события.
type CompleteLessonUseCase struct {
    db       *sql.DB
    outbox   *outbox.Repository
    bus      eventbus.EventBus
}

// NewCompleteLessonUseCase создаёт use-case с зависимостями.
func NewCompleteLessonUseCase(db *sql.DB, outbox *outbox.Repository, bus eventbus.EventBus) *CompleteLessonUseCase {
    return &CompleteLessonUseCase{db: db, outbox: outbox, bus: bus}
}

// Execute завершает урок для пользователя.
func (uc *CompleteLessonUseCase) Execute(ctx context.Context, req CompleteLessonRequest) error {
    // Создаём доменное событие
    evt := domain.NewLessonCompleted(
        middleware.CorrelationFromCtx(ctx),
        req.UserID, req.LessonID,
        req.TrackSlug, req.LessonSlug,
    )

    // Сериализуем payload для outbox
    payload, err := json.Marshal(evt)
    if err != nil {
        return fmt.Errorf("marshal event: %w", err)
    }

    // Транзакция: прогресс + outbox
    tx, err := uc.db.BeginTx(ctx, nil)
    if err != nil {
        return fmt.Errorf("begin tx: %w", err)
    }
    defer tx.Rollback()

    // 1. Обновляем прогресс. completed = false в условии: повторный PUT
    // (двойной клик, ретрай клиента) не должен порождать новый факт.
    res, err := tx.ExecContext(ctx,
        `UPDATE lesson_progress
         SET completed = true, completed_at = now()
         WHERE user_id = $1 AND lesson_id = $2 AND completed = false`,
        req.UserID, req.LessonID,
    )
    if err != nil {
        return fmt.Errorf("update progress: %w", err)
    }
    n, err := res.RowsAffected()
    if err != nil {
        return fmt.Errorf("rows affected: %w", err)
    }
    if n == 0 {
        return nil // урок уже завершён (или прогресса нет): события нет
    }

    // 2. Записываем событие в outbox (в той же транзакции)
    _, err = tx.ExecContext(ctx,
        `INSERT INTO outbox (event_id, event_type, payload)
         VALUES ($1, $2, $3)`,
        evt.EventID, evt.Type, payload,
    )
    if err != nil {
        return fmt.Errorf("insert outbox: %w", err)
    }

    if err := tx.Commit(); err != nil {
        return fmt.Errorf("commit: %w", err)
    }

    // После коммита: публикуем в in-process bus для немедленной обработки.
    // Путь доставки один - строка outbox: если все подписчики отработали,
    // отмечаем её опубликованной, иначе её дошлёт poller.
    if pubErr := uc.bus.Publish(ctx, evt); pubErr != nil {
        slog.WarnContext(ctx, "in-process publish failed, outbox poller will retry",
            slog.String("event_id", evt.EventID),
            slog.String("err", pubErr.Error()),
        )
        return nil
    }
    if err := uc.outbox.MarkPublishedByEventID(ctx, evt.EventID); err != nil {
        // Не страшно: poller пришлёт событие ещё раз, подписчики идемпотентны
        slog.WarnContext(ctx, "outbox mark failed",
            slog.String("event_id", evt.EventID),
            slog.String("err", err.Error()),
        )
    }

    return nil
}
<?php
// src/Application/UseCase/CompleteLessonUseCase.php
declare(strict_types=1);

namespace App\Application\UseCase;

use App\Application\Port\EventBus;
use App\Application\Port\OutboxRepository;
use App\Domain\Event\LessonCompleted;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
use Throwable;

final readonly class CompleteLessonRequest
{
    public function __construct(
        public int $userId,
        public int $lessonId,
        public string $trackSlug,
        public string $lessonSlug,
        public string $correlationId,
    ) {}
}

final class CompleteLessonUseCase
{
    public function __construct(
        private readonly Connection $connection,
        private readonly OutboxRepository $outbox,
        private readonly EventBus $bus,
        private readonly LoggerInterface $logger,
    ) {}

    public function execute(CompleteLessonRequest $req): void
    {
        $event = LessonCompleted::create(
            correlationId: $req->correlationId,
            userId: $req->userId,
            lessonId: $req->lessonId,
            trackSlug: $req->trackSlug,
            lessonSlug: $req->lessonSlug,
        );

        // Транзакция: progress + outbox. completed = false в условии: повторный
        // запрос (двойной клик, ретрай клиента) не должен порождать новый факт.
        $created = $this->connection->transactional(function (Connection $tx) use ($req, $event): bool {
            $affected = $tx->executeStatement(
                'UPDATE lesson_progress SET completed = true, completed_at = now()
                 WHERE user_id = :user_id AND lesson_id = :lesson_id AND completed = false',
                ['user_id' => $req->userId, 'lesson_id' => $req->lessonId],
            );
            if ($affected === 0) {
                return false; // урок уже завершён (или прогресса нет): события нет
            }

            $this->outbox->saveInTx($tx, $event);

            return true;
        });
        if (!$created) {
            return;
        }

        // После коммита: пробуем сразу опубликовать в in-process bus.
        // Путь доставки один - строка outbox: если все подписчики отработали,
        // отмечаем её опубликованной, иначе её дошлёт poller.
        try {
            $this->bus->publish($event);
        } catch (Throwable $e) {
            $this->logger->warning('in-process publish failed, outbox poller will retry', [
                'event_id' => $event->eventId,
                'err' => $e->getMessage(),
            ]);

            return;
        }

        // Если отметка упадёт, poller пришлёт событие ещё раз - подписчики идемпотентны
        $this->outbox->markPublishedByEventId($event->eventId);
    }
}
# usecase/complete_lesson.py
from __future__ import annotations

import logging
from dataclasses import dataclass

from psycopg.types.json import Jsonb
from psycopg_pool import ConnectionPool

from backend.domain.events import new_lesson_completed
from backend.eventbus.bus import EventBus
from backend.middleware.correlation import correlation_from_ctx
from backend.outbox.repository import Repository

logger = logging.getLogger(__name__)


@dataclass(frozen=True, slots=True)
class CompleteLessonRequest:
    user_id: int
    lesson_id: int
    track_slug: str
    lesson_slug: str


class CompleteLessonUseCase:
    """Завершение урока с публикацией события.

    ConnectionPool - аналог *sql.DB: пул соединений, безопасен для потоков.
    """

    def __init__(self, pool: ConnectionPool, outbox: Repository, bus: EventBus) -> None:
        self._pool = pool
        self._outbox = outbox
        self._bus = bus

    def execute(self, req: CompleteLessonRequest) -> None:
        """Завершает урок для пользователя.

        Ошибки БД не оборачиваются в error, а летят исключениями psycopg.
        """
        # Создаём доменное событие; correlation_id - из contextvar,
        # который заполнил HTTP-middleware (аналог ctx.Value в Go)
        evt = new_lesson_completed(
            correlation_from_ctx(),
            req.user_id, req.lesson_id,
            req.track_slug, req.lesson_slug,
        )

        # Сериализуем payload для outbox (Jsonb - адаптер для колонки JSONB)
        payload = Jsonb(evt.to_dict())

        # Транзакция: прогресс + outbox.
        # conn.transaction() - commit на выходе, rollback при исключении
        with self._pool.connection() as conn, conn.transaction():
            # 1. Обновляем прогресс. completed = false в условии: повторный запрос
            # (двойной клик, ретрай клиента) не должен порождать новый факт.
            cur = conn.execute(
                """UPDATE lesson_progress
                   SET completed = true, completed_at = now()
                   WHERE user_id = %s AND lesson_id = %s AND completed = false""",
                (req.user_id, req.lesson_id),
            )
            if cur.rowcount == 0:
                return  # урок уже завершён (или прогресса нет): события нет

            # 2. Записываем событие в outbox (в той же транзакции)
            conn.execute(
                """INSERT INTO outbox (event_id, event_type, payload)
                   VALUES (%s, %s, %s)""",
                (evt.event_id, evt.event_type, payload),
            )

        # После коммита: публикуем в in-process bus для немедленной обработки.
        # Путь доставки один - строка outbox: если все подписчики отработали,
        # отмечаем её опубликованной, иначе её дошлёт poller.
        try:
            self._bus.publish(evt)
        except Exception as exc:
            logger.warning(
                "in-process publish failed, outbox poller will retry",
                extra={"event_id": evt.event_id, "err": str(exc)},
            )
            return

        # Если отметка упадёт, poller пришлёт событие ещё раз - подписчики идемпотентны
        self._outbox.mark_published_by_event_id(evt.event_id)

Обратите внимание: ошибка bus.Publish не приводит к ошибке use-case. Данные уже закоммичены, а событие лежит в outbox неотмеченным - значит есть что дослать. Это работает только потому, что Publish возвращает ошибки подписчиков, а не глотает их: иначе use-case и poller отмечали бы событие опубликованным даже после сбоя подписчика. Доставка остаётся at-least-once: poller может успеть взять строку до отметки, а при повторе событие снова получат все подписчики, в том числе уже отработавшие. Поэтому каждый подписчик обязан быть идемпотентным (дедупликация по event_id и имени обработчика, урок 6).

Подписчик 1: AchievementChecker

Проверяет, заработал ли пользователь бейдж после завершения урока. Подписчик обязан выдержать повторную доставку того же события, поэтому запись идёт через UPSERT, а не INSERT - остальные приёмы в уроке про идемпотентность:

// subscribers/achievement_checker.go

// AchievementChecker проверяет условия ачивок при завершении урока.
type AchievementChecker struct {
    db *sql.DB
}

func NewAchievementChecker(db *sql.DB) *AchievementChecker {
    return &AchievementChecker{db: db}
}

// Handle обрабатывает событие lesson.completed.
func (a *AchievementChecker) Handle(ctx context.Context, event eventbus.Event) error {
    evt, ok := event.(domain.LessonCompleted)
    if !ok {
        return fmt.Errorf("unexpected event type: %T", event)
    }

    slog.InfoContext(ctx, "checking achievements",
        slog.Int64("user_id", evt.UserID),
        slog.String("track_slug", evt.TrackSlug),
        slog.String("correlation_id", evt.CorrelationID),
    )

    // Подсчитываем завершённые уроки в треке
    var completedCount int
    err := a.db.QueryRowContext(ctx,
        `SELECT COUNT(*) FROM lesson_progress
         WHERE user_id = $1 AND track_slug = $2 AND completed = true`,
        evt.UserID, evt.TrackSlug,
    ).Scan(&completedCount)
    if err != nil {
        return fmt.Errorf("count completed: %w", err)
    }

    // Проверяем условия ачивок
    achievements := checkAchievementRules(evt.TrackSlug, completedCount)
    for _, achievement := range achievements {
        // UPSERT - идемпотентно: повторный вызов не создаёт дубль
        _, err := a.db.ExecContext(ctx,
            `INSERT INTO user_achievements (user_id, achievement_slug, earned_at)
             VALUES ($1, $2, now())
             ON CONFLICT (user_id, achievement_slug) DO NOTHING`,
            evt.UserID, achievement,
        )
        if err != nil {
            slog.ErrorContext(ctx, "grant achievement failed",
                slog.String("achievement", achievement),
                slog.String("err", err.Error()),
            )
        }
    }

    return nil
}

// checkAchievementRules возвращает список заслуженных ачивок.
func checkAchievementRules(trackSlug string, completedCount int) []string {
    var result []string
    if completedCount >= 1 {
        result = append(result, "first_lesson")
    }
    if completedCount >= 5 {
        result = append(result, "five_lessons")
    }
    if completedCount >= 10 {
        result = append(result, fmt.Sprintf("track_%s_master", trackSlug))
    }
    return result
}
<?php
// src/Application/Subscriber/AchievementChecker.php
declare(strict_types=1);

namespace App\Application\Subscriber;

use App\Domain\Event\LessonCompleted;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler]
final class AchievementChecker
{
    public function __construct(
        private readonly Connection $connection,
        private readonly LoggerInterface $logger,
    ) {}

    public function __invoke(LessonCompleted $event): void
    {
        $this->logger->info('checking achievements', [
            'user_id' => $event->userId,
            'track_slug' => $event->trackSlug,
            'correlation_id' => $event->correlationId,
        ]);

        $completedCount = (int) $this->connection->fetchOne(
            'SELECT COUNT(*) FROM lesson_progress
             WHERE user_id = :uid AND track_slug = :slug AND completed = true',
            ['uid' => $event->userId, 'slug' => $event->trackSlug],
        );

        foreach ($this->checkAchievementRules($event->trackSlug, $completedCount) as $achievement) {
            // UPSERT - идемпотентно: повторный вызов не создаёт дубль
            $this->connection->executeStatement(
                'INSERT INTO user_achievements (user_id, achievement_slug, earned_at)
                 VALUES (:uid, :slug, now())
                 ON CONFLICT (user_id, achievement_slug) DO NOTHING',
                ['uid' => $event->userId, 'slug' => $achievement],
            );
        }
    }

    /** @return list<string> */
    private function checkAchievementRules(string $trackSlug, int $completedCount): array
    {
        $result = [];
        if ($completedCount >= 1) {
            $result[] = 'first_lesson';
        }
        if ($completedCount >= 5) {
            $result[] = 'five_lessons';
        }
        if ($completedCount >= 10) {
            $result[] = sprintf('track_%s_master', $trackSlug);
        }
        return $result;
    }
}
# subscribers/achievement_checker.py
from __future__ import annotations

import logging

import psycopg
from psycopg_pool import ConnectionPool

from backend.domain.events import LessonCompleted
from backend.eventbus.bus import Event

logger = logging.getLogger(__name__)


class AchievementChecker:
    """Проверяет условия ачивок при завершении урока."""

    def __init__(self, pool: ConnectionPool) -> None:
        self._pool = pool

    def handle(self, event: Event) -> None:
        """Обрабатывает событие lesson.completed."""
        if not isinstance(event, LessonCompleted):
            raise TypeError(f"unexpected event type: {type(event).__name__}")
        evt = event

        logger.info(
            "checking achievements",
            extra={
                "user_id": evt.user_id,
                "track_slug": evt.track_slug,
                "correlation_id": evt.correlation_id,
            },
        )

        # pool.connection() - commit на выходе из with, rollback при исключении
        with self._pool.connection() as conn:
            # Подсчитываем завершённые уроки в треке
            row = conn.execute(
                """SELECT COUNT(*) FROM lesson_progress
                   WHERE user_id = %s AND track_slug = %s AND completed = true""",
                (evt.user_id, evt.track_slug),
            ).fetchone()
            completed_count = int(row[0]) if row else 0

            # Проверяем условия ачивок
            for achievement in check_achievement_rules(evt.track_slug, completed_count):
                # UPSERT - идемпотентно: повторный вызов не создаёт дубль
                try:
                    conn.execute(
                        """INSERT INTO user_achievements (user_id, achievement_slug, earned_at)
                           VALUES (%s, %s, now())
                           ON CONFLICT (user_id, achievement_slug) DO NOTHING""",
                        (evt.user_id, achievement),
                    )
                except psycopg.Error as exc:
                    logger.error(
                        "grant achievement failed",
                        extra={"achievement": achievement, "err": str(exc)},
                    )


def check_achievement_rules(track_slug: str, completed_count: int) -> list[str]:
    """Возвращает список заслуженных ачивок."""
    result: list[str] = []
    if completed_count >= 1:
        result.append("first_lesson")
    if completed_count >= 5:
        result.append("five_lessons")
    if completed_count >= 10:
        result.append(f"track_{track_slug}_master")
    return result

Подписчик 2: AnalyticsRecorder

Записывает факт завершения урока для статистики:

// subscribers/analytics_recorder.go

// AnalyticsRecorder записывает метрику завершения урока.
type AnalyticsRecorder struct {
    db *sql.DB
}

func NewAnalyticsRecorder(db *sql.DB) *AnalyticsRecorder {
    return &AnalyticsRecorder{db: db}
}

// Handle записывает событие в таблицу аналитики.
func (a *AnalyticsRecorder) Handle(ctx context.Context, event eventbus.Event) error {
    evt, ok := event.(domain.LessonCompleted)
    if !ok {
        return fmt.Errorf("unexpected event type: %T", event)
    }

    // UPSERT: идемпотентно - повторный вызов обновляет timestamp
    _, err := a.db.ExecContext(ctx,
        `INSERT INTO analytics_events (event_id, event_type, user_id, track_slug, lesson_slug, occurred_at)
         VALUES ($1, $2, $3, $4, $5, $6)
         ON CONFLICT (event_id) DO NOTHING`,
        evt.EventID, evt.Type, evt.UserID,
        evt.TrackSlug, evt.LessonSlug, evt.OccurredAt,
    )
    if err != nil {
        return fmt.Errorf("insert analytics: %w", err)
    }

    slog.InfoContext(ctx, "analytics event recorded",
        slog.String("event_id", evt.EventID),
        slog.Int64("user_id", evt.UserID),
        slog.String("correlation_id", evt.CorrelationID),
    )
    return nil
}
<?php
// src/Application/Subscriber/AnalyticsRecorder.php
declare(strict_types=1);

namespace App\Application\Subscriber;

use App\Domain\Event\LessonCompleted;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler]
final class AnalyticsRecorder
{
    public function __construct(
        private readonly Connection $connection,
        private readonly LoggerInterface $logger,
    ) {}

    public function __invoke(LessonCompleted $event): void
    {
        // ON CONFLICT DO NOTHING - идемпотентно по event_id
        $this->connection->executeStatement(
            'INSERT INTO analytics_events (event_id, event_type, user_id, track_slug, lesson_slug, occurred_at)
             VALUES (:eid, :etype, :uid, :track, :lesson, :occurred)
             ON CONFLICT (event_id) DO NOTHING',
            [
                'eid' => $event->eventId,
                'etype' => $event->eventType(),
                'uid' => $event->userId,
                'track' => $event->trackSlug,
                'lesson' => $event->lessonSlug,
                'occurred' => $event->occurredAt->format('Y-m-d H:i:s'),
            ],
        );

        $this->logger->info('analytics event recorded', [
            'event_id' => $event->eventId,
            'user_id' => $event->userId,
            'correlation_id' => $event->correlationId,
        ]);
    }
}
# subscribers/analytics_recorder.py
from __future__ import annotations

import logging

from psycopg_pool import ConnectionPool

from backend.domain.events import LessonCompleted
from backend.eventbus.bus import Event

logger = logging.getLogger(__name__)


class AnalyticsRecorder:
    """Записывает метрику завершения урока."""

    def __init__(self, pool: ConnectionPool) -> None:
        self._pool = pool

    def handle(self, event: Event) -> None:
        """Записывает событие в таблицу аналитики.

        Ошибка INSERT летит исключением psycopg - bus залогирует "subscriber failed".
        """
        if not isinstance(event, LessonCompleted):
            raise TypeError(f"unexpected event type: {type(event).__name__}")
        evt = event

        # UPSERT: идемпотентно - повторный вызов не создаёт дубль
        with self._pool.connection() as conn:
            conn.execute(
                """INSERT INTO analytics_events (event_id, event_type, user_id, track_slug, lesson_slug, occurred_at)
                   VALUES (%s, %s, %s, %s, %s, %s)
                   ON CONFLICT (event_id) DO NOTHING""",
                (
                    evt.event_id, evt.event_type, evt.user_id,
                    evt.track_slug, evt.lesson_slug, evt.occurred_at,
                ),
            )

        logger.info(
            "analytics event recorded",
            extra={
                "event_id": evt.event_id,
                "user_id": evt.user_id,
                "correlation_id": evt.correlation_id,
            },
        )

Подписчик 3: NotificationSender

Отправляет поздравление пользователю (заглушка - в реальности это может быть email, push или in-app уведомление):

// subscribers/notification_sender.go

// NotificationSender отправляет уведомление при завершении урока.
type NotificationSender struct {
    notifier Notifier
}

// Notifier - порт для отправки уведомлений.
type Notifier interface {
    Send(ctx context.Context, userID int64, message string) error
}

func NewNotificationSender(notifier Notifier) *NotificationSender {
    return &NotificationSender{notifier: notifier}
}

// Handle отправляет поздравление.
func (n *NotificationSender) Handle(ctx context.Context, event eventbus.Event) error {
    evt, ok := event.(domain.LessonCompleted)
    if !ok {
        return fmt.Errorf("unexpected event type: %T", event)
    }

    message := fmt.Sprintf("Отлично! Вы завершили урок %q в треке %q.",
        evt.LessonSlug, evt.TrackSlug)

    if err := n.notifier.Send(ctx, evt.UserID, message); err != nil {
        return fmt.Errorf("send notification: %w", err)
    }

    slog.InfoContext(ctx, "notification sent",
        slog.Int64("user_id", evt.UserID),
        slog.String("correlation_id", evt.CorrelationID),
    )
    return nil
}
<?php
// src/Application/Subscriber/NotificationSender.php
declare(strict_types=1);

namespace App\Application\Subscriber;

use App\Application\Port\NotifierPort;
use App\Domain\Event\LessonCompleted;
use Psr\Log\LoggerInterface;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler]
final class NotificationSender
{
    public function __construct(
        private readonly NotifierPort $notifier,
        private readonly LoggerInterface $logger,
    ) {}

    public function __invoke(LessonCompleted $event): void
    {
        $message = sprintf(
            "Отлично! Вы завершили урок '%s' в треке '%s'.",
            $event->lessonSlug,
            $event->trackSlug,
        );

        $this->notifier->send($event->userId, $message);

        $this->logger->info('notification sent', [
            'user_id' => $event->userId,
            'correlation_id' => $event->correlationId,
        ]);
    }
}
# subscribers/notification_sender.py
from __future__ import annotations

import logging
from typing import Protocol

from backend.domain.events import LessonCompleted
from backend.eventbus.bus import Event

logger = logging.getLogger(__name__)


class Notifier(Protocol):
    """Порт для отправки уведомлений."""

    def send(self, user_id: int, message: str) -> None: ...


class NotificationSender:
    """Отправляет уведомление при завершении урока."""

    def __init__(self, notifier: Notifier) -> None:
        self._notifier = notifier

    def handle(self, event: Event) -> None:
        """Отправляет поздравление."""
        if not isinstance(event, LessonCompleted):
            raise TypeError(f"unexpected event type: {type(event).__name__}")
        evt = event

        message = f'Отлично! Вы завершили урок "{evt.lesson_slug}" в треке "{evt.track_slug}".'

        # Ошибка отправки летит исключением наверх - bus залогирует её
        self._notifier.send(evt.user_id, message)

        logger.info(
            "notification sent",
            extra={"user_id": evt.user_id, "correlation_id": evt.correlation_id},
        )

⚠️ NotificationSender пока не идемпотентен

AchievementChecker защищён UPSERT-ом, AnalyticsRecorder - дедупликацией по event_id, а уведомление при повторной доставке уйдёт второй раз. Повтор случается: poller может успеть взять строку outbox до отметки из use-case, а при сбое одного подписчика событие заново получат все. Для настоящей отправки добавь дедупликацию по (event_id, handler) через таблицу processed_events, как в уроке про идемпотентность, или передавай event_id провайдеру как ключ идемпотентности.

Outbox: DDL и Repository

CREATE TABLE outbox (
    id           BIGSERIAL    PRIMARY KEY,
    event_id     VARCHAR(64)  NOT NULL UNIQUE,
    event_type   VARCHAR(128) NOT NULL,
    payload      JSONB        NOT NULL,
    created_at   TIMESTAMPTZ  NOT NULL DEFAULT now(),
    published_at TIMESTAMPTZ,
    attempts     INT          NOT NULL DEFAULT 0
);

CREATE INDEX idx_outbox_unpublished
    ON outbox (created_at)
    WHERE published_at IS NULL;
// outbox/repository.go

// Repository предоставляет доступ к outbox-таблице.
type Repository struct {
    db *sql.DB
}

func NewRepository(db *sql.DB) *Repository {
    return &Repository{db: db}
}

// FetchUnpublished возвращает пачку неотправленных событий без блокировки.
// Для тестов и отладки; poller берёт строки через claimBatch.
func (r *Repository) FetchUnpublished(ctx context.Context, limit int) ([]OutboxEntry, error) {
    rows, err := r.db.QueryContext(ctx,
        `SELECT id, event_id, event_type, payload
         FROM outbox
         WHERE published_at IS NULL
         ORDER BY created_at
         LIMIT $1`,
        limit,
    )
    if err != nil {
        return nil, fmt.Errorf("query outbox: %w", err)
    }
    defer rows.Close()

    var entries []OutboxEntry
    for rows.Next() {
        var e OutboxEntry
        if err := rows.Scan(&e.ID, &e.EventID, &e.EventType, &e.Payload); err != nil {
            return nil, fmt.Errorf("scan: %w", err)
        }
        entries = append(entries, e)
    }
    return entries, rows.Err()
}

// claimBatch забирает пачку неопубликованных событий, блокируя строки
// от других экземпляров поллера до конца транзакции tx (как в уроке 7).
// Пачка считывается целиком и rows закрывается до публикаций.
func (r *Repository) claimBatch(ctx context.Context, tx *sql.Tx, limit int) ([]OutboxEntry, error) {
    rows, err := tx.QueryContext(ctx,
        `SELECT id, event_id, event_type, payload
         FROM outbox
         WHERE published_at IS NULL
         ORDER BY created_at
         LIMIT $1
         FOR UPDATE SKIP LOCKED`,
        limit,
    )
    if err != nil {
        return nil, fmt.Errorf("query outbox: %w", err)
    }
    defer rows.Close()

    var entries []OutboxEntry
    for rows.Next() {
        var e OutboxEntry
        if err := rows.Scan(&e.ID, &e.EventID, &e.EventType, &e.Payload); err != nil {
            return nil, fmt.Errorf("scan: %w", err)
        }
        entries = append(entries, e)
    }
    return entries, rows.Err()
}

// MarkPublishedByEventID отмечает событие отправленным после немедленной
// публикации из use-case. Если строку уже отметил poller - ничего не меняет.
func (r *Repository) MarkPublishedByEventID(ctx context.Context, eventID string) error {
    _, err := r.db.ExecContext(ctx,
        `UPDATE outbox SET published_at = now()
         WHERE event_id = $1 AND published_at IS NULL`, eventID)
    return err
}
<?php
// src/Infrastructure/Outbox/OutboxRepository.php
declare(strict_types=1);

namespace App\Infrastructure\Outbox;

use App\Application\Port\OutboxRepository as OutboxRepositoryPort;
use App\Domain\Event\LessonCompleted;
use Doctrine\DBAL\Connection;
use DateTimeInterface;

final readonly class OutboxEntry
{
    public function __construct(
        public int $id,
        public string $eventId,
        public string $eventType,
        public string $payload,
    ) {}
}

final class OutboxRepository implements OutboxRepositoryPort
{
    public function __construct(
        private readonly Connection $connection,
    ) {}

    public function saveInTx(Connection $tx, LessonCompleted $event): void
    {
        $tx->insert('outbox', [
            'event_id' => $event->eventId,
            'event_type' => $event->eventType(),
            'payload' => json_encode([
                'event_id' => $event->eventId,
                'correlation_id' => $event->correlationId,
                'occurred_at' => $event->occurredAt->format(DateTimeInterface::RFC3339),
                'user_id' => $event->userId,
                'lesson_id' => $event->lessonId,
                'track_slug' => $event->trackSlug,
                'lesson_slug' => $event->lessonSlug,
            ], JSON_THROW_ON_ERROR),
        ]);
    }

    /**
     * Неотправленные события без блокировки - для тестов и отладки.
     *
     * @return list<OutboxEntry>
     */
    public function fetchUnpublished(int $limit): array
    {
        return $this->toEntries($this->connection->fetchAllAssociative(
            'SELECT id, event_id, event_type, payload
             FROM outbox
             WHERE published_at IS NULL
             ORDER BY created_at
             LIMIT :lim',
            ['lim' => $limit],
        ));
    }

    /**
     * Забирает пачку для poller-а, блокируя строки до конца транзакции $tx.
     * SKIP LOCKED работает только внутри транзакции: в autocommit блокировка
     * снялась бы сразу после SELECT.
     *
     * @return list<OutboxEntry>
     */
    public function claimBatch(Connection $tx, int $limit): array
    {
        return $this->toEntries($tx->fetchAllAssociative(
            'SELECT id, event_id, event_type, payload
             FROM outbox
             WHERE published_at IS NULL
             ORDER BY created_at
             LIMIT :lim
             FOR UPDATE SKIP LOCKED',
            ['lim' => $limit],
        ));
    }

    /**
     * @param list<array<string, mixed>> $rows
     * @return list<OutboxEntry>
     */
    private function toEntries(array $rows): array
    {
        return array_map(
            static fn(array $r) => new OutboxEntry(
                id: (int) $r['id'],
                eventId: $r['event_id'],
                eventType: $r['event_type'],
                payload: (string) $r['payload'],
            ),
            $rows,
        );
    }

    public function markPublished(Connection $tx, int $id): void
    {
        $tx->executeStatement(
            'UPDATE outbox SET published_at = now() WHERE id = :id',
            ['id' => $id],
        );
    }

    public function bumpAttempts(Connection $tx, int $id): void
    {
        $tx->executeStatement(
            'UPDATE outbox SET attempts = attempts + 1 WHERE id = :id',
            ['id' => $id],
        );
    }

    // Отметка после немедленной публикации из use-case. Если строку уже
    // отметил poller - ничего не меняет.
    public function markPublishedByEventId(string $eventId): void
    {
        $this->connection->executeStatement(
            'UPDATE outbox SET published_at = now()
             WHERE event_id = :event_id AND published_at IS NULL',
            ['event_id' => $eventId],
        );
    }
}
# outbox/repository.py
from __future__ import annotations

from dataclasses import dataclass
from typing import Any

from psycopg import Connection
from psycopg_pool import ConnectionPool


@dataclass(frozen=True, slots=True)
class OutboxEntry:
    id: int
    event_id: str
    event_type: str
    payload: dict[str, Any]  # JSONB psycopg отдаёт уже распарсенным dict


class Repository:
    """Предоставляет доступ к outbox-таблице."""

    def __init__(self, pool: ConnectionPool) -> None:
        self._pool = pool

    def fetch_unpublished(self, limit: int) -> list[OutboxEntry]:
        """Возвращает пачку неотправленных событий без блокировки (для тестов и отладки)."""
        with self._pool.connection() as conn:
            rows = conn.execute(
                """SELECT id, event_id, event_type, payload
                   FROM outbox
                   WHERE published_at IS NULL
                   ORDER BY created_at
                   LIMIT %s""",
                (limit,),
            ).fetchall()

        return [
            OutboxEntry(id=row[0], event_id=row[1], event_type=row[2], payload=row[3])
            for row in rows
        ]

    def claim_batch(self, conn: Connection, limit: int) -> list[OutboxEntry]:
        """Забирает пачку для poller-а, блокируя строки до конца транзакции conn."""
        rows = conn.execute(
            """SELECT id, event_id, event_type, payload
               FROM outbox
               WHERE published_at IS NULL
               ORDER BY created_at
               LIMIT %s
               FOR UPDATE SKIP LOCKED""",
            (limit,),
        ).fetchall()
        return [
            OutboxEntry(id=row[0], event_id=row[1], event_type=row[2], payload=row[3])
            for row in rows
        ]

    def mark_published_by_event_id(self, event_id: str) -> None:
        """Отметка после немедленной публикации из use-case.

        Если строку уже отметил poller - ничего не меняет.
        """
        with self._pool.connection() as conn:
            conn.execute(
                """UPDATE outbox SET published_at = now()
                   WHERE event_id = %s AND published_at IS NULL""",
                (event_id,),
            )

Outbox Poller

// outbox/poller.go

// Poller периодически читает outbox и публикует события в EventBus.
type Poller struct {
    repo     *Repository
    bus      eventbus.EventBus
    interval time.Duration
    batch    int
}

func NewPoller(repo *Repository, bus eventbus.EventBus, interval time.Duration, batch int) *Poller {
    return &Poller{repo: repo, bus: bus, interval: interval, batch: batch}
}

// Run запускает polling. Останавливается по отмене контекста.
func (p *Poller) Run(ctx context.Context) {
    ticker := time.NewTicker(p.interval)
    defer ticker.Stop()

    slog.Info("outbox poller started",
        slog.Duration("interval", p.interval),
        slog.Int("batch_size", p.batch),
    )

    for {
        select {
        case <-ctx.Done():
            slog.Info("outbox poller stopped")
            return
        case <-ticker.C:
            if err := p.pollBatch(ctx); err != nil {
                slog.ErrorContext(ctx, "outbox poll failed",
                    slog.String("err", err.Error()),
                )
            }
        }
    }
}

// pollBatch публикует одну пачку - так же, как PollBatch из урока 7: одна
// транзакция, SELECT ... FOR UPDATE SKIP LOCKED, публикация и отметки внутри
// неё, затем COMMIT. Блокировка держит строки до COMMIT, поэтому второй
// экземпляр поллера их не возьмёт. Упали между Publish и COMMIT - событие
// уйдёт ещё раз (at-least-once), поэтому подписчики идемпотентны.
func (p *Poller) pollBatch(ctx context.Context) error {
    tx, err := p.repo.db.BeginTx(ctx, nil)
    if err != nil {
        return fmt.Errorf("begin tx: %w", err)
    }
    defer tx.Rollback()

    entries, err := p.repo.claimBatch(ctx, tx, p.batch)
    if err != nil {
        return err
    }

    for _, entry := range entries {
        // Десериализуем событие по типу и публикуем. Publish возвращает
        // ошибки подписчиков, поэтому сбой подписчика не отметит событие.
        evt, err := deserializeEvent(entry.EventType, entry.Payload)
        if err == nil {
            err = p.bus.Publish(ctx, evt)
        }
        if err != nil {
            slog.ErrorContext(ctx, "outbox publish failed",
                slog.String("event_id", entry.EventID),
                slog.String("err", err.Error()),
            )
            if _, uErr := tx.ExecContext(ctx,
                `UPDATE outbox SET attempts = attempts + 1 WHERE id = $1`, entry.ID,
            ); uErr != nil {
                return fmt.Errorf("bump attempts %s: %w", entry.EventID, uErr)
            }
            continue
        }

        if _, err := tx.ExecContext(ctx,
            `UPDATE outbox SET published_at = now() WHERE id = $1`, entry.ID,
        ); err != nil {
            return fmt.Errorf("mark published %s: %w", entry.EventID, err)
        }
    }

    return tx.Commit()
}

// deserializeEvent восстанавливает событие из JSON по типу.
func deserializeEvent(eventType string, payload []byte) (eventbus.Event, error) {
    switch eventType {
    case "lesson.completed":
        var evt domain.LessonCompleted
        if err := json.Unmarshal(payload, &evt); err != nil {
            return nil, err
        }
        return evt, nil
    default:
        return nil, fmt.Errorf("unknown event type: %s", eventType)
    }
}
<?php
// src/Application/Cron/OutboxPollCommand.php
declare(strict_types=1);

namespace App\Application\Cron;

use App\Application\Port\EventBus;
use App\Domain\Event\LessonCompleted;
use App\Infrastructure\Outbox\OutboxRepository;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use DateTimeImmutable;
use LogicException;
use Throwable;

// Альтернатива - Symfony Messenger worker (`messenger:consume outbox-transport`).
// Здесь - однопроходная команда из cron, проще в развёртывании.
#[AsCommand(name: 'app:outbox-poll')]
final class OutboxPollCommand extends Command
{
    private const BATCH_SIZE = 10;

    public function __construct(
        private readonly Connection $connection,
        private readonly OutboxRepository $repo,
        private readonly EventBus $bus,
        private readonly LoggerInterface $logger,
    ) {
        parent::__construct();
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // Как PollBatch из урока 7: одна транзакция, SELECT ... FOR UPDATE SKIP LOCKED,
        // публикация и отметки внутри неё, затем COMMIT. Два запуска cron внахлёст
        // не возьмут одни и те же строки.
        $this->connection->transactional(function (Connection $tx): void {
            foreach ($this->repo->claimBatch($tx, self::BATCH_SIZE) as $entry) {
                try {
                    $event = $this->deserializeEvent($entry->eventType, $entry->payload);
                    // publish бросает исключение, если упал хоть один подписчик
                    $this->bus->publish($event);
                } catch (Throwable $e) {
                    $this->logger->error('outbox publish failed', [
                        'event_id' => $entry->eventId,
                        'err' => $e->getMessage(),
                    ]);
                    $this->repo->bumpAttempts($tx, $entry->id);
                    continue;
                }

                $this->repo->markPublished($tx, $entry->id);
            }
        });

        return Command::SUCCESS;
    }

    private function deserializeEvent(string $eventType, string $payload): LessonCompleted
    {
        $data = json_decode($payload, true, 512, JSON_THROW_ON_ERROR);

        return match ($eventType) {
            'lesson.completed' => new LessonCompleted(
                eventId: $data['event_id'],
                correlationId: $data['correlation_id'],
                occurredAt: new DateTimeImmutable($data['occurred_at']),
                userId: $data['user_id'],
                lessonId: $data['lesson_id'],
                trackSlug: $data['track_slug'],
                lessonSlug: $data['lesson_slug'],
            ),
            default => throw new LogicException(sprintf('unknown event type: %s', $eventType)),
        };
    }
}
# outbox/poller.py
from __future__ import annotations

import logging
import threading
from typing import Any

from psycopg_pool import ConnectionPool

from backend.domain.events import LessonCompleted
from backend.eventbus.bus import Event, EventBus
from backend.outbox.repository import Repository

logger = logging.getLogger(__name__)


class Poller:
    """Периодически читает outbox и публикует события в EventBus."""

    def __init__(
        self, pool: ConnectionPool, repo: Repository, bus: EventBus, interval: float, batch: int,
    ) -> None:
        self._pool = pool
        self._repo = repo
        self._bus = bus
        self._interval = interval  # секунды
        self._batch = batch

    def run(self, stop: threading.Event) -> None:
        """Запускает polling в текущем потоке (main стартует его в threading.Thread).

        Останавливается по stop-флагу - аналог отмены контекста в Go.
        """
        logger.info(
            "outbox poller started",
            extra={"interval": self._interval, "batch_size": self._batch},
        )

        # stop.wait(interval) - это и ticker, и проверка ctx.Done() в одном вызове
        while not stop.wait(self._interval):
            try:
                self.poll_batch()
            except Exception as exc:
                logger.error("outbox poll failed", extra={"err": str(exc)})

        logger.info("outbox poller stopped")

    def poll_batch(self) -> None:
        """Публикует одну пачку - как poll_batch из урока 7.

        Одна транзакция, SELECT ... FOR UPDATE SKIP LOCKED, публикация и отметки
        внутри неё, затем COMMIT при выходе из with. Второй экземпляр поллера
        эти строки не возьмёт.
        """
        with self._pool.connection() as conn, conn.transaction():
            for entry in self._repo.claim_batch(conn, self._batch):
                try:
                    evt = deserialize_event(entry.event_type, entry.payload)
                    # publish пробрасывает ошибки подписчиков (ExceptionGroup)
                    self._bus.publish(evt)
                except Exception as exc:
                    logger.error(
                        "outbox publish failed",
                        extra={"event_id": entry.event_id, "err": str(exc)},
                    )
                    conn.execute(
                        "UPDATE outbox SET attempts = attempts + 1 WHERE id = %s", (entry.id,)
                    )
                    continue

                conn.execute(
                    "UPDATE outbox SET published_at = now() WHERE id = %s", (entry.id,)
                )


def deserialize_event(event_type: str, payload: dict[str, Any]) -> Event:
    """Восстанавливает событие из JSON по типу."""
    match event_type:
        case "lesson.completed":
            return LessonCompleted.from_dict(payload)
        case _:
            raise ValueError(f"unknown event type: {event_type}")

Wiring в main.go

Всё собирается в main.go - создаём bus, регистрируем подписчиков, передаём bus в use-case:

// cmd/server/main.go (фрагмент)

func main() {
    // ... DB, router, middleware setup ...

    // 1. Создаём EventBus
    bus := eventbus.NewInProcessBus()

    // 2. Создаём подписчиков
    achievementChecker := subscribers.NewAchievementChecker(db)
    analyticsRecorder := subscribers.NewAnalyticsRecorder(db)
    notificationSender := subscribers.NewNotificationSender(stubNotifier{})

    // 3. Регистрируем подписчиков (одна строка на подписчика!)
    bus.Subscribe("lesson.completed", achievementChecker.Handle)
    bus.Subscribe("lesson.completed", analyticsRecorder.Handle)
    bus.Subscribe("lesson.completed", notificationSender.Handle)

    // 4. Создаём outbox и use-case
    outboxRepo := outbox.NewRepository(db)
    completeLessonUC := usecase.NewCompleteLessonUseCase(db, outboxRepo, bus)

    // 5. Запускаём outbox poller в фоне
    pollerCtx, pollerCancel := context.WithCancel(context.Background())
    defer pollerCancel()

    poller := outbox.NewPoller(outboxRepo, bus, 500*time.Millisecond, 10)
    go poller.Run(pollerCtx)

    // 6. Регистрируем handler
    router.Put("/progress/lessons/{id}/complete", handler.CompleteLesson(completeLessonUC))

    // ... server start, graceful shutdown ...
}
<?php
// config/services.yaml - autoconfigure через #[AsMessageHandler].
// Контроллер просто инжектит MessageBusInterface и dispatches DomainEvent.

// src/Controller/ProgressController.php
declare(strict_types=1);

namespace App\Controller;

use App\Application\UseCase\CompleteLessonRequest;
use App\Application\UseCase\CompleteLessonUseCase;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;

final class ProgressController extends AbstractController
{
    public function __construct(
        private readonly CompleteLessonUseCase $completeLesson,
    ) {}

    #[Route('/api/progress/lessons/{id}/complete', methods: ['PUT'])]
    public function complete(int $id, Request $request): JsonResponse
    {
        $payload = json_decode($request->getContent(), true, 512, JSON_THROW_ON_ERROR);

        $this->completeLesson->execute(new CompleteLessonRequest(
            userId: $this->getUser()->getId(),
            lessonId: $id,
            trackSlug: $payload['track_slug'],
            lessonSlug: $payload['lesson_slug'],
            correlationId: $request->headers->get('X-Correlation-Id', 'unknown'),
        ));

        return new JsonResponse(['status' => 'ok']);
    }
}

// Подписчики (AchievementChecker, AnalyticsRecorder, NotificationSender)
// с #[AsMessageHandler] - Symfony автоматически подвязывает их к типу события.
// Outbox poller: `bin/console app:outbox-poll` через systemd-timer или
// `bin/console messenger:consume outbox` для async-транспорта.
# cmd/server/main.py (фрагмент)
import os
import threading

from psycopg_pool import ConnectionPool

from backend.eventbus.bus import InProcessBus
from backend.outbox.poller import Poller
from backend.outbox.repository import Repository
from backend.subscribers.achievement_checker import AchievementChecker
from backend.subscribers.analytics_recorder import AnalyticsRecorder
from backend.subscribers.notification_sender import NotificationSender
from backend.usecase.complete_lesson import CompleteLessonUseCase


def main() -> None:
    # ... DB, router, middleware setup ...
    pool = ConnectionPool(os.environ["DATABASE_URL"])  # аналог *sql.DB

    # 1. Создаём EventBus
    bus = InProcessBus()

    # 2. Создаём подписчиков
    achievement_checker = AchievementChecker(pool)
    analytics_recorder = AnalyticsRecorder(pool)
    notification_sender = NotificationSender(StubNotifier())

    # 3. Регистрируем подписчиков (одна строка на подписчика!)
    bus.subscribe("lesson.completed", achievement_checker.handle)
    bus.subscribe("lesson.completed", analytics_recorder.handle)
    bus.subscribe("lesson.completed", notification_sender.handle)

    # 4. Создаём outbox и use-case
    outbox_repo = Repository(pool)
    complete_lesson_uc = CompleteLessonUseCase(pool, outbox_repo, bus)

    # 5. Запускаем outbox poller в фоновом потоке
    poller_stop = threading.Event()
    poller = Poller(pool, outbox_repo, bus, interval=0.5, batch=10)
    threading.Thread(
        target=poller.run, args=(poller_stop,), name="outbox-poller", daemon=True
    ).start()

    # 6. Регистрируем handler. Роутинг фреймворк-независим: в FastAPI это
    # @app.put("/progress/lessons/{id}/complete"), в Django - path() в urls.py
    router.put("/progress/lessons/{id}/complete", complete_lesson_handler(complete_lesson_uc))

    # ... server start, graceful shutdown: poller_stop.set() перед выходом ...

Добавить нового подписчика = один файл с реализацией + одна строка bus.Subscribe(...). Ни один существующий файл не меняется (Open-Closed Principle).

Тестирование: FakeEventBus

Для unit-тестов use-case не нужен реальный bus. Создаём FakeEventBus - подставную реализацию того же интерфейса, которая никому ничего не доставляет, а просто записывает опубликованные события в срез. Что это даёт:

  • тестам use-case не нужен брокер и сеть: шина живёт в памяти процесса;
  • видно, какие именно события опубликованы - тип, поля, количество;
  • можно проверить обратное: если use-case вернул ошибку, fake.Events должен остаться пустым, иначе подписчики отреагируют на факт, которого не было.

Подписчиков FakeEventBus не вызывает (Subscribe - пустышка), поэтому их тестируют отдельно, передавая событие прямо в обработчик (ниже).

// eventbus/bus_test.go

// FakeEventBus записывает все опубликованные события для проверки в тестах.
type FakeEventBus struct {
    mu     sync.Mutex
    Events []Event
}

func NewFakeEventBus() *FakeEventBus {
    return &FakeEventBus{}
}

func (f *FakeEventBus) Publish(_ context.Context, event Event) error {
    f.mu.Lock()
    defer f.mu.Unlock()
    f.Events = append(f.Events, event)
    return nil
}

func (f *FakeEventBus) Subscribe(_ string, _ Handler) {
    // No-op для тестов
}

// Published возвращает все опубликованные события данного типа.
func (f *FakeEventBus) Published(eventType string) []Event {
    f.mu.Lock()
    defer f.mu.Unlock()
    var result []Event
    for _, e := range f.Events {
        if e.EventType() == eventType {
            result = append(result, e)
        }
    }
    return result
}
<?php
// tests/Fake/FakeEventBus.php
declare(strict_types=1);

namespace App\Tests\Fake;

use App\Application\Port\EventBus;
use App\Domain\Event\DomainEvent;

// Каждый t.Run в PHPUnit/Pest создаёт новый bus - класс stateful, не singleton.
final class FakeEventBus implements EventBus
{
    /** @var list<DomainEvent> */
    public array $events = [];

    public function subscribe(string $eventClass, callable $handler): void
    {
        // No-op для тестов
    }

    public function publish(DomainEvent $event): void
    {
        $this->events[] = $event;
    }

    /** @return list<DomainEvent> */
    public function published(string $eventType): array
    {
        return array_values(array_filter(
            $this->events,
            static fn(DomainEvent $e) => $e->eventType() === $eventType,
        ));
    }
}
# eventbus/test_bus.py
import threading

from backend.eventbus.bus import Event, Handler


class FakeEventBus:
    """Записывает все опубликованные события для проверки в тестах.

    Каждый тест создаёт свой экземпляр - класс stateful, не singleton.
    """

    def __init__(self) -> None:
        self._lock = threading.Lock()
        self.events: list[Event] = []

    def publish(self, event: Event) -> None:
        with self._lock:
            self.events.append(event)

    def subscribe(self, event_type: str, handler: Handler) -> None:
        pass  # No-op для тестов

    def published(self, event_type: str) -> list[Event]:
        """Возвращает все опубликованные события данного типа."""
        with self._lock:
            return [e for e in self.events if e.event_type == event_type]

Тест use-case:

func TestCompleteLesson_PublishesEvent(t *testing.T) {
    db := setupTestDB(t) // in-memory или testcontainers
    fakeBus := eventbus.NewFakeEventBus()
    outboxRepo := outbox.NewRepository(db)
    uc := usecase.NewCompleteLessonUseCase(db, outboxRepo, fakeBus)

    err := uc.Execute(context.Background(), usecase.CompleteLessonRequest{
        UserID:     1,
        LessonID:   42,
        TrackSlug:  "go",
        LessonSlug: "goroutines",
    })
    require.NoError(t, err)

    // Проверяем, что событие опубликовано
    events := fakeBus.Published("lesson.completed")
    require.Len(t, events, 1)

    evt := events[0].(domain.LessonCompleted)
    assert.Equal(t, int64(1), evt.UserID)
    assert.Equal(t, int64(42), evt.LessonID)
    assert.Equal(t, "go", evt.TrackSlug)
    assert.Equal(t, "lesson.completed", evt.Type)
    assert.NotEmpty(t, evt.EventID)
}

func TestCompleteLesson_WritesToOutbox(t *testing.T) {
    db := setupTestDB(t)
    fakeBus := eventbus.NewFakeEventBus()
    outboxRepo := outbox.NewRepository(db)
    uc := usecase.NewCompleteLessonUseCase(db, outboxRepo, fakeBus)

    err := uc.Execute(context.Background(), usecase.CompleteLessonRequest{
        UserID:     1,
        LessonID:   42,
        TrackSlug:  "go",
        LessonSlug: "goroutines",
    })
    require.NoError(t, err)

    // Проверяем, что запись появилась в outbox. FakeEventBus принял событие,
    // поэтому use-case уже отметил её опубликованной: ищем без фильтра по published_at.
    var count int
    err = db.QueryRow(`SELECT COUNT(*) FROM outbox
        WHERE event_type = 'lesson.completed' AND published_at IS NOT NULL`).Scan(&count)
    require.NoError(t, err)
    assert.Equal(t, 1, count)
}
<?php
// tests/Application/UseCase/CompleteLessonUseCaseTest.php
declare(strict_types=1);

namespace App\Tests\Application\UseCase;

use App\Application\UseCase\CompleteLessonRequest;
use App\Application\UseCase\CompleteLessonUseCase;
use App\Domain\Event\LessonCompleted;
use App\Tests\Fake\FakeEventBus;
use PHPUnit\Framework\TestCase;
use Psr\Log\LoggerInterface;

final class CompleteLessonUseCaseTest extends TestCase
{
    public function testPublishesEvent(): void
    {
        $db = $this->setUpTestDB();
        $fakeBus = new FakeEventBus();
        $outboxRepo = new OutboxRepository($db);
        $uc = new CompleteLessonUseCase($db, $outboxRepo, $fakeBus, $this->createMock(LoggerInterface::class));

        $uc->execute(new CompleteLessonRequest(
            userId: 1,
            lessonId: 42,
            trackSlug: 'go',
            lessonSlug: 'goroutines',
            correlationId: 'test-corr',
        ));

        // Проверяем, что событие опубликовано
        $events = $fakeBus->published('lesson.completed');
        self::assertCount(1, $events);

        /** @var LessonCompleted $evt */
        $evt = $events[0];
        self::assertSame(1, $evt->userId);
        self::assertSame(42, $evt->lessonId);
        self::assertSame('go', $evt->trackSlug);
        self::assertSame('lesson.completed', $evt->eventType());
        self::assertNotEmpty($evt->eventId);
    }

    public function testWritesToOutbox(): void
    {
        $db = $this->setUpTestDB();
        $fakeBus = new FakeEventBus();
        $outboxRepo = new OutboxRepository($db);
        $uc = new CompleteLessonUseCase($db, $outboxRepo, $fakeBus, $this->createMock(LoggerInterface::class));

        $uc->execute(new CompleteLessonRequest(
            userId: 1,
            lessonId: 42,
            trackSlug: 'go',
            lessonSlug: 'goroutines',
            correlationId: 'test-corr',
        ));

        // FakeEventBus принял событие, поэтому use-case уже отметил строку
        // опубликованной: ищем без фильтра по published_at IS NULL.
        $count = $db->fetchOne(
            "SELECT COUNT(*) FROM outbox WHERE event_type = 'lesson.completed' AND published_at IS NOT NULL",
        );
        self::assertSame(1, (int) $count);
    }
}
# usecase/test_complete_lesson.py
import pytest

from backend.domain.events import LessonCompleted
from backend.eventbus.test_bus import FakeEventBus
from backend.outbox.repository import Repository
from backend.usecase.complete_lesson import CompleteLessonRequest, CompleteLessonUseCase


@pytest.fixture
def test_pool():
    # testcontainers-python или локальный Postgres из docker-compose
    pool = setup_test_db()
    yield pool
    pool.close()


def test_complete_lesson_publishes_event(test_pool) -> None:
    fake_bus = FakeEventBus()
    outbox_repo = Repository(test_pool)
    uc = CompleteLessonUseCase(test_pool, outbox_repo, fake_bus)

    uc.execute(CompleteLessonRequest(
        user_id=1,
        lesson_id=42,
        track_slug="go",
        lesson_slug="goroutines",
    ))

    # Проверяем, что событие опубликовано
    events = fake_bus.published("lesson.completed")
    assert len(events) == 1

    evt = events[0]
    assert isinstance(evt, LessonCompleted)
    assert evt.user_id == 1
    assert evt.lesson_id == 42
    assert evt.track_slug == "go"
    assert evt.event_type == "lesson.completed"
    assert evt.event_id


def test_complete_lesson_writes_to_outbox(test_pool) -> None:
    fake_bus = FakeEventBus()
    outbox_repo = Repository(test_pool)
    uc = CompleteLessonUseCase(test_pool, outbox_repo, fake_bus)

    uc.execute(CompleteLessonRequest(
        user_id=1,
        lesson_id=42,
        track_slug="go",
        lesson_slug="goroutines",
    ))

    # Проверяем, что запись появилась в outbox. FakeEventBus принял событие,
    # поэтому use-case уже отметил её опубликованной: ищем без фильтра по published_at.
    with test_pool.connection() as conn:
        (count,) = conn.execute(
            """SELECT COUNT(*) FROM outbox
               WHERE event_type = 'lesson.completed' AND published_at IS NOT NULL"""
        ).fetchone()
    assert count == 1

Тест подписчика:

func TestAchievementChecker_GrantsFirstLesson(t *testing.T) {
    db := setupTestDB(t)
    checker := subscribers.NewAchievementChecker(db)

    // Подготовка: один завершённый урок
    insertLessonProgress(t, db, 1, "go", true)

    evt := domain.LessonCompleted{
        EventID:   "test-event-1",
        Type:      "lesson.completed",
        UserID:    1,
        TrackSlug: "go",
    }

    err := checker.Handle(context.Background(), evt)
    require.NoError(t, err)

    // Проверяем ачивку
    var count int
    db.QueryRow(`SELECT COUNT(*) FROM user_achievements
        WHERE user_id = 1 AND achievement_slug = 'first_lesson'`).Scan(&count)
    assert.Equal(t, 1, count)

    // Повторный вызов - идемпотентно, ачивка не дублируется
    err = checker.Handle(context.Background(), evt)
    require.NoError(t, err)

    db.QueryRow(`SELECT COUNT(*) FROM user_achievements
        WHERE user_id = 1 AND achievement_slug = 'first_lesson'`).Scan(&count)
    assert.Equal(t, 1, count) // по-прежнему 1
}
<?php
// tests/Application/Subscriber/AchievementCheckerTest.php
declare(strict_types=1);

namespace App\Tests\Application\Subscriber;

use App\Application\Subscriber\AchievementChecker;
use App\Domain\Event\LessonCompleted;
use PHPUnit\Framework\TestCase;
use DateTimeImmutable;
use Psr\Log\LoggerInterface;

final class AchievementCheckerTest extends TestCase
{
    public function testGrantsFirstLesson(): void
    {
        $db = $this->setUpTestDB();
        $checker = new AchievementChecker($db, $this->createMock(LoggerInterface::class));

        // Подготовка: один завершённый урок
        $this->insertLessonProgress($db, 1, 'go', true);

        $event = new LessonCompleted(
            eventId: 'test-event-1',
            correlationId: 'test-corr',
            occurredAt: new DateTimeImmutable(),
            userId: 1,
            lessonId: 1,
            trackSlug: 'go',
            lessonSlug: 'goroutines',
        );

        $checker($event);

        // Проверяем ачивку
        $count = (int) $db->fetchOne(
            'SELECT COUNT(*) FROM user_achievements
             WHERE user_id = 1 AND achievement_slug = :slug',
            ['slug' => 'first_lesson'],
        );
        self::assertSame(1, $count);

        // Повторный вызов - идемпотентно, ачивка не дублируется
        $checker($event);

        $count = (int) $db->fetchOne(
            'SELECT COUNT(*) FROM user_achievements
             WHERE user_id = 1 AND achievement_slug = :slug',
            ['slug' => 'first_lesson'],
        );
        self::assertSame(1, $count); // по-прежнему 1
    }
}
# subscribers/test_achievement_checker.py
from datetime import datetime, timezone

from backend.domain.events import LessonCompleted
from backend.subscribers.achievement_checker import AchievementChecker


def count_achievements(pool, user_id: int, slug: str) -> int:
    with pool.connection() as conn:
        row = conn.execute(
            """SELECT COUNT(*) FROM user_achievements
               WHERE user_id = %s AND achievement_slug = %s""",
            (user_id, slug),
        ).fetchone()
    return int(row[0])


def test_achievement_checker_grants_first_lesson(test_pool) -> None:
    checker = AchievementChecker(test_pool)

    # Подготовка: один завершённый урок
    insert_lesson_progress(test_pool, 1, "go", True)

    # frozen dataclass требует все поля - в Go незаполненные были бы zero value
    evt = LessonCompleted(
        event_id="test-event-1",
        event_type="lesson.completed",
        correlation_id="test-corr",
        occurred_at=datetime.now(timezone.utc),
        user_id=1,
        lesson_id=1,
        track_slug="go",
        lesson_slug="goroutines",
    )

    checker.handle(evt)

    # Проверяем ачивку
    assert count_achievements(test_pool, 1, "first_lesson") == 1

    # Повторный вызов - идемпотентно, ачивка не дублируется
    checker.handle(evt)

    assert count_achievements(test_pool, 1, "first_lesson") == 1  # по-прежнему 1

ℹ️ Добавить нового подписчика = один файл + одна строка регистрации. Ни один существующий код не меняется.

Это главное преимущество event-driven архитектуры. Завтра понадобится отправлять данные в рекомендательную систему? Создайте RecommendationUpdater, реализуйте Handle, добавьте bus.Subscribe("lesson.completed", recommender.Handle) в main.go. Use-case, другие подписчики, outbox - всё остаётся нетронутым.

Чеклист проекта

Убедитесь, что реализовано:

  • Доменное событие LessonCompleted с полями event_id, type, correlation_id, occurred_at, user_id, lesson_id, track_slug, lesson_slug
  • Интерфейс EventBus с методами Publish и Subscribe
  • InProcessBus - реализация через горутины с логированием ошибок подписчиков
  • Таблица outbox с DDL (id, event_id, event_type, payload, created_at, published_at, attempts)
  • Use-case CompleteLessonUseCase, который сохраняет прогресс и outbox в одной транзакции
  • Подписчик AchievementChecker с идемпотентным UPSERT
  • Подписчик AnalyticsRecorder с дедупликацией по event_id
  • Подписчик NotificationSender с интерфейсом Notifier (заглушка)
  • OutboxPoller - горутина с интервалом; пачка в одной транзакции с FOR UPDATE SKIP LOCKED, публикация и mark published до COMMIT
  • Wiring в main.go: bus -> subscribers -> use-case -> poller
  • FakeEventBus для unit-тестов
  • Тест: CompleteLesson публикует событие и записывает в outbox
  • Тест: AchievementChecker идемпотентен при повторном вызове

Типичные ошибки в этом проекте

  • bus.Publish напрямую из use-case вместо outbox - публикация в брокер до commit транзакции. Откат БД → событие уже ушло. Use-case пишет только в outbox-таблицу в той же транзакции, что и progress; брокеру отправляет poller.
  • OutboxPoller - два инстанса без leader election - оба читают одну запись, дубли × N. Либо FOR UPDATE SKIP LOCKED, либо один инстанс с k8s Recreate strategy.
  • AchievementChecker через INSERT вместо UPSERT - повторное событие → unique violation, retry, DLQ. Идемпотентность через INSERT ... ON CONFLICT DO NOTHING или ON CONFLICT (event_id) DO NOTHING - фундамент проекта.
  • AnalyticsRecorder пишет в Redis без AOF - событие записано, Redis перезагрузился, аналитика потеряна. Для аналитики достаточно at-least-once; для критики - PostgreSQL/долговечное хранилище.
  • NotificationSender отправляет email синхронно - SMTP отвечает за 5 секунд, subscriber обрабатывает 1 событие в 5с, очередь растёт. Notifier с deadline + retry + DLQ, либо отдельный сервис отправки.
  • FakeEventBus для теста разделён между параллельными t.Run - события одного теста ловит handler другого. Создавай новый bus в каждом setup.
  • Outbox-таблица без индекса на (published_at, created_at) - poller-запрос WHERE published_at IS NULL под нагрузкой делает seqscan на миллионе строк. Индекс - обязательно с первого дня.
  • correlation_id не пробрасывается в горутину subscriber-а - лог HTTP-запроса и лог subscriber-а не сопоставить. Subscriber извлекает correlation_id из envelope и добавляет в slog-контекст; как настроить это один раз через middleware и handler логгера - в уроке про наблюдаемость.

Мини-задание

  • Реализуй полный pipeline: use-case -> outbox -> poller -> bus -> subscribers
  • Напиши unit-тест с FakeEventBus, проверяющий публикацию LessonCompleted
  • Убедись, что каждый подписчик идемпотентен (вызови Handle дважды - результат не меняется)
  • Добавь четвёртого подписчика (например, RecommendationUpdater), не меняя ни одного существующего файла
  • Запусти go test ./... и убедись, что все тесты проходят

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.