Каталог Kafka топиков

Все взаимодействие между сервисами в платформе Манитон происходит через единую шину событий Kafka. Топики разделены по доменным областям.

Правила именования

Формат: maniton.<domain>.events.v1

• maniton — префикс организации.
• <domain> — доменная область (identity, ledger, besu и т.д.).
• events — тип данных.
• v1 — версия схемы.

Список топиков

Формат сообщения (EventEnvelope)

Каждое сообщение в Kafka оборачивается в структуру EventEnvelope, которая соответствует спецификации CloudEvents и обогащена контекстом запроса.

message EventEnvelope {
  // Уникальный ID события (UUID)
  string id = 1;
  // Источник (например, "maniton.service.ledger")
  string source = 2;
  // Тип события (например, "maniton.ledger.v1.BalanceUpdated")
  string type = 3;
  // Время возникновения
  google.protobuf.Timestamp time = 4;
  // Сами данные (сериализованный Protobuf)
  bytes data = 5;
  // Контекст запроса для трассировки и идемпотентности
  RequestContext context = 6;
}

RequestContext

Используется для сквозной трассировки (distributed tracing) и обеспечения идемпотентности во всей системе.

message RequestContext {
  string request_id = 1;        // UUID запроса
  string correlation_id = 2;    // UUID для связи запрос-ответ
  string idempotency_key = 3;   // Ключ идемпотентности
  string trace_id = 5;          // OpenTelemetry trace_id
  string user_id = 6;           // Инициатор (если есть)
  string client_ip = 8;
  Contour contour = 9;          // RF (РФ) или EXTERNAL (Внешний)
}

Гарантии доставки

Платформа использует режим At-Least-Once доставки сообщений. Это означает:

1. Обработчики (Consumers) обязаны быть идемпотентными.
2. Использование idempotency_key из контекста обязательно для всех записей в БД.
3. Повторная обработка события с тем же ID не должна приводить к повторным начислениям или списаниям.