docs(specs): remove runtime OpenAPI gate

This commit is contained in:
2026-09-13 19:08:13 +03:00
parent 9590dedc01
commit 05e314cebb
5 changed files with 23 additions and 50 deletions
+2 -1
View File
@@ -7,7 +7,8 @@
Если нужна существующая behavioral spec, выбери точный target через Если нужна существующая behavioral spec, выбери точный target через
[AI_INDEX](AI_INDEX.md). Specs не являются вторым editable HTTP OpenAPI: [AI_INDEX](AI_INDEX.md). Specs не являются вторым editable HTTP OpenAPI:
его authority — backend runtime document; workflow находится в backend публикует контракт, а frontend доверяет предоставленному snapshot и
локально проверяет generated types; flow описан в
[docs](../docs/development/runtime-openapi-verification.md). [docs](../docs/development/runtime-openapi-verification.md).
Архивы и чужие active changes сохраняй. Для правки индекса проверь targets, Архивы и чужие active changes сохраняй. Для правки индекса проверь targets,
+3 -2
View File
@@ -7,8 +7,9 @@ As-built факты и принятие решений — через [docs inde
При конфликте с текущим поведением установи расхождение; не копируй устаревшее При конфликте с текущим поведением установи расхождение; не копируй устаревшее
правило или случайный код молча. правило или случайный код молча.
HTTP OpenAPI имеет единственный editable source в backend, а не здесь: HTTP OpenAPI имеет единственный editable source в backend, а не здесь.
[contract workflow](../docs/development/runtime-openapi-verification.md). Frontend доверяет предоставленному snapshot и локально проверяет generated
types: [OpenAPI contract flow](../docs/development/runtime-openapi-verification.md).
| Тема / trigger | Existing spec | | Тема / trigger | Existing spec |
| --- | --- | | --- | --- |
@@ -106,8 +106,6 @@ artifacts:
- **Delivery Map**: ровно `frontend`, `backend`, `specs`, `docs`; каждая - **Delivery Map**: ровно `frontend`, `backend`, `specs`, `docs`; каждая
area имеет `affected` outcome или конкретный `N/A` reason. `specs` всегда area имеет `affected` outcome или конкретный `N/A` reason. `specs` всегда
`affected`. `affected`.
- **Contract Gate Decision**: `runtime-openapi` = `required`, только когда
меняются обе стороны API contract; иначе конкретный `N/A`.
- **Risks / Trade-offs** и **Migration Plan**. - **Risks / Trade-offs** и **Migration Plan**.
- В Migration Plan — `### Rollback Contract`: `required` с Trigger, - В Migration Plan — `### Rollback Contract`: `required` с Trigger,
Actions, Data safety, Verification для auth/security, data integrity/ Actions, Data safety, Verification для auth/security, data integrity/
@@ -56,12 +56,6 @@
| specs | `affected` | <!-- normative result --> | | specs | `affected` | <!-- normative result --> |
| docs | `affected` or `N/A` | <!-- as-built documentation result or reason --> | | 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 ## Solution Assessment
<!-- Include only when the change crosses a mandatory build-vs-buy trigger. <!-- Include only when the change crosses a mandatory build-vs-buy trigger.
+18 -39
View File
@@ -2,7 +2,8 @@
## Purpose ## Purpose
Определяет единый, проверяемый контракт HTTP API между backend и frontend, исключающий ручное расхождение типов и маршрутов. Определяет направление HTTP API contract между backend и frontend, исключающее
ручное расхождение frontend snapshot и generated types.
## Requirements ## Requirements
@@ -13,23 +14,27 @@ Backend SHALL публиковать версионированный OpenAPI-д
- **WHEN** backend запущен в локальной среде разработки - **WHEN** backend запущен в локальной среде разработки
- **THEN** разработчик может получить OpenAPI-документ для генерации frontend-клиента - **THEN** разработчик может получить OpenAPI-документ для генерации frontend-клиента
### Requirement: Frontend использует сгенерированный API-клиент ### Requirement: Frontend использует предоставленный OpenAPI snapshot
Frontend SHALL хранить в репозитории версионируемый snapshot опубликованного OpenAPI-документа и генерировать transport types из этого snapshot. Команда синхронизации MUST получать документ из backend, а затем обновлять snapshot и сгенерированный результат только при успешном завершении всего процесса. Сгенерированный результат MUST храниться в frontend-репозитории. Frontend SHALL хранить в репозитории версионируемый snapshot предоставленного
актуального OpenAPI-документа и генерировать transport types из этого snapshot.
Команда генерации MUST читать frontend snapshot и обновлять сгенерированный
результат. Она MUST NOT читать файлы соседнего backend checkout, запускать
backend scripts или проверять backend runtime OpenAPI. Сгенерированный результат
MUST храниться в frontend-репозитории.
#### Scenario: API-контракт синхронизируется #### Scenario: Types генерируются из предоставленного snapshot
- **WHEN** разработчик запускает команду синхронизации при доступном backend с валидным OpenAPI-документом - **WHEN** разработчик запускает frontend-команду генерации
- **THEN** frontend обновляет versioned snapshot и сгенерированные transport types из опубликованного контракта - **THEN** frontend обновляет generated transport types из versioned snapshot
#### Scenario: API-контракт изменяется #### Scenario: API-контракт изменяется
- **WHEN** backend меняет опубликованный API-контракт - **WHEN** backend меняет опубликованный API-контракт и frontend получает новый snapshot
- **THEN** frontend может синхронизировать snapshot и повторно сгенерировать transport types до интеграции изменения - **THEN** frontend может повторно сгенерировать transport types до интеграции изменения
#### Scenario: Синхронизация контракта завершается ошибкой
- **WHEN** backend недоступен или публикует невалидный OpenAPI-документ
- **THEN** команда завершается с ошибкой и существующие snapshot и сгенерированные transport types не изменяются
### Requirement: Frontend не зависит от OpenAPI во время работы ### 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 #### Scenario: OpenAPI endpoint недоступен после сборки frontend
- **WHEN** frontend уже собран, а endpoint OpenAPI временно недоступен - **WHEN** frontend уже собран, а endpoint OpenAPI временно недоступен
@@ -39,32 +44,6 @@ Frontend SHALL хранить в репозитории версионируем
- **WHEN** разработчик запускает локальный frontend quality gate - **WHEN** разработчик запускает локальный frontend quality gate
- **THEN** проверка актуальности generated artifact использует сохранённый snapshot и не обращается к OpenAPI endpoint - **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 обнаруживает дрейф сгенерированного контракта ### Requirement: Frontend обнаруживает дрейф сгенерированного контракта
Frontend SHALL проверять, что committed generated transport types соответствуют versioned OpenAPI snapshot, и MUST завершать quality gate с ошибкой при расхождении. Frontend SHALL проверять, что committed generated transport types соответствуют versioned OpenAPI snapshot, и MUST завершать quality gate с ошибкой при расхождении.