docs: align OpenAPI workflow guidance #3
Frontend verify / verify (push) Successful in 4m31s

This commit is contained in:
2026-09-13 19:08:13 +03:00
parent 0c6bac8b90
commit 7a89356f87
4 changed files with 14 additions and 9 deletions
+9 -5
View File
@@ -14,16 +14,19 @@ pages/features/entities и прямой T-Bank call запрещены. Снач
## Типы и contract
Backend runtime OpenAPI — source; committed frontend snapshot и generated
`schema.d.ts` производны. Тип request/response бери из generated `paths`, например:
Backend-owned OpenAPI contract поступает во frontend как предоставленный
актуальный snapshot; generated `schema.d.ts` производен от него. Тип
request/response бери из generated `paths`, например:
```ts
type User = paths["/api/v1/auth/me"]["get"]["responses"][200]["content"]["application/json"];
```
Domain/UI type допустим, когда он отличается по смыслу, а не копирует transport DTO.
Generated TS вручную не исправляется. Изменение wire shape/status/route проходит
[общий contract workflow](../../../docs/development/runtime-openapi-verification.md).
Generated TS вручную не исправляется. Frontend-команды не читают соседний
backend checkout и не проверяют backend runtime OpenAPI; изменение wire
shape/status/route следует
[OpenAPI contract flow](../../../docs/development/runtime-openapi-verification.md).
Одна UI-модель не требует менять API. `openapi:generate` работает offline от snapshot;
`openapi:check` генерирует во временный каталог и сравнивает, не меняя tracked files.
@@ -53,4 +56,5 @@ Default focus refetch выключен; freshness и retry определяют
Изменяя header/retry/invalidation, проверяй наблюдаемое поведение через MSW и
[Testing](frontend-testing.md); не обращайся к реальному T-Bank.
`npm run openapi:check`, `npm run typecheck` и targeted tests проверяют разные
части решения. Для API semantics нужны также exact docs и contract gate.
части решения. Для API semantics нужны exact docs и проверки наблюдаемого
HTTP-поведения на стороне backend.