docs(specs): remove runtime OpenAPI gate

2026-09-13 19:08:13 +03:00
parent 9590dedc01
commit 05e314cebb
5 changed files with 23 additions and 50 deletions
@@ -106,8 +106,6 @@ artifacts:
      - **Delivery Map**: ровно `frontend`, `backend`, `specs`, `docs`; каждая
        area имеет `affected` outcome или конкретный `N/A` reason. `specs` всегда
        `affected`.
-      - **Contract Gate Decision**: `runtime-openapi` = `required`, только когда
-        меняются обе стороны API contract; иначе конкретный `N/A`.
      - **Risks / Trade-offs** и **Migration Plan**.
      - В Migration Plan — `### Rollback Contract`: `required` с Trigger,
        Actions, Data safety, Verification для auth/security, data integrity/
@@ -56,12 +56,6 @@
 | specs | `affected` | <!-- normative result --> |
 | docs | `affected` or `N/A` | <!-- as-built documentation result or reason --> |

-### Contract Gate Decision
-
-| Gate | Status | Reason |
-| --- | --- | --- |
-| runtime-openapi | `required` or `N/A` | <!-- required only when both API contract sides change; otherwise concrete N/A reason --> |
-
 ## Solution Assessment

 <!-- Include only when the change crosses a mandatory build-vs-buy trigger.
@@ -2,7 +2,8 @@

 ## Purpose

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

 ## Requirements

@@ -13,23 +14,27 @@ Backend SHALL публиковать версионированный OpenAPI-д
 - **WHEN** backend запущен в локальной среде разработки
 - **THEN** разработчик может получить OpenAPI-документ для генерации frontend-клиента

-### Requirement: Frontend использует сгенерированный API-клиент
-Frontend SHALL хранить в репозитории версионируемый snapshot опубликованного OpenAPI-документа и генерировать transport types из этого snapshot. Команда синхронизации MUST получать документ из backend, а затем обновлять snapshot и сгенерированный результат только при успешном завершении всего процесса. Сгенерированный результат MUST храниться в 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: API-контракт синхронизируется
- **WHEN** разработчик запускает команду синхронизации при доступном backend с валидным OpenAPI-документом
- **THEN** frontend обновляет versioned snapshot и сгенерированные transport types из опубликованного контракта
+#### Scenario: Types генерируются из предоставленного snapshot
+- **WHEN** разработчик запускает frontend-команду генерации
+- **THEN** frontend обновляет generated transport types из versioned snapshot

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

 ### Requirement: Frontend не зависит от OpenAPI во время работы
-Работающий frontend MUST использовать ранее сгенерированные transport types и MUST NOT требовать доступность Swagger или OpenAPI endpoint во время запуска, выполнения пользовательского сценария или локальной проверки актуальности generated artifact. Доступ к backend OpenAPI endpoint разрешён только команде синхронизации snapshot и отдельной read-only runtime-contract command.
+Работающий frontend MUST использовать ранее сгенерированные transport types и
+MUST NOT требовать доступность Swagger или OpenAPI endpoint во время запуска,
+выполнения пользовательского сценария, генерации types или локальной проверки
+актуальности generated artifact.

 #### Scenario: OpenAPI endpoint недоступен после сборки frontend
 - **WHEN** frontend уже собран, а endpoint OpenAPI временно недоступен
@@ -39,32 +44,6 @@ Frontend SHALL хранить в репозитории версионируем
 - **WHEN** разработчик запускает локальный frontend quality gate
 - **THEN** проверка актуальности generated artifact использует сохранённый snapshot и не обращается к OpenAPI endpoint

-#### Scenario: Разработчик проверяет runtime-контракт
- **WHEN** разработчик запускает отдельную runtime-contract command
- **THEN** command может поднять изолированный local backend только для сравнения
-  его полного runtime OpenAPI document с committed frontend snapshot и не
-  обновляет ни один из артефактов
-
-### Requirement: Отдельная команда обнаруживает runtime drift OpenAPI
-Runtime-contract command MUST получать полный OpenAPI document от изолированного
-local backend по `/api/docs-json`, рекурсивно canonicalize порядок JSON object
-keys, сохраняя каждое field и array order, и сравнивать его SHA-256 с canonical
-committed frontend snapshot. При любом content mismatch она MUST завершаться
-ошибкой и показывать diff. Verification MUST NOT вызывать snapshot
-synchronization command или записывать committed OpenAPI либо generated type
-artifacts.
-
-#### Scenario: Runtime success status отличается от committed snapshot
- **WHEN** backend runtime OpenAPI описывает response status, отличный от
-  committed frontend snapshot
- **THEN** runtime-contract command завершается ошибкой с diff и оставляет
-  snapshot и generated types без изменений
-
-#### Scenario: Runtime OpenAPI совпадает с committed snapshot
- **WHEN** каждое field canonical runtime document совпадает с canonical
-  committed frontend snapshot
- **THEN** runtime-contract stage завершается успешно без изменения frontend files
-
 ### Requirement: Frontend обнаруживает дрейф сгенерированного контракта
 Frontend SHALL проверять, что committed generated transport types соответствуют versioned OpenAPI snapshot, и MUST завершать quality gate с ошибкой при расхождении.