sync

2026-04-20 09:43:43 +03:00
parent 4aeb1dd6b2
commit 47658cdbb9
7 changed files with 108 additions and 187 deletions
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -73,7 +73,7 @@ jobs:
          ssh -i ~/.ssh/deploy_key root@188.225.47.78 bash -s <<'SCRIPT'
            set -e
            IMAGE="${{ env.REGISTRY_IMAGE }}:latest"
-            CONTAINER="nextjs-style-guide"
+            CONTAINER="frontend-style-guide"

            # Логин в реестр
            echo '${{ secrets.CR_TOKEN }}' | docker login ${{ env.DOCKER_REGISTRY }} -u '${{ secrets.CR_USER }}' --password-stdin
--- a/166
+++ b/166
@@ -1,153 +1,23 @@
-ФЛОУ
- - после создания компонента, заменить шаблонный коментарий документа на реальный.
+# TODO

+## Триггеры: классификация и расширение

- Проблема, неочевидность слоев (наследие FSD)
+Текущий список триггеров слабо проработан. Нужно:

+1. Классифицировать триггеры по группам:
+   - Создание — новые модули, компоненты, страницы
+   - Ресурсы — ассеты (иконки, шрифты, изображения, видео)
+   - Данные — API, сторы, серверные данные, формы
+   - Навигация — роутинг, middleware, редиректы
+   - Модификация — рефакторинг, перенос, удаление
+   - Инфраструктура — зависимости, переводы, настройка окружения

-Архитектурные слои проекта
-Каждый нижний слой не знает о существовании верхних. Импорты идут только сверху вниз.
-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 = () => (
-  <MainLayout>
-    <KnvScreen />
-  </MainLayout>
-)
---
-2. Layouts (src/layouts/)
-Каркас страницы — общие элементы, которые одинаковы на всех страницах в рамках этого layout.
-Содержит в ui/: header, footer, sidebar — дочерние компоненты, которые привязаны к layout и не переиспользуются отдельно.
-Критерий: компонент одинаков на всех страницах, использующих этот layout? → layouts/{name}/ui/
-Пример:
-src/layouts/main/
-├── main.layout.tsx        # <Header /> + children + <Footer />
-├── ui/
-│   ├── header/            # всегда одинаковый на всех страницах
-│   └── footer/            # всегда одинаковый на всех страницах
---
-3. Screens (src/screens/)
-Контент конкретной страницы. Собирает свои секции и переиспользуемые widgets/features/entities.
-Содержит в ui/: блоки, которые существуют только на этой странице и не переиспользуются.
-Критерий: компонент используется только на одной странице? → screens/{name}/ui/
-Пример:
-src/screens/knv/
-├── knv.screen.tsx
-├── ui/
-│   ├── hero-section/         # hero только на главной КНВ
-│   ├── products-section/     # секция препаратов только на главной
-│   ├── diseases-section/     # секция заболеваний только на главной
-│   └── doctor-section/       # секция врачей только на главной
-Каждая секция внутри может использовать shared/ui компоненты:
-// screens/knv/ui/products-section/products-section.widget.tsx
-import { Carousel } from 'src/shared/ui/carousel'
-import { ProductCard } from './ui/product-card'  // локальный, пока не переиспользуется
-Когда локальный компонент начинает использоваться на 2+ страницах — выносим в entities/ или shared/ui.
---
-4. Widgets (src/widgets/)
-Составные блоки с данными/логикой, которые переиспользуются на 2+ страницах.
-Критерий: блок с бизнес-логикой + данными используется на нескольких страницах? → widgets/
-Пример: Слайдер «Популярные препараты» с загрузкой данных из API, который показывается и на главной, и на странице заболевания, и в каталоге:
-src/widgets/
-├── popular-products-slider/
-│   ├── popular-products-slider.widget.tsx  # Carousel + ProductCard + useProducts()
-│   ├── hooks/
-│   │   └── use-products.hook.ts           # запрос данных
-Не widget: секция «Подобрать врача» которая есть только на главной → screens/knv/ui/
---
-5. Features (src/features/)
-Пользовательское действие или интерактивный сценарий. Содержит бизнес-логику взаимодействия.
-Критерий: это действие пользователя (отправить форму, авторизоваться, добавить в корзину)? → features/
-Примеры:
-src/features/
-├── auth/                    # авторизация (форма + логика + стор)
-│   ├── auth.feature.tsx
-│   ├── hooks/
-│   │   └── use-auth.hook.ts
-│   └── stores/
-│       └── auth.store.ts
-│
-├── order-drug/              # заказ препарата (кнопка + модалка + API)
-│   ├── order-drug.feature.tsx
-│   └── hooks/
-│       └── use-order.hook.ts
-Не feature: отображение карточки препарата без взаимодействия → entities/ или shared/ui
---
-6. Entities (src/entities/)
-Бизнес-сущность с её отображением и типами. Привязана к домену (препарат, заболевание, врач, пользователь).
-Критерий: это представление бизнес-объекта, которое переиспользуется в разных контекстах? → entities/
-Примеры:
-src/entities/
-├── product/                 # Препарат
-│   ├── ui/
-│   │   └── product-card/    # карточка препарата (каталог, слайдеры, поиск)
-│   ├── types/
-│   │   └── product.type.ts  # { id, name, mnn, indication }
-│   └── index.ts
-│
-├── disease/                 # Заболевание
-│   ├── ui/
-│   │   └── disease-card/
-│   ├── types/
-│   │   └── disease.type.ts
-│   └── index.ts
-Отличие от shared/ui: entity-компонент знает о бизнес-домене (принимает Product, а не абстрактные пропсы). shared/ui Button не знает ничего о бизнесе.
---
-7. Shared (src/shared/)
-Переиспользуемые компоненты, утилиты, стили без бизнес-логики.
-Критерий: компонент не знает о бизнес-домене, работает с абстрактными данными? → shared/
-src/shared/
-├── ui/                      # UI-компоненты
-│   ├── carousel/            # принимает children, не знает о препаратах
-│   ├── container/
-│   ├── section/
-│   └── icon-svg/
-├── styles/                  # CSS-переменные, media
-│   ├── variables.css
-│   └── media.css
-├── sprites/                 # SVG-спрайты
-└── lib/                     # утилиты, хелперы
---
-Сводная таблица принятия решений
-Вопрос	Да →	Нет ↓
-Это точка входа маршрута?	pages/	↓
-Одинаков на всех страницах layout?	layouts/{name}/ui/	↓
-Используется только на одной странице?	screens/{name}/ui/	↓
-Составной блок с данными на 2+ страницах?	widgets/	↓
-Это действие пользователя с логикой?	features/	↓
-Привязан к бизнес-сущности?	entities/	↓
-Абстрактный UI без бизнес-логики?	shared/ui/	—
+2. Добавить недостающие триггеры. Примеры пробелов:
+   - Создание: утилита/хелпер, тип/интерфейс, контекст
+   - Данные: создать форму, добавить валидацию
+   - Навигация: динамический роут, middleware, редирект
+   - Модификация: рефакторинг компонента, перенос модуля, удаление модуля
+   - Обработка ошибок: error boundary, fallback UI, error.tsx, not-found.tsx, loading.tsx
+   - Авторизация: защита страницы, проверка прав

-
-И еще размышлений
-
-
-
-
-
-
-Что у нас по факту
-Мы взяли FSD и добавили:
- Слой Layouts — каркас страницы
- Слой Screens — контент страницы с локальными компонентами
- Правило scope — компонент живёт максимально близко к месту использования, и поднимается на уровень выше только при переиспользовании
-Это не FSD в чистом виде. Но и не что-то принципиально новое.
-Существующие названия
-Feature-Sliced Design (FSD) — то от чего отталкиваемся, но расходимся в деталях.
-Screaming Architecture (Robert C. Martin) — структура проекта "кричит" о том, что он делает. Открываешь screens/knv/ui/ — видишь КНВ. Открываешь widgets/ — видишь глобальное. Это близко к нашему подходу.
-Colocation Principle — держи код рядом с тем, где он используется. Именно этот принцип отличает нас от FSD: page-specific компоненты лежат внутри screen, а не в глобальном widgets/.
-Как назвать
-Я бы не стал придумывать новое название. Это:
-> FSD с принципом колокации (FSD + Colocation)
-Или проще — адаптированный FSD. Суть отличия укладывается в одно правило:
-> Компонент живёт на самом низком уровне, где он используется. Поднимается выше только при переиспользовании на 2+ страницах.
-Если хочется краткое название для внутренней документации — можно SLD (Scoped Layer Design), подчёркивая что каждый компонент привязан к scope (shared → entity → feature → widget → screen → layout → page).
+3. Обновить секцию "Триггеры" в DEVELOP.md — перейти на новые группы.
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,11 +1,11 @@
 {
-  "name": "nextjs-style-guide",
+  "name": "frontend-style-guide",
  "version": "0.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
-      "name": "nextjs-style-guide",
+      "name": "frontend-style-guide",
      "version": "0.0.0",
      "devDependencies": {
        "vitepress": "^1.6.3"
--- a/package.json
+++ b/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "nextjs-style-guide",
+  "name": "frontend-style-guide",
  "private": true,
  "type": "module",
  "version": "0.0.0",
--- a/scripts/nextjs.build.js
+++ b/scripts/nextjs.build.js
@@ -17,7 +17,6 @@ export default {
    "basics/architecture.md":     "base/basics/architecture.md",
    "basics/code-style.md":       "base/basics/code-style.md",
    "basics/documentation.md":    "base/basics/documentation.md",
-    "basics/getting-started.md":  "base/basics/getting-started.md",
    "basics/naming.md":           "base/basics/naming.md",
    "basics/tech-stack.md":       "base/basics/tech-stack.md",
    "basics/typing.md":           "base/basics/typing.md",
--- a/src/base/basics/architecture.md
+++ b/src/base/basics/architecture.md
@@ -1,3 +1,10 @@
+---
+title: Архитектура
+scope: basics
+keywords: [SLM Design, слой, модуль, сегмент, архитектура, FSD, scoped layered module]
+when: "Организация кода: слои, модули, зависимости между модулями"
+---
+
 <!-- /index -->
 # SLM Design
 Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
--- a/src/nextjs/DEVELOP.md
+++ b/src/nextjs/DEVELOP.md
@@ -4,48 +4,93 @@

 ## Как работать

-1. Найди задачу в таблицах ниже → открой триггер.
-2. Триггер укажет какие разделы прочитать и какие шаги выполнить.
-3. Перед каждой подзадачей возвращайся к этой таблице — проверяй, нет ли готового триггера.
-4. Если задачи нет в таблицах — ищи в `applied/` (по области) или `basics/` (общие правила).
+1. **Изучи обязательные правила** (таблица ниже) — они действуют при любой задаче.
+2. Найди задачу в таблицах триггеров → открой триггер.
+3. Триггер укажет какие прикладные разделы прочитать и какие шаги выполнить.
+4. Перед каждой подзадачей возвращайся к триггерам — проверяй, нет ли готового.
+5. Если триггера нет — ищи прикладной раздел по области задачи.

-## Создание
+---

-| Задача | Триггер | Когда / Когда НЕ |
-|--------|---------|-------------------|
-| Создать компонент | triggers/develop/create-component.md | Переиспользуемый UI без бизнес-логики. НЕ для: фичи, виджета, сущности |
-| Создать фичу | triggers/develop/create-feature.md | Самодостаточный блок с бизнес-логикой и UI. НЕ для: утилитарного UI (→ компонент) |
-| Создать виджет | triggers/develop/create-widget.md | Композиция фичей и сущностей. НЕ для: одиночного UI (→ компонент) |
-| Создать сущность | triggers/develop/create-entity.md | Бизнес-объект с UI и моделью данных. НЕ для: UI без модели (→ компонент) |
-| Создать хук | triggers/develop/create-hook.md | Кастомный React-хук. НЕ для: хука внутри стора |
-| Создать стор | triggers/develop/create-store.md | Глобальное или модульное состояние. НЕ для: локального useState |
-| Создать страницу | triggers/develop/create-page.md | Новый route в Next.js. Всегда экран + page.tsx |
-| Создать layout | triggers/develop/create-layout.md | layout.tsx для группы страниц |
-| Создать проект | triggers/develop/create-project.md | Новый проект из шаблона |
-| Сгенерировать модуль | triggers/develop/generate-module.md | Любой модуль из `.templates/`. Ручное создание файлов запрещено |
+## Обязательные правила

-## Стилизация и ресурсы
+Прочитай эти разделы **до начала работы**. Соблюдай при написании любого кода.

-| Задача | Триггер | Когда / Когда НЕ |
-|--------|---------|-------------------|
-| Стилизовать компонент | triggers/develop/style-component.md | Выбор подхода + написание CSS. НЕ для: Mantine-пропсов (они не требуют CSS) |
+| Раздел | Файл | Что внутри |
+|--------|------|------------|
+| Структура проекта | applied/project-structure.md | Организация папок и файлов |
+| Архитектура | basics/architecture.md | SLM Design: слои, модули, сегменты |
+| Стиль кода | basics/code-style.md | Форматирование, импорты, отступы |
+| Именование | basics/naming.md | Имена файлов, переменных, событий |
+| Типизация | basics/typing.md | type vs interface, generic, any/unknown |
+| Документирование | basics/documentation.md | JSDoc для функций, компонентов, типов |
+| Технологии | basics/tech-stack.md | Допустимые библиотеки и зависимости |
+
+---
+
+## Прикладные разделы
+
+Справочник по областям. Читай тот раздел, который относится к текущей задаче.
+
+| Область | Файл | Когда читать |
+|---------|------|--------------|
+| Компоненты | applied/components.md | Создание или редактирование React-компонентов |
+| Стили | applied/styles.md | CSS Modules, PostCSS, переменные, медиа-запросы |
+| Файлы роутинга | applied/page-level.md | page.tsx, layout.tsx, error.tsx, not-found.tsx |
+| Шаблоны и генерация | applied/templates-generation.md | Генерация кода из шаблонов |
+| Настройка VS Code | applied/vscode.md | Расширения, settings.json, сниппеты |
+| SVG-спрайты | applied/svg-sprites.md | Работа с SVG-иконками и спрайтами |
+| Хуки | applied/hooks.md | Создание и использование кастомных хуков *(в разработке)* |
+| Сторы | applied/stores.md | Глобальное состояние, Zustand *(в разработке)* |
+| API | applied/api.md | Запросы, клиенты, обработка ответов *(в разработке)* |
+| Локализация | applied/localization.md | i18next, переводы *(в разработке)* |
+| Изображения | applied/images-sprites.md | Подключение и оптимизация изображений *(в разработке)* |
+| Шрифты | applied/fonts.md | Подключение и настройка шрифтов *(в разработке)* |
+| Видео | applied/video.md | Встраивание видео *(в разработке)* |
+
+---
+
+## Триггеры
+
+Пошаговые инструкции. Найди задачу → открой триггер → выполняй по шагам.
+
+### Создание
+
+| Задача | Триггер | Описание |
+|--------|---------|----------|
+| Создать компонент | triggers/develop/create-component.md | Переиспользуемый UI-элемент без бизнес-логики |
+| Создать фичу | triggers/develop/create-feature.md | Самодостаточный блок с бизнес-логикой и UI |
+| Создать виджет | triggers/develop/create-widget.md | Композиция нескольких фичей и сущностей |
+| Создать сущность | triggers/develop/create-entity.md | Бизнес-объект с моделью данных и UI-представлением |
+| Создать хук | triggers/develop/create-hook.md | Кастомный React-хук с переиспользуемой логикой |
+| Создать стор | triggers/develop/create-store.md | Глобальное или модульное состояние через Zustand |
+| Создать страницу | triggers/develop/create-page.md | Новый route в Next.js — экран + page.tsx |
+| Создать layout | triggers/develop/create-layout.md | Общая обёртка layout.tsx для группы страниц |
+| Создать проект | triggers/develop/create-project.md | Инициализация нового проекта из шаблона |
+| Сгенерировать модуль | triggers/develop/generate-module.md | Создание модуля из шаблонов `.templates/` |
+
+### Стилизация и ресурсы
+
+| Задача | Триггер | Описание |
+|--------|---------|----------|
+| Стилизовать компонент | triggers/develop/style-component.md | Выбор подхода и написание CSS для компонента |
 | Добавить иконку | triggers/develop/add-icon.md | SVG-иконка через спрайт-систему |
 | Добавить изображение | triggers/develop/add-image.md | Растровое изображение (png, jpg, webp) |
-| Добавить видео | triggers/develop/add-video.md | Встраивание видео |
-| Подключить шрифт | triggers/develop/add-font.md | Новый шрифт в проект |
+| Добавить видео | triggers/develop/add-video.md | Встраивание видео на страницу |
+| Подключить шрифт | triggers/develop/add-font.md | Подключение нового шрифта в проект |

-## Данные и состояние
+### Данные и состояние

-| Задача | Триггер | Когда / Когда НЕ |
-|--------|---------|-------------------|
-| Добавить API-запрос | triggers/develop/add-api-request.md | Клиентский запрос (SWR). НЕ для: серверных данных (→ add-server-data) |
-| Подключить стор | triggers/develop/connect-store.md | Подключение стора к компоненту. НЕ для: создания стора (→ create-store) |
-| Серверные данные (RSC) | triggers/develop/add-server-data.md | Данные в серверных компонентах. НЕ для: клиентских запросов (→ add-api-request) |
+| Задача | Триггер | Описание |
+|--------|---------|----------|
+| Добавить API-запрос | triggers/develop/add-api-request.md | Клиентский запрос данных через SWR |
+| Подключить стор | triggers/develop/connect-store.md | Подключение существующего стора к компоненту |
+| Серверные данные (RSC) | triggers/develop/add-server-data.md | Получение данных в серверных компонентах |

-## Инфраструктура
+### Инфраструктура

-| Задача | Триггер | Когда / Когда НЕ |
-|--------|---------|-------------------|
+| Задача | Триггер | Описание |
+|--------|---------|----------|
 | Добавить перевод | triggers/develop/add-localization.md | Ключи перевода и подключение i18next |
-| Добавить зависимость | triggers/develop/add-dependency.md | Новая npm-библиотека. Проверь допустимость |
-| Настроить VS Code | triggers/develop/setup-vscode.md | Расширения, настройки, сниппеты |
+| Добавить зависимость | triggers/develop/add-dependency.md | Подключение новой npm-библиотеки |
+| Настроить VS Code | triggers/develop/setup-vscode.md | Расширения, настройки редактора, сниппеты |