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

Payload Family Outlines For High-Value Channels — Первые bounded payload shapes для ключевых async channels

Версия: 1.0
Дата: 24.04.2026
Статус: Готов к обсуждению

Назначение документа​

Этот документ фиксирует первые bounded payload family outlines для наиболее значимых async channels платформы.

Его задача — определить:

  • какие payload families должны быть описаны первыми;
  • какие поля обязательны на уровне domain-significant событий;
  • где payload должен быть thin signal, а где richer state snapshot;
  • как correlation, actor, tenant, financial and operational context должны попадать в события;
  • какие payload shapes уже должны быть согласованы с domain model, contract package и channel catalog.

Документ не является финальным schema registry или полной AsyncAPI payload спецификацией. Он является первым shape-level baseline для high-value event families.

Опорные документы​

Почему Этот Документ Нужен Отдельно​

После появления:

  • event taxonomy;
  • async skeleton;
  • channel catalog draft;

уже недостаточно понимать только channel families и producers/consumers.

Нужен следующий bounded слой, который впервые отвечает:

  • какой payload shape мы вообще ожидаем от high-value event family;
  • что должно быть в metadata envelope, а что в domain payload;
  • где допустим только reference-based signal, а где нужен richer payload snapshot;
  • какие поля нельзя опускать без потери observability, replayability или supportability.

Без этого канал может быть “формально описан”, но всё равно остаться слишком расплывчатым для реальной implementation discipline.

Главный Принцип​

High-value async payload должен быть:

  • semantic, not transport-noisy;
  • correlation-complete;
  • tenant-aware where relevant;
  • actor-aware where relevant;
  • replay-safe where required;
  • small enough to avoid accidental payload bloat;
  • rich enough to support downstream decision-making without blind lookup chains.

Envelope-Level Field Families​

Для first-wave high-value events уже должны быть различимы следующие группы полей:

1. Identity Fields​

  • event_name
  • event_version
  • event_id
  • occurred_at
  • producer

2. Correlation Fields​

  • correlation_id
  • causation_id, where applicable
  • request_id, where applicable
  • actor_context_id, where applicable

3. Scope Fields​

  • tenant_id, where applicable
  • workspace_id, where applicable
  • surface_scope, where relevant

4. Domain Reference Fields​

  • entity identifiers central to the event family
  • minimal reference to parent/related transaction when relevant

5. Delivery/Replay Hints​

  • delivery_class
  • replay_sensitivity
  • schema_family

Payload Family 1. Canonical Change Payloads​

Target Families​

  • canonical.property.*
  • canonical.product.*
  • canonical.mapping.changed

Minimal Domain Shape​

  • canonical_entity_type
  • canonical_entity_id
  • change_kind
  • source_change_basis
  • governance_state, where relevant

Optional Rich Fields​

  • changed_field_groups
  • source_trace_refs
  • mapping_decision_ref

Design Rule​

Canonical change payloadы не должны тащить весь canonical object snapshot по умолчанию.

Они должны быть:

  • reconstruction-friendly;
  • enough for downstream invalidation/materialization decisions;
  • not a hidden substitute for read models.

Payload Family 2. Offer Publication Payloads​

Target Families​

  • offer.materialized
  • offer.updated
  • offer.integrity.blocked
  • offer.publication.allowed
  • offer.publication.suppressed

Minimal Domain Shape​

  • offer_id
  • offer_revision
  • property_id
  • publication_state
  • integrity_state
  • freshness_state

Optional Rich Fields​

  • suppression_reason_codes
  • integrity_rule_refs
  • publication_scope
  • affected_surface_classes

Design Rule​

Publication payloadы должны быть downstream-usable для projections, но не должны раскрывать raw supplier or hidden governance internals.

Payload Family 3. Quote Lifecycle Payloads​

Target Families​

  • quote.created
  • quote.expired
  • quote.invalidated
  • quote.repricing.required
  • quote.repriced

Minimal Domain Shape​

  • quote_id
  • offer_id
  • quote_state
  • price_basis_ref
  • currency_code
  • quote_valid_until, where relevant
  • commercial_context_ref

Required Correlation Additions​

  • tenant_id
  • workspace_id, where relevant
  • actor_context_id, where relevant

Optional Rich Fields​

  • repricing_reason_code
  • invalidated_by_event_ref
  • price_view_class
  • quote_visibility_scope

Design Rule​

Quote payloadы не должны быть full monetary breakdown dump по умолчанию.

Они должны:

  • однозначно различать quoted promise и indicative context;
  • быть пригодными для UI refresh, booking guards и support trace;
  • не подменять audited storage truth.

Payload Family 4. Booking Transition Payloads​

Target Families​

  • booking.intent.created
  • booking.confirmation.pending
  • booking.confirmed
  • booking.partially.failed
  • booking.unknown.external.state
  • booking.cancel.requested
  • booking.cancelled

Minimal Domain Shape​

  • booking_id
  • booking_state
  • quote_id, where applicable
  • booking_reference_scope
  • supplier_confirmation_state
  • transactional_outcome_class

Required Operational Fields​

  • support_visibility_class
  • manual_intervention_required
  • recovery_path_ref, where applicable

Optional Rich Fields​

  • supplier_booking_ref, where available
  • failure_reason_code
  • unknown_state_reason_code
  • cancellation_path_class

Design Rule​

Booking payloadы должны быть operationally usable.

Нельзя делать их настолько thin, что downstream support or post-booking contours вынуждены читать историю по косвенным признакам.

Payload Family 5. Post-Booking Case Payloads​

Target Families​

  • postbooking.change.requested
  • postbooking.support.case.opened
  • postbooking.support.case.resolved
  • postbooking.disruption.detected

Minimal Domain Shape​

  • post_booking_case_id
  • booking_id
  • case_type
  • case_state
  • service_owner_scope
  • customer_impact_class

Optional Rich Fields​

  • supplier_action_required
  • sla_bucket
  • resolution_path_class
  • disruption_severity

Design Rule​

Post-booking payloadы должны быть case-centric, а не booking-centric.

Они должны помогать service operations, а не только “доклеиваться” к booking timeline.

Payload Family 6. Settlement And Reconciliation Payloads​

Target Families​

  • settlement.event.posted
  • settlement.adjustment.required
  • reconciliation.case.opened
  • reconciliation.case.resolved

Minimal Domain Shape​

  • financial_event_id or reconciliation_case_id
  • booking_id, where applicable
  • financial_state_class
  • currency_code
  • amount_scope_class
  • financial_counterparty_scope

Required Financial Fields​

  • settlement_basis_ref
  • clearing_context_ref, where applicable
  • discrepancy_class, where applicable

Optional Rich Fields​

  • adjustment_reason_code
  • reconciliation_owner_scope
  • fx_context_ref
  • rounding_context_ref

Design Rule​

Financial payloadы должны быть traceable and safe for downstream financial operations, но не должны по умолчанию становиться full accounting ledger export.

Payload Family 7. Usage Governance Payloads​

Target Families​

  • usage.quota.nearing_limit
  • usage.quota.exhausted
  • usage.profile.degraded
  • tenant.surface.restricted

Minimal Domain Shape​

  • tenant_id
  • usage_profile_id, where applicable
  • governance_state
  • affected_surface_scope
  • enforcement_class

Optional Rich Fields​

  • quota_window_ref
  • degradation_reason_code
  • throttle_policy_ref
  • clearing_block_ref, where applicable

Design Rule​

Usage governance payloadы должны быть sufficient for surface enforcement and partner success operations, но не должны становиться low-level metrics dump.

Reference-Heavy Vs Snapshot-Heavy Policy​

Reference-Heavy Families​

Предпочтительны для:

  • canonical changes;
  • policy changes;
  • governance signals.

Richer Snapshot Families​

Нужны для:

  • quote lifecycle;
  • booking transitions;
  • post-booking case lifecycle;
  • settlement/reconciliation events.

Correlation Completeness Rules​

Для high-value payload families должны действовать следующие правила:

  • если событие затрагивает external promise, нужен correlation_id;
  • если событие влияет на actor-visible path, нужен actor_context_id where relevant;
  • если событие tenant-sensitive, нужен tenant_id;
  • если событие financial or post-booking critical, нужен link to upstream booking/quote/case/financial basis.

What Must Stay Out Of Scope​

Пока не нужно:

  • фиксировать exact JSON schema для каждого поля;
  • описывать every optional extension field;
  • смешивать payload families с broker serialization details;
  • моделировать binary/blob delivery;
  • превращать outline в full event catalog.

Что Должно Появиться Следом​

Следующий практический слой после этого документа:

Этот документ создаёт первый shape-level baseline для high-value async channels и связывает channel catalog с будущими более формальными payload schemas.

Уточнение под Фазы 4–6 (28.04.2026)​

Документ опубликован 24.04.2026 (Фаза 3). После Фаз 4–6 опубликованы каноничные payload structures для всех критичных high-value channels — использовать актуальные структуры из специализированных доменов:

Каноничный сводный каталог имён — initial-event-taxonomy.md. Каноничные guarantees per event class — eventing-and-queue-baseline.md (6 классов).

Уточнение выполнено через no-destruction.