sync

parts/1-tech-stack.md

@@ -0,0 +1,20 @@
+---
+title: Стек технологий и библиотек
+---
+
+# Стек технологий и библиотек
+
+Базовый стек технологий и библиотек, на который опираются проекты и примеры в документации.
+
+## Что используем обычно
+
+- **TypeScript** — типизация всей логики и компонентов.
+- **FSD (Feature-Sliced Design)** — структура проекта и границы модулей.
+- **React + Next.js** — основной стек для UI и приложения.
+- **Mantine UI** — базовые UI-компоненты.
+- **SWR** — получение данных по GET (кеширование и revalidate).
+- **Zustand** — глобальное состояние.
+- **i18next (i18n)** — локализация всех пользовательских текстов.
+- **Vitest** — тестирование.
+- **PostCSS Modules** — изоляция стилей.
+- **Mobile First** — подход к адаптивной верстке.

parts/2-architecture.md

@@ -0,0 +1,49 @@
+---
+title: Архитектура
+---
+
+# Архитектура
+
+Архитектура построена на FSD (Feature‑Sliced Design) и строгих границах модулей.
+Цель — разделить ответственность, упростить сопровождение и контроль зависимостей.
+
+## Принципы
+
+- Разделять UI, бизнес-логику и инфраструктуру.
+- Держать зависимости однонаправленными.
+- Открывать наружу только публичный API модулей.
+- Не допускать циклических зависимостей.
+
+## Слои
+
+- **app** — инициализация приложения, роутинг, конфигурации, глобальные провайдеры.
+- **screens** — экраны и их композиция.
+- **layouts** — каркас и шаблоны страниц.
+- **widgets** — крупные блоки интерфейса, собирающие несколько сценариев.
+- **features** — отдельные пользовательские действия и сценарии.
+- **entities** — бизнес-сущности и их модель.
+- **shared** — переиспользуемая инфраструктура, утилиты и базовые UI‑компоненты.
+
+## Правила зависимостей
+
+- Допустимые импорты идут сверху вниз: `app → screens → layouts → widgets → features → entities → shared`.
+- Импорты между слоями — через публичный API.
+- Внутри одного слоя — относительные импорты.
+
+## Публичный API модулей
+
+- Каждый модуль экспортирует наружу только то, что нужно другим слоям.
+- Внешние импорты идут только через `index`‑файл модуля.
+- Внутренние файлы не импортируются напрямую извне.
+
+## Границы ответственности
+
+- Бизнес‑логика не размещается в UI‑компонентах.
+- UI‑компоненты должны быть максимально простыми и предсказуемыми.
+- Связь между независимыми сценариями поднимается на уровень выше.
+
+## Типовые ошибки
+
+- Импорт из более высокого слоя в более низкий.
+- Смешивание логики нескольких слоёв в одном модуле.
+- Прямые импорты внутренних файлов, минуя публичный API.

parts/3-code-style.md

@@ -0,0 +1,164 @@
+---
+title: Стиль кода
+---
+
+# Стиль кода
+
+Раздел описывает единые правила оформления кода: отступы, переносы, кавычки, порядок импортов и базовую читаемость.
+
+## Отступы и переносы
+
+- Использовать 2 пробела для отступов.
+- Не использовать табы.
+- Одна инструкция — одна строка.
+- Между логическими блоками оставлять пустую строку по необходимости, если это улучшает читаемость.
+- В многострочных конструкциях выравнивать закрывающую скобку по началу выражения.
+
+**Хорошо**
+```ts
+const payload = {
+  id: 1,
+  name: 'User',
+  meta: {
+    role: 'admin',
+  },
+};
+```
+
+**Плохо**
+```ts
+const payload = { id: 1, name: 'User', meta: { role: 'admin' } };
+```
+
+## Длина строк
+
+- Ориентироваться на 100 символов, но превышение допустимо, если строка читается легко.
+- Переносить выражение на новые строки, когда строка становится плохо читаемой.
+- Не переносить строку внутри строковых литералов без необходимости.
+
+**Хорошо**
+```ts
+const config = createRequestConfig(
+  endpoint,
+  {
+    headers: {
+      'X-Request-Id': requestId,
+      'X-User-Id': userId,
+    },
+    params: {
+      page,
+      pageSize,
+      sort: 'createdAt',
+    },
+  },
+  timeoutMs,
+);
+```
+
+**Плохо**
+```ts
+const config = createRequestConfig(endpoint, { headers: { 'X-Request-Id': requestId, 'X-User-Id': userId }, params: { page, pageSize, sort: 'createdAt' } }, timeoutMs);
+```
+
+## Кавычки
+
+- В JavaScript/TypeScript использовать одинарные кавычки.
+- В JSX/TSX для атрибутов использовать двойные кавычки.
+- Шаблонные строки использовать только при интерполяции или многострочном тексте.
+
+**Хорошо**
+```ts
+const label = 'Сохранить';
+const title = `Привет, ${name}`;
+```
+
+```tsx
+<input type="text" placeholder="Введите имя" />
+```
+
+**Плохо**
+```ts
+const label = "Сохранить";
+const title = 'Привет, ' + name;
+```
+
+```tsx
+<input type='text' placeholder='Введите имя' />
+```
+
+## Точки с запятой и запятые
+
+- Допускаются упущения точки с запятой, если код остаётся читаемым и однозначным.
+- В многострочных массивах, объектах и параметрах функции запятая в конце допускается, но не обязательна.
+
+## Импорты
+
+- В именованных импортах использовать пробелы внутри фигурных скобок.
+- Типы импортировать через `import type`.
+- `default` импорт и экспорт избегать, использовать именованные.
+- Избегать импорта всего модуля через `*`.
+
+**Хорошо**
+```ts
+import { MyComponent } from 'MyComponent';
+import type { User } from '../model/types';
+```
+
+**Плохо**
+```ts
+import MyComponent from 'MyComponent';
+import type {User} from '../model/types';
+```
+
+## Ранние возвраты (early return)
+
+- Использовать ранние возвраты для упрощения чтения.
+- Избегать `else` после `return`.
+
+**Хорошо**
+```ts
+const getName = (user?: { name: string }) => {
+  if (!user) {
+    return 'Гость';
+  }
+
+  return user.name;
+};
+```
+
+**Плохо**
+```ts
+const getName = (user?: { name: string }) => {
+  if (user) {
+    return user.name;
+  } else {
+    return 'Гость';
+  }
+};
+```
+
+## Форматирование объектов и массивов
+
+- В многострочных объектах каждое свойство на новой строке.
+- В многострочных массивах каждый элемент на новой строке.
+- Объекты и массивы можно писать в одну строку, если длина строки не превышает 100 символов.
+- В однострочных объектах и массивах использовать пробелы после запятых.
+
+**Хорошо**
+```ts
+const roles = ['admin', 'editor'];
+const options = { id: 1, name: 'User' };
+
+const config = {
+  url: '/api/users',
+  method: 'GET',
+  params: { page: 1, pageSize: 20 },
+};
+```
+
+**Плохо**
+```ts
+const roles = ['admin','editor'];
+const options = { id: 1,name: 'User' };
+const config = { url: '/api/users', method: 'GET', params: { page: 1, pageSize: 20 } };
+```