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

Initial Contract Package — Первый implementation-ready пакет контрактов платформы

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

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

Этот документ фиксирует первый implementation-ready набор контрактов платформы.

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

  • какие contract families нужны уже на первом practical implementation этапе;
  • какие из них должны быть synchronous surface contracts, а какие async event contracts;
  • какие envelopes, identifiers and metadata уже должны быть унифицированы;
  • какие contract packages можно считать обязательными для первых release units.

Этот документ не является финальной OpenAPI/AsyncAPI спецификацией. Он является мостом между архитектурой и будущими formal schemas.

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

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

Уже недостаточно иметь:

  • общий документ про API;
  • общий документ про event taxonomy;
  • общий документ про release units.

Команде нужен первый связанный package, который говорит:

  • какие контракты делаем в первую волну;
  • в каком порядке;
  • какие identifiers and envelopes считаются обязательными;
  • какие promises уже должны быть contractually honest.

Без этого implementation быстро расползётся в локальные ad hoc схемы.

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

Первый contract package должен быть:

  • достаточно мал, чтобы реально быть внедрённым;
  • достаточно полон, чтобы покрыть первые release units;
  • достаточно строг, чтобы остановить хаос в naming and envelopes;
  • достаточно честен, чтобы не обещать внешним поверхностям больше, чем платформа реально держит.

Contract Families Первой Волны​

1. Canonical Envelope Standards​

Это базовые оболочки, без которых нельзя собирать остальные контракты.

Нужно унифицировать:

  • request correlation fields;
  • response metadata;
  • error envelope;
  • pagination metadata where needed;
  • async event envelope;
  • queue job envelope.

2. Identity / Tenant / Access Context Contract​

Минимальный baseline для:

  • actor context propagation;
  • tenant binding;
  • workspace binding where relevant;
  • auth scope declaration;
  • partner/client credential binding.

3. Search And Offer Discovery Contract​

Первый bounded search/offer family должен покрывать:

  • search context;
  • search result summary;
  • offer identity;
  • publication state visibility;
  • freshness/revalidation hints;
  • tenant-aware visibility.

4. Quote Contract Family​

Должен покрывать:

  • quote creation request;
  • quote response;
  • quote validity window;
  • repricing required state;
  • invalidation semantics;
  • policy trace references at the right abstraction level.

5. Booking Contract Family​

Должен покрывать:

  • booking intent creation;
  • booking state response;
  • unknown external state visibility;
  • cancellation request baseline;
  • booking event correlation fields.

6. Post-Booking Case Contract Family​

Минимальный baseline для:

  • cancellation/amendment request surfaces;
  • support/disruption case visibility;
  • case status and owner semantics;
  • actor-visible pending vs resolved states.

7. Clearing And Usage Contract Signals​

Даже если full finance API ещё не открыт, уже должны быть contractually visible:

  • insufficient balance / limit states;
  • blocked-by-clearing states;
  • quota nearing limit;
  • quota exhausted;
  • degraded usage profile.

8. Event Contract Families​

Первая волна async contracts должна покрывать:

  • canonical model change events;
  • offer/publication events;
  • quote events;
  • booking events;
  • post-booking case events;
  • clearing/reconciliation events;
  • usage governance events.

Envelope Standards​

1. Synchronous Response Envelope​

На текущем этапе должен как минимум допускать:

  • data
  • meta
  • warnings
  • errors
  • correlation_id

2. Error Envelope​

Должен различать:

  • business rule violation;
  • state conflict;
  • revalidation required;
  • blocked by policy;
  • blocked by clearing;
  • throttled / quota exhausted;
  • temporarily degraded external dependency.

3. Event Envelope​

Минимально должен содержать:

  • event_name
  • event_version
  • event_id
  • occurred_at
  • producer
  • correlation_id
  • causation_id where applicable
  • domain object identifiers

4. Queue Job Envelope​

Минимально должен содержать:

  • job_type
  • job_id
  • created_at
  • attempt
  • max_attempts
  • correlation_id
  • deduplication_key where applicable
  • payload reference or payload body

Identifier Standards​

На первом этапе уже нужно зафиксировать, что:

  • property_id не заменяет offer_id;
  • offer_id не заменяет quote_id;
  • quote_id не заменяет booking_id;
  • booking_id не заменяет post_booking_case_id;
  • tenant_id, workspace_id, partner_id, agency_id не должны сливаться в один generic actor field.

Correlation Standard​

Все первые contract families должны поддерживать единый correlation model:

  • correlation_id
  • request_id where surface-specific
  • actor_context_id where relevant
  • domain ids relevant to the transaction

Это критично для observability and support.

First Mandatory Contract Packages By Release Unit​

RU-1 Core Truth Backbone​

Нужны:

  • identity/tenant context contract;
  • canonical error envelope;
  • internal operator mutation safety envelopes.

RU-2 Supplier Intake And Canonicalization​

Нужны:

  • queue job envelope;
  • ingestion event envelopes;
  • review trigger contract baseline.

RU-3 Offer And Publication​

Нужны:

  • search and offer discovery contract;
  • offer publication state contract;
  • offer/publication events.

RU-4 Commercial And Quote​

Нужны:

  • quote create/read contract;
  • repricing/invalidation response semantics;
  • quote event family.

RU-5 Booking Commit​

Нужны:

  • booking intent contract;
  • booking state contract;
  • booking event family;
  • failure and unknown-state response semantics.

RU-6 Post-Booking And Clearing​

Нужны:

  • post-booking case contract;
  • clearing-state surface signals;
  • reconciliation/case events.

RU-7 Controlled External Surface​

Нужны:

  • externalized partner search/offer contract;
  • partner quote/booking bounded contract;
  • quota/throttle/error semantics;
  • partner-visible lifecycle constraints.

What Must Stay Out Of Scope For The First Package​

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

  • описывать every optional field for all future products;
  • детализировать advanced white-label custom payloads;
  • публиковать final external contract for all partner scenarios;
  • prematurely freeze full AsyncAPI catalog;
  • унифицировать internal and external payloads at any cost.

Change Discipline​

Каждый contract family первой волны должен иметь:

  • owner contour;
  • versioning note;
  • compatibility expectation;
  • replay impact note for events;
  • observability correlation requirement.

Следующий Практический Шаг​

После этого документа логично делать уже один из двух more formal artifacts:

  1. openapi-skeletons-and-resource-families.md
  2. asyncapi-skeletons-and-event-envelopes.md

Первый из них теперь зафиксирован отдельно в OpenAPI Skeletons And Resource Families — Первый bounded synchronous contract artifact.

Второй из них теперь зафиксирован отдельно в AsyncAPI Skeletons And Event Envelopes — Первый bounded asynchronous contract artifact.

Краткий Итог​

Этот документ фиксирует первый contract package не как “всё API сразу”, а как минимально достаточный слой формализации для первых release units.

Именно он должен удерживать связь между:

  • surface contracts;
  • event families;
  • envelopes;
  • identifiers;
  • release discipline;
  • observability requirements.

Уточнение под Ось 6 (28.04.2026) — связь с home-to-go-api и OpenAPI-first​

Этот документ описывает первый implementation-ready пакет контрактов. Реализация опирается на работающее ядро home-to-go-api.

Главный мост — relation-to-implementation-baseline.md​

Полная карта current vs target — в overview/relation-to-implementation-baseline.md. При формализации каждого контракта использовать его как авторитет.

Текущее состояние контрактов в home-to-go-api​

На 27.04.2026:

  • Stuba module имеет внутренний контракт (home-to-go-api/api-module-stuba/docs/CONTRACT.md) — это adapter контракт, не Partner API Surface;
  • Partner API Surface — не существует в формализованном виде; первая задача стадии 1;
  • OpenAPI specifications — отсутствуют; формализация — первая задача стадии 1;
  • AsyncAPI specifications — отсутствуют; формализация — первая задача стадии 1;
  • Webhook contracts — отсутствуют; формализация — Phase 2.

Каноничный path для контрактов​

Согласно proposal-openapi-first-polyglot-codegen.md:

  • Single source of truth — openapi.yaml per surface (multiple files: platform-v1.yaml, partner-v1.yaml, internal-v1.yaml);
  • AsyncAPI для events и webhooks;
  • Code generation:
    • Go: oapi-codegen (server stubs + clients);
    • Rust: OpenAPI Generator (clients + types);
    • TypeScript: openapi-typescript + openapi-fetch;
    • Python: openapi-python-client;
  • Documentation portal:
    • Redoc для public partner docs;
    • Swagger UI для interactive sandbox.

При создании каждого контракта в этом пакете использовать OpenAPI 3.1 + Spectral linting + canonical error envelope.

Каноничный repository layout (предложение)​

vitiana-platform/
├── api/
│   ├── openapi/
│   │   ├── platform-v1.yaml
│   │   ├── partner-v1.yaml
│   │   └── internal-v1.yaml
│   ├── asyncapi/
│   │   ├── domain-events-v1.yaml
│   │   └── webhooks-v1.yaml
│   └── README.md
├── services/
│   └── ...
├── sdks/
│   └── ...
└── docs/
    ├── redoc/
    └── swagger-ui/

Связь с принципом OpenAPI-first​

Каждый каноничный контракт этого пакета (см. перечень в этом документе) должен реализоваться из central openapi.yaml, не в него. При появлении нового resource family — сначала фиксация в OpenAPI, потом implementation на Go/TypeScript/Rust через codegen.

При несоответствии этого документа и proposal-openapi-first-polyglot-codegen — proposal recent more детальный для polyglot стратегии и tooling.

Каноничные приоритеты контрактов стадии 1​

Согласно development/roadmap.md и implementation-ready-breakdown.md, стадия 1:

Первые контракты (приоритет 1):

  1. Identity / Tenancy / Capability Set — GET /capability/me, auth flow;
  2. Booking commit (с booking state machine 14 состояний);
  3. Payment Intent (PSP integration);
  4. DSR API (compliance baseline).

Вторые контракты (приоритет 2): 5. Search; 6. Notification webhook subscription; 7. Partner sandbox lifecycle.

При формализации использовать каноничные имена событий из reference/initial-event-taxonomy.md (с уточнением фаз 4–6).

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