# Проверка runtime OpenAPI

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

`npm run test:openapi-contract` в `backend/` строит configured Nest application,
создаёт runtime OpenAPI document и сверяет его с committed snapshot
`frontend/src/shared/api/spec/openapi.json` после детерминированной canonicalization.

Это отдельный контрактный gate, а не общий verifier всех репозиториев. Он обязателен перед завершением задачи, меняющей
backend API или frontend transport contract и не заменяет
локальные lint/typecheck команды приложений.

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

1. Определите, меняется wire contract (route, request/response field, status, error shape) или только внутренний код/UI model. Во втором случае snapshot не меняется.
2. Прочитайте [HTTP semantics](../architecture/http-api.md) и нужный feature/domain source. Backend Nest controllers/DTO/Swagger metadata — единственный editable источник OpenAPI; specs repo не является вторым OpenAPI source.
3. Измените этот source и проверьте representative HTTP behavior. При изменении контракта скопируйте generated runtime OpenAPI в committed frontend snapshot, затем в frontend выполните `npm run openapi:generate`.
4. Выполните frontend `npm run openapi:check` и backend `npm run test:openapi-contract`, а также verify affected repos. Эти команды проверяют разное: schema parity не доказывает validation/auth/error behavior.

Generated frontend TS и backend Prisma client вручную не редактируются.
Frontend domain/UI type допустим, когда он отличается от transport DTO по смыслу.
Перед compatibility-sensitive изменением оцените существующих consumers и
rollback/data constraints; одного обновления snapshot недостаточно.

## Запуск

Из корня workspace:

```bash
cd backend
nvm use --silent
npm run test:openapi-contract
```

Перед первым запуском в backend выполняют `npm ci` под Node 22.

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

Команда:

- использует configured Nest application на integration boundary;
- рекурсивно сортирует только ключи JSON objects и сохраняет порядок arrays;
- не записывает snapshot или generated frontend types.

Она не записывает committed snapshot или generated frontend types и не
обращается к T-Bank либо другому внешнему сервису. Если контракт действительно
изменён, snapshot обновляют явным копированием backend OpenAPI document в
`frontend/src/shared/api/spec/openapi.json`, затем в `frontend` запускают
`npm run openapi:generate` и снова выполняют эту проверку.

## Ограничение e2e

Проверка Swagger не запускает backend e2e tests. WL-P2-05 (runnable e2e) и
WL-P2-13 (единый workspace verdict) отложены из-за нестабильного Prisma 7.9.1
migration gate; дата, rationale и trigger пересмотра находятся в
[audit remediation registry](audit-remediation.md).