spec: finalize wealth-ledger SDD migration

openspec/changes/archive/2026-10-09-versioned-deployment-bundle/specs/deployment-bundle/spec.md

@@ -0,0 +1,169 @@
+## Purpose
+
+Определяет установку выбранного релиза WealthLedger одной командой,
+сохранение состояния сервера и безопасный результат успешного или неудачного обновления.
+
+## ADDED Requirements
+
+### Requirement: Релиз определяет полную пару компонентов
+
+Комплект SHALL иметь отдельную неизменяемую версию, однозначно определяющую
+проверенную пару версий интерфейса и API. Оператор MUST явно выбирать релиз
+комплекта. Публикация компонента MUST NOT автоматически выпускать комплект
+или обновлять сервер; локальные настройки MUST NOT незаметно подменять пару.
+
+#### Scenario: Установка выбранного релиза
+
+- **WHEN** оператор выбирает опубликованный релиз комплекта
+- **THEN** устанавливается ровно закреплённая в нём пара, даже если опубликованы
+  более новые версии компонентов
+
+#### Scenario: Отсутствующий или изменённый релиз
+
+- **WHEN** выбранный релиз отсутствует либо ранее полученная версия теперь
+  указывает на другое содержимое
+- **THEN** операция завершается ошибкой до изменения работающей установки
+
+### Requirement: Проверки предшествуют изменению установки
+
+Одна команда SHALL выполнять установку выбранного релиза на подготовленном
+сервере. До остановки приложения она MUST проверить доступность комплекта,
+его компонентов, обязательных настроек и постоянных ресурсов.
+Отсутствующая база существующей установки MUST NOT трактоваться как новая
+пустая установка. Секреты MUST NOT попадать в диагностический вывод.
+
+#### Scenario: Компонент недоступен
+
+- **WHEN** выбранный компонент нельзя получить или обязательный сертификат
+  либо каталог данных недоступен
+- **THEN** обновление завершается с понятной ошибкой, не останавливая
+  работающие компоненты и не создавая замену отсутствующим данным
+
+#### Scenario: Новая установка
+
+- **WHEN** оператор явно подготовил новую установку с отдельным пустым
+  хранилищем и необходимыми настройками
+- **THEN** команда подготавливает данные и запускает выбранный релиз,
+  не требуя предыдущей установленной версии
+
+### Requirement: Существующая установка сохраняет состояние
+
+Подключение существующей установки и последующие обновления MUST сохранять
+её пользовательские данные, сессии, ключи шифрования и настройки доверия
+внешнему провайдеру. Эти ресурсы MUST храниться независимо от обновляемого
+комплекта. Команда MUST NOT запускать второй API на той же базе или генерировать
+новые ключи вместо действующих.
+
+#### Scenario: Переход с прежнего способа запуска
+
+- **WHEN** оператор подключает существующую установку к комплекту
+- **THEN** используются её прежние данные и ключи; после запуска доступны
+  существующие записи и расшифровка сохранённого подключения
+
+### Requirement: Обновление затрагивает только изменённые компоненты
+
+Если меняется только интерфейс, команда MUST сохранять работающий API,
+не изменять данные и не запускать миграции или резервное копирование.
+Изменение настроек API SHALL считаться изменением API, даже при той же версии.
+Обновление только API MUST NOT пересоздавать неизменный интерфейс.
+Повторное применение уже установленного исправного релиза с теми же настройками
+MUST NOT выполнять ненужное обновление или резервное копирование.
+
+#### Scenario: Новый интерфейс при прежнем API
+
+- **WHEN** выбранный релиз меняет только интерфейс, а API и его настройки
+  подтверждённо совпадают с установленными
+- **THEN** обновляется только интерфейс, API продолжает работу без миграций
+  и резервного копирования для этой операции
+
+#### Scenario: Та же версия API с другими настройками
+
+- **WHEN** версия API прежняя, но его настройки изменились
+- **THEN** применяется безопасная процедура обновления API
+
+#### Scenario: Повтор успешно установленного релиза
+
+- **WHEN** выбран уже установленный исправный релиз без изменений настроек
+- **THEN** команда сообщает, что обновление не требуется, без остановки
+  компонентов и без новой резервной копии
+
+### Requirement: Обновление API сохраняет согласованную копию
+
+Перед обновлением API существующей установки команда MUST остановить запись
+и успешно сохранить согласованную копию всех постоянных данных до миграций.
+Копии MUST находиться вне обновляемого комплекта; команда MUST NOT удалять
+или перезаписывать прежние копии автоматически. Неуспешная копия MUST
+блокировать миграции. Новая пустая установка не требует фиктивного backup.
+
+#### Scenario: Подготовка обновления API
+
+- **WHEN** выбран релиз с изменением API существующей установки
+- **THEN** до миграций сохраняется отдельная согласованная копия при отсутствии
+  пишущих процессов, и оператор получает её расположение
+
+#### Scenario: Копию сохранить не удалось
+
+- **WHEN** резервное копирование завершилось ошибкой
+- **THEN** миграции и запуск новой версии не выполняются, существующие данные
+  и прежние копии сохраняются, операция сообщает ошибку
+
+### Requirement: Неудачное обновление не скрывает риск для данных
+
+Ошибка миграции MUST блокировать запуск новой версии API. Если после миграции
+API не готов, команда MUST остановить неисправный API и завершиться с ошибкой.
+Любая неуспешная проверка обновляемого компонента MUST блокировать отметку
+релиза как успешно установленного. Диагностика SHALL указывать этап сбоя,
+предыдущую версию и доступный backup без раскрытия секретов.
+Автоматический откат или восстановление данных MUST NOT выполняться.
+
+#### Scenario: Миграция не прошла
+
+- **WHEN** подготовка схемы завершается ошибкой
+- **THEN** API остаётся остановленным, а результат содержит сведения для
+  отдельного решения о восстановлении
+
+#### Scenario: Новый API не готов
+
+- **WHEN** миграция завершилась успешно, но проверка готовности API не прошла
+- **THEN** неисправный API останавливается без автоматического запуска старой
+  версии или восстановления базы
+
+#### Scenario: Неудачное обновление интерфейса
+
+- **WHEN** при обновлении только интерфейса его проверка запуска не прошла
+- **THEN** операция завершается ошибкой, API продолжает работу, база не
+  восстанавливается, релиз не отмечается успешно установленным
+
+### Requirement: Повтор и конкуренция не нарушают порядок обновления
+
+Команда MUST исключать одновременные изменения одной установки несколькими
+запусками. Прерванное или неуспешное обновление MUST отличаться от успешно
+установленного релиза. Повтор команды после потенциального изменения данных
+MUST NOT скрывать незавершённую операцию или автоматически восстанавливать данные.
+
+#### Scenario: Второе обновление
+
+- **WHEN** для установки уже выполняется обновление
+- **THEN** второй запуск завершается без изменения её состояния
+
+#### Scenario: Процесс прерван после начала обновления
+
+- **WHEN** предыдущая операция прервана после остановки API или начала миграции
+- **THEN** следующий запуск сообщает о незавершённой операции и необходимости
+  проверки состояния до нового обновления
+
+### Requirement: Оператор располагает полным порядком эксплуатации
+
+Инструкция комплекта SHALL описывать последовательность подготовки сервера,
+первой установки и подключения существующей установки, подготовку проверенной
+пары и выпуск релиза, обновление, диагностику, откат версии и отдельное
+восстановление базы. Она MUST указывать сохранение ключей, ручную очистку
+локальных копий и отсутствие защиты от потери диска только локальным backup.
+Восстановление MUST требовать явного выбора копии и принятия потери более
+новых данных; откат API — проверки совместимости с текущей схемой.
+
+#### Scenario: Оператор восстанавливает установку
+
+- **WHEN** оператор использует инструкцию после неудачного обновления
+- **THEN** он может отдельно выбрать совместимую версию приложения или
+  восстановление конкретной копии с явным учётом потери новых данных