docs: simplify system documentation
Docs security / security (push) Successful in 7s
Docs verify / verify (push) Successful in 9s

This commit is contained in:
2026-09-14 05:51:29 +03:00
parent 67f152d365
commit 9b19a5cf4d
30 changed files with 104 additions and 2445 deletions
+14 -26
View File
@@ -1,39 +1,27 @@
# 014. Актуальная OpenAPI-схема как вход frontend
**Статус:** принято 2026-09-13; docs, specs и frontend-инструкции приведены
к решению. Настройка remote issues и branch protection выполняется отдельно.
**Статус:** принято 2026-09-13.
## Контекст
Frontend и backend — независимые репозитории. Знание путей и команд backend
в frontend связывает их внутреннее устройство. Для текущего процесса разработки
владелец проекта принимает актуальность переданной OpenAPI-схемы как допущение;
проверка пары revisions и дополнительное сравнение схем не требуются.
Frontend и backend — независимые репозитории. Зависимость frontend от путей
и команд backend связывала бы их внутреннее устройство. Предоставленная
OpenAPI-схема служит границей между владельцем API и его потребителем.
## Решение
Backend остаётся источником HTTP-контракта согласно [ADR 002](002-nest-generated-openapi-contract.md).
Backend остаётся источником HTTP-контракта согласно
[ADR 002](002-nest-generated-openapi-contract.md).
Frontend принимает предоставленную OpenAPI-схему как актуальную и генерирует
из неё типы локально. Его команды не читают файлы соседнего backend checkout
и не запускают backend-скрипты. Подготовка и доставка схемы находятся вне frontend.
Не требуется фиксировать пару SHA frontend/backend или сравнивать frontend-схему
с runtime OpenAPI backend. Локальная проверка соответствия generated types
входной схеме сохраняется: она не проверяет актуальность схемы относительно backend.
Обычные CI checks по-прежнему должны проверять текущий commit изменения.
из неё типы локально, без доступа к соседнему backend checkout.
Подготовка и доставка схемы находятся вне frontend.
## Последствия
Задача frontend #3 ограничивается локальной генерацией из предоставленной схемы;
экспорт backend не становится обязанностью frontend. Из frontend #2 исключается
требование проверки явно выбранной пары revisions. Требования безопасности
frontend #4 этим решением не меняются.
Frontend зависит от публичного контракта, а не от внутреннего устройства
backend. Соответствие типов входной схеме не гарантирует её актуальность:
рассинхронизацию предоставленной схемы и работающего API frontend не выявляет
сравнением схем. Актуальность входа остаётся принятым допущением.
OpenAPI endpoint не является runtime-зависимостью SPA.
Рассинхронизацию предоставленной схемы и backend отдельный gate не обнаруживает:
её отсутствие принято как допущение. Тесты HTTP-поведения, валидации и авторизации
остаются нужны.
Решение заменяет прежнее требование сравнения runtime OpenAPI с frontend
snapshot в [OpenAPI contract flow](../development/runtime-openapi-verification.md)
и [спецификации генерации API](../../specs/openspec/specs/api-contract-generation/spec.md).
Связанные remote issues и настройки защиты ветки требуют отдельного обновления.
Текущее взаимодействие описано в [HTTP API](../architecture/http-api.md).