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

Implementation Ready Breakdown — Первые release units, execution slices и порядок практической реализации

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

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

Этот документ переводит собранный архитектурный пакет vitiana-api-platform в implementation-oriented форму.

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

  • какие первые release units действительно нужны платформе;
  • как должны выглядеть первые execution slices;
  • в каком порядке их безопасно реализовывать;
  • какие domain and operational gates должен проходить каждый slice;
  • где проходят границы между “можно строить вместе” и “нужно отделять уже на первом этапе”.

Этот документ не заменяет Development Roadmap — Путь развития платформы от архитектурного baseline к промышленной эксплуатации. Он является его практическим продолжением.

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

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

Пакет уже содержит:

  • domain core;
  • execution baseline;
  • technology baseline;
  • eventing baseline;
  • observability baseline.

Но этого всё ещё недостаточно, чтобы команда начала реализацию без риска снова скатиться в:

  • слишком большой стартовый монолит без границ;
  • преждевременный zoo of microservices;
  • случайный порядок реализации “по удобству” вместо architecture-first rollout.

Нужен отдельный документ, который отвечает на вопрос:

что именно мы строим первым набором release units и почему именно так.

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

Первые implementation slices должны идти не по принципу “сначала красивый UI” и не по принципу “сразу разнесём всё на 20 сервисов”, а по принципу:

  1. сначала truth-bearing backbone;
  2. затем supplier-to-offer path;
  3. затем commercial and quote path;
  4. затем booking path;
  5. затем post-booking, clearing and operational hardening;
  6. только потом расширение surfaces and scale.

Что Такое Release Unit В Этом Документе​

Release unit здесь — это минимально осмысленная единица изменения, которую можно:

  • разрабатывать;
  • тестировать;
  • выкатывать;
  • наблюдать;
  • откатывать или forward-fix without architectural chaos.

Release unit не обязан совпадать:

  • с доменным документом;
  • с отдельным сервисом;
  • с отдельным контейнером.

Стартовая Модель Реализации​

На первом practical этапе платформе не нужен fully exploded microservice landscape.

Но ей уже нужен controlled separation между следующими runtime groups:

  1. core platform runtime
  2. ingestion runtime
  3. search/read projection runtime
  4. async workers and scheduled jobs
  5. operator and diagnostics runtime

Это даёт достаточную управляемость без premature fragmentation.

Первые Release Units​

RU-1. Core Truth Backbone​

Назначение​

Собрать минимальную truth-bearing основу платформы.

Включает​

  • canonical persistent model;
  • tenancy and identity backbone;
  • tenant configuration baseline;
  • governance case persistence;
  • partner clearing account primitives;
  • migration discipline and base schemas.

Не Включает​

  • rich search delivery;
  • final partner API surface;
  • production-grade supplier breadth;
  • advanced tour builder.

Gate​

Нельзя двигаться дальше без:

  • устойчивой schema evolution discipline;
  • actor/tenant isolation correctness;
  • audit-significant persistence for quote/booking-adjacent truth classes where already introduced.

RU-2. Supplier Intake And Canonicalization Slice​

Назначение​

Построить управляемый supplier-to-canonical path.

Включает​

  • initial supplier adapters;
  • raw trace persistence;
  • normalization path;
  • mapping and review path;
  • replay-safe queue jobs;
  • canonical update events.

Gate​

Нельзя двигаться дальше без:

  • reproducible replay;
  • anomaly and quarantine handling;
  • observable intake pipeline;
  • first stable event families from initial-event-taxonomy.

RU-3. Offer And Publication Slice​

Назначение​

Собрать путь от canonical state к operational offer and controlled publication.

Включает​

  • offer materialization;
  • freshness logic;
  • publication integrity gating;
  • read projection for offer discovery;
  • invalidation and repricing triggers.

Gate​

Нельзя двигаться дальше без:

  • visible distinction between internal-only and publishable state;
  • suppression of obviously unsafe offers;
  • replay-aware regeneration of offer projections.

RU-4. Commercial And Quote Slice​

Назначение​

Собрать actor-aware commercial interpretation and quote fixation.

Включает​

  • normalized base price handling;
  • commercial rule application;
  • quote creation;
  • quote expiry and invalidation;
  • repricing path;
  • tenant-aware visibility.

Gate​

Нельзя двигаться дальше без:

  • clear difference between indicative price and quoted promise;
  • observable quote lifecycle;
  • contract-safe quote semantics for first internal/agency surface.

RU-5. Booking Commit Slice​

Назначение​

Построить bounded, failure-aware booking path.

Включает​

  • booking intent;
  • supplier confirmation loop;
  • uncertain state handling;
  • booking events;
  • first operational recovery actions.

Gate​

Нельзя двигаться дальше без:

  • durable booking truth;
  • visible unknown external state handling;
  • idempotent booking-side retries;
  • no hidden reliance on manual archaeology.

RU-6. Post-Booking And Clearing Slice​

Назначение​

Сделать платформу не только sell-capable, но и service-capable.

Включает​

  • post-booking cases;
  • cancellation/amendment basics;
  • partner financial admissibility checks;
  • holds and limit checks;
  • first reconciliation triggers;
  • support-case visibility.

Gate​

Нельзя двигаться дальше без:

  • basic cancellation and change handling;
  • no uncontrolled partner financial exposure;
  • observable handoff from booking to post-booking and clearing.

RU-7. Controlled External Surface Slice​

Назначение​

Открыть платформу наружу ограниченно и честно.

Включает​

  • bounded agency surface;
  • bounded partner API surface;
  • quota and metering semantics;
  • publication-safe search and quote contract;
  • external-facing errors and throttling behavior.

Gate​

Нельзя считать slice завершённым без:

  • usage governance;
  • contract stability rules;
  • supportable external troubleshooting path;
  • release-safe compatibility discipline.

Первые Execution Slices​

Ниже — рекомендуемая practical sequencing, которая режет систему не “по сервисам вообще”, а по executable value streams.

Slice A. Tenant + Canonical + Ingestion Base​

Должен дать:

  • tenant bootstrap;
  • canonical storage;
  • supplier trace;
  • normalization path;
  • first review queues.

Slice B. Offer Projection + Publication Integrity​

Должен дать:

  • materialized offers;
  • integrity states;
  • publishable/internal distinction;
  • first search-ready projection.

Slice C. Quote And Commercial Fixation​

Должен дать:

  • actor-aware quote lifecycle;
  • repricing and invalidation;
  • policy-aware price delivery.

Slice D. Booking Commit And Recovery​

Должен дать:

  • booking intent to confirmation;
  • unknown-state handling;
  • booking recovery jobs;
  • booking event stream.

Slice E. Post-Booking / Clearing / Reconciliation Base​

Должен дать:

  • change/cancel cases;
  • clearing holds and limits;
  • basic financial trace;
  • reconciliation case opening.

Slice F. External Controlled Beta​

Должен дать:

  • first agency operational surface;
  • first partner integration surface;
  • quota-aware external delivery;
  • observability-backed support path.

Что Можно Объединять На Первом Этапе​

На раннем этапе допустимо объединять в один deployable runtime:

  • tenancy + internal auth + tenant policy basics;
  • offer + quote orchestration if boundaries are preserved logically;
  • booking + post-booking basics if state models remain separate internally;
  • operator tooling + diagnostics views.

Что Уже На Первом Этапе Лучше Разводить​

Желательно не смешивать даже на старте:

  • ingestion runtime и transactional core;
  • supplier-heavy async processing и partner/public read surfaces;
  • search projection store и canonical source of truth;
  • queue workers and synchronous API fronts;
  • observability stack and application logic.

Initial Runtime Shape​

Наиболее разумная early implementation shape сейчас выглядит так:

Runtime 1. Core API And Domain Runtime​

Содержит:

  • tenant/identity basics;
  • offer/quote orchestration;
  • booking truth;
  • post-booking and clearing basics;
  • operator-facing APIs.

Runtime 2. Ingestion And Replay Runtime​

Содержит:

  • supplier intake;
  • normalization;
  • mapping;
  • replay jobs;
  • canonical update emitters.

Runtime 3. Projection And Search Runtime​

Содержит:

  • search index updates;
  • publication-safe projections;
  • read-heavy search delivery.

Runtime 4. Async Worker Runtime​

Содержит:

  • expiry jobs;
  • revalidation/repricing jobs;
  • booking follow-up;
  • reconciliation and support queues.

Initial Contract Package​

Первый implementation-ready contract package должен включать:

  • canonical event envelopes;
  • queue job families;
  • quote and booking contract skeletons;
  • publication-state contract semantics;
  • metering/quota response semantics;
  • correlation field standard.

Release Discipline For First Units​

Каждый из первых release units должен сопровождаться:

  • schema expansion plan;
  • feature flag or staged gate;
  • event compatibility note;
  • observability watch list;
  • rollback/forward-fix rule;
  • replay impact note.

Что Пока Не Нужно Делать​

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

  • разносить каждый доменный контур в отдельный independently deployed microservice;
  • обещать final topology;
  • prematurely shard transactional truth;
  • открывать широкий public surface раньше controlled beta;
  • считать implementation breakdown substitute for product prioritization.

Следующий Практический Шаг После Этого Документа​

После фиксации этого breakdown логично делать уже не ещё один общий документ, а один из двух next-step артефактов:

  1. initial contract package
  2. release-unit-by-release-unit delivery checklist

Первый из них теперь зафиксирован отдельно в Initial Contract Package — Первый implementation-ready пакет контрактов платформы.

Следующий более формальный слой после него теперь зафиксирован в OpenAPI Skeletons And Resource Families — Первый bounded synchronous contract artifact.

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

Следующий более прикладной async layer теперь зафиксирован в Channel Catalog Drafts By Release Unit — Первые channel families, producers, consumers и delivery expectations.

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

Этот документ фиксирует, что практическая реализация платформы должна идти:

  • через несколько осмысленных release units;
  • через staged execution slices;
  • через раннюю защиту truth-bearing contours;
  • через controlled separation между ingestion, projections, core truth and async work;
  • без premature microservice explosion, но и без возврата к бесформенному монолиту.

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

Этот документ описывает первые release units и порядок практической реализации. Реализация не green-field — она опирается на работающее ядро home-to-go-api.

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

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

  • что уже реализовано в home-to-go-api;
  • что нужно реализовать для каждого release unit;
  • какие технические долги (8 каноничных) затрагиваются;
  • какой path конвергенции через Strangler Fig pattern.

Целевой технологический стек​

Согласно reference/implementation-technology-baseline.md и open proposals:

Каноничные приоритеты release units (стадия 1 implementation baseline)​

Согласно development/roadmap.md, стадия 1 приоритеты:

Приоритет 1 (критические gaps, блокирующие production):

  1. Multi-tenancy migration — tenant_id во все таблицы apivitianadb;
  2. Booking state machine миграция — 14 каноничных состояний;
  3. Payment domain — выбор PSP (Stripe рекомендуется), PaymentIntent flow;
  4. Compliance baseline — privacy notice, consent management, DSR API minimal;
  5. Security baseline — MFA, secrets manager, audit logging;
  6. DR baseline для Tier 1 — verified backup и restore.

Приоритет 2 (controlled internal platform): 7. Notification service; 8. Search service (PostgreSQL FTS minimum); 9. Event store baseline (Redis Streams); 10. API as Product partner lifecycle (sandbox + certification для второго supplier); 11. Media abstraction; 12. i18n baseline.

Приоритет 3 (для controlled external beta стадия 3): 13. Tour Builder operational model; 14. A/B testing infrastructure; 15. Analytics baseline; 16. Runbooks для всех каноничных incident classes; 17. SLA monitoring; 18. Capacity planning automation.

При создании каждого release unit — сверка с приоритетом и path конвергенции в relation-to-implementation-baseline.md.

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