# Модель stage delivery и release handoff

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

- Статус документа: working reference
- Актуально на: 1 апреля 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при изменении stage release workflow, ownership-модели или границы между текущим сервером и stage-контуром
- Область применения: каноническая модель передачи backend/frontend изменений в `main` и их автоматического развёртывания на отдельном stage-сервере
- Связанные документы:
  - [Runbook эксплуатации и деплоя](./deployment-runbook.md)
  - [Памятка для frontend-команды](../frontend/frontend-handoff.md)
  - [Стандарт change package](../governance/change-package-standard.md)
  - [Текущее состояние](../project/current-state.md)

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

Этот документ фиксирует простую и недвусмысленную 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/frontend-change-log.md), если пакет влияет на frontend;
- обновлять [execution-checkpoints.md](../project/execution-checkpoints.md) и [project-change-log.md](../project/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-сервере.