# OpenAPI contract flow

## Назначение

Backend остаётся источником HTTP-контракта и формирует OpenAPI из публичного
API. Frontend принимает предоставленный `openapi.json` как актуальный вход,
хранит его snapshot и генерирует из него transport types локально. Причины
выбора backend-generated контракта описаны в
[ADR 002](../adr/002-nest-generated-openapi-contract.md), отказ от frontend
проверки backend runtime-схемы — в [ADR 014](../adr/014-trusted-openapi-input.md).

Frontend не проверяет, что переданный snapshot совпадает с текущим backend
runtime OpenAPI, не фиксирует пару frontend/backend SHA и не зависит от пути к
соседнему backend checkout. Подготовка и доставка актуального OpenAPI-документа
находятся вне frontend.

## Выбор и направление изменения

Изменением контракта считается изменение маршрута, входного или выходного поля,
статуса либо формы ошибки. Внутреннее изменение представления без изменения
API не требует нового описания контракта.

Направление согласования: публичный API backend → предоставленный OpenAPI →
frontend snapshot → generated types. Две независимо редактируемые версии
контракта создавали бы риск расхождения. Перед изменением, влияющим на
совместимость, учитываются существующие потребители и сохранность данных.
Семантика запросов и ошибок описана в [HTTP API](../architecture/http-api.md).

## Границы и результат

Frontend-команда генерации читает только committed snapshot и обновляет
generated types. Frontend-проверка генерирует types из этого snapshot во
временный каталог и сравнивает результат с committed generated artifact.
Несовпадение означает, что snapshot и generated types в frontend расходятся.

Эта проверка не доказывает актуальность snapshot относительно backend. Это
принятое допущение, а не свойство frontend gate. Она также не доказывает
фактическую работу валидации, авторизации, статусов, cookie и обработки ошибок:
для этого нужны наблюдения полного HTTP-потока.

## Граница runtime

Работающий frontend использует сгенерированные types и обычные HTTP-запросы к
API. Swagger или OpenAPI endpoint не являются runtime-зависимостью SPA.
Полные HTTP-сценарии и хранение данных проверяются отдельными backend-gates;
локальный frontend gate выполняется без backend.