spec: define containerized application delivery #10

openspec/changes/containerized-application-delivery/specs/application-delivery/spec.md

@@ -0,0 +1,105 @@
+## Purpose
+
+Определяет поддерживаемые эксплуатационные свойства локального и серверного
+запуска WealthLedger, включая поставку компонентов и сохранность состояния.
+
+## ADDED Requirements
+
+### Requirement: Локальная среда воспроизводит границы поставленного приложения
+
+Поддерживаемый локальный запуск SHALL предоставлять один browser origin для
+интерфейса и API WealthLedger. Разработка интерфейса MUST сохранять быстрый
+цикл обратной связи при изменении исходного кода, а разработка API MUST
+перезапускать затронутый runtime без ручной пересборки всей среды. Локальные
+данные MUST быть изолированы от server data.
+
+#### Scenario: Разработчик открывает локальное приложение
+
+- **WHEN** поддерживаемая локальная среда успешно запущена
+- **THEN** браузер получает интерфейс и обращается к API через тот же origin,
+  не зная внутреннего адреса API
+
+#### Scenario: Разработчик меняет интерфейс
+
+- **WHEN** разработчик изменяет исходный код интерфейса в запущенной локальной
+  среде
+- **THEN** браузер получает изменение без ручной полной пересборки среды
+
+### Requirement: Серверное приложение имеет одну внешнюю точку входа
+
+Поддерживаемый server deployment SHALL принимать HTTP-трафик WealthLedger на
+одной внешней точке входа. Через неё MUST быть доступны интерфейс и API с
+сохранением их действующих путей и session semantics. API и хранилище данных
+MUST NOT требовать отдельного внешнего сетевого доступа.
+
+#### Scenario: Внешний reverse proxy направляет запрос приложению
+
+- **WHEN** server reverse proxy передаёт запрос на единственную точку входа
+  WealthLedger
+- **THEN** пользователь получает интерфейс, а запросы к действующему API
+  обрабатываются приложением без отдельного маршрута reverse proxy к API
+
+### Requirement: Поставка допускает независимое обновление компонентов
+
+Система SHALL предоставлять versioned delivery artifacts для интерфейса и API
+как независимых компонентов. Оператор MUST иметь возможность установить
+выбранную версию только одного компонента, сохранив другой компонент и
+постоянное пользовательское состояние работающими. Поддерживаемая поставка
+MUST явно фиксировать выбранные версии обоих компонентов.
+
+#### Scenario: Обновляется только интерфейс
+
+- **WHEN** оператор устанавливает новую версию интерфейса при неизменной
+  совместимой версии API
+- **THEN** API и его постоянное состояние не пересоздаются, а приложение
+  начинает отдавать новую версию интерфейса
+
+#### Scenario: Обновляется только API
+
+- **WHEN** оператор устанавливает новую версию API при неизменной совместимой
+  версии интерфейса
+- **THEN** интерфейс не пересоздаётся, а приложение начинает обрабатывать
+  запросы новой версией API после её готовности
+
+### Requirement: Постоянное состояние и секреты переживают штатный lifecycle
+
+Пользовательские данные, session state и ключи, необходимые для чтения
+зашифрованных подключений, MUST сохраняться при штатных перезапусках и
+обновлениях компонентов. Секреты MUST задаваться отдельно от versioned delivery
+artifacts и MUST NOT попадать в интерфейс, журналы или публичный HTTP-ответ.
+
+#### Scenario: Приложение штатно перезапускается
+
+- **WHEN** оператор штатно перезапускает приложение без восстановления данных
+- **THEN** после запуска доступны прежние пользовательские данные и действующие
+  session semantics, а сохранённые зашифрованные подключения остаются читаемыми
+  тем же ключом
+
+### Requirement: Обновление API сохраняет целостность данных
+
+Перед тем как новая версия API начинает принимать запросы, необходимые
+изменения схемы постоянных данных MUST быть применены успешно. При ошибке
+изменения данных новая версия API MUST NOT объявляться готовой. Краткий простой
+обновляемого компонента допустим; непрерывность обслуживания и несколько
+одновременных экземпляров API не являются обещанием этой capability.
+
+#### Scenario: Подготовка данных новой версии не прошла
+
+- **WHEN** обязательное изменение постоянных данных завершается ошибкой
+- **THEN** новая версия API не начинает обслуживать запросы, а оператор получает
+  диагностируемый неуспешный результат обновления
+
+### Requirement: Восстановление не выдаёт откат приложения за откат данных
+
+Поддерживаемая процедура обновления и восстановления MUST различать возврат
+версии компонентов и восстановление пользовательских данных. Она MUST требовать
+согласованную резервную копию перед изменением постоянных данных и MUST NOT
+заменять более новые пользовательские данные прежней копией как побочный эффект
+возврата версии приложения.
+
+#### Scenario: Оператор возвращает предыдущую версию API
+
+- **WHEN** оператор возвращает прежнюю версию API после неуспешного обновления
+- **THEN** процедура явно проверяет совместимость этой версии с текущими
+  данными и не выполняет восстановление старой копии данных без отдельного
+  решения оператора