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

External Async Projection Catalog By Surface And Partner Class — Каталог внешних async-проекций по surface-ам и классам партнёров

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

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

Этот документ фиксирует первый каталог допустимых внешних async projections платформы.

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

  • какие внешние surface-ы вообще имеют право получать async notifications;
  • какие классы партнёров могут получать разные типы внешних уведомлений;
  • какие внутренние event families допустимо проецировать наружу и в какой bounded форме;
  • какие уведомления должны быть доступны только через pull/read model, а не через push;
  • где проходят границы между partner API, agency workflow, white-label channel и другими внешними поверхностями.

Документ не заменяет webhook policy и не описывает финальные payload schemas. Он является catalog-layer между общим boundary policy и будущими конкретными webhook contract packages.

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

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

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

  • общего webhook boundary;
  • producer and consumer readiness gates;
  • tenant enablement and usage governance logic;

уже недостаточно знать только “можно ли вообще вывести это наружу”.

Нужен отдельный catalog-layer, который отвечает:

  • для какого external surface это допустимо;
  • для какого partner class это допустимо;
  • какой уровень детализации и promises разрешён;
  • где нужен webhook, а где лучше оставить pull-only contract;
  • как tenant policy и partner trust class ограничивают внешний async surface.

Без этого внешний async слой быстро превращается либо в слишком богатую утечку внутренних событий, либо в хаотический набор ad hoc подписок.

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

External async projection must be surface-specific and partner-class-specific.

Это означает:

  • один и тот же внутренний доменный факт не обязан одинаково проецироваться во все внешние контуры;
  • разные partner classes могут получать разные bounded projections;
  • наличие внешнего API surface ещё не означает автоматического права на webhook family;
  • tenant enablement и trust profile должны быть частью projection decision.

Surface Classes​

В рамках текущего каталога различаются следующие внешние surface-ы:

1. Agency Working Surface​

Это human-facing рабочая поверхность агентств.

Для неё допустимы:

  • action-oriented notifications;
  • workflow continuity notifications;
  • quote/booking/post-booking state changes;
  • proposal/customer-facing follow-up signals where relevant.

Недопустимы:

  • сырые governance internals;
  • технические queue/recovery сигналы;
  • settlement internals без явного human workflow.

2. Partner API Surface​

Это machine-to-machine интеграционный surface.

Для него допустимы:

  • bounded status transitions;
  • quota and governance notifications;
  • partner-safe booking and post-booking notifications;
  • selective quote notifications if partner реально строит workflow на quote lifecycle.

Недопустимы:

  • raw internal orchestration events;
  • operator-only incident signals;
  • publication internals, если они не влияют на partner-visible contract.

3. White-Label And Embedded Surface​

Это отдельный class surface-ов, где внешний канал частично живёт на базе платформы, но с tenant-specific branding и policy.

Для него допустимы:

  • quote and booking notifications;
  • proposal/publication-adjacent notifications;
  • selected client-facing status updates;
  • usage/governance notifications для технического владельца канала, но не для конечного клиента.

4. Customer-Facing Proposal Or Self-Service Surface​

Это ограниченный внешний contour для конечного клиента.

Для него допустимы только очень аккуратные bounded projections:

  • proposal published/updated;
  • booking confirmed;
  • booking requires follow-up;
  • cancellation accepted;
  • major itinerary-impacting disruption, если бизнес действительно хочет self-service awareness.

Для него почти всегда недопустимы:

  • quote lifecycle as-is;
  • quota/governance signals;
  • partner/agency operational notifications;
  • supplier ambiguity internals.

Partner Classes​

Для внешнего async-каталога различаются следующие partner classes:

1. Internal-Equivalent Trusted Partner​

Высокий trust, высокая договорная близость, возможна глубокая интеграция.

Может получать:

  • более широкий набор booking/post-booking signals;
  • usage governance signals;
  • некоторые quote-related notifications;
  • richer correlation context.

2. Standard API Partner​

Нормальный внешний B2B-партнёр с устойчивой интеграцией.

Может получать:

  • bounded booking notifications;
  • selected quote notifications;
  • selected post-booking notifications;
  • usage/quota notifications.

3. White-Label Partner​

Партнёр, который использует платформу как основу собственного внешнего канала.

Может получать:

  • booking and post-booking notifications;
  • proposal/publication notifications;
  • selected quote notifications;
  • usage/governance notifications for operating owners.

4. Restricted Or Low-Trust Partner​

Партнёр с ограниченным enablement profile.

Может получать только:

  • минимальные booking-status notifications;
  • quota/governance notifications where contractually required.

Для него предпочтителен narrower external async surface and stronger pull reconciliation dependence.

Projection Families​

1. Quote-Status Projections​

Источник:

  • internal quote-lifecycle

Допустимые внешние projections:

  • quote-created
  • quote-invalidated
  • quote-expiring
  • quote-expired

Допустимые surface-ы:

  • agency working surface
  • partner API surface
  • white-label surface

Обычно недопустимо для:

  • customer-facing self-service surface

Partner-class note:

  • standard API partners и trusted partners могут получать;
  • low-trust partners — только если quote workflow действительно включён и bounded.

2. Booking-Status Projections​

Источник:

  • internal booking-transitions

Допустимые внешние projections:

  • booking-received
  • booking-confirmed
  • booking-pending
  • booking-requires-action
  • booking-cancelled
  • booking-state-uncertain

Допустимые surface-ы:

  • agency working surface
  • partner API surface
  • white-label surface
  • selected customer-facing self-service surface

Partner-class note:

  • доступны почти всем external classes, но детализация должна зависеть от trust level.

3. Post-Booking-Service Projections​

Источник:

  • internal post-booking-case

Допустимые внешние projections:

  • change-request-received
  • change-request-updated
  • cancellation-request-updated
  • supplier-disruption-affecting-booking
  • manual-follow-up-required

Допустимые surface-ы:

  • agency working surface
  • partner API surface
  • white-label surface

Ограниченно допустимо для:

  • customer-facing self-service surface, только если effect truly client-relevant and bounded

4. Usage-And-Quota Projections​

Источник:

  • internal usage-governance

Допустимые внешние projections:

  • quota-nearing-exhaustion
  • quota-exhausted
  • temporary-restriction-applied
  • access-restored

Допустимые surface-ы:

  • partner API surface
  • white-label operator surface
  • selected agency operator surface

Недопустимо для:

  • customer-facing surface

5. Proposal-And-Publication Projections​

Источник:

  • proposal/publication related internal contours

Допустимые внешние projections:

  • proposal-published
  • proposal-updated
  • proposal-withdrawn

Допустимые surface-ы:

  • agency working surface
  • white-label surface
  • customer-facing proposal surface

Ограничения:

  • нельзя путать proposal publication с internal offer/publication internals;
  • нельзя раскрывать governance or integrity internals behind publication decisions.

Projection Matrix By Surface And Partner Class​

Agency Working Surface​

  • trusted partner / high-trust agency tenant:

    • quote-status: yes
    • booking-status: yes
    • post-booking-service: yes
    • usage-and-quota: selected
    • proposal-and-publication: yes

  • standard agency tenant:

    • quote-status: yes
    • booking-status: yes
    • post-booking-service: yes
    • usage-and-quota: selected
    • proposal-and-publication: yes

Partner API Surface​

  • trusted partner:

    • quote-status: yes
    • booking-status: yes
    • post-booking-service: selected
    • usage-and-quota: yes
    • proposal-and-publication: selected

  • standard API partner:

    • quote-status: selected
    • booking-status: yes
    • post-booking-service: selected
    • usage-and-quota: yes
    • proposal-and-publication: usually no

  • restricted/low-trust partner:

    • quote-status: usually no
    • booking-status: selected minimal
    • post-booking-service: usually no
    • usage-and-quota: yes
    • proposal-and-publication: no

White-Label And Embedded Surface​

  • white-label partner:
    • quote-status: yes
    • booking-status: yes
    • post-booking-service: selected
    • usage-and-quota: operator-only
    • proposal-and-publication: yes

Customer-Facing Proposal Or Self-Service Surface​

  • end-customer class:
    • quote-status: no
    • booking-status: selected bounded
    • post-booking-service: minimal client-relevant only
    • usage-and-quota: no
    • proposal-and-publication: yes

Pull-Preferred Vs Push-Allowed​

Не вся внешняя truth должна идти через webhook.

Push-Allowed​

  • booking state transitions;
  • quote invalidation/expiry for workflow-dependent partners;
  • proposal publication changes;
  • quota and restriction notifications;
  • client-relevant major disruption notifications.

Pull-Preferred​

  • rich offer/publication availability detail;
  • full commercial breakdown changes;
  • detailed discrepancy or clearing information;
  • high-frequency low-stability informational state.

Если consumer нуждается в подробной и часто меняющейся read model, webhook должен использоваться только как nudge-to-refresh, а не как carrier of full truth.

Tenant Enablement Constraints​

Любая внешняя projection subscription должна проходить через tenant enablement policy:

  1. enabled surfaces;
  2. allowed projection families;
  3. trust class and support model;
  4. quota and delivery limits;
  5. secrecy/privacy restrictions;
  6. whether partner has required pull reconciliation endpoints and operational maturity.

What Must Stay Out Of Scope​

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

  • фиксировать final webhook endpoints and field schemas;
  • описывать broker/provider-specific delivery plumbing;
  • считать, что every enabled surface must receive push notifications by default.

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

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

Этот документ делает внешний async surface намного более управляемым и связывает webhook boundary с surface model, tenant enablement и partner-class reality.

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

External async projection catalog per surface × partner class должен учитывать:

Per surface (см. overview/layers.md — 6 surface contracts) × per client surface (см. reference/clients.md — 6 client surfaces) — две ortogonal таксономии. Partner async projections видны через:

  • Partner Machine Surface — contract-approved fields (subset);
  • Partner UI/SDK Surface — partner-tier dependent;
  • White-Label Embedded — partner-defined visibility;
  • B2C — never (partner data не видно конечным клиентам).

Per partner class (см. reference/api-as-product.md):

  • trusted partner — расширенный доступ к event projections;
  • standard partner — typical projection;
  • sandbox-only — sandbox events only.

Truth visibility per entity — каноничная матрица в reference/clients.md.

Tenant-scoped projections — все per-tenant aware (см. multi-tenant-isolation-strength.md).

Каноничные имена async events — initial-event-taxonomy.md.

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