From 7a89356f8783a14d6dde752358ee995d0dcadd66 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Sun, 13 Sep 2026 19:08:13 +0300 Subject: [PATCH] docs: align OpenAPI workflow guidance #3 --- .ai/CONVENTIONS.md | 2 +- .ai/SOURCES.md | 2 +- .ai/conventions/frontend-data.md | 14 +++++++++----- AGENTS.md | 5 +++-- 4 files changed, 14 insertions(+), 9 deletions(-) diff --git a/.ai/CONVENTIONS.md b/.ai/CONVENTIONS.md index 92013d5..5441618 100644 --- a/.ai/CONVENTIONS.md +++ b/.ai/CONVENTIONS.md @@ -13,7 +13,7 @@ | query/mutation, shared/api, server state/cache, generated types, Bearer/refresh | [Data](conventions/frontend-data.md) | | Тесты или behavior с testing risk | [Testing](conventions/frontend-testing.md) | | Новый abstraction/dependency, refactor или неоднозначный scope | [Общий выбор реализации](../../docs/development/engineering-governance.md#выбор-реализации) | -| Request/response field, route/status/error shape, OpenAPI snapshot/generated type | [Общий contract workflow](../../docs/development/runtime-openapi-verification.md) | +| Request/response field, route/status/error shape, OpenAPI snapshot/generated type | [OpenAPI contract flow](../../docs/development/runtime-openapi-verification.md) | | Login/refresh/logout, token/cookie, auth ownership | Data + [security](../../backend/.ai/conventions/security-auth.md) + Testing | | Storybook/theme/tokens/shared UI | UI + точные [источники](SOURCES.md) дизайн-системы/каталога | diff --git a/.ai/SOURCES.md b/.ai/SOURCES.md index 8c296c1..3be0700 100644 --- a/.ai/SOURCES.md +++ b/.ai/SOURCES.md @@ -3,7 +3,7 @@ | Что нужно установить | Владелец | | --- | --- | | Какое implementation-решение принять | [CONVENTIONS](CONVENTIONS.md) | -| HTTP wire contract и направление генерации | Backend runtime OpenAPI → [snapshot/types workflow](../../docs/development/runtime-openapi-verification.md) | +| HTTP wire contract и направление генерации | Backend-owned contract → provided snapshot → [local snapshot/types flow](../../docs/development/runtime-openapi-verification.md) | | Error codes/validation/error envelope | [docs: HTTP API](../../docs/architecture/http-api.md) | | Auth/session, token storage и refresh | [Аутентификация](../../docs/domains/authentication/overview.md), [подключение брокера](../../docs/integrations/tbank.md) | | Значение Money, cached snapshot, account/position/income | [docs: Domain](../../docs/glossary.md) | diff --git a/.ai/conventions/frontend-data.md b/.ai/conventions/frontend-data.md index d1c0c10..7b472c3 100644 --- a/.ai/conventions/frontend-data.md +++ b/.ai/conventions/frontend-data.md @@ -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. diff --git a/AGENTS.md b/AGENTS.md index c1cc6af..1a47aaf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,8 +12,9 @@ React/Vite-клиент; общие правила работы — в root `AGE dependency boundaries и сборки приложения/Storybook без backend. Точные scripts принадлежат `package.json`; targeted checks — у выбранного convention. -HTTP contract changes дополнительно проходят общий -[contract workflow](../docs/development/runtime-openapi-verification.md). +HTTP contract changes используют предоставленный OpenAPI snapshot; frontend +локально проверяет только соответствие generated types этому snapshot: +[OpenAPI contract flow](../docs/development/runtime-openapi-verification.md). Generated types редактируются через их source; T-Bank доступен только через backend. Frontend dependencies используют exact versions. Pre-commit запускает staged formatting и FSD checks; сообщения commits — Conventional Commits.