diff --git a/.ai/CONVENTIONS.md b/.ai/CONVENTIONS.md index 5441618..5b5becd 100644 --- a/.ai/CONVENTIONS.md +++ b/.ai/CONVENTIONS.md @@ -12,8 +12,8 @@ | TS declaration/import/export, domain literals, magic values | [Код](conventions/frontend-ui.md#код-и-components) + [Domain literals](conventions/frontend-ui.md#domain-literals-and-magic-values) | | 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 | [OpenAPI contract flow](../../docs/development/runtime-openapi-verification.md) | +| Новый abstraction/dependency, refactor или неоднозначный scope | [Общий выбор реализации](../../AGENTS.md) | +| Request/response field, route/status/error shape, OpenAPI snapshot/generated type | [Источник HTTP-контракта](../../docs/architecture/http-api.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 3be0700..916b004 100644 --- a/.ai/SOURCES.md +++ b/.ai/SOURCES.md @@ -3,11 +3,11 @@ | Что нужно установить | Владелец | | --- | --- | | Какое implementation-решение принять | [CONVENTIONS](CONVENTIONS.md) | -| HTTP wire contract и направление генерации | Backend-owned contract → provided snapshot → [local snapshot/types flow](../../docs/development/runtime-openapi-verification.md) | +| HTTP wire contract и направление генерации | Backend-owned contract → provided snapshot → [Источник HTTP-контракта](../../docs/architecture/http-api.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) | -| Mantine/theme/tokens и существующие stories | [Дизайн-система](../../docs/development/design-system.md), [UI-каталог](../../docs/development/ui-catalog.md) | +| Mantine/theme/tokens и существующие stories | [Дизайн-система](../../docs/design/overview.md), [UI-каталог](../README.md#ui-каталог-storybook) | | As-built behavior нужной feature | [docs: Features](../../docs/README.md#предметные-области) | | Существующие behavioral requirements, если нужны по задаче | [specs index](../../specs/AI_INDEX.md) | | Действующие versions/scripts/check scope | package.json, lockfile, Biome/TS/dependency configs | diff --git a/.ai/conventions/frontend-architecture.md b/.ai/conventions/frontend-architecture.md index d0d49a8..ec83d4a 100644 --- a/.ai/conventions/frontend-architecture.md +++ b/.ai/conventions/frontend-architecture.md @@ -40,7 +40,7 @@ designTokens, color roles, CSSVariablesResolver и base styles. Внешний c `shared/ui` содержит StateView/LoadingSkeleton. Existing route-aware AppShell также лежит в shared/ui, но не является общим catalog primitive; его расположение не служит основанием переносить новую domain/navigation логику в shared. -Изменяя foundation, прочитай [design system](../../../docs/development/design-system.md). +Изменяя foundation, прочитай [design system](../../../docs/design/overview.md). ## Примеры diff --git a/.ai/conventions/frontend-data.md b/.ai/conventions/frontend-data.md index 7b472c3..1b1428b 100644 --- a/.ai/conventions/frontend-data.md +++ b/.ai/conventions/frontend-data.md @@ -25,8 +25,8 @@ type User = paths["/api/v1/auth/me"]["get"]["responses"][200]["content"]["applic Domain/UI type допустим, когда он отличается по смыслу, а не копирует transport DTO. Generated TS вручную не исправляется. Frontend-команды не читают соседний backend checkout и не проверяют backend runtime OpenAPI; изменение wire -shape/status/route следует -[OpenAPI contract flow](../../../docs/development/runtime-openapi-verification.md). +shape/status/route сохраняет +[границу HTTP-контракта](../../../docs/architecture/http-api.md#источник-контракта). Одна UI-модель не требует менять API. `openapi:generate` работает offline от snapshot; `openapi:check` генерирует во временный каталог и сравнивает, не меняя tracked files. diff --git a/.ai/conventions/frontend-testing.md b/.ai/conventions/frontend-testing.md index fa78f41..143be13 100644 --- a/.ai/conventions/frontend-testing.md +++ b/.ai/conventions/frontend-testing.md @@ -2,7 +2,8 @@ ## Выбор проверки -Читай при изменении тестов или behavior с [testing risk](../../../docs/development/engineering-governance.md#risk-based-testing). +Читай при изменении тестов, доступа, денежных расчётов, восстановления +интерфейса или исправлении подтверждённой регрессии. Выбирай boundary по наблюдаемому исходу, а не внутреннему helper/component state. | Изменение | Дешёвая надёжная проверка | diff --git a/.ai/conventions/frontend-ui.md b/.ai/conventions/frontend-ui.md index 8994521..c211935 100644 --- a/.ai/conventions/frontend-ui.md +++ b/.ai/conventions/frontend-ui.md @@ -13,7 +13,7 @@ Mantine component и общую тему. Для выпадающего выбо Wrapper нужен для проектной ответственности, а не ради нового имени для Button. Локальный CSS module принадлежит component; общий token вводи для -реально общей роли через [design system](../../../docs/development/design-system.md). +реально общей роли через [design system](../../../docs/design/overview.md). | Состояние | Владелец | | --- | --- | @@ -154,5 +154,5 @@ incidental значения с объяснением, например пере Type/style: `npm run typecheck`, `npm run lint`. Для risk behavior/изменения тестов используй [Testing](frontend-testing.md). UI: keyboard, narrow viewport, -loading/error/empty/loaded и recovery по применимости. [Storybook](../../../docs/development/ui-catalog.md) +loading/error/empty/loaded и recovery по применимости. [Storybook](../../README.md#ui-каталог-storybook) уже установлен; используй его как reference, но сверяй UI с задачей отдельно от build. diff --git a/AGENTS.md b/AGENTS.md index 1a47aaf..0d73a47 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ dependency boundaries и сборки приложения/Storybook без back HTTP contract changes используют предоставленный OpenAPI snapshot; frontend локально проверяет только соответствие generated types этому snapshot: -[OpenAPI contract flow](../docs/development/runtime-openapi-verification.md). +[Источник HTTP-контракта](../docs/architecture/http-api.md#источник-контракта). Generated types редактируются через их source; T-Bank доступен только через backend. Frontend dependencies используют exact versions. Pre-commit запускает staged formatting и FSD checks; сообщения commits — Conventional Commits. diff --git a/README.md b/README.md index 348aee2..e44d5db 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,14 @@ TypeScript остаётся на 5.9.3: `openapi-typescript@7.13.0` требуе обновите `src/shared/api/spec/openapi.json` копированием backend OpenAPI document и затем выполните `npm run openapi:generate`. +## UI-каталог Storybook + +После `nvm use --silent` выполните `npm run dev:catalog`; статическая сборка — +`npm run build:catalog`. Каталог использует общую тему приложения, вымышленные +данные и локальные действия без application API. Примеры не доказывают +восстановление реального запроса. Визуальные роли описаны в +[дизайн-системе](../docs/design/overview.md). + ## Документация - [Router conventions](.ai/CONVENTIONS.md) и [источники](.ai/SOURCES.md) @@ -56,12 +64,9 @@ document и затем выполните `npm run openapi:generate`. - [UI, state, формы и компоненты](.ai/conventions/frontend-ui.md) - [Data/API/cache](.ai/conventions/frontend-data.md) - [Testing](.ai/conventions/frontend-testing.md) -- [Поставленный UI-каталог Storybook](../docs/development/ui-catalog.md) +- [UI-каталог Storybook](#ui-каталог-storybook) - [Обзор поставленной системы](../docs/overview.md) -- [Engineering governance и risk-based testing](../docs/development/engineering-governance.md) - [Карта проектных фактов](../docs/README.md) -- [Границы проверки интерфейса](../docs/development/verification.md#интерфейс) -- [Remediation registry](../docs/development/audit-remediation.md) Runtime OpenAPI backend сверяется с frontend snapshot отдельной read-only backend командой `npm run test:openapi-contract`.