# api-contract-generation Specification

## Purpose

Определяет направление HTTP API contract между backend и frontend, исключающее
ручное расхождение frontend snapshot и generated types.

## Requirements

### Requirement: Backend публикует машиночитаемый API-контракт
Backend SHALL публиковать версионированный OpenAPI-документ, описывающий доступные HTTP-маршруты, параметры, тела запросов, ответы и ошибки API `/api/v1`.

#### Scenario: Разработчик получает контракт API
- **WHEN** backend запущен в локальной среде разработки
- **THEN** разработчик может получить OpenAPI-документ для генерации frontend-клиента

### Requirement: Frontend использует предоставленный OpenAPI snapshot
Frontend SHALL хранить в репозитории версионируемый snapshot предоставленного
актуального OpenAPI-документа и генерировать transport types из этого snapshot.
Команда генерации MUST читать frontend snapshot и обновлять сгенерированный
результат. Она MUST NOT читать файлы соседнего backend checkout, запускать
backend scripts или проверять backend runtime OpenAPI. Сгенерированный результат
MUST храниться в frontend-репозитории.

#### Scenario: Types генерируются из предоставленного snapshot
- **WHEN** разработчик запускает frontend-команду генерации
- **THEN** frontend обновляет generated transport types из versioned snapshot

#### Scenario: API-контракт изменяется
- **WHEN** backend меняет опубликованный API-контракт и frontend получает новый snapshot
- **THEN** frontend может повторно сгенерировать transport types до интеграции изменения

### Requirement: Frontend не зависит от OpenAPI во время работы
Работающий frontend MUST использовать ранее сгенерированные transport types и
MUST NOT требовать доступность Swagger или OpenAPI endpoint во время запуска,
выполнения пользовательского сценария, генерации types или локальной проверки
актуальности generated artifact.

#### Scenario: OpenAPI endpoint недоступен после сборки frontend
- **WHEN** frontend уже собран, а endpoint OpenAPI временно недоступен
- **THEN** frontend продолжает использовать сгенерированный код для запросов к API

#### Scenario: Локальная проверка выполняется без backend
- **WHEN** разработчик запускает локальный frontend quality gate
- **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** проверка контракта завершается с ошибкой