docs: document versioned deployment bundle

adr/016-versioned-deployment-bundle.md

@@ -0,0 +1,72 @@
+# 016. Версионируемый комплект развёртывания
+
+**Status:** Accepted
+
+Frontend и backend выпускаются независимо. Выбор их версий непосредственно
+на сервере перекладывает подбор совместимой пары на оператора при каждом
+обновлении. Принято решение выпускать комплект в репозитории `deploy`:
+его релиз закрепляет проверенную пару конкретных версий обоих образов.
+Независимые релизы компонентов сохраняются; выпуск компонента сам по себе
+не означает готовность нового релиза развёртывания.
+
+Оператор подключается к серверу по SSH и одной командой запускает обновление
+до выбранного релиза развёртывания. При обновлении backend команда должна
+скачать образы до его остановки, сохранить резервную копию остановленной базы,
+выполнить миграции и проверить запуск. Ограничения
+[ADR 015](015-single-server-sqlite-deployment.md)
+сохраняются: один backend, краткий простой, неуспешная миграция блокирует запуск;
+откат образа не восстанавливает базу автоматически.
+
+## Доставка и подготовка сервера
+
+На сервере хранится Git checkout `deploy`. Команда обновления получает
+выбранный тег комплекта и загружает закреплённые образы из Nexus;
+сборка приложения на сервере не требуется.
+
+Docker с Compose, внешний HTTPS и доступ к registry считаются подготовленными.
+README комплекта должен описывать последовательность этой разовой подготовки
+и подключения существующей установки. Автоматическое provisioning сервера
+в комплект не входит.
+
+Рабочие данные, сертификат доверия T-Bank и секреты остаются вне обновляемого
+checkout. При подключении существующей установки сохраняются её БД,
+JWT secret и ключ шифрования. Сертификат `certs/tbank-ca.pem` монтируется
+в контейнер только для чтения; путь внутри контейнера задаётся через
+`TBANK_CA_CERT_PATH`. Этот сертификат не обслуживает входящий HTTPS.
+
+## Резервные копии
+
+Перед обновлением backend создаётся согласованная копия всего каталога данных
+при остановленном backend. Копии хранятся в локальном `backups/` вне checkout,
+без автоматического удаления; очистку выполняет оператор вручную.
+Такие копии позволяют восстановиться после неудачного обновления, но сами
+по себе не защищают от потери диска сервера.
+
+## Обновление и сбои
+
+Если релиз меняет только frontend, обновляется только его контейнер:
+backend не останавливается, миграции и резервное копирование БД для этого
+обновления не выполняются. Этот путь применим только при неизменных образе
+и конфигурации backend.
+
+Если миграции прошли, но новый backend не прошёл проверку запуска, обновление
+завершается с ошибкой, неисправный backend останавливается. Оператор получает
+диагностику, сведения о предыдущей версии и путь к резервной копии.
+Автоматического отката нет: прежний образ может быть несовместим с новой
+схемой. Откат образа и восстановление базы остаются отдельными явными действиями
+по правилам ADR 015.
+
+## Выпуск комплекта
+
+После публикации образов компонентов отдельно готовится релиз `deploy`:
+фиксируется совместимая пара версий, выполняется её проверка и выпускается
+тег комплекта. Публикация компонента не создаёт релиз комплекта автоматически
+и не запускает обновление сервера. Оператор выбирает выпущенный тег при
+запуске команды развёртывания.
+
+## Состояние реализации
+
+Комплект и команда реализованы в отдельном репозитории `deploy`.
+Публикация первого тега и обновление рабочего сервера — отдельные действия.
+[Контейнерная поставка](../architecture/deployment.md) описывает границы,
+пошаговая инструкция находится в README комплекта.