Перейти к основному содержимому

Event Contract: <event.name> (<EventName>)

Версионируемый контракт интеграционного Kafka-события. Consumer-документы ссылаются сюда, не переописывая payload.

Назначение​

Какое доменное изменение фиксирует событие, кто producer, почему оно публичное и какие consumers его используют без синхронного запроса в owning-контекст.

Metadata​

ПолеЗначение
Event type<event.name> (напр. pin.crm.client-fixated)
Topic<topic-name> (напр. pin.crm.client-fixations.v1)
Partitions / key<кол-во партиций> / ключ = MessageId (Guid v7) или AggregateId
ContractVersion<n>
Producer<context/service>
Статусdraft / approved / deprecated

Событие публикуется атомарно со сменой состояния агрегата: пока изменение не зафиксировано, событие не отправляется потребителям; после фиксации — доставляется гарантированно (at-least-once).

Payload <EventName>​

Публичные display-поля бизнес-состояния. Snapshot-поля ссылаются на дом сущности (entity: <EntityName>) — перечисляется только то, что реально в событии.

ПолеТипОбязательностьИсточник (поле агрегата)CompatibilityОписание
<AggregateId>GuidДа<Entity>.IdImmutableКлюч агрегата.
TenantIdGuidДа<Entity>.TenantIdImmutableTenant boundary.
<Snapshot><SnapshotModel>ДаaggregateAdditive onlyТипизированный snapshot.

Вложенная модель <SnapshotModel>​

ПолеТипОбязательностьОграниченияОписание

Когда публикуется​

УсловиеПереход состоянияПубликация
<condition><From> → <To>атомарно со сменой состояния агрегата

Потребители (consumers)​

Consumer-контекстConsumerSide effectsИдемпотентностьЗадержка (SLA)
<context><ConsumerName><projection/command/export>MessageId/business key<SLA>

Версионирование и совместимость​

  • Версия — один ContractVersion; consumer при Version != ContractVersion логирует предупреждение и продолжает обработку. Топик кодирует версию по конвенции — суффикс .vN в имени.
  • Additive-only для minor: новые поля добавляются как optional с безопасным default — без bump.
  • Breaking (удаление/переименование/смена типа/смысла) — новый ContractVersion + новый топик .vN+1
    • параллельная публикация (dual-publish) на период миграции + deadline миграции consumers + sunset старой.
  • Unknown enum — обрабатывается явно (fallback). Deprecated-версия — sunset rule.

Безопасность​

ПолеКласс данныхПравило
<FieldName>Public/Internal/PII/Sensitiveinclude/mask/exclude

Событие НЕ содержит secrets, tokens, raw credentials, полные PII и иные чувствительные реквизиты, unbounded вложения.

Обратные ссылки​

Автоссылки: где используется этот документ.

Связанные документы​