add: refactor foundation

openspec/specs/api-contract-generation/spec.md

@@ -14,15 +14,38 @@ Backend SHALL публиковать версионированный OpenAPI-д
 - **THEN** разработчик может получить OpenAPI-документ для генерации frontend-клиента
 
 ### Requirement: Frontend использует сгенерированный API-клиент
-Frontend SHALL генерировать типы и модуль HTTP-запросов из опубликованного OpenAPI-документа. Сгенерированный результат MUST храниться в frontend-репозитории и обновляться локальной воспроизводимой командой.
+Frontend SHALL хранить в репозитории версионируемый snapshot опубликованного OpenAPI-документа и генерировать transport types из этого snapshot. Команда синхронизации MUST получать документ из backend, а затем обновлять snapshot и сгенерированный результат только при успешном завершении всего процесса. Сгенерированный результат MUST храниться в frontend-репозитории.
+
+#### Scenario: API-контракт синхронизируется
+- **WHEN** разработчик запускает команду синхронизации при доступном backend с валидным OpenAPI-документом
+- **THEN** frontend обновляет versioned snapshot и сгенерированные transport types из опубликованного контракта
 
 #### Scenario: API-контракт изменяется
 - **WHEN** backend меняет опубликованный API-контракт
-- **THEN** frontend может повторно сгенерировать типы и запросный модуль до интеграции изменения
+- **THEN** frontend может синхронизировать snapshot и повторно сгенерировать transport types до интеграции изменения
+
+#### Scenario: Синхронизация контракта завершается ошибкой
+- **WHEN** backend недоступен или публикует невалидный OpenAPI-документ
+- **THEN** команда завершается с ошибкой и существующие snapshot и сгенерированные transport types не изменяются
 
 ### Requirement: Frontend не зависит от OpenAPI во время работы
-Работающий frontend MUST использовать ранее сгенерированный клиент и MUST NOT требовать доступность Swagger или OpenAPI endpoint во время запуска или выполнения пользовательского сценария.
+Работающий frontend MUST использовать ранее сгенерированные transport types и MUST NOT требовать доступность Swagger или OpenAPI endpoint во время запуска, выполнения пользовательского сценария или локальной проверки актуальности generated artifact. Доступ к backend OpenAPI endpoint разрешён только команде синхронизации snapshot.
 
 #### Scenario: OpenAPI endpoint недоступен после сборки frontend
 - **WHEN** frontend уже собран, а endpoint OpenAPI временно недоступен
 - **THEN** frontend продолжает использовать сгенерированный код для запросов к API
+
+#### Scenario: Локальная проверка выполняется без backend
+- **WHEN** разработчик запускает локальный quality gate без доступного backend
+- **THEN** проверка актуальности generated artifact использует сохранённый snapshot и не обращается к OpenAPI endpoint
+
+### Requirement: Frontend обнаруживает дрейф сгенерированного контракта
+Frontend SHALL проверять, что committed generated transport types соответствуют versioned OpenAPI snapshot, и MUST завершать quality gate с ошибкой при расхождении.
+
+#### Scenario: Generated artifact устарел
+- **WHEN** OpenAPI snapshot изменён, а generated transport types не обновлены
+- **THEN** проверка контракта завершается с ошибкой
+
+#### Scenario: Generated artifact изменён вручную
+- **WHEN** generated transport types отличаются от результата генерации из сохранённого snapshot
+- **THEN** проверка контракта завершается с ошибкой