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

Развитие без деградации

Версия: 1.0 Дата: 25.04.2026 Статус: Утверждён

Каждое архитектурное решение в vitiana-api-platform работает на развитие платформы, а не на деградацию.

Платформа строится как зрелая глобальная система, не MVP. Заглушки (stubs), временные решения (temporary workarounds), «потом перепишем» (cheap shortcuts), хардкод (hardcoded values), upgradable-later компоненты — запрещены как архитектурный приоритет.

Зафиксировано 25.04.2026.

Главный тезис​

«Сейчас одна модель, потом разделим» — это деградация в самом первом документе. Каждое такое упрощение в стартовой архитектуре превращается в дорогое переписывание через 6-12 месяцев. Платформа верхнего уровня не может позволить себе такие переходы — они затрагивают доменную модель, surface contracts, governance.

Решение — зрелая архитектура с фазированной реализацией, где каждая фаза не создаёт долг, а финальная картина зафиксирована в документации с самого начала.

Что считается деградацией (запрещено)​

1. Заглушки​

  • Поле в каноничной модели, которое «пока всегда null».
  • Логика, которая возвращает фиксированный ответ «временно».
  • Сущность, которая существует только для backward compatibility с одним поставщиком.
  • API endpoint, который возвращает заглушку с not_implemented_yet.

2. Временные решения​

  • Архитектурный паттерн, выбранный потому что «проще для MVP».
  • Storage-решение, которое «пока в одной БД, потом разнесём».
  • Захватная интеграция (captive integration), которая «пока завязана на одного поставщика, рефакторим позже».
  • Manual reconciliation как штатный путь.

3. Hardcode​

  • Названия поставщиков в каноничной модели.
  • Tenant-specific логика в общем коде.
  • Константы как бизнес-правила без явной policy entity.

4. Backward-compatibility долг от старта​

  • Документ, который описывает «v1 модель и v2 модель», когда v1 ещё не выпущена.
  • Дублирование сущностей под разные surface contracts на старте.
  • Compatibility shims в самой первой версии canonical schema.

Что разрешено и обязательно​

Зрелые решения с фазированной реализацией​

Решение может быть реализовано в несколько фаз, если выполнены все четыре условия:

  1. Конечная архитектура чётко описана в документе.
  2. Каждая промежуточная фаза не создаёт долг, который нужно потом переписывать.
  3. Переход между фазами — это расширение, не миграция.
  4. Триггеры перехода фиксированы в документации (метрические или business signals).

Это не заглушка, а incremental delivery зрелой архитектуры.

Пример приемлемого подхода:

  • Фаза 1: один Kubernetes-кластер для всех execution contours.
  • Фаза 2: разделение на dedicated clusters per contour.

Это работает, потому что каноничная модель сервисов одна и та же, изменяется только packaging. Никакой код не переписывается.

Пример неприемлемого подхода:

  • Фаза 1: shared schema для booking и canonical.
  • Фаза 2: «разделим потом».

Это создаёт долг, который повлияет на все домены через схему БД.

Открытые развилки фиксируются явно​

Если в документе обнаружено решение, требующее долгого исследования или эскалации, оно не превращается в заглушку. Оно фиксируется как открытая развилка в специальном разделе документа («Открытые вопросы», «Развилки требующие решения») и эскалируется владельцу платформы.

Развилка — это признание неопределённости. Заглушка — это спрятанная неопределённость. Первое допустимо, второе запрещено.

Исключения через явное тезисное обоснование​

Временное решение может быть допущено только если выполнены все пять пунктов:

  1. В документе явно написано, что это временное решение.
  2. Указана причина (тезисы), почему оно введено.
  3. Указан конкретный триггер, при котором оно убирается.
  4. Указан план миграции на зрелое решение.
  5. Создан follow-up task в системе (или явная отметка в документе для будущей итерации).

Без этих 5 пунктов временное решение не может быть зафиксировано в документе.

Принципы развития vs деградации​

Развитие​

  • Каноничная модель проектируется так, чтобы любое расширение шло через добавление, не через переписывание.
  • Surface contracts проектируются так, чтобы новые fields были additive, не breaking.
  • Storage layer проектируется так, чтобы добавление storage class было операционным, не архитектурным.
  • Eventing проектируется так, чтобы новые event families не ломали consumers.
  • Tenancy проектируется так, чтобы добавление нового tenant tier было configuration change, не code change.

Деградация​

  • «Сейчас одна модель, потом разделим».
  • «Сейчас один surface, потом добавим нюансы».
  • «Сейчас один storage, потом разнесём».
  • «Сейчас события одной формы, потом усилим».
  • «Сейчас один tenant tier, потом сделаем enterprise».

Если в документе появляется одна из формулировок «деградации» — он не готов.

Как применять при написании документа​

Перед публикацией каждого документа задаю вопросы:

  1. Содержит ли документ упрощения, которые потом будут переписаны?
  2. Если содержит — есть ли явный план миграции и триггер?
  3. Нет ли заглушек, hardcode, captive integrations?
  4. Является ли документ описанием зрелого решения, реализуемого по фазам, или это MVP-документация?
  5. Если решение частичное — где зафиксированы открытые развилки и эскалация?

Документ, описывающий MVP без явной финальной архитектуры — переписывается.

Что это означает для существующих документов​

При ревью существующих документов нахожу:

  • Любые формулировки «MVP scope» / «pilot phase» / «временное решение без плана миграции» — переформулирую.
  • Заглушки в схеме данных (если есть) — фиксирую как технический долг слоя приёма данных, не как архитектуру.
  • Захватная логика (captive logic) для конкретного поставщика — переношу в supplier capability matrix.

Действия делаю в рамках полномочий главного архитектора, кроме случаев, когда переписывание затрагивает уже зафиксированную несущую логику (см. CLAUDE.md §0).

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