docs(specs): archive local verification remediation

This commit is contained in:
2026-08-23 21:21:22 +03:00
parent 51344d4988
commit 72444dbbb1
11 changed files with 441 additions and 4 deletions
+28 -2
View File
@@ -29,16 +29,42 @@ Frontend SHALL хранить в репозитории версионируем
- **THEN** команда завершается с ошибкой и существующие snapshot и сгенерированные transport types не изменяются
### Requirement: Frontend не зависит от OpenAPI во время работы
Работающий frontend MUST использовать ранее сгенерированные transport types и MUST NOT требовать доступность Swagger или OpenAPI endpoint во время запуска, выполнения пользовательского сценария или локальной проверки актуальности generated artifact. Доступ к backend OpenAPI endpoint разрешён только команде синхронизации snapshot.
Работающий frontend MUST использовать ранее сгенерированные transport types и MUST NOT требовать доступность Swagger или OpenAPI endpoint во время запуска, выполнения пользовательского сценария или локальной проверки актуальности generated artifact. Доступ к backend OpenAPI endpoint разрешён только команде синхронизации snapshot и отдельной read-only runtime-contract command.
#### Scenario: OpenAPI endpoint недоступен после сборки frontend
- **WHEN** frontend уже собран, а endpoint OpenAPI временно недоступен
- **THEN** frontend продолжает использовать сгенерированный код для запросов к API
#### Scenario: Локальная проверка выполняется без backend
- **WHEN** разработчик запускает локальный quality gate без доступного backend
- **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 с ошибкой при расхождении.