From 1195c7b75d55b451fcaa44473679810a5803ba7e Mon Sep 17 00:00:00 2001 From: "S.Gromov" Date: Tue, 28 Apr 2026 16:02:00 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=83=D1=82=D0=BE=D1=87=D0=BD=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D0=BF=D1=80=D0=B0=D0=B2=D0=B8=D0=BB=D0=B0=20?= =?UTF-8?q?=D0=B8=20=D0=B7=D0=B0=D0=B3=D0=BE=D0=BB=D0=BE=D0=B2=D0=BA=D0=B8?= =?UTF-8?q?=20=D0=B2=D0=BB=D0=BE=D0=B6=D0=B5=D0=BD=D0=BD=D1=8B=D1=85=20?= =?UTF-8?q?=D1=80=D0=B0=D0=B7=D0=B4=D0=B5=D0=BB=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Подзаголовки архитектуры подняты до самодостаточных: Слои SLM, Модули SLM, Сегменты SLM - Подзаголовки REST-клиентов подняты до самодостаточных: Автогенерация REST-клиента, Ручное создание REST-клиента - Для серверных/клиентских компонентов h1 оставлен коротким, контекст полностью переносится в описание - Лендинг docs/docs/index.md актуализирован под новые имена; «Создание проекта» и «Данные» вынесены в отдельные группы - В CONTRIBUTING описана отдельная группа разделов «Настройка» и весь набор типов: basics, creating-project, setup, usage - Зафиксирован принцип: подъём контекста в h1 — только грамматически естественный, иначе контекст переносится в описание - Frontmatter дополнен обязательным полем description - Удалены устаревшие OLD_parts/ и notes --- CONTRIBUTING.md | 108 ++++++-- OLD_parts/1-assistent.md | 19 -- OLD_parts/10-stores.md | 84 ------ OLD_parts/11-css.md | 227 ---------------- OLD_parts/12-components.md | 88 ------- OLD_parts/13-hooks.md | 68 ----- OLD_parts/14-api-hooks.md | 124 --------- OLD_parts/15-api.md | 242 ------------------ OLD_parts/3-general-principles.md | 21 -- OLD_parts/4-arkhitektura.md | 22 -- OLD_parts/5-code-style.md | 74 ------ OLD_parts/6-naming.md | 18 -- OLD_parts/7-docs.md | 69 ----- OLD_parts/8-typing.md | 187 -------------- OLD_parts/9-localization.md | 12 - README.md | 58 +++-- docs-overview.md | 16 +- .../basics/architecture/reference/layers.md | 8 +- .../basics/architecture/reference/modules.md | 8 +- .../basics/architecture/reference/segments.md | 8 +- docs/docs/index.md | 56 ++-- docs/docs/usage/data/rest/clients/auto.md | 4 +- docs/docs/usage/data/rest/clients/manual.md | 4 +- notes | 153 ----------- 24 files changed, 184 insertions(+), 1494 deletions(-) delete mode 100644 OLD_parts/1-assistent.md delete mode 100644 OLD_parts/10-stores.md delete mode 100644 OLD_parts/11-css.md delete mode 100644 OLD_parts/12-components.md delete mode 100644 OLD_parts/13-hooks.md delete mode 100644 OLD_parts/14-api-hooks.md delete mode 100644 OLD_parts/15-api.md delete mode 100644 OLD_parts/3-general-principles.md delete mode 100644 OLD_parts/4-arkhitektura.md delete mode 100644 OLD_parts/5-code-style.md delete mode 100644 OLD_parts/6-naming.md delete mode 100644 OLD_parts/7-docs.md delete mode 100644 OLD_parts/8-typing.md delete mode 100644 OLD_parts/9-localization.md delete mode 100644 notes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fc6d3d8..11d7ac8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,20 +25,25 @@ docs/ ├── index.md # Лендинг (URL `/`) └── docs/ # Контент документации (URL `/docs/...`) ├── index.md # Главная страница - ├── workflow.md - ├── workflow/ # Процессы разработки - ├── basics/ # Базовые правила + ├── workflow.md # Подсказки + ├── basics/ # Базовые правила: каким должен быть код │ ├── tech-stack.md │ ├── architecture/ │ ├── code-style.md │ ├── naming.md │ ├── documentation.md │ └── typing.md - ├── setup/ # Установка: разовая настройка проекта + ├── creating-project/ # Создание проекта: как поднять новый проект + │ ├── from-template.md + │ ├── manual.md + │ └── nextjs.md + ├── setup/ # Настройка: разовая настройка инструментов │ ├── aliases.md │ ├── biome.md │ ├── postcss.md + │ ├── styles.md │ ├── svg-sprites.md + │ ├── templates.md │ └── vscode.md └── usage/ # Использование: повседневная работа ├── project-structure.md @@ -64,36 +69,81 @@ generate-llms.ts # Скрипт генерации llms.txt и R ### Добавление нового раздела -1. Создать `.md`-файл в нужной папке (`docs/docs/basics/`, `docs/docs/setup/` или `docs/docs/usage/`). +1. Создать `.md`-файл в нужной папке: `basics/`, `creating-project/`, + `setup/` или `usage/`. 2. Добавить пункт в сайдбар — `.vitepress/config.ts`. Сайдбар — единственный источник порядка и группировки для `llms.txt`. 3. Запустить `npm run llms` для обновления `llms.txt` и README. -## Два типа документации +## Типы разделов -### Базовые правила +Документация разделена на четыре группы. Каждая отвечает на свой вопрос +и имеет свою природу — это влияет на содержимое и структуру страницы. + +### Базовые правила (`basics/`) **Отвечает на вопрос:** «Каким должен быть любой код?» Универсальные стандарты, **не привязанные к конкретной области**. -Правило базовое, если оно применимо ко всему коду одинаково: именование переменных, оформление импортов, когда использовать `type` vs `interface`. +Правило базовое, если оно применимо ко всему коду одинаково: именование +переменных, оформление импортов, когда использовать `type` vs `interface`. -Примеры в базовых правилах допускаются, но служат иллюстрацией принципа, а не инструкцией по конкретной области. +Примеры в базовых правилах допускаются, но служат иллюстрацией принципа, +а не инструкцией по конкретной области. -**Граница:** если правило касается только одной области (только стили, только компоненты, только API) — оно живёт в прикладном разделе, не в базовых. +**Граница:** если правило касается только одной области (только стили, +только компоненты, только API) — оно живёт в прикладном разделе, не в базовых. -### Прикладные разделы +### Создание проекта (`creating-project/`) -**Отвечает на вопрос:** «Как работать с X?» +**Отвечает на вопрос:** «Как поднять новый проект?» -Полное описание конкретной области: структура файлов, правила, именование, типизация, примеры. +Сценарии запуска нового проекта целиком: из шаблона, вручную, чистая +установка фреймворка. Раздел описывает порядок шагов на уровне всего +проекта; детали отдельных инструментов лежат в `setup/`. -**Граница:** прикладной раздел не дублирует базовые правила. -Если правило уже описано в базовых — прикладной раздел ссылается на него, но не повторяет. +**Граница:** не дублирует разделы `setup/`. Ссылается на них как на +шаги в общем сценарии. + +### Настройка (`setup/`) + +**Отвечает на вопрос:** «Как поставить и сконфигурировать инструмент +в новом проекте?» + +Разовая установка отдельного инструмента или подсистемы (линтер, +CSS-процессор, генератор спрайтов, шаблоны). Каждый раздел — +самостоятельная подсистема. Выполняется один раз при заведении +проекта или при смене мажорной версии инструмента. + +Типичная структура `setup/`-страницы: требования → установка (шаги) → +конфиг → проверка. + +**Граница:** `setup/` — про настройку, `usage/` — про написание кода +с использованием уже настроенного инструмента. + +### Использование (`usage/`) + +**Отвечает на вопрос:** «Как этим пользоваться в коде?» + +Повседневная работа: как писать компоненты, стили, как получать данные, +как работать со сторами, локализацией, ассетами. Полное описание +конкретной области: структура файлов, правила, именование, типизация, примеры. + +Шаблон страницы описан ниже в секции «Структура прикладного раздела». + +**Граница:** прикладной раздел не дублирует базовые правила. Если правило +уже описано в `basics/` — прикладной раздел ссылается на него, но не +повторяет. ## Структура прикладного раздела -Шаблон ниже описывает все допустимые секции. Раздел включает только те секции, которые для него релевантны — пустые секции не создаются. +Шаблон ниже относится к разделам `usage/` (повседневная работа). +Разделы `setup/` и `creating-project/` имеют другую структуру — +ориентированную на пошаговую установку (требования → установка → +проверка). + +Шаблон описывает все допустимые секции. Раздел включает только те, +которые для него релевантны — пустые секции не создаются. ```markdown # {Название} @@ -179,10 +229,15 @@ generate-llms.ts # Скрипт генерации llms.txt и R ```yaml --- title: Название раздела +description: Описание раздела одним предложением. --- ``` -Значение `title` совпадает с текстом `h1`-заголовка в файле. +- `title` совпадает с текстом `h1`-заголовка в файле. +- `description` совпадает с абзацем-описанием сразу под `h1`. + +Подробнее о требованиях к самому заголовку и описанию — секция +«Заголовок и описание» ниже. ### Заголовок и описание @@ -206,11 +261,26 @@ title: Название раздела - Самодостаточен — читается без контекста сайдбара. - Исключение: имя инструмента допустимо, если оно — единственное устойчивое имя самой области (`PostCSS`, `Biome`, `VS Code`). +- Если страница вложена в семантическую группу + (`Архитектура → Слои`, `Данные → REST → Серверные компоненты`) + и короткое имя теряет смысл при прямой ссылке — `h1` поднимает + имя родителя в заголовок: `Слои SLM`, `Сегменты SLM`. В сайдбаре + допустимо оставить короткий вариант (`Слои`, `Сегменты`) — там + путь группы виден через дерево. +- Подъём в заголовок применяется только когда читается грамматически + естественно (`Слои SLM`, `Автогенерация REST-клиента`). Если + получается натянутая конструкция (`REST в серверных компонентах`) — + заголовок остаётся коротким, а контекст полностью переносится + в описание. Заголовок и описание — пара: если один не несёт + контекст, его обязательно несёт второй. -**Хорошо:** «Алиасы импортов», «Структура проекта», «SVG-спрайты». +**Хорошо:** «Алиасы импортов», «Структура проекта», «SVG-спрайты», +«Слои SLM», «Автогенерация REST-клиента». **Плохо:** «Установка и настройка» (что устанавливаем?), -«Использование» (что используем?), «Введение» (во что?). +«Использование» (что используем?), «Введение» (во что?), +«Сегменты» (чего сегменты?), «REST в серверных компонентах» +(грамматически натянуто — лучше короткий h1 + контекст в описании). #### Описание diff --git a/OLD_parts/1-assistent.md b/OLD_parts/1-assistent.md deleted file mode 100644 index 33a8f3f..0000000 --- a/OLD_parts/1-assistent.md +++ /dev/null @@ -1,19 +0,0 @@ -# Ассистент - -## Для ассистента - -- Всегда используй Русский язык для общения и генерации документации/комментариев/коммитов. -- Всегда следуй этим правилам при генерации кода и ответах. -- Всегда пиши план действий перед генерацией кода. -- Всегда спрашивай разрешения у пользователя перед генерацией кода. -- Всегда проверяй, что код соответствует линтингу и форматированию. -- Всегда сверяйся с чек-листом при генерации кода. -- Не предлагай решения, которые противоречат этим правилам этого файла. -- Если не уверен — уточни у пользователя, не гадай, не придумывай. - -## Обязательность чек-листов - -- Все чек-листы, приведённые в правилах, обязательны к исполнению. -- Ассистент обязан сверяться с чек-листом при выполнении любой задачи, связанной с кодом. -- Нельзя сокращать, игнорировать или опускать пункты чек-листа — каждый пункт должен быть выполнен или явно отмечен как невыполнимый с объяснением причины. -- В каждом ответе, связанном с генерацией или изменением кода, ассистент обязан ссылаться на соответствующий чек-лист и подтверждать его выполнение. diff --git a/OLD_parts/10-stores.md b/OLD_parts/10-stores.md deleted file mode 100644 index 04d8ce6..0000000 --- a/OLD_parts/10-stores.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Stores ---- - -# Stores - -## Сторы (Stores) - -> В этом разделе собраны основные правила и рекомендации по созданию и оформлению сторов. Следуйте этим принципам, чтобы обеспечить чистую архитектуру, удобство поддержки и единый стиль работы с состоянием в проекте. -> В проекте для организации состояния используется только библиотека Zustand. - -### Структура -- Store размещается в файле `.store.ts` в папке `stores/` на своём уровне абстракции согласно архитектуре проекта. -- Интерфейс состояния описывается в этом же файле с суффиксом `State` (PascalCase). -- Для каждого store создаётся отдельный хук доступа (например, `useTodoStore`). -- Для глобальных сторов используйте только `shared/store`. - -### Именование -- Соблюдайте [правила именования файлов и папок](#правила-именования-файлов-и-папок): -- Файл store — `.store.ts` (kebab-case). -- Имя интерфейса состояния — PascalCase с суффиксом `State`. -- Имя хука — camelCase с префиксом `use`. - -### Требования -- В store допускается только хранение состояния и методы управления им, без бизнес-логики, асинхронных операций и side-effects (см. раздел "Правила организации и использовалья Store"). -- Для методов, изменяющих состояние через set, если используется функция — тело функции в фигурных скобках, return с новой строки после стрелки. -- Не дублируйте логику между сторами. - -### Типизация -- Всегда указывайте типы для всех полей состояния и методов. -- Не используйте неявное приведение типов и не полагайтесь на автоматический вывод, если это может снизить читаемость или безопасность. - -### Документирование -- Документируйте только назначение store и смысл полей, строго по [правилам документирования кода](#правило-для-документирования-кода). - -### Экспорт -- Экспортируйте хук доступа к store и интерфейс состояния через `index.ts` слоя/компонента. - -### Примеры - -```ts -import { create } from 'zustand'; -import { TodoItem } from './types/todo-item.interface'; - -/** - * Состояние хранилища задач. - */ -export interface TodoStoreState { - /** Массив задач. */ - items: TodoItem[]; - /** Добавить задачу. */ - addTodo: (item: TodoItem) => void; - /** Удалить задачу. */ - removeTodo: (id: string) => void; -} - -/** - * Хук для доступа к хранилищу задач. - */ -export const useTodoStore = create((set) => ({ - items: [], - addTodo: (item) => set((state) => { - return { - items: [...state.items, item], - }; - }), - removeTodo: (id) => set((state) => { - return { - items: state.items.filter((t) => t.id !== id), - }; - }), -})); -``` - -### Чек-лист - -- [ ] Store размещён в `stores/.store.ts` на своём уровне абстракции согласно архитектуре проекта. -- [ ] Именование файлов и сущностей соответствует [правилам именования файлов и папок](#правила-именования-файлов-и-папок). -- [ ] Все поля и методы строго типизированы (см. [общие правила типизации](#общие-правила-типизации)). -- [ ] В store только состояние и методы управления им, без бизнес-логики и side-effects. -- [ ] Для методов, изменяющих состояние через set, используется функция с return с новой строки. -- [ ] Документировано только назначение store и смысл полей (см. [правила документирования кода](#правило-для-документирования-кода)). -- [ ] Нет неиспользуемого или невалидного кода. -- [ ] Экспорт через индексный файл. diff --git a/OLD_parts/11-css.md b/OLD_parts/11-css.md deleted file mode 100644 index d736f27..0000000 --- a/OLD_parts/11-css.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: CSS ---- - -# CSS - -## Правила оформления и стилизации CSS-кода - -- **Препроцессоры** - Используй PostCSS и модули для стилизации. - -- **Архитектура написания стилей** - Используй подход **Mobile First** - Используй CSS переменные для стилизации. - Используй Custom Media Queries для адаптивных стилей. - Используй BEM для именования классов. - Между каждым CSS-правилом (селектором) должен быть один пустой сброс строки, пример: - ```css - .todo-list { - max-width: 600px; - padding: var(--space-3); - - @media (--md) { - max-width: 800px; - } - } - - .todo-list__text { - font-size: 18px; - - @media (--md) { - font-size: 22px; - } - } - ``` - Запрещено писать правила подряд без пустой строки: - ```css - /* Так делать нельзя! */ - .todo-list { ... } - .todo-list__text { ... } - ``` - -- **Методология именования классов** - Использовать методологию **BEM** для именования классов. - - Блок: kebab-case, пример `.user-bar { }` - - Елемент: kebab-case, соеденный с блоком двойным нижним подчеркиванием, пример `.user-bar__slide { }` - - Модификатор: kebab-case, отдельный самостоятельный класс, **не соединяется** с блоком/елементом, имя модификатора всегда начинается с нижнего подчеркивания, пример: `._red { }` - -- **Единицы измерения** - Используй `px` как основная единица измирения, так-же допускается использовать остальные единицы измерения если того требует реализуемый дизайн. - -- **Импорт стилей** - Стили компонента должны импортироваться только внутри соответствующего компонента. - Запрещено импортировать стили одного компонента в другой. - Запрещено импортировать `css переменные` в файлы стилей, они доступны глобально. - Запрещено импортировать `custom media` в файлы стилей, они доступны глобально. - -- **Переменные** - Все значения переменных нужно писать в `/shared/styles` или в Mantine ThemeProvider. - Все что не является цветами, брекпоинтами, отступами, скруглением допускаются использоваться в компонентах. - Обязательное создавай CSS перменные для: - - "Цветов", пример: `--color-danger: red;`. - - "Брекпоинты", описываем в (Сustom media) пример: `@custom-media --md (min-width: 62em);`. - - "Отспупы (--space)", , пример: `--space-1: 4px;`, `--space-2: 8px;`, `--space-3: 12px;` итд.. - - "Скругление углов (--radius)", пример: `--radius-1: 4px;`,`--radius-2: 8px;`,`--radius-3: 12px;` итд.. - -- **Вложенность селекторов** - Запрещено использовать вложенность селекторов. - Разрешено использовать вложенность только для: - - Псевдо-классов `:hover`, `:active` итд.. - - Псевдо-елементов `::before`, `::after` - - Медиа запросов `@media` - - Классы **модификаторы** по методологии BEM - Каждый вложенный селектор отделяется 1 пустой строкой. - -- **Медиа запросы** - Строго запрещено использовать `@media` без вложения в селектор. - Строго запрещено использовать в теле `@media` любые селекторы. - Разрешено использовать только Custom Media Queries (например, `@media (--md) {}`). - Запрещено использовать любые произвольные значения breakpoints (например, max-width: 768px). - **Пример как правильно писать @media** - ```css - .todo-list { - max-width: 600px; - padding: 24px; - - @media (--md) { - max-width: 800px; - } - } - - .todo-list__text { - font-size: 18px; - - @media (--md) { - font-size: 22px; - } - } - - ``` - **Пример как неправильно писать @media** - ```css - // Медиа запрос не вложен в селектор - @media (--md) { - .todo-list { - max-width: 600px; - padding: 24px; - } - .todo-list__text { - font-size: 18px; - } - } - // Используется стандартный `min-width: 992px` вмето Custom Media Queries - @media (min-width: 992px) { - // Внутри @media запроса используются селекторы - .todo-list { - max-width: 600px; - padding: 24px; - } - .todo-list__text { - font-size: 18px; - } - } - ``` - -- **Глобальные стили и сбросы** - Все глобальные стили (например, сбросы) должны располагаться в отдельном файле, например, `src/app/styles/global.css`. - -- **Использование Mantine и PostCSS** - Для стандартных визуальных компонентов (кнопки, инпуты, layout, grid, notifications и т.д.) использовать только Mantine и его ThemeProvider. - Запрещено использовать в Mantine компонентах его props/styling, вмето этого нужно добавлять кастомные стили PostCSS. - Кастомные стили допускаются только в случае, если требуемый дизайн невозможно реализовать средствами Mantine. - При написании кастомных стилей стараться использовать переменные и токены Mantine, если это возможно. - -- **Порядок CSS-свойств** - В стилях рекомендуется придерживаться логического порядка свойств: - 1. Позиционирование (position, top, left, z-index и т.д.) - 2. Блочная модель (display, width, height, margin, padding и т.д.) - 3. Оформление (background, border, box-shadow и т.д.) - 4. Текст (font, color, text-align и т.д.) - 5. Прочее (transition, animation и т.д.) - -- **Комментарии** - В стилях запрещено использовать комментарии. - -- **Дублирования** - Не дублировать стили между компонентами. Общие стили выносить в shared/styles или использовать переменные. - -- **Примеры кода стилей** - Пример как хорошо: - ```css - /* Блок BEM */ - .user-bar { - display: none; - color: black; - - /* Медиа запрос custom media и отделяется 1 пустой строкой */ - @media (--md) { - display: flex; - } - } - - /* Елемент BEM отделяется 1 пустой строкой*/ - .user-bar__button-next { - background-color: #f0f0f0; - - /* Псевдо-класс отделяется 1 пустой строкой*/ - &:hover { - background-color: #e0e0e0; - } - - /* Модификатор BEM отделяется 1 пустой строкой*/ - &._blue { - background-color: #2b2bbe; - } - - /* Модификатор BEM отделяется 1 пустой строкой*/ - &._green { - background-color: #29c53d; - } - } - ``` - Пример как плохо писать: - ```css - .user-bar { - display: none; - color: black; - &__button { - &_next { - background-color: #f0f0f0; - &:hover { - background-color: #e0e0e0; - } - &._blue { - background-color: #2b2bbe; - } - &._green { - background-color: #29c53d; - } - } - } - } - @media (min-width: 992px) { - .user-bar { - display: flex; - } - } - ``` - -**Чек лист для проверки стилизации.** -- [ ] Используется PostCSS и CSS-модули для стилизации. -- [ ] Применён подход Mobile First. -- [ ] Именование классов строго по BEM: - - [ ] Модификатор — отдельный класс, начинается с нижнего подчёркивания (например, `._red`, `._active`) -- [ ] Все CSS-переменные (цвета, брейкпоинты, отступы, скругления) определены только в `/shared/styles` или через Mantine ThemeProvider. -- [ ] Для медиа-запросов используются только custom media переменные из `/shared/styles/media.css`. -- [ ] Соблюдается правила вложености селекторов. -- [ ] Соблюдается правила отступов селекторов. -- [ ] Глобальные стили (reset) вынесены в отдельный файл, остальные стили — модульные. -- [ ] Для стандартных UI-элементов используются только компоненты Mantine, кастомные стили — только при необходимости. -- [ ] В Mantine-компонентах не используются props/styling для стилизации, только PostCSS. -- [ ] Кастомные стили используют переменные и токены Mantine, если это возможно. -- [ ] В стилях нет комментариев. -- [ ] Стили компонента импортируются только внутри соответствующего компонента. -- [ ] Нет импорта стилей одного компонента в другой. -- [ ] Нет импорта файлов переменных и custom media — они доступны глобально. -- [ ] Нет дублирования стилей между компонентами, общие стили вынесены в shared/styles или используются переменные. diff --git a/OLD_parts/12-components.md b/OLD_parts/12-components.md deleted file mode 100644 index 37786ce..0000000 --- a/OLD_parts/12-components.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Компоненты ---- - -# Компоненты - -## Правила создания и работы с компонентами. - -### 1. Структура компонента -Ассистент при создании/рефакторинге компонента должен **строго** придерживаться следующей структуры файлов и папок: - -``` -component-name/ - index.ts - component-name.tsx - styles/ - component-name.module.css - locales/ - ru.json - en.json - types/ - component-name.interface.ts - component-name.type.ts - component-name.enum.ts - schemas/ - schema-name.schema.ts - utils/ - util-name.util.ts - hooks/ - use-hook-name.hook.ts - stores/ - store-name.store.ts - ui/ - ... # вложенные компоненты для component-name -``` - -Пояснения к структуре компонента: -**Обязательные файлы** обязательны для всех компонентов, даже если они пустые. - - component-name/: Папка компонента корень для всего компонента. - - index.ts: экспортирует главный компонент, интерфейс и всё, что может быть переиспользовано. - - component-name.tsx: главный компонент. - - styles/component-name.module.css: стили компонента. - - locales/ru.json: локализация на русском языке. - - locales/en.json: локализация на английском языке. - - types/component-name.interface.ts: интерфейс пропсов компонента. -**Не обязательные файлы** добавляются только при необходимости - - types/component-name.type.ts: типы компонента. - - types/component-name.enum.ts: enum компонента. - - schemas/schema-name.schema.ts: схемы валидации. - - utils/util-name.util.ts: утилиты компонента. - - hooks/use-hook-name.hook.ts: хуки компонента. - - stores/store-name.store.ts: хранилища состояния компонента. - - ui/: Папка для вложенных компонентов. - -### Требования к компоненту -- Использовать `memo()` для всех компонентов, которые принимают пропсы. -- Использовать `useMemo` для всех вычислений, которые передаются в пропсы других компонентов. -- Использовать `useCallback` для всех функций/методов, которые передаются в пропсы других компонентов. - -### Требования к вложенным компонентам -- Вложенный компонент — это полноценный компонент, который обязан полностью соблюдать все правила, описанные для компонентов (структура, именование, документация, типизация, стилизация и т.д.). -- Все вложенные компоненты размещаются только в папке ui/ основного компонента. - -**Пояснение** -Нет необходимости повторять структуру и требования — вложенный компонент подчиняется тем же правилам, что и любой другой компонент, только располагается в папке ui/ родительского компонента. - -### Требования к локализации -- Все добавленные локализации обязательно подключать в экземпляр `app/i18n` (чтобы новые namespace были доступны для i18next). - ---- - -### Чек-лист для создания нового компонента -- [ ] Главный компонент размещён в корне и назван по правилу PascalCase. -- [ ] Создан файл стилей в папке `styles/`, имя в kebab-case, используется BEM. -- [ ] Все классы применяются через `className={styles['component-name']}`. -- [ ] Создана папка `locales/` с файлами `ru.json` и `en.json`. -- [ ] Создан файл интерфейса пропсов в папке `types/`, даже если интерфейс пустой. -- [ ] Создан файл `index.ts` с экспортом главного компонента и интерфейса. -- [ ] Внутренние компоненты (если есть) размещены в папке `ui/`. -- [ ] Все важные части кода документированы по TSDoc (см. раздел 16). -- [ ] Остальные файлы (schemas, дополнительные типы, enum) добавлены только при необходимости. -- [ ] Именование файлов и папок соответствует правилам (см. выше). -- [ ] Нет неиспользуемого или невалидного кода. -- [ ] Для компонентов с пропсами используется `React.memo`. -- [ ] Для вычислений, передаваемых в пропсы, используется `useMemo`. -- [ ] Для функций, передаваемых в пропсы, используется `useCallback`. -- [ ] Все тексты вынесены в локализационные файлы и используются через i18n. -- [ ] Новые namespace подключены в экземпляр i18n. diff --git a/OLD_parts/13-hooks.md b/OLD_parts/13-hooks.md deleted file mode 100644 index c0b1878..0000000 --- a/OLD_parts/13-hooks.md +++ /dev/null @@ -1,68 +0,0 @@ -# Хуки (React Hooks) - -> В проекте для создания пользовательских хуков используется только React (функциональные компоненты и хуки). -> В этом разделе собраны основные правила и рекомендации по созданию и оформлению хуков. Следуйте этим принципам, чтобы обеспечить чистую архитектуру, переиспользуемость и единый стиль работы с хуками в проекте. - -## Рекомендации по использованию сторонних хуков -- Если есть возможность, используйте хуки Mantine в компонентах и кастомных хуках для работы с состоянием, темизацией, медиа-запросами и другими возможностями библиотеки. -- Не дублируйте функциональность, уже реализованную в Mantine. - -## Структура -- Каждый хук размещается в отдельном файле с именем `use-.hook.ts` в папке `hooks/` на своём уровне абстракции согласно архитектуре проекта. -- Имя хука — в стиле camelCase с префиксом `use` (например, `useTodoFilter`). -- Для сложных возвращаемых структур использовать отдельные типы или интерфейсы, размещая их в папке `types/` на своём уровне абстракции. - -## Именование -- Соблюдайте [правила именования файлов и папок](#правила-именования-файлов-и-папок): - - Файл хука — `use-.hook.ts` (kebab-case). - - Имя хука — camelCase с префиксом `use`. - -## Требования -- Хук должен быть строго типизирован: все параметры, возвращаемые значения и внутренние переменные должны иметь явные типы. -- Не хранить бизнес-логику, связанную с несколькими слоями — хук должен быть изолирован в рамках своего слоя/feature. -- Не дублировать логику между хуками — общие части выносить в shared. -- Не использовать side-effects вне useEffect/useLayoutEffect. -- Для мемоизации возвращаемых значений и функций использовать useMemo и useCallback. -- Не использовать устаревшие или неразрешённые паттерны React. - -## Типизация -- Всегда явно указывать типы для всех параметров, возвращаемых значений и состояния внутри хука. -- Не используйте неявное приведение типов и не полагайтесь на автоматический вывод, если это может снизить читаемость или безопасность. - -## Документирование -- Документируйте только назначение хука (описание), строго по [правилам документирования кода](#правило-для-документирования-кода). - -## Экспорт -- Экспортируйте хук только именованным экспортом через `index.ts` слоя/компонента. - -## Примеры - -```ts -import { useMemo } from 'react'; -import { TodoItem } from '../types/todo-item.interface'; -import { TodoStatus } from '../types/todo-status.enum'; - -/** - * Хук фильтрации задач по статусу. - */ -export const useTodoFilter = (items: TodoItem[], filter: TodoStatus): TodoItem[] => { - return useMemo(() => { - if (filter === TodoStatus.ALL) return items; - if (filter === TodoStatus.ACTIVE) return items.filter((t) => !t.completed); - return items.filter((t) => t.completed); - }, [items, filter]); -}; -``` - -## Чек-лист - -- [ ] Хук размещён в файле `use-.hook.ts` в папке `hooks/` на своём уровне абстракции согласно архитектуре проекта. -- [ ] Именование файлов и сущностей соответствует [правилам именования файлов и папок](#правила-именования-файлов-и-папок). -- [ ] Все параметры, возвращаемые значения и внутренние переменные строго типизированы. -- [ ] Вся бизнес-логика изолирована в рамках слоя/feature. -- [ ] Нет дублирования логики между хуками. -- [ ] Для мемоизации используется useMemo/useCallback. -- [ ] Не используются side-effects вне useEffect/useLayoutEffect. -- [ ] Документировано только назначение хука (см. [правила документирования кода](#правило-для-документирования-кода)). -- [ ] Нет неиспользуемого или невалидного кода. -- [ ] Экспорт только именованный через индексный файл. diff --git a/OLD_parts/14-api-hooks.md b/OLD_parts/14-api-hooks.md deleted file mode 100644 index 93234e5..0000000 --- a/OLD_parts/14-api-hooks.md +++ /dev/null @@ -1,124 +0,0 @@ -# Хуки API (React Hooks) - -> В проекте для работы с API-хуками используется только React и библиотека SWR для получения данных (GET-запросы). -> В этом разделе собраны основные правила и рекомендации по созданию и оформлению хуков для работы с API. Следуйте этим принципам, чтобы обеспечить чистую архитектуру, переиспользуемость и единый стиль работы с API-хуками в проекте. - -## Описание и назначение API-хуков - -API-хуки предназначены для получения данных с сервера (GET-запросы) и используются в компонентах или других хуках. -В проекте для этого применяется библиотека SWR, которая обеспечивает кэширование, автоматическое обновление и удобную работу с асинхронными запросами. - -**Fetcher** — это функция, которую использует SWR для выполнения запроса к API. В проекте fetcher обычно экспортируется из файла клиента (например, `backendFetcher` из `shared/api/backend/client.ts`) и инкапсулирует логику обращения к конкретному API-клиенту. - -**API-клиент** — это отдельный модуль (папка), отвечающий за взаимодействие с конкретным внешним или внутренним API. -API-клиент включает: -- инициализацию экземпляра HTTP-клиента (например, Axios), -- настройку базового URL, интерцепторов и общих обработчиков ошибок, -- организацию всех сущностей и методов для работы с этим API (например, users, auth, orders и т.д.), -- экспорт всех функций, типов и fetcher через индексные файлы. - -Каждый API-клиент размещается в папке `src/shared/api//` и имеет собственную структуру согласно архитектуре проекта. - -## Структура -- Каждый API-хук размещается в отдельном файле с именем `use-.hook-api.ts` в папке `hooks/api//` на своём уровне абстракции согласно архитектуре проекта. -- Имя хука — в стиле camelCase с префиксом `use` (например, `useGetUser`). -- Для сложных возвращаемых структур используйте отдельные типы или интерфейсы, размещая их в папке `types/` на своём уровне абстракции. - -## Именование -- Соблюдайте [правила именования файлов и папок](#правила-именования-файлов-и-папок): - - Файл хука — `use-.hook-api.ts` (kebab-case). - - Имя хука — camelCase с префиксом `use`. - -## Требования -- Хук должен быть строго типизирован: все параметры, возвращаемые значения и внутренние переменные должны иметь явные типы. -- Для получения данных используйте только SWR. -- Не дублируйте логику между хуками — общие части выносите в shared. -- Не используйте side-effects вне useEffect/useLayoutEffect. - -## Типизация -- Всегда явно указывайте типы для всех параметров, возвращаемых значений и состояния внутри хука. -- Придерживайтесь [общих правил типизации проекта](#общие-правила-типизации). -- Не используйте неявное приведение типов и не полагайтесь на автоматический вывод, если это может снизить читаемость или безопасность. - -## Документирование -- Документируйте только назначение хука (описание), строго по [правилам документирования кода](#правило-для-документирования-кода). - -## Экспорт -- Экспортируйте хук только именованным экспортом через `index.ts` слоя/компонента. - -## Пример API хука - -```ts -// use-get-me.hook-api.ts -import useSWR from 'swr'; -import { backendFetcher } from 'shared/api/backend/client'; -import { UserDto } from 'shared/api/backend/entities/users/get-me.api'; - -/** - * Хук для получения информации о текущем пользователе. - */ -export const useGetMe = () => { - const { data, error, isLoading } = useSWR('/users/me', backendFetcher); - - return { - data, - error, - isLoading, - }; -}; -``` - -### Пример использования хука в компоненте - -```tsx -import React from 'react'; -import { useGetMe } from 'shared/hooks/api/backend/use-get-me.hook-api'; - -export const UserInfo: React.FC = () => { - const { data, error, isLoading } = useGetMe(); - - if (isLoading) { - return
Загрузка...
; - } - - if (error) { - return
Ошибка загрузки данных
; - } - - if (!data) { - return
Нет данных о пользователе
; - } - - return ( -
-
Имя: {data.name}
-
Email: {data.email}
-
- ); -}; -``` - -## Чек-лист для создания API-хука - -- [ ] Для каждого GET-запроса создан отдельный хук. -- [ ] Хук размещён в `hooks/api//use-.hook-api.ts` на своём уровне абстракции согласно архитектуре проекта. -- [ ] Именование файлов и сущностей соответствует [правилам именования файлов и папок](#правила-именования-файлов-и-папок). -- [ ] Используется SWR для получения данных. -- [ ] Все параметры, возвращаемые значения и внутренние переменные строго типизированы. -- [ ] Нет дублирования логики между хуками. -- [ ] Не используются side-effects вне useEffect/useLayoutEffect. -- [ ] Документировано только назначение хука (см. [правила документирования кода](#правило-для-документирования-кода)). -- [ ] Нет неиспользуемого или невалидного кода. -- [ ] Экспорт только именованный через индексный файл. - ---- - -## Чек-лист для использования API-хука - -- [ ] Импортируется только нужный хук через публичные экспорты (`index.ts`). -- [ ] Использование хука строго по назначению (только для получения данных). -- [ ] Если требуется получить данные через GET-запрос в компоненте — обязательно используется соответствующий API-хук. - **Запрещено вызывать GET-методы API напрямую в компонентах, только через хуки.** -- [ ] Обработка состояний загрузки, ошибки и данных реализована корректно. -- [ ] Не происходит дублирования логики, связанной с получением данных. -- [ ] Нет неиспользуемого или невалидного кода. diff --git a/OLD_parts/15-api.md b/OLD_parts/15-api.md deleted file mode 100644 index 17d2cb6..0000000 --- a/OLD_parts/15-api.md +++ /dev/null @@ -1,242 +0,0 @@ -# API - -> В этом разделе собраны основные правила и рекомендации по созданию, оформлению и использованию API-клиентов и функций для работы с сервером. Следуйте этим принципам, чтобы обеспечить единый стиль, безопасность и удобство поддержки API-слоя в проекте. - -## Описание и назначение API-клиента - -API-клиент — это модуль (папка), отвечающий за взаимодействие с конкретным внешним или внутренним API. -В проекте для HTTP-запросов используется только Axios. -API-клиент инкапсулирует: -- инициализацию экземпляра Axios, -- настройку базового URL, интерцепторов, обработчиков ошибок, -- организацию всех сущностей и методов для работы с этим API (например, users, auth, orders и т.д.), -- экспорт всех функций, типов и fetcher через индексные файлы. - -Каждый API-клиент размещается в папке `src/shared/api//` и имеет собственную структуру согласно архитектуре проекта. - - -## Использование методов API - -- Все методы API должны использоваться строго внутри блока `try...catch`. -- При вызове методов API всегда используйте полный путь, например: - `await api.backend.createUser({ email, password });` -- Запрещено вызывать методы API вне блока `try...catch` даже в тестах, утилитах и других вспомогательных функциях. - - -## Структура клиента -```text -src/shared/api/backend/ -│ -├── client.ts -├── index.ts -└── entities/ - ├── users/ - │ ├── get-me.api.ts - │ ├── create-user.api.ts - │ ├── update-user.api.ts - │ └── index.ts - ├── auth/ - │ ├── login.api.ts - │ ├── register.api.ts - │ └── index.ts - └── index.ts -``` - -## Описание ключевых элементов - -- **client.ts** - Экземпляр Axios с настройками, интерцепторами, экспортом fetcher для SWR. - -- **index.ts** - Главная точка экспорта: экспортирует client, fetcher, все сущности и их методы. - -- **entities/** - Папка для бизнес-сущностей (например, users, auth, orders и т.д.). - -- **`/`** - Папка для отдельной сущности. Имя — в kebab-case, отражает бизнес-область (например, users, auth). - -- **`.api.ts`** - Файл для каждой операции (CRUD, спец. действия). - Внутри: - - DTO (интерфейсы запроса/ответа) - - Функция, реализующая запрос через client - -- **index.ts (внутри ``/)** - Экспортирует все методы и типы этой сущности. - -- **index.ts (внутри entities/)** - Экспортирует все сущности (users, auth и т.д.). - - -## Именование - -- Соблюдайте [правила именования файлов и папок](#правила-именования-файлов-и-папок): - - Файл клиента — `client.ts`. - - Файл функции — `-.api.ts` (например, `create-user.api.ts`). - - DTO — в папке `dto/` (например, `create-user.dto.ts`). - - Все функции и типы экспортируются через индексные файлы на каждом уровне (сущность, entities, клиент). - - -## Требования - -- Для каждого действия (CRUD, спец. действия) — отдельная функция и файл. -- Все функции используют общий экземпляр Axios из `client.ts`. -- Все функции строго типизированы (используются DTO). -- DTO объявляется в отдельном файле в папке `dto/` перед функцией, которая его использует. -- Для каждого GET метода обязательно должен быть создан API-хук. -- Все API-хуки должны создаваться строго по [документации раздела "Хуки для API"](#хуки-для-api-api-hooks). - - -## Типизация - -- Все функции и DTO строго типизированы. -- Все интерфейсы, типы и enum размещены в папке `types/` на своём уровне абстракции. -- Все DTO размещены в папке `dto/` на своём уровне абстракции. -- Придерживайтесь [общих правил типизации проекта](#общие-правила-типизации). - - -## Документирование - -- Документируйте только назначение функций и DTO. -- В описании указывается только смысл функции/типа. - - -## Экспорт - -- Все функции и типы экспортируются через индексные файлы на каждом уровне (сущность, entities, клиент). - - -## Примеры - -### Пример клиента API - -```ts -// client.ts -import axios, { AxiosInstance } from "axios"; -export { AxiosError, isAxiosError } from 'axios'; -export type { AxiosResponse } from 'axios'; - -/** - * Экземпляр HTTP-клиента для работы с backend API. - */ -export const backendHttpClient: AxiosInstance = axios.create({ - baseURL: '/api', - timeout: 10000, -}); - -// Интерцептор запроса -backendHttpClient.interceptors.request.use( - (config) => { - // Здесь можно добавить авторизационные заголовки или другую логику - return config; - }, - (error) => Promise.reject(error) -); - -// Интерцептор ответа -backendHttpClient.interceptors.response.use( - (response) => response, - (error) => { - // Здесь можно обработать ошибки (например, показать уведомление) - return Promise.reject(error); - } -); -``` - -### Пример DTO - -```ts -// dto/create-user.dto.ts -/** - * DTO для создания пользователя. - */ -export interface CreateUserDto { - /** Email пользователя. */ - email: string; - /** Пароль пользователя. */ - password: string; -} -``` - -### Пример API-функции - -```ts -// create-user.api.ts -import { backendHttpClient } from '../client'; -import { CreateUserDto } from './dto/create-user.dto'; - -/** - * Создать пользователя. - */ -export const createUser = (data: CreateUserDto) => backendHttpClient.post('/users', data); -``` - -### Пример index.ts (в папке сущности) - -```ts -export * from './create-user.api'; -export * from './get-user.api'; -``` - -### Пример использования API-функции в компоненте - -```tsx -import React, { useState } from 'react'; -import { api } from 'shared/api'; - -export const CreateUserForm: React.FC = () => { - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); - - const handleSubmit = async (e: React.FormEvent) => { - e.preventDefault(); - try { - await api.backend.createUser({ email, password }); - console.log('Пользователь создан!'); - } catch { - console.log('Ошибка создания пользователя'); - } - }; - - return ( -
- setEmail(e.target.value)} - placeholder="Email" - required - /> - setPassword(e.target.value)} - placeholder="Пароль" - required - /> - -
- ); -}; -``` - - -## Чек-лист для создания клиента -- [ ] Новый клиент размещён в `src/shared/api//`. -- [ ] В корне клиента есть client.ts (экземпляр Axios) и index.ts (главный экспорт). -- [ ] Все бизнес-сущности размещены в entities/, каждая — в отдельной папке. -- [ ] Для каждой операции создан отдельный файл ``.api.ts с DTO и функцией. -- [ ] DTO объявлен непосредственно перед функцией. -- [ ] В каждой папке сущности есть свой index.ts для экспорта методов и типов. -- [ ] В папке entities/ есть общий index.ts для экспорта всех сущностей. -- [ ] Все экспорты организованы через индексные файлы. -- [ ] Для каждого GET-метода создан отдельный SWR-хук (см. правила API-хуков). -- [ ] Нет дублирования кода и неиспользуемых файлов. - -## Чек-лист для использования API -- [ ] Импортируется только нужный метод через публичные экспорты (index.ts). -- [ ] Все вызовы API обёрнуты в try...catch. -- [ ] Используются только строго типизированные методы. -- [ ] Не происходит обращения к Axios напрямую — только через client. -- [ ] Нет дублирования логики и неиспользуемого кода. diff --git a/OLD_parts/3-general-principles.md b/OLD_parts/3-general-principles.md deleted file mode 100644 index 94ce72b..0000000 --- a/OLD_parts/3-general-principles.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Общие принципы ---- - -# Общие принципы - -## Стек технологий и библиотеки -- Использовать **TypeScript** для всех файлов логики и компонентов. -- Использовать **FSD (Feature-Sliced Design)**: разделять код на features, entities, processes, widgets, shared. -- Использовать **React** (функциональные компоненты, хуки). -- Использовать **Mantine UI** для UI-компонентов. -- Использовать **Axios** в качестве клиента для работы с API. -- Использовать **SWR** для data fetching (GET-запросы). -- Использовать **Zustand** для глобального состояния. -- Использовать **i18n** для локализации. -- Использовать **Vitest** для тестирования. -- Использовать **PostCSS модули** для стилизации. -- Использовать **BEM** для именований классов в стилях -- Использовать **Mobile First** подход для написания стилей. -- Использовать **Context7** примеров использования библиотек. -- Использовать **i18n** (i18next) для локализации всех пользовательских текстов. diff --git a/OLD_parts/4-arkhitektura.md b/OLD_parts/4-arkhitektura.md deleted file mode 100644 index eaf7289..0000000 --- a/OLD_parts/4-arkhitektura.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Архитектура ---- - -# Архитектура - -## Архитектура проекта -В проекте используется FSD (Feature-Sliced Design) архитектура. - -- **FSD-границы** - - Не нарушать границы слоёв (например, feature не может импортировать из widgets). - - Бизнес-логика должна быть вынесена в хуки или сервисы. -- **Импорты** - - Внутри слоя — относительные импорты. - - Между слоями — абсолютные импорты. -- **Требования** - - Не смешивать логику разных слоёв. - - Не хранить бизнес-логику в UI-компонентах. -- **Именование** - - Файлы и папки kebab-case. - ---- diff --git a/OLD_parts/5-code-style.md b/OLD_parts/5-code-style.md deleted file mode 100644 index 297395b..0000000 --- a/OLD_parts/5-code-style.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Стиль кода ---- - -# Стиль кода - -## Отступы - - Используем 2 пробела для отступов во всём проекте. Не используем табы. - - -## Кавычки - -Используем **одинарные кавычки** для строк в JavaScript/TypeScript, и **двойные кавычки** для атрибутов в JSX/TSX. - -**Пример:** - -```ts -// JavaScript/TypeScript -const message = 'Привет, мир!'; -const name = 'ProjectName'; -``` - -```tsx -// JSX/TSX - - -``` - -## Строгая типизация - -всегда указывать типы для пропсов, возвращаемых значений, параметров функций. - -## Ранние возвраты - -(early return) для повышения читаемости. - -## Мемоизация - -Старайся оптимизировать код если это возможно. - -## Документирование - -Документируем ТОЛЬКО ОПИСАНИЕ (функций, компонентов, типов и их полей). - -## any, unknown - -запрещено использовать без крайней необходимости. - -## Классы в TSX - -Для стилизации компонентов используем CSS-модули и методологию BEM. Классы подключаются через объект стилей, импортированный из соответствующего `.module.css` файла. - -> Объект стилей всегда импортируется с именем `s` (сокращённо от style), а не `styles`. - -**Пример:** - -```tsx -import s from './my-component.module.css'; - -export const MyComponent = () => ( -
- - Текст - -
-); -``` - -- Имя класса всегда берётся из объекта `s`. -- Для модификаторов используется отдельный класс с нижним подчёркиванием (например, `s._active`). -- Не используйте строковые литералы с классами напрямую — только через объект `s`. diff --git a/OLD_parts/6-naming.md b/OLD_parts/6-naming.md deleted file mode 100644 index 8275ba6..0000000 --- a/OLD_parts/6-naming.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Именование ---- - -# Именование - -## Именование файлов и папок -- Папка компонента: kebab-case, совпадает с названием компонента, пример: `component-name`. -- React-компонент: kebab-case, совпадает с названием компонента, пример: `component-name.tsx`. -- Стили: kebab-case, шаблон: `.module.css`, пример: `style-name.module.css`. -- Интерфейсы: kebab-case, шаблон: `.interface.ts`, пример: `interface-name.interface.ts`. -- Типы: kebab-case, шаблон: `.type.ts`, пример: `type-name.type.ts`. -- Enum: kebab-case, шаблон: `.enum.ts`, пример: `enum-name.enum.ts`. -- Схемы: kebab-case, шаблон: `.schema.ts`, пример: `schema-name.schema.ts`. -- Локализация: kebab-case, пример: `ru.json`, `en.json`. -- Утилиты: kebab-case, шаблон: `.util.ts`, пример: `util-name.util.ts` -- React Hooks: kebab-case, шаблон: `use-.hook.ts`, пример: `use-hook-name.hook.ts` -- Хранилища состояния компонента: kebab-case, шаблон: `.store.ts`, пример: `store-name.store.ts` diff --git a/OLD_parts/7-docs.md b/OLD_parts/7-docs.md deleted file mode 100644 index 2d58d42..0000000 --- a/OLD_parts/7-docs.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Документирование ---- - -# Документирование - -## Правило для документирования кода - -- Документировать разрешено только описание (назначение) функций, компонентов, типов, интерфейсов, enum и их полей. -- Строго запрещено документировать параметры, возвращаемые значения, типы пропсов, аргументы, возвращаемые значения функций, компоненты, хуки и т.д. -- В интерфейсах, типах и enum разрешено документировать только смысл (описание) каждого поля или значения. -- В React-компонентах, функциях, хранилищах, схемах, утилитах разрешено документировать только назначение (описание), без детализации параметров и возвращаемых значений. -- Описание должно быть кратким, информативным и реально помогать понять структуру и бизнес-логику. -- Не допускается избыточная или дублирующая очевидное документация. -- В конце описания всегда ставить точку. - -**Примеры правильного документирования** -```tsx -/** - * Список задач пользователя. - */ -export const TodoList = memo(() => { ... }); - -/** - * Интерфейс задачи. - */ -export interface TodoItem { - /** Уникальный идентификатор задачи. */ - id: string; - /** Текст задачи. */ - text: string; - /** Статус выполнения задачи. */ - completed: boolean; -} - -/** - * Перечисление фильтров задач. - */ -export enum TodoFilter { - /** Все задачи. */ - All = 'all', - /** Только активные задачи. */ - Active = 'active', - /** Только выполненные задачи. */ - Completed = 'completed', -} -``` - -**Примеры неправильного документирования** -```ts -// ❌ Не нужно:/ -/** - * @param id - идентификатор задачи - * @returns объект задачи - */ - -// ❌ Не нужно:/ -/** - * @param props - пропсы компонента - * @returns JSX.Element - */ - -// ❌ Не нужно:/ -/** - * id — идентификатор задачи - * text — текст задачи - * completed — статус выполнения - */ -``` diff --git a/OLD_parts/8-typing.md b/OLD_parts/8-typing.md deleted file mode 100644 index e16c47b..0000000 --- a/OLD_parts/8-typing.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: Типизация ---- - -# Типизация - -## Общие правила типизации - -> Данный раздел определяет единые требования к типизации для всего проекта. Соблюдение этих правил обеспечивает читаемость, предсказуемость и безопасность кода. - -- Использовать только строгую типизацию TypeScript для всех файлов логики, компонентов, хуков, API, сторов и утилит. -- Всегда явно указывать типы для: - - Пропсов компонентов - - Параметров функций и методов - - Возвращаемых значений функций и методов - - Всех переменных состояния (в том числе в store) - - Всех значимых переменных и констант, если их тип не очевиден из присваивания -- Не использовать `any` и `unknown` без крайней необходимости. Если использование неизбежно — обязательно добавить комментарий с обоснованием. -- Все интерфейсы, типы и enum всегда размещать в папке `types/` на своём уровне абстракции (например, `features/todo/types/`). -- Для DTO всегда использовать отдельную папку `dto/` на уровне сущности или слоя. -- Для сложных структур использовать отдельные интерфейсы или типы, размещая их в соответствующих файлах в папке `types/`. -- Для DTO, enum, схем и других сущностей — всегда создавать отдельные типы/интерфейсы с осмысленными именами. -- Ключи enum всегда писать ЗАГЛАВНЫМИ_БУКВАМИ (SCREAMING_SNAKE_CASE). -- Не использовать неявное приведение типов и не полагаться на автоматический вывод, если это может снизить читаемость или безопасность. -- Для массивов и объектов всегда указывать тип элементов/ключей. -- Для возвращаемых значений асинхронных функций всегда указывать тип Promise. -- Типизацию коллбеков и функций, передаваемых в пропсы, указывать инлайн, не выносить в отдельные типы. -- Для типизации внешних библиотек использовать официальные типы или создавать собственные декларации при необходимости. -- Не использовать устаревшие или не рекомендуемые паттерны типизации (например, `Function`, `Object`, `{}`). ---- - -### Примеры - -#### Интерфейс и типы для сущностей (всегда в папке types/) - -```ts -// features/todo/types/todo-item.interface.ts - -/** - * Интерфейс задачи. - */ -export interface TodoItem { - /** Уникальный идентификатор задачи. */ - id: string; - /** Текст задачи. */ - text: string; - /** Статус выполнения задачи. */ - completed: boolean; -} -``` - -#### Типизация enum (всегда в папке types/) - -```ts -// features/todo/types/todo-status.enum.ts - -/** - * Перечисление статусов задачи. - */ -export enum TodoStatus { - /** Активная задача. */ - ACTIVE = 'active', - /** Выполненная задача. */ - COMPLETED = 'completed', -} -``` - -#### Типизация пропсов компонента - -```ts -import { FC, memo } from 'react'; -import { TodoItem } from './types/todo-item.interface'; - -/** - * Список задач. - */ -export interface TodoListProps { - /** Массив задач. */ - items: TodoItem[]; -} - -export const TodoList: FC = memo(({ items }) => ( -
    - {items.map((item) => ( -
  • {item.text}
    • - ))} -
-)); -``` - -#### Типизация функций и коллбеков (инлайн) - -```ts -/** - * Функция фильтрации задач. - */ -export const getCompletedTodos = (items: TodoItem[]): TodoItem[] => { - return items.filter((t) => t.completed); -}; - -/** - * Колбэк для обработки клика (инлайн). - */ -const handleClick = (id: string): void => { - console.log('Clicked:', id); -}; -``` - -#### Типизация асинхронных функций - -```ts -/** - * Получить задачи с сервера. - */ -export const fetchTodos = async (): Promise => { - const response = await fetch('/api/todos'); - return response.json(); -}; -``` - -#### Типизация состояния в store (интерфейс в types/) - -```ts -// features/todo/types/todo-store.interface.ts - -/** - * Состояние хранилища задач. - */ -export interface TodoStoreState { - /** Массив задач. */ - items: TodoItem[]; - /** Добавить задачу. */ - addTodo: (item: TodoItem) => void; - /** Удалить задачу. */ - removeTodo: (id: string) => void; -} -``` - -#### Типизация DTO (всегда в папке dto/) - -```ts -// features/todo/dto/create-todo.dto.ts - -/** - * DTO для создания задачи. - */ -export interface CreateTodoDto { - /** Текст задачи. */ - text: string; -} - -// features/todo/dto/todo-response.dto.ts - -/** - * DTO ответа сервера. - */ -export interface TodoResponseDto { - /** Созданная задача. */ - todo: TodoItem; -} -``` - -#### Типизация внешних библиотек - -```ts -import type { AxiosResponse } from 'axios'; - -export const getData = async (): Promise> => { - // ... -}; -``` -### Чек-лист проверки типизации - -- [ ] Все пропсы компонентов явно типизированы через интерфейс или тип в папке `types/`. -- [ ] Все параметры и возвращаемые значения функций и методов явно типизированы. -- [ ] Все переменные состояния (в том числе в store) имеют явные типы. -- [ ] Все интерфейсы, типы и enum размещены в папке `types/` на своём уровне абстракции. -- [ ] Ключи всех enum написаны ЗАГЛАВНЫМИ_БУКВАМИ (SCREAMING_SNAKE_CASE). -- [ ] Все DTO размещены в папке `dto/` на своём уровне абстракции. -- [ ] Не используется `any` и `unknown` без крайней необходимости и поясняющего комментария. -- [ ] Для сложных структур используются отдельные интерфейсы или типы. -- [ ] Для массивов и объектов указан тип элементов/ключей. -- [ ] Для асинхронных функций указан тип Promise с конкретным типом результата. -- [ ] Типы коллбеков и функций, передаваемых в пропсы, указаны инлайн. -- [ ] Не используются устаревшие типы (`Function`, `Object`, `{}`). -- [ ] Для внешних библиотек используются официальные типы или собственные декларации. -- [ ] Нет неявного приведения типов, все типы читаемы и прозрачны. diff --git a/OLD_parts/9-localization.md b/OLD_parts/9-localization.md deleted file mode 100644 index 089e517..0000000 --- a/OLD_parts/9-localization.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Локализация ---- - -# Локализация - -## Правила использования локализации - -- Все пользовательские тексты должны быть вынесены в локализационные файлы. -- Для каждого компонента создавать папку `locales/` с файлами `ru.json`, `en.json` и т.д. -- Новые namespace обязательно регистрировать в экземпляре i18n (см. `app/i18n.ts`). -- В коде использовать только функцию перевода из i18n, не использовать "жёстко" прописанные строки. diff --git a/README.md b/README.md index e8a6ee4..24405ad 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # NextJS Style Guide -Соглашения по разработке Next.js проектов: архитектура и слои приложения, структура кода, организация модулей, стилизация, типизация и инфраструктура. +Стандарты разработки фронтенд-приложений на Next.js и TypeScript. Сайт: https://nextjs-style-guide.gromlab.ru @@ -17,9 +17,9 @@ ## Структура документации -### Workflow +### Подсказки -[Workflow](docs/docs/workflow.md) — пошаговая карта типовых задач: с чего начать, как добавить страницу/компонент, как подключить данные, стили, локализацию. +[Подсказки](docs/docs/workflow.md) — короткие ответы на типовые вопросы и решения для спорных ситуаций. ### Базовые правила @@ -29,7 +29,7 @@ |--------|-------------------| | Технологии и библиотеки | Какой стек используем? | | Именование | Как называть файлы, переменные, компоненты, хуки? | -| Архитектура: Обзор | Что такое SLM и зачем она нужна? | +| SLM Design | Что такое SLM и зачем она нужна? | | Архитектура: Слои | Какие слои есть и как между ними устроены зависимости? | | Архитектура: Модули | Что такое модуль и как он устроен? | | Архитектура: Сегменты | Какие сегменты есть внутри модуля? | @@ -37,20 +37,27 @@ | Документирование | Как писать JSDoc: что документировать, а что нет? | | Типизация | Как типизировать: type vs interface, any/unknown? | -### Установка и настройка +### Создание проекта -**Как поднять и сконфигурировать проект** — пошаговая настройка инструментов и инфраструктуры. +**Как начать новый проект** — варианты установки и эталонный набор инструментов. | Раздел | Отвечает на вопрос | |--------|-------------------| -| Создание проекта: Из шаблона | Как начать проект из готового шаблона? | -| Создание проекта: Вручную | Как поднять проект с нуля без шаблона? | -| Next.js | Как настроить Next.js под проект? | -| Алиасы | Как настроить путевые алиасы импортов? | -| Biome | Как настроить Biome (линтер и форматер)? | -| Стили | Как подключить и настроить стили проекта? | +| Создание проекта из шаблона | Как начать проект из готового шаблона? | +| Создание проекта вручную | Как поднять проект с нуля без шаблона? | +| Чистая установка Next.js | Как поставить голый Next.js под дальнейшую сборку? | + +### Настройка + +**Как сконфигурировать проект** — пошаговая настройка инструментов и инфраструктуры. + +| Раздел | Отвечает на вопрос | +|--------|-------------------| +| Алиасы импортов | Как настроить алиасы импортов? | +| Biome | Как настроить линтер и форматтер? | | PostCSS | Какие плагины PostCSS нужны и как их настроить? | -| SVG-спрайты | Как настроить генерацию SVG-спрайтов? | +| Стили | Как подключить базовые стили и токены? | +| SVG-спрайты | Как подключить генерацию SVG-спрайтов? | | Шаблоны генерации | Как подключить шаблоны для кодогенерации? | | VS Code | Как настроить редактор для проекта? | @@ -62,19 +69,26 @@ |--------|-------------------| | Структура проекта | Как организованы папки и файлы по SLM? | | Компоненты | Как устроен компонент: файлы, пропсы, clsx? | -| Страницы (App Router) | Как описывать layout, page, loading, error, not-found? | -| Данные: Введение | Как устроена работа с данными в проекте? | -| Данные: REST: Клиенты: Автоматическая генерация | Как сгенерировать REST-клиент автоматически из OpenAPI? | -| Данные: REST: Клиенты: Ручное создание | Как написать REST-клиент вручную? | -| Данные: REST: Получение данных: Серверные компоненты | Как получать данные в серверных компонентах? | -| Данные: REST: Получение данных: Клиентские компоненты | Как получать данные в клиентских компонентах (SWR)? | -| Данные: Realtime | Как работать с realtime-каналами и сокетами? | +| Файлы роутинга | Как описывать layout, page, loading, error, not-found? | | Шаблоны и генерация кода | Как работают шаблоны, синтаксис и инструменты генерации? | -| Стили | Как писать CSS: PostCSS Modules, вложенность, медиа, токены? | -| Изображения | _(не заполнен)_ | +| Стили | Как писать CSS: вложенность, медиа, токены? | | SVG-спрайты | Как использовать SVG-спрайты в коде? | +| Изображения | _(не заполнен)_ | | Видео | _(не заполнен)_ | | Stores | _(не заполнен)_ | | Хуки | _(не заполнен)_ | | Шрифты | _(не заполнен)_ | | Локализация | _(не заполнен)_ | + +### Данные + +**Как работать с источниками данных** — REST, realtime и потребление в компонентах. + +| Раздел | Отвечает на вопрос | +|--------|-------------------| +| Источники данных | Как устроена работа с данными в проекте? | +| REST: Автоматическая генерация | Как сгенерировать REST-клиент автоматически из OpenAPI? | +| REST: Ручное создание | Как написать REST-клиент вручную? | +| REST: Серверные компоненты | Как получать данные в серверных компонентах? | +| REST: Клиентские компоненты | Как получать данные в клиентских компонентах? | +| Realtime | Как работать с realtime-каналами и сокетами? | diff --git a/docs-overview.md b/docs-overview.md index 394ccc8..7deadb8 100644 --- a/docs-overview.md +++ b/docs-overview.md @@ -30,16 +30,16 @@ **Описание:** Архитектурный подход проекта: что такое SLM и как он устроен. ### docs/docs/basics/architecture/reference/layers.md -**Заголовок:** Слои -**Описание:** Из каких слоёв состоит архитектура и как они связаны. +**Заголовок:** Слои SLM +**Описание:** Из каких слоёв состоит SLM-архитектура и как они связаны. ### docs/docs/basics/architecture/reference/modules.md -**Заголовок:** Модули -**Описание:** Что такое модуль в архитектуре и как он устроен. +**Заголовок:** Модули SLM +**Описание:** Что такое модуль в SLM-архитектуре и как он устроен. ### docs/docs/basics/architecture/reference/segments.md -**Заголовок:** Сегменты -**Описание:** Что такое сегмент модуля и какие они бывают. +**Заголовок:** Сегменты SLM +**Описание:** Что такое сегмент модуля в SLM-архитектуре и какие они бывают. ### docs/docs/basics/code-style.md **Заголовок:** Стиль кода @@ -154,11 +154,11 @@ **Описание:** Какие источники данных используются в проекте и как с ними работать. ### docs/docs/usage/data/rest/clients/auto.md -**Заголовок:** Автоматическая генерация +**Заголовок:** Автогенерация REST-клиента **Описание:** Генерация REST-клиента из OpenAPI-спецификации. ### docs/docs/usage/data/rest/clients/manual.md -**Заголовок:** Ручное создание +**Заголовок:** Ручное создание REST-клиента **Описание:** Создание REST-клиента вручную, когда нет OpenAPI-спецификации. ### docs/docs/usage/data/rest/fetching/server.md diff --git a/docs/docs/basics/architecture/reference/layers.md b/docs/docs/basics/architecture/reference/layers.md index 5bb065d..c9f3407 100644 --- a/docs/docs/basics/architecture/reference/layers.md +++ b/docs/docs/basics/architecture/reference/layers.md @@ -1,11 +1,11 @@ --- -title: Слои -description: Из каких слоёв состоит архитектура и как они связаны. +title: Слои SLM +description: Из каких слоёв состоит SLM-архитектура и как они связаны. --- -# Слои +# Слои SLM -Из каких слоёв состоит архитектура и как они связаны. +Из каких слоёв состоит SLM-архитектура и как они связаны. ## Определение diff --git a/docs/docs/basics/architecture/reference/modules.md b/docs/docs/basics/architecture/reference/modules.md index 224f5c8..ee607fb 100644 --- a/docs/docs/basics/architecture/reference/modules.md +++ b/docs/docs/basics/architecture/reference/modules.md @@ -1,11 +1,11 @@ --- -title: Модули -description: Что такое модуль в архитектуре и как он устроен. +title: Модули SLM +description: Что такое модуль в SLM-архитектуре и как он устроен. --- -# Модули +# Модули SLM -Что такое модуль в архитектуре и как он устроен. +Что такое модуль в SLM-архитектуре и как он устроен. ## Определение diff --git a/docs/docs/basics/architecture/reference/segments.md b/docs/docs/basics/architecture/reference/segments.md index 92ebf39..22eb7b0 100644 --- a/docs/docs/basics/architecture/reference/segments.md +++ b/docs/docs/basics/architecture/reference/segments.md @@ -1,11 +1,11 @@ --- -title: Сегменты -description: Что такое сегмент модуля и какие они бывают. +title: Сегменты SLM +description: Что такое сегмент модуля в SLM-архитектуре и какие они бывают. --- -# Сегменты +# Сегменты SLM -Что такое сегмент модуля и какие они бывают. +Что такое сегмент модуля в SLM-архитектуре и какие они бывают. ## Определение diff --git a/docs/docs/index.md b/docs/docs/index.md index 2448d4f..80cacc5 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -20,9 +20,9 @@ description: Стандарты разработки фронтенд-прило ## Структура документации -### Workflow +### Подсказки -[Workflow](/docs/workflow) — пошаговая карта типовых задач: с чего начать, как добавить страницу/компонент, как подключить данные, стили, локализацию. +[Подсказки](/docs/workflow) — короткие ответы на типовые вопросы и решения для спорных ситуаций. ### Базовые правила @@ -32,7 +32,7 @@ description: Стандарты разработки фронтенд-прило |--------|-------------------| | Технологии и библиотеки | Какой стек используем? | | Именование | Как называть файлы, переменные, компоненты, хуки? | -| Архитектура: Обзор | Что такое SLM и зачем она нужна? | +| SLM Design | Что такое SLM и зачем она нужна? | | Архитектура: Слои | Какие слои есть и как между ними устроены зависимости? | | Архитектура: Модули | Что такое модуль и как он устроен? | | Архитектура: Сегменты | Какие сегменты есть внутри модуля? | @@ -40,20 +40,27 @@ description: Стандарты разработки фронтенд-прило | Документирование | Как писать JSDoc: что документировать, а что нет? | | Типизация | Как типизировать: type vs interface, any/unknown? | -### Установка и настройка +### Создание проекта -**Как поднять и сконфигурировать проект** — пошаговая настройка инструментов и инфраструктуры. +**Как начать новый проект** — варианты установки и эталонный набор инструментов. | Раздел | Отвечает на вопрос | |--------|-------------------| -| Создание проекта: Из шаблона | Как начать проект из готового шаблона? | -| Создание проекта: Вручную | Как поднять проект с нуля без шаблона? | -| Next.js | Как настроить Next.js под проект? | -| Алиасы | Как настроить путевые алиасы импортов? | -| Biome | Как настроить Biome (линтер и форматер)? | -| Стили | Как подключить и настроить стили проекта? | +| Создание проекта из шаблона | Как начать проект из готового шаблона? | +| Создание проекта вручную | Как поднять проект с нуля без шаблона? | +| Чистая установка Next.js | Как поставить голый Next.js под дальнейшую сборку? | + +### Настройка + +**Как сконфигурировать проект** — пошаговая настройка инструментов и инфраструктуры. + +| Раздел | Отвечает на вопрос | +|--------|-------------------| +| Алиасы импортов | Как настроить алиасы импортов? | +| Biome | Как настроить линтер и форматтер? | | PostCSS | Какие плагины PostCSS нужны и как их настроить? | -| SVG-спрайты | Как настроить генерацию SVG-спрайтов? | +| Стили | Как подключить базовые стили и токены? | +| SVG-спрайты | Как подключить генерацию SVG-спрайтов? | | Шаблоны генерации | Как подключить шаблоны для кодогенерации? | | VS Code | Как настроить редактор для проекта? | @@ -65,19 +72,26 @@ description: Стандарты разработки фронтенд-прило |--------|-------------------| | Структура проекта | Как организованы папки и файлы по SLM? | | Компоненты | Как устроен компонент: файлы, пропсы, clsx? | -| Страницы (App Router) | Как описывать layout, page, loading, error, not-found? | -| Данные: Введение | Как устроена работа с данными в проекте? | -| Данные: REST: Клиенты: Автоматическая генерация | Как сгенерировать REST-клиент автоматически из OpenAPI? | -| Данные: REST: Клиенты: Ручное создание | Как написать REST-клиент вручную? | -| Данные: REST: Получение данных: Серверные компоненты | Как получать данные в серверных компонентах? | -| Данные: REST: Получение данных: Клиентские компоненты | Как получать данные в клиентских компонентах (SWR)? | -| Данные: Realtime | Как работать с realtime-каналами и сокетами? | +| Файлы роутинга | Как описывать layout, page, loading, error, not-found? | | Шаблоны и генерация кода | Как работают шаблоны, синтаксис и инструменты генерации? | -| Стили | Как писать CSS: PostCSS Modules, вложенность, медиа, токены? | -| Изображения | _(не заполнен)_ | +| Стили | Как писать CSS: вложенность, медиа, токены? | | SVG-спрайты | Как использовать SVG-спрайты в коде? | +| Изображения | _(не заполнен)_ | | Видео | _(не заполнен)_ | | Stores | _(не заполнен)_ | | Хуки | _(не заполнен)_ | | Шрифты | _(не заполнен)_ | | Локализация | _(не заполнен)_ | + +### Данные + +**Как работать с источниками данных** — REST, realtime и потребление в компонентах. + +| Раздел | Отвечает на вопрос | +|--------|-------------------| +| Источники данных | Как устроена работа с данными в проекте? | +| REST: Автоматическая генерация | Как сгенерировать REST-клиент автоматически из OpenAPI? | +| REST: Ручное создание | Как написать REST-клиент вручную? | +| REST: Серверные компоненты | Как получать данные в серверных компонентах? | +| REST: Клиентские компоненты | Как получать данные в клиентских компонентах? | +| Realtime | Как работать с realtime-каналами и сокетами? | diff --git a/docs/docs/usage/data/rest/clients/auto.md b/docs/docs/usage/data/rest/clients/auto.md index 4de1ac8..2bc3ae0 100644 --- a/docs/docs/usage/data/rest/clients/auto.md +++ b/docs/docs/usage/data/rest/clients/auto.md @@ -1,10 +1,10 @@ --- -title: Автоматическая генерация +title: Автогенерация REST-клиента description: Генерация REST-клиента из OpenAPI-спецификации. keywords: [api, rest, openapi, codegen, генерация, клиент, api-codegen, gromlab, infrastructure, swagger-typescript-api] --- -# Автоматическая генерация +# Автогенерация REST-клиента Генерация REST-клиента из OpenAPI-спецификации. diff --git a/docs/docs/usage/data/rest/clients/manual.md b/docs/docs/usage/data/rest/clients/manual.md index 80f03c6..beb5079 100644 --- a/docs/docs/usage/data/rest/clients/manual.md +++ b/docs/docs/usage/data/rest/clients/manual.md @@ -1,10 +1,10 @@ --- -title: Ручное создание +title: Ручное создание REST-клиента description: "Создание REST-клиента вручную, когда нет OpenAPI-спецификации." keywords: [api, rest, клиент, ручной, fetch, infrastructure, api-клиент] --- -# Ручное создание +# Ручное создание REST-клиента Создание REST-клиента вручную, когда нет OpenAPI-спецификации. diff --git a/notes b/notes deleted file mode 100644 index 7bfbf2f..0000000 --- a/notes +++ /dev/null @@ -1,153 +0,0 @@ -ФЛОУ - - после создания компонента, заменить шаблонный коментарий документа на реальный. - - - Проблема, неочевидность слоев (наследие FSD) - - -Архитектурные слои проекта -Каждый нижний слой не знает о существовании верхних. Импорты идут только сверху вниз. -pages → layouts → screens → widgets → features → entities → shared ---- -1. Pages (pages/) -Точка входа маршрута. Только связывает layout и screen. -Правила: -- Никакой логики, стилей, разметки кроме композиции -- Один page = один layout + один screen -Пример: -// pages/knv-new.js -import { KnvScreen } from 'src/screens/knv' -import { MainLayout } from 'src/layouts/main' -const KnvNewPage = () => ( - - - -) ---- -2. Layouts (src/layouts/) -Каркас страницы — общие элементы, которые одинаковы на всех страницах в рамках этого layout. -Содержит в ui/: header, footer, sidebar — дочерние компоненты, которые привязаны к layout и не переиспользуются отдельно. -Критерий: компонент одинаков на всех страницах, использующих этот layout? → layouts/{name}/ui/ -Пример: -src/layouts/main/ -├── main.layout.tsx #
+ children +