Модель stage delivery и release handoff

Паспорт документа

• Статус документа: working reference
• Актуально на: 1 апреля 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении stage release workflow, ownership-модели или границы между текущим сервером и stage-контуром
• Область применения: каноническая модель передачи backend/frontend изменений в main и их автоматического развёртывания на отдельном stage-сервере
• Связанные документы:
  • Runbook эксплуатации и деплоя
  • Памятка для frontend-команды
  • Стандарт change package
  • Текущее состояние

Цель документа

Этот документ фиксирует простую и недвусмысленную release-модель проекта:

• текущая машина используется для разработки, исправлений, документирования и локальных инженерных проверок;
• отдельный stage-сервер отвечает за сборку/развёртывание UI-проверочного контура;
• релизным действием считается не ручной деплой с этой машины, а попадание согласованного change package в main.

1. Канонический процесс

Правильная модель сейчас такая:

1. backend/platform-команда готовит change package в qadam-core;
2. frontend-команда готовит свой change package в qadam-web;
3. backend фиксирует frontend-impact в frontend-change-log.md;
4. frontend-команда подтверждает готовность или закрывает свой remediation scope;
5. обе стороны мержат согласованные изменения в main;
6. отдельный stage-сервер автоматически забирает main и разворачивает актуальное состояние проекта;
7. UI и интеграция проверяются уже на stage-сервере, а не на этой машине.

2. Что это означает для текущего сервера

На текущем сервере:

• можно разрабатывать backend и documentation packages;
• можно собирать инженерный контекст, прогонять тесты, чинить код и синхронизировать контракты;
• нельзя считать локальный ручной deploy обязательной частью каждого change package;
• нельзя считать этот сервер каноническим stage-контуром для frontend-проверок.

Если нужен UI-проверочный результат, источником истины становится отдельный stage-сервер после merge в main.

3. Что считается release-событием

Для проекта release-событием сейчас считается:

• merge change package в main репозитория qadam-core, если пакет backend/platform-значимый;
• merge change package в main репозитория qadam-web, если пакет frontend-значимый;
• завершённый handoff между командами, если пакет требует согласованного внедрения с обеих сторон.

Сам по себе локальный commit не считается release.

Сам по себе локальный docker build, systemctl restart или ручной smoke на этой машине не считается релизом stage-контура.

4. Роль backend-команды в этой модели

Backend/platform-команда обязана:

• доводить change package до merge-ready состояния;
• обновлять OpenAPI, если меняется контракт;
• обновлять frontend-change-log.md, если пакет влияет на frontend;
• обновлять execution-checkpoints.md и project-change-log.md;
• не передавать изменения frontend-команде только устно.

Backend/platform-команда не обязана вручную выкатывать каждый пакет на stage с текущей машины, если stage разворачивается внешним автоматическим контуром.

5. Роль frontend-команды в этой модели

Frontend-команда обязана:

• брать в работу только опубликованные и зафиксированные backend handoff-пакеты;
• использовать frontend-change-log.md и frontend-adoption-backlog.md как рабочий контур;
• подтверждать статус на qadam-roadmap.2fab.app, если пакет появился как ready_for_frontend;
• мержить готовый пакет в main, если он согласован по UX и контракту.

6. Граница между текущим сервером и stage-сервером

Текущий сервер:

• development/control plane;
• документация;
• локальные проверки;
• backend/platform runtime и production-история, описанная в deployment-runbook.md.

Stage-сервер:

• UI-проверочный контур;
• автоматический deploy из main;
• место, где подтверждается согласованная работа frontend и backend в браузере.

Важно: этот документ не описывает внутреннюю реализацию stage pipeline. Он фиксирует только каноническое правило взаимодействия команд и то, что stage deploy уже живёт вне текущей машины.

7. Что запрещено

• считать ручной деплой с текущего сервера обязательным release-этапом, если речь идёт о stage-проверке;
• утверждать, что staging обновится от feature-ветки, если release-модель завязана на main;
• считать backend-пакет завершённым для frontend без записи в frontend-change-log.md;
• передавать задачу на frontend словами вместо changelog/checkpoint/handoff-контура.

8. Короткий operational вывод

Локально мы:

• чиним;
• добавляем фичи;
• синхронизируем документацию и контракты;
• доводим пакет до merge-ready состояния.

Релизно мы:

• мержим в main;
• даём внешнему stage-контуру автоматически развернуть актуальный backend и frontend;
• проверяем интеграцию уже на stage-сервере.