Compare commits
26 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 1a1de7cad4 | |||
| 07542330b5 | |||
| 245dbbe302 | |||
| ee5b947fb0 | |||
| b3d501c920 | |||
| 5431651814 | |||
| 54b4060b6f | |||
|
004a73a869 | ||
| 7ee243389d | |||
| 5553ece16d | |||
| db34c20981 | |||
| 6ed8fd09cd | |||
| 9eef2cc472 | |||
| dfc56f918a | |||
| d3a152e177 | |||
| 515506e01e | |||
| 35763617b5 | |||
| 979df1205a | |||
|
|
d9b9748691 | ||
| 32892fb799 | |||
|
|
c6803710c6 | ||
| 2dfdc78c79 | |||
|
|
9d0ac66cdc | ||
| 42703b107b | |||
|
|
0e2380dc3f | ||
| 6c82d9d747 |
@@ -2,62 +2,66 @@ name: CI/CD Pipeline
|
|||||||
|
|
||||||
on:
|
on:
|
||||||
push:
|
push:
|
||||||
branches: [main]
|
branches: [main, dev]
|
||||||
|
|
||||||
jobs:
|
jobs:
|
||||||
docs:
|
build:
|
||||||
runs-on: ubuntu-latest
|
runs-on: ubuntu-latest
|
||||||
if: "!contains(github.event.head_commit.message, '[skip ci]')"
|
if: "!contains(github.event.head_commit.message, '[skip ci]')"
|
||||||
outputs:
|
|
||||||
new_tag: ${{ steps.tag.outputs.new_tag }}
|
|
||||||
steps:
|
steps:
|
||||||
- name: Checkout
|
- name: Checkout
|
||||||
uses: actions/checkout@v4
|
uses: actions/checkout@v4
|
||||||
with:
|
|
||||||
fetch-depth: 0
|
|
||||||
|
|
||||||
- name: Setup Node.js
|
- name: Setup Node.js
|
||||||
uses: actions/setup-node@v4
|
uses: actions/setup-node@v4
|
||||||
with:
|
with:
|
||||||
node-version: 24
|
node-version: 24
|
||||||
|
|
||||||
- name: Генерация ARCHITECTURE.md
|
- name: Установка зависимостей
|
||||||
run: |
|
run: npm ci
|
||||||
npm ci
|
|
||||||
npm run docs
|
|
||||||
|
|
||||||
- name: Коммит generated/
|
- name: Генерация артефактов
|
||||||
run: |
|
run: npm run generate
|
||||||
git config user.name "CI Bot"
|
|
||||||
git config user.email "ci@gromlab.ru"
|
|
||||||
git add generated/
|
|
||||||
if git diff --cached --quiet; then
|
|
||||||
echo "ARCHITECTURE.md не изменился, пропуск"
|
|
||||||
else
|
|
||||||
git commit -m "docs: обновить ARCHITECTURE.md [skip ci]"
|
|
||||||
git push origin main
|
|
||||||
fi
|
|
||||||
|
|
||||||
- name: Автоматический тег (semver patch)
|
- name: Сборка документации
|
||||||
id: tag
|
run: npm run docs:build
|
||||||
|
|
||||||
|
- name: Сборка лендинга
|
||||||
|
run: npm run build
|
||||||
|
|
||||||
|
version:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
needs: build
|
||||||
|
if: github.ref == 'refs/heads/main' && !contains(github.event.head_commit.message, '[skip ci]')
|
||||||
|
outputs:
|
||||||
|
version: ${{ steps.version.outputs.version }}
|
||||||
|
steps:
|
||||||
|
- name: Checkout
|
||||||
|
uses: actions/checkout@v4
|
||||||
|
with:
|
||||||
|
fetch-depth: 0
|
||||||
|
|
||||||
|
- name: Версия из package.json
|
||||||
|
id: version
|
||||||
run: |
|
run: |
|
||||||
LAST_TAG=$(git tag -l 'v*' --sort=-v:refname | head -1)
|
VERSION="v$(node -p "require('./package.json').version")"
|
||||||
if [ -z "$LAST_TAG" ]; then
|
echo "version=$VERSION" >> $GITHUB_OUTPUT
|
||||||
NEW_TAG="v0.1.0"
|
echo "Версия: $VERSION"
|
||||||
|
|
||||||
|
- name: Создать тег
|
||||||
|
run: |
|
||||||
|
VERSION=${{ steps.version.outputs.version }}
|
||||||
|
if git tag -l "$VERSION" | grep -q "$VERSION"; then
|
||||||
|
echo "Тег $VERSION уже существует, пропуск"
|
||||||
else
|
else
|
||||||
MAJOR=$(echo "$LAST_TAG" | cut -d. -f1)
|
git tag "$VERSION"
|
||||||
MINOR=$(echo "$LAST_TAG" | cut -d. -f2)
|
git push origin "$VERSION"
|
||||||
PATCH=$(echo "$LAST_TAG" | cut -d. -f3)
|
echo "Создан тег: $VERSION"
|
||||||
NEW_TAG="${MAJOR}.${MINOR}.$((PATCH + 1))"
|
|
||||||
fi
|
fi
|
||||||
git tag "$NEW_TAG"
|
|
||||||
git push origin "$NEW_TAG"
|
|
||||||
echo "new_tag=$NEW_TAG" >> $GITHUB_OUTPUT
|
|
||||||
echo "Создан тег: $NEW_TAG"
|
|
||||||
|
|
||||||
docker:
|
docker:
|
||||||
runs-on: ubuntu-latest
|
runs-on: ubuntu-latest
|
||||||
needs: docs
|
needs: version
|
||||||
if: "!contains(github.event.head_commit.message, '[skip ci]')"
|
if: "!contains(github.event.head_commit.message, '[skip ci]')"
|
||||||
steps:
|
steps:
|
||||||
- name: Checkout
|
- name: Checkout
|
||||||
@@ -91,7 +95,7 @@ jobs:
|
|||||||
type=ref,event=branch
|
type=ref,event=branch
|
||||||
type=sha,prefix=
|
type=sha,prefix=
|
||||||
type=raw,value=latest,enable={{is_default_branch}}
|
type=raw,value=latest,enable={{is_default_branch}}
|
||||||
type=raw,value=${{ needs.docs.outputs.new_tag }}
|
type=raw,value=${{ needs.version.outputs.version }}
|
||||||
|
|
||||||
- name: Build and push
|
- name: Build and push
|
||||||
uses: docker/build-push-action@v5
|
uses: docker/build-push-action@v5
|
||||||
@@ -103,7 +107,7 @@ jobs:
|
|||||||
tags: ${{ steps.meta.outputs.tags }}
|
tags: ${{ steps.meta.outputs.tags }}
|
||||||
labels: ${{ steps.meta.outputs.labels }}
|
labels: ${{ steps.meta.outputs.labels }}
|
||||||
build-args: |
|
build-args: |
|
||||||
VERSION_TAG=${{ needs.docs.outputs.new_tag }}
|
VERSION_TAG=${{ needs.version.outputs.version }}
|
||||||
provenance: false
|
provenance: false
|
||||||
sbom: false
|
sbom: false
|
||||||
|
|
||||||
@@ -132,31 +136,23 @@ jobs:
|
|||||||
IMAGE="${{ env.REGISTRY_IMAGE }}:latest"
|
IMAGE="${{ env.REGISTRY_IMAGE }}:latest"
|
||||||
CONTAINER="slm-design"
|
CONTAINER="slm-design"
|
||||||
|
|
||||||
# Логин в реестр
|
|
||||||
echo '${{ secrets.CR_TOKEN }}' | docker login ${{ env.DOCKER_REGISTRY }} -u '${{ secrets.CR_USER }}' --password-stdin
|
echo '${{ secrets.CR_TOKEN }}' | docker login ${{ env.DOCKER_REGISTRY }} -u '${{ secrets.CR_USER }}' --password-stdin
|
||||||
|
|
||||||
# Сохранить ID текущего образа до pull
|
|
||||||
OLD_IMAGE_ID=$(docker images -q "$IMAGE" 2>/dev/null || true)
|
OLD_IMAGE_ID=$(docker images -q "$IMAGE" 2>/dev/null || true)
|
||||||
|
|
||||||
# Скачать новый образ
|
|
||||||
docker pull "$IMAGE"
|
docker pull "$IMAGE"
|
||||||
|
|
||||||
# Перезапустить контейнер
|
|
||||||
docker stop "$CONTAINER" 2>/dev/null || true
|
docker stop "$CONTAINER" 2>/dev/null || true
|
||||||
docker rm "$CONTAINER" 2>/dev/null || true
|
docker rm "$CONTAINER" 2>/dev/null || true
|
||||||
docker run -d --name "$CONTAINER" --network web --restart unless-stopped "$IMAGE"
|
docker run -d --name "$CONTAINER" --network web --restart unless-stopped "$IMAGE"
|
||||||
|
|
||||||
# Удалить старый образ если он отличается от нового
|
|
||||||
NEW_IMAGE_ID=$(docker images -q "$IMAGE")
|
NEW_IMAGE_ID=$(docker images -q "$IMAGE")
|
||||||
if [ -n "$OLD_IMAGE_ID" ] && [ "$OLD_IMAGE_ID" != "$NEW_IMAGE_ID" ]; then
|
if [ -n "$OLD_IMAGE_ID" ] && [ "$OLD_IMAGE_ID" != "$NEW_IMAGE_ID" ]; then
|
||||||
docker rmi "$OLD_IMAGE_ID" 2>/dev/null || true
|
docker rmi "$OLD_IMAGE_ID" 2>/dev/null || true
|
||||||
fi
|
fi
|
||||||
|
|
||||||
# Очистка
|
|
||||||
docker image prune -af --filter "label=org.opencontainers.image.title=$CONTAINER"
|
docker image prune -af --filter "label=org.opencontainers.image.title=$CONTAINER"
|
||||||
docker image prune -f
|
docker image prune -f
|
||||||
docker builder prune -f 2>/dev/null || true
|
docker builder prune -f 2>/dev/null || true
|
||||||
|
|
||||||
# Статус
|
|
||||||
docker ps --filter "name=$CONTAINER"
|
docker ps --filter "name=$CONTAINER"
|
||||||
SCRIPT
|
SCRIPT
|
||||||
|
|||||||
14
.gitignore
vendored
14
.gitignore
vendored
@@ -135,10 +135,18 @@ dist
|
|||||||
.vitepress/cache
|
.vitepress/cache
|
||||||
.vitepress/dist
|
.vitepress/dist
|
||||||
docs/.vitepress
|
docs/.vitepress
|
||||||
|
docs/public/
|
||||||
|
|
||||||
|
# Generated artifacts
|
||||||
|
public/docs/
|
||||||
|
public/llms.txt
|
||||||
|
public/llms-full.txt
|
||||||
|
public/slm-design.zip
|
||||||
|
generated/
|
||||||
|
|
||||||
|
# Vite
|
||||||
|
dist
|
||||||
|
|
||||||
# Рабочие заметки
|
# Рабочие заметки
|
||||||
notes
|
notes
|
||||||
|
|
||||||
|
|
||||||
# Генерируемые файлы
|
|
||||||
README_RU.md
|
|
||||||
@@ -1,59 +1,36 @@
|
|||||||
import { defineConfig } from 'vitepress';
|
import { defineConfig } from 'vitepress';
|
||||||
|
|
||||||
const ruSidebar = [
|
const sidebar = [
|
||||||
{
|
{
|
||||||
text: 'Введение',
|
text: 'Архитектура',
|
||||||
link: '/',
|
|
||||||
},
|
|
||||||
{
|
|
||||||
text: 'Справочник',
|
|
||||||
items: [
|
items: [
|
||||||
{ text: 'Слои', link: '/reference/layers' },
|
{ text: 'Обзор', link: '/architecture/' },
|
||||||
{ text: 'Модули', link: '/reference/modules' },
|
{ text: 'Слои', link: '/architecture/layers' },
|
||||||
{ text: 'Сегменты', link: '/reference/segments' },
|
{ text: 'Модули', link: '/architecture/modules' },
|
||||||
],
|
{ text: 'Сегменты', link: '/architecture/segments' },
|
||||||
},
|
|
||||||
|
|
||||||
];
|
|
||||||
|
|
||||||
const enSidebar = [
|
|
||||||
{
|
|
||||||
text: 'Architecture',
|
|
||||||
items: [
|
|
||||||
{ text: 'Overview', link: '/en/architecture/overview' },
|
|
||||||
{ text: 'Terminology', link: '/en/architecture/terminology' },
|
|
||||||
{ text: 'Layers', link: '/en/architecture/layers' },
|
|
||||||
{ text: 'Module', link: '/en/architecture/module' },
|
|
||||||
{ text: 'Edge Cases', link: '/en/architecture/edge-cases' },
|
|
||||||
{ text: 'Rationale', link: '/en/architecture/rationale' },
|
|
||||||
],
|
],
|
||||||
},
|
},
|
||||||
];
|
];
|
||||||
|
|
||||||
export default defineConfig({
|
export default defineConfig({
|
||||||
srcDir: 'docs',
|
srcDir: 'docs',
|
||||||
|
srcExclude: ['public/**'],
|
||||||
|
outDir: 'public/docs',
|
||||||
title: 'SLM Design',
|
title: 'SLM Design',
|
||||||
description: 'Правила и стандарты архитектуры проекта',
|
description: 'Правила и стандарты архитектуры проекта',
|
||||||
|
base: '/docs/',
|
||||||
|
cleanUrls: true,
|
||||||
|
head: [
|
||||||
|
['meta', { name: 'llms', content: '/llms.txt' }],
|
||||||
|
['link', { rel: 'alternate llms', type: 'text/plain', href: '/llms.txt', title: 'llms.txt' }],
|
||||||
|
['link', { rel: 'alternate', type: 'text/plain', href: '/llms-full.txt', title: 'llms-full.txt' }],
|
||||||
|
['link', { rel: 'alternate', type: 'text/markdown', href: '/ARCHITECTURE.md', title: 'ARCHITECTURE.md' }],
|
||||||
|
],
|
||||||
|
|
||||||
rewrites: {
|
|
||||||
'ru/:rest*': ':rest*',
|
|
||||||
},
|
|
||||||
|
|
||||||
locales: {
|
|
||||||
root: {
|
|
||||||
label: 'Русский',
|
|
||||||
lang: 'ru-RU',
|
|
||||||
themeConfig: {
|
themeConfig: {
|
||||||
sidebar: ruSidebar,
|
sidebar,
|
||||||
},
|
socialLinks: [
|
||||||
},
|
{ icon: 'github', link: 'https://gromlab.ru/gromov/slm-design' },
|
||||||
en: {
|
],
|
||||||
label: 'English',
|
|
||||||
lang: 'en-US',
|
|
||||||
link: '/en/',
|
|
||||||
themeConfig: {
|
|
||||||
sidebar: enSidebar,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
},
|
},
|
||||||
});
|
});
|
||||||
|
|||||||
@@ -1,17 +0,0 @@
|
|||||||
.VPNavBarTitle.has-sidebar .title {
|
|
||||||
border-top: none !important;
|
|
||||||
padding-top: 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
.VPNavBarTitle .title {
|
|
||||||
white-space: normal;
|
|
||||||
line-height: 1.2;
|
|
||||||
padding: 6px 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
.VPNavBarTitle .title span {
|
|
||||||
display: block;
|
|
||||||
min-width: 0;
|
|
||||||
max-width: 100%;
|
|
||||||
overflow-wrap: anywhere;
|
|
||||||
}
|
|
||||||
@@ -1,4 +0,0 @@
|
|||||||
import DefaultTheme from 'vitepress/theme';
|
|
||||||
import './custom.css';
|
|
||||||
|
|
||||||
export default DefaultTheme;
|
|
||||||
198
CONTRIBUTING.md
198
CONTRIBUTING.md
@@ -4,182 +4,79 @@
|
|||||||
|
|
||||||
## О проекте
|
## О проекте
|
||||||
|
|
||||||
Документационный сайт с правилами и стандартами фронтенд-разработки на Next.js + TypeScript.
|
Сайт-документация архитектуры SLM Design с лендингом.
|
||||||
|
|
||||||
- Движок: VitePress
|
- Лендинг: React + Vite
|
||||||
- Языки: русский (основной), английский
|
- Документация: VitePress
|
||||||
- Русская версия: `docs/ru/`
|
- Язык: русский
|
||||||
- Английская версия: `docs/en/`
|
- Документация: `docs/architecture/`
|
||||||
|
|
||||||
## Команды
|
## Команды
|
||||||
|
|
||||||
| Команда | Что делает |
|
| Команда | Что делает |
|
||||||
|---------|-----------|
|
|---------|-----------|
|
||||||
| `npm run dev` | Локальный сервер разработки |
|
| `npm run dev` | Локальный сервер лендинга |
|
||||||
| `npm run build` | Сборка статического сайта |
|
| `npm run build` | Сборка лендинга |
|
||||||
| `npm run docs` | Генерация `generated/{lang}/RULES.md` — единый файл для AI-ассистентов |
|
| `npm run docs:dev` | Локальный сервер документации |
|
||||||
|
| `npm run docs:build` | Сборка документации |
|
||||||
|
| `npm run generate` | Генерация артефактов (llms.txt, llms-full.txt, ARCHITECTURE.md, ZIP, README) |
|
||||||
|
|
||||||
## Структура файлов
|
## Структура файлов
|
||||||
|
|
||||||
```
|
```
|
||||||
docs/
|
docs/
|
||||||
├── ru/ # Русская версия (основная)
|
├── index.md # Страница навигации по документации
|
||||||
│ ├── index.md # Главная страница
|
└── architecture/ # Разделы архитектуры
|
||||||
│ ├── basics/ # Базовые правила
|
├── index.md # Обзор SLM Design
|
||||||
│ │ ├── tech-stack.md
|
├── layers.md # Слои
|
||||||
│ │ ├── architecture.md
|
├── modules.md # Модули
|
||||||
│ │ ├── code-style.md
|
└── segments.md # Сегменты
|
||||||
│ │ ├── naming.md
|
|
||||||
│ │ ├── documentation.md
|
|
||||||
│ │ └── typing.md
|
|
||||||
│ └── applied/ # Прикладные разделы
|
|
||||||
│ ├── vscode.md
|
|
||||||
│ ├── project-structure.md
|
|
||||||
│ ├── components.md
|
|
||||||
│ ├── page-level.md
|
|
||||||
│ ├── templates-generation.md
|
|
||||||
│ ├── styles.md
|
|
||||||
│ ├── images-sprites.md
|
|
||||||
│ ├── svg-sprites.md
|
|
||||||
│ ├── video.md
|
|
||||||
│ ├── api.md
|
|
||||||
│ ├── stores.md
|
|
||||||
│ ├── hooks.md
|
|
||||||
│ ├── fonts.md
|
|
||||||
│ └── localization.md
|
|
||||||
├── en/ # Английская версия (зеркало ru/)
|
|
||||||
.vitepress/
|
.vitepress/
|
||||||
├── config.ts # Конфигурация VitePress, сайдбары, локали
|
├── config.ts # Конфигурация VitePress, сайдбар
|
||||||
generated/
|
public/
|
||||||
├── ru/RULES.md # Сгенерированный единый файл (ru)
|
├── llms.txt # Карта документации для LLM
|
||||||
└── en/RULES.md # Сгенерированный единый файл (en)
|
├── llms-full.txt # Полная документация в одном файле
|
||||||
concat-md.js # Скрипт генерации RULES.md
|
└── ARCHITECTURE.md # Единый файл архитектуры
|
||||||
|
generate.ts # Скрипт генерации артефактов
|
||||||
|
src/ # Исходники лендинга (React + Vite)
|
||||||
```
|
```
|
||||||
|
|
||||||
### Добавление нового раздела
|
### Добавление нового раздела
|
||||||
|
|
||||||
1. Создать `.md`-файл в нужной папке (`basics/` или `applied/`).
|
1. Создать `.md`-файл в `docs/architecture/`.
|
||||||
2. Добавить пункт в сайдбар — `.vitepress/config.ts` (оба языка, если есть перевод).
|
2. Добавить пункт в сайдбар — `.vitepress/config.ts`.
|
||||||
3. Добавить файл в массив `fileOrder` — `concat-md.js` (для генерации RULES.md).
|
3. Добавить `description` в frontmatter файла — используется для `llms.txt`.
|
||||||
|
4. Запустить `npm run generate` для обновления артефактов.
|
||||||
|
|
||||||
## Два типа документации
|
## Frontmatter
|
||||||
|
|
||||||
### Базовые правила
|
|
||||||
|
|
||||||
**Отвечает на вопрос:** «Каким должен быть любой код?»
|
|
||||||
|
|
||||||
Универсальные стандарты, **не привязанные к конкретной области**.
|
|
||||||
Правило базовое, если оно применимо ко всему коду одинаково: именование переменных, оформление импортов, когда использовать `type` vs `interface`.
|
|
||||||
|
|
||||||
Примеры в базовых правилах допускаются, но служат иллюстрацией принципа, а не инструкцией по конкретной области.
|
|
||||||
|
|
||||||
**Граница:** если правило касается только одной области (только стили, только компоненты, только API) — оно живёт в прикладном разделе, не в базовых.
|
|
||||||
|
|
||||||
### Прикладные разделы
|
|
||||||
|
|
||||||
**Отвечает на вопрос:** «Как работать с X?»
|
|
||||||
|
|
||||||
Полное описание конкретной области: структура файлов, правила, именование, типизация, примеры.
|
|
||||||
|
|
||||||
**Граница:** прикладной раздел не дублирует базовые правила.
|
|
||||||
Если правило уже описано в базовых — прикладной раздел ссылается на него, но не повторяет.
|
|
||||||
|
|
||||||
## Структура прикладного раздела
|
|
||||||
|
|
||||||
Шаблон ниже описывает все допустимые секции. Раздел включает только те секции, которые для него релевантны — пустые секции не создаются.
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# {Название}
|
|
||||||
|
|
||||||
Краткое описание: о чём раздел и какие аспекты работы с областью он охватывает.
|
|
||||||
|
|
||||||
## Что нужно знать
|
|
||||||
|
|
||||||
Неочевидная информация, которую читатель должен знать перед чтением раздела.
|
|
||||||
Если для раздела нет такой вводной — секция не создаётся.
|
|
||||||
|
|
||||||
## Структура
|
|
||||||
|
|
||||||
Файловая организация: какие файлы создавать и куда класть.
|
|
||||||
Обязательно — дерево файлов через code-block.
|
|
||||||
|
|
||||||
## Правила
|
|
||||||
|
|
||||||
Конкретные требования, специфичные для области. Делятся на две подсекции:
|
|
||||||
|
|
||||||
### Реализация
|
|
||||||
|
|
||||||
Как написан код внутри файла: синтаксис, паттерны, API.
|
|
||||||
Отвечает на вопрос: «Как писать код?»
|
|
||||||
|
|
||||||
Примеры: объявление через `const`, деструктуризация пропсов, формат вызова `cl()`, способ подключения стилей, структура хука.
|
|
||||||
|
|
||||||
### Организация
|
|
||||||
|
|
||||||
Как компонент/модуль встроен в проект: файловые границы, зоны ответственности, экспорт.
|
|
||||||
Отвечает на вопрос: «Где что лежит и за что отвечает?»
|
|
||||||
|
|
||||||
Примеры: один компонент — один файл, вложенные компоненты в `ui/`, логика выносится в `model/`.
|
|
||||||
|
|
||||||
Формат обеих подсекций — маркированный список.
|
|
||||||
Для неочевидных случаев — блоки «Хорошо / Плохо».
|
|
||||||
Если в области нет правил одной из категорий — подсекция не создаётся.
|
|
||||||
|
|
||||||
## Именование
|
|
||||||
|
|
||||||
Соглашения по именам, специфичные для этой области.
|
|
||||||
Только то, что НЕ покрыто в базовом разделе «Именование».
|
|
||||||
|
|
||||||
## Типизация
|
|
||||||
|
|
||||||
Правила типизации, специфичные для этой области.
|
|
||||||
Только то, что НЕ покрыто в базовом разделе «Типизация».
|
|
||||||
|
|
||||||
## Документирование
|
|
||||||
|
|
||||||
Что и как документировать в этой области.
|
|
||||||
Только то, что НЕ покрыто в базовом разделе «Документирование».
|
|
||||||
|
|
||||||
## Примеры
|
|
||||||
|
|
||||||
Полноценные примеры кода.
|
|
||||||
Каждый пример с путём к файлу и пояснениями.
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
### Порядок секций
|
|
||||||
|
|
||||||
Порядок фиксированный: контекст → структура → правила → специализации базовых правил → примеры.
|
|
||||||
|
|
||||||
Логика: читатель сначала понимает «что это», потом «где это лежит», потом «как это делать», и в конце видит полный пример.
|
|
||||||
|
|
||||||
### Секции-расширения базовых правил
|
|
||||||
|
|
||||||
«Именование», «Типизация», «Документирование» в прикладном разделе — это **точки расширения** базовых правил.
|
|
||||||
|
|
||||||
- В базовых описано общее: `camelCase` для переменных, `type` vs `interface`, формат JSDoc.
|
|
||||||
- В прикладном разделе описано специфичное: как именовать CSS-классы (стили), как типизировать пропсы компонентов (компоненты), как документировать хуки (хуки).
|
|
||||||
|
|
||||||
Если для области нет специфики по именованию, типизации или документированию — секция не создаётся.
|
|
||||||
|
|
||||||
## Конвенции оформления
|
|
||||||
|
|
||||||
### Frontmatter
|
|
||||||
|
|
||||||
Каждый `.md`-файл начинается с YAML frontmatter:
|
Каждый `.md`-файл начинается с YAML frontmatter:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
title: Название раздела
|
title: Название раздела
|
||||||
|
description: Краткое описание для llms.txt
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
Значение `title` совпадает с текстом `h1`-заголовка в файле.
|
- `title` — совпадает с `h1`-заголовком в файле.
|
||||||
|
- `description` — кратное описание содержимого страницы, используется при генерации `llms.txt`.
|
||||||
|
|
||||||
|
## Структура страницы документации
|
||||||
|
|
||||||
|
Каждая страница начинается одинаково:
|
||||||
|
|
||||||
|
1. **Заголовок** (`h1`) — совпадает с `title` из frontmatter.
|
||||||
|
2. **Описание раздела** — 1–2 строки сразу после заголовка. Говорит, что это за раздел, какую информацию он описывает и что читатель в нём получит.
|
||||||
|
3. **Определение** (`## Определение`) — для справочных страниц, посвящённых одному термину. Короткая формулировка жирным: что это за сущность и какую роль она играет.
|
||||||
|
4. **Контент** — остальные `h2`-подразделы.
|
||||||
|
|
||||||
|
## Конвенции оформления
|
||||||
|
|
||||||
### Заголовки
|
### Заголовки
|
||||||
|
|
||||||
- Один `h1` на файл — совпадает с `title` из frontmatter.
|
- Один `h1` на файл — совпадает с `title` из frontmatter.
|
||||||
- Сразу после `h1` — вводный абзац (одно-два предложения).
|
- Сразу после `h1` — описание раздела (1–2 предложения).
|
||||||
- Основные секции — `h2`.
|
- Основные секции — `h2`.
|
||||||
- Подсекции внутри `h2` — `h3`.
|
- Подсекции внутри `h2` — `h3`.
|
||||||
- `h4` не используется.
|
- `h4` не используется.
|
||||||
@@ -194,8 +91,6 @@ title: Название раздела
|
|||||||
|
|
||||||
Используются для контрастного сравнения правильного и неправильного подхода.
|
Используются для контрастного сравнения правильного и неправильного подхода.
|
||||||
|
|
||||||
Формат:
|
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
**Хорошо:**
|
**Хорошо:**
|
||||||
|
|
||||||
@@ -217,11 +112,10 @@ title: Название раздела
|
|||||||
|
|
||||||
### Ссылки между разделами
|
### Ссылки между разделами
|
||||||
|
|
||||||
Прикладной раздел может ссылаться на другие разделы, но не дублирует их содержимое.
|
Раздел может ссылаться на другие разделы, но не дублирует их содержимое.
|
||||||
|
|
||||||
## Принципы
|
## Принципы
|
||||||
|
|
||||||
1. **Не дублировать.** Одна мысль живёт в одном месте. Остальные ссылаются.
|
1. **Не дублировать.** Одна мысль живёт в одном месте. Остальные ссылаются.
|
||||||
2. **Базовое vs прикладное.** Если правило применимо ко всему коду — оно базовое. Если только к одной области — прикладное.
|
2. **Пустые секции не создавать.** Если для раздела нет специфики — секция не создаётся.
|
||||||
3. **Пустые секции не создавать.** Если для раздела нет специфики по именованию — секции «Именование» в нём нет.
|
3. **Примеры обязательны.** Раздел без примеров кода — незавершён.
|
||||||
4. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.
|
|
||||||
|
|||||||
39
Caddyfile
39
Caddyfile
@@ -1,5 +1,40 @@
|
|||||||
:8082 {
|
:8082 {
|
||||||
root * /srv
|
root * /srv
|
||||||
file_server
|
|
||||||
try_files {path} /index.html
|
# Устаревшие пути llms.txt в подпапках ведём к корневым артефактам.
|
||||||
|
redir /docs/llms.txt /llms.txt 301
|
||||||
|
redir /docs/llms-full.txt /llms-full.txt 301
|
||||||
|
|
||||||
|
# Чистые URL: запросы вида `/docs/foo.html` редиректим на `/docs/foo`.
|
||||||
|
@legacyHtml {
|
||||||
|
path_regexp legacyHtml ^(/.+)\.html$
|
||||||
|
not path /index.html
|
||||||
|
}
|
||||||
|
redir @legacyHtml {re.legacyHtml.1} 301
|
||||||
|
|
||||||
|
header Link "</llms.txt>; rel=\"llms\""
|
||||||
|
|
||||||
|
@existingText {
|
||||||
|
path *.txt
|
||||||
|
file
|
||||||
|
}
|
||||||
|
header @existingText Content-Type "text/plain; charset=utf-8"
|
||||||
|
|
||||||
|
@existingMarkdown {
|
||||||
|
path *.md
|
||||||
|
file
|
||||||
|
}
|
||||||
|
header @existingMarkdown Content-Type "text/markdown; charset=utf-8"
|
||||||
|
|
||||||
|
@architecture path /ARCHITECTURE.md
|
||||||
|
header @architecture Cache-Control "no-cache, no-store, must-revalidate"
|
||||||
|
|
||||||
|
@missingText {
|
||||||
|
path *.txt *.md
|
||||||
|
not file
|
||||||
|
}
|
||||||
|
respond @missingText 404
|
||||||
|
|
||||||
|
file_server
|
||||||
|
try_files {path} {path}.html {path}/index.html /index.html
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,12 +1,12 @@
|
|||||||
FROM node:24-alpine AS build
|
FROM node:24-alpine AS build
|
||||||
ARG VERSION_TAG=main
|
ARG VERSION_TAG=main
|
||||||
WORKDIR /app
|
WORKDIR /app
|
||||||
|
RUN apk add --no-cache zip
|
||||||
COPY package*.json ./
|
COPY package*.json ./
|
||||||
RUN npm ci
|
RUN npm ci
|
||||||
COPY . .
|
COPY . .
|
||||||
RUN sed -i "s|raw/branch/main/generated|raw/tag/${VERSION_TAG}/generated|" docs/ru/index.md \
|
RUN npm run generate && npm run docs:build && npm run build
|
||||||
&& npm run build
|
|
||||||
|
|
||||||
FROM caddy:2-alpine
|
FROM caddy:2-alpine
|
||||||
COPY Caddyfile /etc/caddy/Caddyfile
|
COPY Caddyfile /etc/caddy/Caddyfile
|
||||||
COPY --from=build /app/.vitepress/dist /srv
|
COPY --from=build /app/dist /srv
|
||||||
|
|||||||
104
README.md
104
README.md
@@ -1,6 +1,104 @@
|
|||||||
# SLM Design
|
# SLM Design
|
||||||
|
Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
|
||||||
|
|
||||||
Scoped Layered Module Design — модульная архитектура фронтенд-приложений.
|
## Разделы спецификации
|
||||||
|
|
||||||
- [Документация](https://slm.gromov.io)
|
Спецификация SLM Design состоит из нескольких связанных разделов. Этот обзор даёт общий контекст, а детальные правила описаны дальше:
|
||||||
- [ARCHITECTURE.md для AI-ассистентов](generated/ru/ARCHITECTURE.md)
|
|
||||||
|
- [Слои](docs/architecture/layers.md) — уровни организации `src/`, направление зависимостей и зона ответственности каждого слоя.
|
||||||
|
- [Модули](docs/architecture/modules.md) — границы ответственности, публичный API, типы модулей и отличие модуля от компонента.
|
||||||
|
- [Сегменты](docs/architecture/segments.md) — внутренние папки модуля (`ui/`, `parts/`, `hooks/`, `types/` и другие) и правила размещения файлов.
|
||||||
|
|
||||||
|
Рекомендуемый порядок чтения: обзор → слои → модули → сегменты.
|
||||||
|
|
||||||
|
## Преимущества
|
||||||
|
|
||||||
|
### Вертикальная организация домена
|
||||||
|
|
||||||
|
Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
|
||||||
|
|
||||||
|
### Dependency Injection без фреймворков
|
||||||
|
|
||||||
|
Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
|
||||||
|
|
||||||
|
### Разделение ответственности без перегрузки слоёв
|
||||||
|
|
||||||
|
Сервисы приложения (`infra/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
|
||||||
|
|
||||||
|
### Горизонтальная инкапсуляция
|
||||||
|
|
||||||
|
Вложенные модули (`parts/`) и направление зависимостей позволяют нескольким разработчикам работать над одной областью приложения параллельно, не затрагивая код друг друга.
|
||||||
|
|
||||||
|
### Колокация по умолчанию
|
||||||
|
|
||||||
|
Код начинает жизнь рядом с местом использования и поднимается в общие слои только при реальной потребности. Глобальные слои не засоряются преждевременными абстракциями.
|
||||||
|
|
||||||
|
### Явное разделение каркаса и контента
|
||||||
|
|
||||||
|
Каркас группы маршрутов (`layouts/`) и контент конкретной страницы (`screens/`) — независимые слои с собственной ответственностью.
|
||||||
|
|
||||||
|
### Масштабирование через группировку
|
||||||
|
|
||||||
|
При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
|
||||||
|
|
||||||
|
## Происхождение
|
||||||
|
|
||||||
|
SLM Design вырос на основе:
|
||||||
|
|
||||||
|
- **Feature-Sliced Design** — слоистая структура, публичный API модуля, направление зависимостей
|
||||||
|
- **Vertical Slice Architecture** — модуль как вертикальный срез, содержащий всё необходимое
|
||||||
|
- **Screaming Architecture** — структура проекта «кричит» о назначении: открыл `business/auth` — видишь авторизацию
|
||||||
|
- **Colocation Principle** — код живёт рядом с местом использования
|
||||||
|
|
||||||
|
## Пример структуры проекта
|
||||||
|
|
||||||
|
```text
|
||||||
|
src/
|
||||||
|
├── app/
|
||||||
|
│
|
||||||
|
├── layouts/
|
||||||
|
│ ├── main/
|
||||||
|
│ └── dashboard/
|
||||||
|
│
|
||||||
|
├── screens/
|
||||||
|
│ ├── home/
|
||||||
|
│ ├── products/
|
||||||
|
│ ├── product-detail/
|
||||||
|
│ └── about/
|
||||||
|
│
|
||||||
|
├── widgets/
|
||||||
|
│ ├── page-heading/
|
||||||
|
│ ├── hero-section/
|
||||||
|
│ └── promo-banner/
|
||||||
|
│
|
||||||
|
├── business/
|
||||||
|
│ ├── auth/
|
||||||
|
│ ├── catalog/
|
||||||
|
│ ├── orders/
|
||||||
|
│ └── chat/
|
||||||
|
│
|
||||||
|
├── infra/
|
||||||
|
│ ├── theme/
|
||||||
|
│ ├── i18n/
|
||||||
|
│ ├── backend-api/
|
||||||
|
│ └── logger/
|
||||||
|
│
|
||||||
|
├── ui/
|
||||||
|
│ ├── button/
|
||||||
|
│ ├── input/
|
||||||
|
│ ├── modal/
|
||||||
|
│ ├── toast/
|
||||||
|
│ └── dropdown/
|
||||||
|
│
|
||||||
|
└── shared/
|
||||||
|
├── lib/
|
||||||
|
├── types/
|
||||||
|
└── styles/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Принципы
|
||||||
|
|
||||||
|
- **Домен — единое целое.** Всё, что относится к домену, живёт в одном модуле.
|
||||||
|
- **Колокация.** Код рождается рядом с местом использования и поднимается только при необходимости.
|
||||||
|
- **Зависимости однонаправлены.** Импорты только сверху вниз, только через публичный API.
|
||||||
|
- **Архитектура — каркас, не клетка.** Правила фиксируют направление зависимостей и структуру модуля, остальное определяет команда.
|
||||||
|
|||||||
76
concat-md.js
76
concat-md.js
@@ -1,76 +0,0 @@
|
|||||||
import path from "path";
|
|
||||||
import fs from "fs";
|
|
||||||
|
|
||||||
// Явный порядок файлов внутри каждого языка
|
|
||||||
const fileOrder = [
|
|
||||||
"index.md",
|
|
||||||
// reference
|
|
||||||
"reference/layers.md",
|
|
||||||
"reference/modules.md",
|
|
||||||
"reference/segments.md",
|
|
||||||
|
|
||||||
];
|
|
||||||
|
|
||||||
// Удалить frontmatter из содержимого md-файла
|
|
||||||
const stripFrontmatter = (content) =>
|
|
||||||
content.replace(/^---[\s\S]*?---\n*/m, "");
|
|
||||||
|
|
||||||
// Удалить блоки между маркерами <!-- rules-link --> и <!-- /rules-link -->
|
|
||||||
const stripRulesLink = (content) =>
|
|
||||||
content.replace(/<!-- rules-link -->[\s\S]*?<!-- \/rules-link -->\n*/g, "");
|
|
||||||
|
|
||||||
// Сдвинуть уровень заголовков на 1 вниз (h1→h2, h2→h3, ...)
|
|
||||||
// Не трогает заголовки внутри блоков кода
|
|
||||||
const shiftHeadings = (content) => {
|
|
||||||
const lines = content.split("\n");
|
|
||||||
let inCodeBlock = false;
|
|
||||||
|
|
||||||
return lines
|
|
||||||
.map((line) => {
|
|
||||||
if (line.startsWith("```")) inCodeBlock = !inCodeBlock;
|
|
||||||
if (inCodeBlock) return line;
|
|
||||||
if (/^#{1,5}\s/.test(line)) return "#" + line;
|
|
||||||
return line;
|
|
||||||
})
|
|
||||||
.join("\n");
|
|
||||||
};
|
|
||||||
|
|
||||||
// Собрать ARCHITECTURE.md с мета-якорями для каждого файла
|
|
||||||
const buildRules = (lang) => {
|
|
||||||
const srcDir = `./docs/${lang}`;
|
|
||||||
const outDir = `./generated/${lang}`;
|
|
||||||
const outFile = path.join(outDir, "ARCHITECTURE.md");
|
|
||||||
|
|
||||||
if (!fs.existsSync(srcDir)) {
|
|
||||||
console.log(`Пропуск ${lang}: папка ${srcDir} не найдена`);
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
fs.mkdirSync(outDir, { recursive: true });
|
|
||||||
|
|
||||||
const parts = [];
|
|
||||||
|
|
||||||
for (const file of fileOrder) {
|
|
||||||
const filePath = path.join(srcDir, file);
|
|
||||||
if (!fs.existsSync(filePath)) continue;
|
|
||||||
|
|
||||||
const raw = fs.readFileSync(filePath, "utf8");
|
|
||||||
const content = stripRulesLink(stripFrontmatter(raw)).trim();
|
|
||||||
if (!content) continue;
|
|
||||||
|
|
||||||
// Мета-якорь: путь VitePress без расширения
|
|
||||||
const route = "/" + file.replace(/\.md$/, "");
|
|
||||||
// index.md остаётся без сдвига (его h1 — главный заголовок документа)
|
|
||||||
const processed = file === "index.md" ? content : shiftHeadings(content);
|
|
||||||
parts.push(`<!-- ${route} -->\n${processed}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
fs.writeFileSync(outFile, parts.join("\n\n"), "utf8");
|
|
||||||
console.log(`ARCHITECTURE.md (${lang}) создан: ${outFile}`);
|
|
||||||
};
|
|
||||||
|
|
||||||
// Собираем ARCHITECTURE.md для обоих языков
|
|
||||||
buildRules("ru");
|
|
||||||
buildRules("en");
|
|
||||||
|
|
||||||
|
|
||||||
@@ -1,13 +1,20 @@
|
|||||||
---
|
---
|
||||||
title: SLM Design
|
title: SLM Design
|
||||||
|
description: Назначение архитектуры, ключевые принципы и карта разделов документации
|
||||||
---
|
---
|
||||||
|
|
||||||
# SLM Design
|
# SLM Design
|
||||||
Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
|
Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
|
||||||
|
|
||||||
<!-- rules-link -->
|
## Разделы спецификации
|
||||||
Для AI-ассистентов доступен [единый файл правил](https://gromlab.ru/gromov/slm-design/raw/branch/main/generated/ru/ARCHITECTURE.md).
|
|
||||||
<!-- /rules-link -->
|
Спецификация SLM Design состоит из нескольких связанных разделов. Этот обзор даёт общий контекст, а детальные правила описаны дальше:
|
||||||
|
|
||||||
|
- [Слои](/architecture/layers) — уровни организации `src/`, направление зависимостей и зона ответственности каждого слоя.
|
||||||
|
- [Модули](/architecture/modules) — границы ответственности, публичный API, типы модулей и отличие модуля от компонента.
|
||||||
|
- [Сегменты](/architecture/segments) — внутренние папки модуля (`ui/`, `parts/`, `hooks/`, `types/` и другие) и правила размещения файлов.
|
||||||
|
|
||||||
|
Рекомендуемый порядок чтения: обзор → слои → модули → сегменты.
|
||||||
|
|
||||||
## Преимущества
|
## Преимущества
|
||||||
|
|
||||||
@@ -15,9 +22,13 @@ Scoped Layered Module Design — модульная архитектура фр
|
|||||||
|
|
||||||
Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
|
Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
|
||||||
|
|
||||||
|
### Dependency Injection без фреймворков
|
||||||
|
|
||||||
|
Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
|
||||||
|
|
||||||
### Разделение ответственности без перегрузки слоёв
|
### Разделение ответственности без перегрузки слоёв
|
||||||
|
|
||||||
Сервисы приложения (`infrastructure/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
|
Сервисы приложения (`infra/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
|
||||||
|
|
||||||
### Горизонтальная инкапсуляция
|
### Горизонтальная инкапсуляция
|
||||||
|
|
||||||
@@ -35,10 +46,6 @@ Scoped Layered Module Design — модульная архитектура фр
|
|||||||
|
|
||||||
При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
|
При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
|
||||||
|
|
||||||
### Dependency Injection без фреймворков
|
|
||||||
|
|
||||||
Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
|
|
||||||
|
|
||||||
## Происхождение
|
## Происхождение
|
||||||
|
|
||||||
SLM Design вырос на основе:
|
SLM Design вырос на основе:
|
||||||
@@ -75,7 +82,7 @@ src/
|
|||||||
│ ├── orders/
|
│ ├── orders/
|
||||||
│ └── chat/
|
│ └── chat/
|
||||||
│
|
│
|
||||||
├── infrastructure/
|
├── infra/
|
||||||
│ ├── theme/
|
│ ├── theme/
|
||||||
│ ├── i18n/
|
│ ├── i18n/
|
||||||
│ ├── backend-api/
|
│ ├── backend-api/
|
||||||
@@ -1,5 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: Слои
|
title: Слои
|
||||||
|
description: Иерархия слоёв от app до shared, правила зависимостей и зона ответственности каждого слоя
|
||||||
---
|
---
|
||||||
|
|
||||||
# Слои
|
# Слои
|
||||||
@@ -17,7 +18,7 @@ title: Слои
|
|||||||
| Группа | Слои | Описание |
|
| Группа | Слои | Описание |
|
||||||
|--------|------|----------|
|
|--------|------|----------|
|
||||||
| Композиция | `app`, `layouts`, `screens`, `widgets` | Собирают интерфейс из готовых блоков: маршруты, каркасы, страницы |
|
| Композиция | `app`, `layouts`, `screens`, `widgets` | Собирают интерфейс из готовых блоков: маршруты, каркасы, страницы |
|
||||||
| Ядро | `business`, `infrastructure`, `ui` | Реализация продукта: бизнес-домены, техсервисы, UI-кит |
|
| Ядро | `business`, `infra`, `ui` | Реализация продукта: бизнес-домены, техсервисы, UI-кит |
|
||||||
| Фундамент | `shared` | Общие ресурсы: утилиты, хелперы, стили, конфиги |
|
| Фундамент | `shared` | Общие ресурсы: утилиты, хелперы, стили, конфиги |
|
||||||
|
|
||||||
## Направление зависимостей
|
## Направление зависимостей
|
||||||
@@ -25,12 +26,12 @@ title: Слои
|
|||||||
Любой импорт между модулями — только через публичный API.
|
Любой импорт между модулями — только через публичный API.
|
||||||
|
|
||||||
```
|
```
|
||||||
app → [ layouts | screens ] → widgets → business → infrastructure → ui → shared
|
app → [ layouts | screens ] → widgets → business → infra → ui → shared
|
||||||
```
|
```
|
||||||
|
|
||||||
- `layouts` и `screens` — параллельные слои, не импортируют друг друга
|
- `layouts` и `screens` — параллельные слои, не импортируют друг друга
|
||||||
- Модули одного слоя в группе «Композиция» изолированы друг от друга
|
- Модули одного слоя в группе «Композиция» изолированы друг от друга
|
||||||
- Модули одного слоя `infrastructure` и `ui` могут импортировать друг друга через публичный API
|
- Модули одного слоя `infra` и `ui` могут импортировать друг друга через публичный API
|
||||||
- Модули `business` — cross-domain зависимости по коду через фабрику, `import type` напрямую
|
- Модули `business` — cross-domain зависимости по коду через фабрику, `import type` напрямую
|
||||||
- Импорт типов (`import type`) в «Ядре» разрешён в обоих направлениях
|
- Импорт типов (`import type`) в «Ядре» разрешён в обоих направлениях
|
||||||
|
|
||||||
@@ -128,7 +129,7 @@ src/widgets/
|
|||||||
|
|
||||||
Бизнес-домены приложения: auth, catalog, orders, checkout, chat. Каждый домен — отдельный модуль со своими типами, логикой, UI и сервисами.
|
Бизнес-домены приложения: auth, catalog, orders, checkout, chat. Каждый домен — отдельный модуль со своими типами, логикой, UI и сервисами.
|
||||||
|
|
||||||
Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`. Cross-domain зависимости по коду реализуются через фабрику. `import type` между доменами разрешён напрямую.
|
Слой входит в группу «Ядро». Импортирует `infra/`, `ui/`, `shared/`. Каждый бизнес-модуль создаёт публичный runtime API через фабрику в корне. Cross-domain зависимости: runtime — через аргументы фабрики, типы — напрямую через `import type`.
|
||||||
|
|
||||||
Business объединяет то, что в FSD разделено на `features` и `entities`: пользовательские сценарии и бизнес-сущности живут вместе, внутри одного домена. Внутри домена сегменты разделяют ответственность: `types/` — доменная модель, `hooks/` и `services/` — сценарии и логика, `mappers/` — трансформация данных, `parts/` — составные блоки.
|
Business объединяет то, что в FSD разделено на `features` и `entities`: пользовательские сценарии и бизнес-сущности живут вместе, внутри одного домена. Внутри домена сегменты разделяют ответственность: `types/` — доменная модель, `hooks/` и `services/` — сценарии и логика, `mappers/` — трансформация данных, `parts/` — составные блоки.
|
||||||
|
|
||||||
@@ -159,19 +160,20 @@ src/business/
|
|||||||
|
|
||||||
- Один модуль = один бизнес-домен
|
- Один модуль = один бизнес-домен
|
||||||
- Циклические зависимости между доменами запрещены
|
- Циклические зависимости между доменами запрещены
|
||||||
- Импорт кода между доменами — через фабрику. `import type` — напрямую
|
- Публичный runtime API — через фабрику в корне модуля (`{name}.factory.ts`). `index.ts` экспортирует только фабрику и type-only экспорты
|
||||||
|
- Импорт runtime-кода между доменами — через фабрику. `import type` — напрямую
|
||||||
- Доменные типы (`User`, `Product`) живут здесь, не в `shared/`
|
- Доменные типы (`User`, `Product`) живут здесь, не в `shared/`
|
||||||
|
|
||||||
## Слой Infrastructure
|
## Слой infra
|
||||||
|
|
||||||
Техсервисы приложения: theme, i18n, API-адаптеры, logger, realtime. Каждый сервис — отдельный модуль.
|
Техсервисы приложения: theme, i18n, API-адаптеры, logger, realtime. Каждый сервис — отдельный модуль.
|
||||||
|
|
||||||
Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`.
|
Слой входит в группу «Ядро». Импортирует `infra/`, `ui/`, `shared/`.
|
||||||
|
|
||||||
Отличие от `shared/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
Отличие от `shared/`: infra — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
||||||
|
|
||||||
```text
|
```text
|
||||||
src/infrastructure/
|
src/infra/
|
||||||
├── theme/
|
├── theme/
|
||||||
├── i18n/
|
├── i18n/
|
||||||
├── backend-api/
|
├── backend-api/
|
||||||
@@ -184,7 +186,7 @@ src/infrastructure/
|
|||||||
### Требования
|
### Требования
|
||||||
|
|
||||||
- Один модуль = один техсервис
|
- Один модуль = один техсервис
|
||||||
- Импортирует `infrastructure/`, `ui/`, `shared/`
|
- Импортирует `infra/`, `ui/`, `shared/`
|
||||||
|
|
||||||
## Слой UI
|
## Слой UI
|
||||||
|
|
||||||
@@ -235,7 +237,7 @@ src/ui/
|
|||||||
|
|
||||||
Слой входит в группу «Фундамент» — ни о ком не знает, никого не импортирует.
|
Слой входит в группу «Фундамент» — ни о ком не знает, никого не импортирует.
|
||||||
|
|
||||||
Отличие от `infrastructure/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
Отличие от `infra/`: infra — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
||||||
|
|
||||||
Отличие от `ui/`: UI-компоненты (button, carousel, modal) живут в слое `ui/`, а не здесь.
|
Отличие от `ui/`: UI-компоненты (button, carousel, modal) живут в слое `ui/`, а не здесь.
|
||||||
|
|
||||||
289
docs/architecture/modules.md
Normal file
289
docs/architecture/modules.md
Normal file
@@ -0,0 +1,289 @@
|
|||||||
|
---
|
||||||
|
title: Модули
|
||||||
|
description: Структура модуля, типы (UI, бизнес, инфра), публичный API, отличие модуля от компонента
|
||||||
|
---
|
||||||
|
|
||||||
|
# Модули
|
||||||
|
|
||||||
|
Раздел описывает модуль как границу ответственности в SLM: что считается модулем, что такое компонент внутри модуля и как модуль взаимодействует с остальным кодом.
|
||||||
|
|
||||||
|
## Определение
|
||||||
|
|
||||||
|
**Модуль — минимальная архитектурная единица SLM. Он живёт на одном из слоёв, владеет конкретной областью ответственности и предоставляет наружу только публичный API.**
|
||||||
|
|
||||||
|
Модуль может содержать всё, что нужно этой области: компоненты, вложенные модули, хуки, сторы, сервисы, типы, стили, конфиги и утилиты. Набор сегментов не фиксирован — модуль включает только то, что реально нужно.
|
||||||
|
|
||||||
|
Модуль не обязан быть UI-блоком. Это может быть страница, виджет, бизнес-домен, инфраструктурный сервис или UI-kit сущность.
|
||||||
|
|
||||||
|
Главная граница модуля — не папка, а ответственность.
|
||||||
|
|
||||||
|
## Компонент
|
||||||
|
|
||||||
|
**Компонент — презентационная единица модуля, которая находится только в `ui/` своего родительского модуля и отвечает за отображение части интерфейса.**
|
||||||
|
|
||||||
|
Компонент не является архитектурной единицей: он не владеет сценарием, зависимостями, данными или внутренней структурой. Он работает только внутри границы родительского модуля.
|
||||||
|
|
||||||
|
> Компонент отображает. Модуль организует.
|
||||||
|
|
||||||
|
Компонент не может:
|
||||||
|
|
||||||
|
- Импортировать код проекта за пределами родительского модуля.
|
||||||
|
- Владеть архитектурными зависимостями.
|
||||||
|
- Содержать любые компоненты.
|
||||||
|
- Содержать любые модули.
|
||||||
|
- Делать внешние запросы.
|
||||||
|
- Самостоятельно получать данные.
|
||||||
|
- Выбирать источник данных.
|
||||||
|
- Композировать данные.
|
||||||
|
- Вызывать сценарные хуки.
|
||||||
|
- Оркестрировать сценарий.
|
||||||
|
- Композировать модули.
|
||||||
|
- Решать, как устроен процесс.
|
||||||
|
- Содержать бизнес-логику.
|
||||||
|
- Содержать сценарную логику.
|
||||||
|
|
||||||
|
Если компоненту требуется что-то из этого списка, он перестаёт быть компонентом и должен быть оформлен как модуль.
|
||||||
|
|
||||||
|
```text
|
||||||
|
auth/
|
||||||
|
├── ui/
|
||||||
|
│ └── logout-button/
|
||||||
|
│ ├── logout-button.tsx
|
||||||
|
│ ├── styles/
|
||||||
|
│ │ └── logout-button.module.css
|
||||||
|
│ ├── types/
|
||||||
|
│ │ └── logout-button-props.type.ts
|
||||||
|
│ └── index.ts
|
||||||
|
└── index.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
## Что считается модулем
|
||||||
|
|
||||||
|
Модулем считается папка, которая представляет самостоятельную область ответственности и имеет публичную границу.
|
||||||
|
|
||||||
|
Примеры модулей:
|
||||||
|
|
||||||
|
- `screens/home/` — модуль страницы.
|
||||||
|
- `widgets/page-heading/` — модуль виджета.
|
||||||
|
- `business/auth/` — модуль бизнес-домена.
|
||||||
|
- `infra/theme/` — модуль инфраструктурного сервиса.
|
||||||
|
- `ui/button/` — модуль UI-kit сущности.
|
||||||
|
- `screens/home/parts/hero-section/` — вложенный модуль страницы.
|
||||||
|
|
||||||
|
Не считаются модулями:
|
||||||
|
|
||||||
|
- `ui/`, `parts/`, `hooks/`, `types/`, `styles/`, `config/` — это сегменты.
|
||||||
|
- `screens/shop/`, `business/commerce/` — это группы, если в них нет `index.ts`.
|
||||||
|
- `screens/home/ui/user-card/` — это компонент, если он находится в `ui/` и соблюдает ограничения компонента.
|
||||||
|
|
||||||
|
## Типы модулей
|
||||||
|
|
||||||
|
Тип модуля определяет обязательный корневой файл и стартовую структуру.
|
||||||
|
|
||||||
|
### UI-модуль
|
||||||
|
|
||||||
|
Модуль строится вокруг основного UI-компонента и обязан иметь основной `.tsx` файл в корне:
|
||||||
|
|
||||||
|
```text
|
||||||
|
header/
|
||||||
|
├── header.tsx
|
||||||
|
└── index.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
`ui/` внутри такого модуля используется только для компонентов, которые помогают корневому `.tsx` файлу.
|
||||||
|
|
||||||
|
### Бизнес-модуль
|
||||||
|
|
||||||
|
Бизнес-модуль — модуль, который строится вокруг публичного runtime API.
|
||||||
|
|
||||||
|
Бизнес-модуль обязан иметь фабрику в корне:
|
||||||
|
|
||||||
|
```text
|
||||||
|
auth/
|
||||||
|
├── auth.factory.ts
|
||||||
|
├── index.ts
|
||||||
|
└── types/
|
||||||
|
```
|
||||||
|
|
||||||
|
Фабрика возвращает публичный runtime API модуля.
|
||||||
|
|
||||||
|
### Инфраструктурный модуль
|
||||||
|
|
||||||
|
Инфраструктурный модуль — модуль, который строится вокруг технического сервиса или интеграции.
|
||||||
|
|
||||||
|
Инфраструктурный модуль не обязан иметь фиксированный корневой файл. Его структура определяется природой сервиса.
|
||||||
|
|
||||||
|
```text
|
||||||
|
theme/
|
||||||
|
├── index.ts
|
||||||
|
├── config/
|
||||||
|
├── hooks/
|
||||||
|
├── styles/
|
||||||
|
└── ui/
|
||||||
|
```
|
||||||
|
|
||||||
|
```text
|
||||||
|
backend-api/
|
||||||
|
├── backend-api.client.ts
|
||||||
|
├── config/
|
||||||
|
├── types/
|
||||||
|
└── index.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
## Структура
|
||||||
|
|
||||||
|
Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль включает только те части, которые нужны его ответственности.
|
||||||
|
|
||||||
|
```text
|
||||||
|
{module-name}/
|
||||||
|
├── {module-name}.factory.ts # фабрика (для business-модулей)
|
||||||
|
├── {module-name}.tsx # корневой файл модуля (опционален)
|
||||||
|
├── ui/ # компоненты модуля
|
||||||
|
├── parts/ # вложенные модули
|
||||||
|
├── hooks/ # хуки
|
||||||
|
├── stores/ # сторы состояния
|
||||||
|
├── services/ # внешние источники данных
|
||||||
|
├── mappers/ # трансформация данных между форматами
|
||||||
|
├── types/ # типы
|
||||||
|
├── styles/ # стили
|
||||||
|
├── lib/ # утилиты модуля
|
||||||
|
├── config/ # константы и конфигурация
|
||||||
|
└── index.ts # публичный API
|
||||||
|
```
|
||||||
|
|
||||||
|
Подробное описание сегментов — в разделе [Сегменты](/architecture/segments).
|
||||||
|
|
||||||
|
## Публичный API
|
||||||
|
|
||||||
|
Внешний код импортирует модуль только через публичный API.
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// Хорошо
|
||||||
|
import { customerFactory } from '@/business/customer'
|
||||||
|
import type { Customer } from '@/business/customer'
|
||||||
|
```
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// Плохо
|
||||||
|
import { validateToken } from '@/business/auth/lib/tokens'
|
||||||
|
```
|
||||||
|
|
||||||
|
`index.ts` модуля не обязан экспортировать всё содержимое. Он экспортирует только то, что действительно нужно снаружи.
|
||||||
|
|
||||||
|
Внутренние сегменты модуля остаются деталями реализации.
|
||||||
|
|
||||||
|
Business-модуль экспортирует из `index.ts` только фабрику и type-only экспорты. Хуки, компоненты, сервисы, мапперы и утилиты напрямую из `index.ts` не экспортируются — они доступны через API, который возвращает фабрика.
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// business/customer/index.ts
|
||||||
|
export { customerFactory } from './customer.factory'
|
||||||
|
|
||||||
|
export type { Customer } from './types/customer.type'
|
||||||
|
export type { CustomerApi } from './types/customer-api.type'
|
||||||
|
export type { CustomerDeps } from './types/customer-deps.type'
|
||||||
|
export type { CustomerFactory } from './types/customer-factory.type'
|
||||||
|
```
|
||||||
|
|
||||||
|
## Фабрика
|
||||||
|
|
||||||
|
Business-модуль всегда экспортирует фабрику. Фабрика лежит в корне модуля (`{name}.factory.ts`), типизируется через `{Name}Factory` и возвращает публичный runtime API модуля.
|
||||||
|
|
||||||
|
Всё, что нужно внешнему коду в runtime, должно быть частью API, который возвращает фабрика.
|
||||||
|
|
||||||
|
Модуль без cross-domain зависимостей экспортирует фабрику без аргументов. Модуль с зависимостями — фабрику, принимающую зависимости доменными именами. Типы всегда экспортируются напрямую через `export type` — `import type` не является runtime-зависимостью.
|
||||||
|
|
||||||
|
Компоновка фабрик происходит на уровне модуля-потребителя: screen, layout, widget или любой другой модуль группы «Композиция».
|
||||||
|
|
||||||
|
### Структура business-модуля
|
||||||
|
|
||||||
|
```text
|
||||||
|
business/customer/
|
||||||
|
├── customer.factory.ts
|
||||||
|
├── index.ts
|
||||||
|
└── types/
|
||||||
|
├── customer.type.ts
|
||||||
|
├── customer-api.type.ts
|
||||||
|
├── customer-deps.type.ts
|
||||||
|
└── customer-factory.type.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
### Типы
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// business/customer/types/customer-api.type.ts
|
||||||
|
export type CustomerApi = {
|
||||||
|
useCustomer: () => Customer
|
||||||
|
CustomerCard: (props: CustomerCardProps) => ReactNode
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// business/order/types/order-deps.type.ts
|
||||||
|
export type OrderDeps = {
|
||||||
|
customer: Pick<CustomerApi, 'useCustomer'>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// business/order/types/order-factory.type.ts
|
||||||
|
export type OrderFactory = (deps: OrderDeps) => OrderApi
|
||||||
|
```
|
||||||
|
|
||||||
|
### Фабрика без зависимостей
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// business/customer/customer.factory.ts
|
||||||
|
import type { CustomerFactory } from './types/customer-factory.type'
|
||||||
|
|
||||||
|
export const customerFactory: CustomerFactory = () => {
|
||||||
|
return {
|
||||||
|
useCustomer,
|
||||||
|
CustomerCard,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Фабрика с зависимостями
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// business/order/order.factory.ts
|
||||||
|
import type { OrderFactory } from './types/order-factory.type'
|
||||||
|
|
||||||
|
export const orderFactory: OrderFactory = (deps) => {
|
||||||
|
return {
|
||||||
|
useOrder,
|
||||||
|
OrderCard,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Композиция на уровне screen
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// screens/home/home.screen.tsx
|
||||||
|
import { customerFactory } from '@/business/customer'
|
||||||
|
import { orderFactory } from '@/business/order'
|
||||||
|
|
||||||
|
const customer = customerFactory()
|
||||||
|
const order = orderFactory({ customer })
|
||||||
|
|
||||||
|
const { useOrder, OrderCard } = order
|
||||||
|
|
||||||
|
export const HomeScreen = () => {
|
||||||
|
const currentOrder = useOrder()
|
||||||
|
|
||||||
|
return <OrderCard order={currentOrder} />
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Жизненный цикл
|
||||||
|
|
||||||
|
Модуль рождается на самом низком уровне использования и поднимается выше только при реальной потребности.
|
||||||
|
|
||||||
|
- Нужен на одной странице → `screens/{name}/parts/`
|
||||||
|
- Появился в 2+ местах → поднимается по природе:
|
||||||
|
- абстрактный UI → `ui/`
|
||||||
|
- блок с данными/логикой → `widgets/`
|
||||||
|
- представление бизнес-домена → `business/{area}/parts/`
|
||||||
|
|
||||||
|
Подъём — обычный рефакторинг в рамках задачи, а не отдельная активность.
|
||||||
@@ -1,5 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: Сегменты
|
title: Сегменты
|
||||||
|
description: Сегменты внутри модуля (ui/, model/, lib/ и др.), назначение и правила размещения файлов
|
||||||
---
|
---
|
||||||
|
|
||||||
# Сегменты
|
# Сегменты
|
||||||
@@ -14,7 +15,7 @@ title: Сегменты
|
|||||||
|
|
||||||
| Сегмент | Содержимое |
|
| Сегмент | Содержимое |
|
||||||
|---------|------------|
|
|---------|------------|
|
||||||
| `ui/` | Компоненты модуля — только `.tsx` файлы |
|
| `ui/` | Презентационные компоненты родительского модуля |
|
||||||
| `parts/` | Вложенные модули со своими сегментами |
|
| `parts/` | Вложенные модули со своими сегментами |
|
||||||
| `hooks/` | React-хуки |
|
| `hooks/` | React-хуки |
|
||||||
| `stores/` | Сторы состояния |
|
| `stores/` | Сторы состояния |
|
||||||
@@ -27,24 +28,48 @@ title: Сегменты
|
|||||||
|
|
||||||
## Сегмент ui/
|
## Сегмент ui/
|
||||||
|
|
||||||
Компоненты, принадлежащие модулю. Содержит только `.tsx` файлы — без своих сегментов, стилей, типов, хуков. Использует сегменты родительского модуля.
|
Презентационные компоненты родительского модуля. `ui/` содержит только компоненты, которые отвечают за отображение части интерфейса и не выходят за границы своего модуля.
|
||||||
|
|
||||||
|
Компонент в `ui/`:
|
||||||
|
|
||||||
|
- Находится в собственной папке.
|
||||||
|
- Может содержать только `{name}.tsx`, `index.ts`, `styles/`, `types/`.
|
||||||
|
- Не содержит любые компоненты.
|
||||||
|
- Не содержит любые модули.
|
||||||
|
- Не импортирует код проекта за пределами родительского модуля.
|
||||||
|
- Не делает внешние запросы.
|
||||||
|
- Не вызывает сценарные хуки.
|
||||||
|
- Не получает данные самостоятельно, не выбирает источник данных и не композирует данные.
|
||||||
|
- Не содержит бизнес-логику или сценарную логику.
|
||||||
|
|
||||||
|
Если UI-сущности нужно что-то за пределами этих ограничений, она должна быть оформлена как модуль. Полная граница описана в разделе [Компонент](/architecture/modules#компонент).
|
||||||
|
|
||||||
|
Корневой файл модуля в `ui/` не размещается. Он лежит в корне модуля: `{module-name}.tsx`.
|
||||||
|
|
||||||
```text
|
```text
|
||||||
auth/
|
user/
|
||||||
├── ui/
|
├── ui/
|
||||||
│ ├── auth-provider.tsx
|
│ ├── user-avatar/
|
||||||
│ ├── auth-guard.tsx
|
│ │ ├── user-avatar.tsx
|
||||||
│ └── logout-button.tsx
|
│ │ ├── styles/
|
||||||
|
│ │ │ └── user-avatar.module.css
|
||||||
|
│ │ ├── types/
|
||||||
|
│ │ │ └── user-avatar-props.type.ts
|
||||||
|
│ │ └── index.ts
|
||||||
|
│ └── user-status/
|
||||||
|
│ ├── user-status.tsx
|
||||||
|
│ └── index.ts
|
||||||
├── types/
|
├── types/
|
||||||
├── hooks/
|
├── hooks/
|
||||||
|
├── user.tsx
|
||||||
└── index.ts
|
└── index.ts
|
||||||
```
|
```
|
||||||
|
|
||||||
Если компоненту нужны собственные сегменты — это уже не `ui/`, а `parts/`.
|
Если UI-сущности нужна внутренняя декомпозиция, сценарная логика, получение данных или собственные архитектурные зависимости — это уже не компонент в `ui/`, а модуль в `parts/`.
|
||||||
|
|
||||||
## Сегмент parts/
|
## Сегмент parts/
|
||||||
|
|
||||||
Вложенные модули со своими сегментами. Каждый элемент `parts/` — полноценный модуль: папка с компонентом, хуками, стилями, типами и т.д.
|
Вложенные модули со своими сегментами. `parts/` содержит только модули: каждый элемент `parts/` — папка полноценного модуля с собственным публичным API. Отдельные `.tsx`, стили, хуки или произвольные файлы в `parts/` не размещаются.
|
||||||
|
|
||||||
```text
|
```text
|
||||||
home/
|
home/
|
||||||
@@ -52,17 +77,20 @@ home/
|
|||||||
│ ├── hero-section/
|
│ ├── hero-section/
|
||||||
│ │ ├── hero-section.tsx
|
│ │ ├── hero-section.tsx
|
||||||
│ │ ├── styles/
|
│ │ ├── styles/
|
||||||
│ │ └── parts/
|
│ │ ├── parts/
|
||||||
│ │ └── top-banner/
|
│ │ │ └── top-banner/
|
||||||
│ │ └── top-banner.tsx
|
│ │ │ ├── top-banner.tsx
|
||||||
|
│ │ │ └── index.ts
|
||||||
|
│ │ └── index.ts
|
||||||
│ └── features-section/
|
│ └── features-section/
|
||||||
│ ├── features-section.tsx
|
│ ├── features-section.tsx
|
||||||
│ └── hooks/
|
│ ├── hooks/
|
||||||
|
│ └── index.ts
|
||||||
├── home.screen.tsx
|
├── home.screen.tsx
|
||||||
└── index.ts
|
└── index.ts
|
||||||
```
|
```
|
||||||
|
|
||||||
Отличие от `ui/`: элемент `parts/` — модуль со своими сегментами. Элемент `ui/` — компонент, один `.tsx` файл.
|
Отличие от `ui/`: элемент `parts/` — модульная папка со своими сегментами. Элемент `ui/` — компонент родительского модуля без собственной архитектурной ответственности.
|
||||||
|
|
||||||
Вложенность `parts/` инкапсулирует область разработки горизонтально: каждый разработчик работает в своём `parts/`-модуле, не затрагивая чужие. Это снижает конфликты при параллельной разработке.
|
Вложенность `parts/` инкапсулирует область разработки горизонтально: каждый разработчик работает в своём `parts/`-модуле, не затрагивая чужие. Это снижает конфликты при параллельной разработке.
|
||||||
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
---
|
|
||||||
title: Edge Cases
|
|
||||||
---
|
|
||||||
|
|
||||||
# Edge Cases
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
---
|
|
||||||
title: Layers
|
|
||||||
---
|
|
||||||
|
|
||||||
# Layers
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
---
|
|
||||||
title: Module
|
|
||||||
---
|
|
||||||
|
|
||||||
# Module
|
|
||||||
@@ -1,7 +0,0 @@
|
|||||||
---
|
|
||||||
title: Overview
|
|
||||||
---
|
|
||||||
|
|
||||||
# Overview
|
|
||||||
|
|
||||||
Architecture based on SLM Design (Scoped Layered Module Design) and strict module boundaries.
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
---
|
|
||||||
title: Rationale
|
|
||||||
---
|
|
||||||
|
|
||||||
# Rationale
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
---
|
|
||||||
title: Terminology
|
|
||||||
---
|
|
||||||
|
|
||||||
# Terminology
|
|
||||||
@@ -1,7 +0,0 @@
|
|||||||
# SLM Design
|
|
||||||
|
|
||||||
Project architecture rules and standards.
|
|
||||||
|
|
||||||
## For Assistants
|
|
||||||
|
|
||||||
Full documentation in a single MD file: https://gromlab.ru/docs/frontend-style-guide/raw/branch/main/generated/en/RULES.md
|
|
||||||
29
docs/index.md
Normal file
29
docs/index.md
Normal file
@@ -0,0 +1,29 @@
|
|||||||
|
---
|
||||||
|
title: Документация
|
||||||
|
---
|
||||||
|
|
||||||
|
# Документация
|
||||||
|
|
||||||
|
Раздел помогает быстро найти нужное правило SLM Design. Здесь собраны маршруты чтения, карта разделов и ссылки на материалы для AI-ассистентов.
|
||||||
|
|
||||||
|
## С чего начать
|
||||||
|
|
||||||
|
- Если вы знакомитесь с подходом впервые — начните с [SLM Design](/architecture/).
|
||||||
|
- Если проектируете структуру `src/` — откройте [Слои](/architecture/layers).
|
||||||
|
- Если создаёте новый домен или блок интерфейса — используйте [Модули](/architecture/modules).
|
||||||
|
- Если выбираете папку внутри модуля — смотрите [Сегменты](/architecture/segments).
|
||||||
|
|
||||||
|
## Разделы
|
||||||
|
|
||||||
|
| Раздел | Когда открывать |
|
||||||
|
|--------|----------------|
|
||||||
|
| [SLM Design](/architecture/) | Нужно понять общую идею архитектуры и контекст правил. |
|
||||||
|
| [Слои](/architecture/layers) | Нужно определить, где должен жить код и какие зависимости допустимы. |
|
||||||
|
| [Модули](/architecture/modules) | Нужно оформить границы модуля, публичный API или фабрику. |
|
||||||
|
| [Сегменты](/architecture/segments) | Нужно выбрать внутреннюю папку для компонента, хука, стиля, типа или конфига. |
|
||||||
|
|
||||||
|
## Для ассистентов
|
||||||
|
|
||||||
|
- `/llms.txt` — краткая карта документации.
|
||||||
|
- `/llms-full.txt` — полный контекст архитектуры.
|
||||||
|
- `/slm-design.zip` — архив Markdown-файлов.
|
||||||
@@ -1,164 +0,0 @@
|
|||||||
---
|
|
||||||
title: Модули
|
|
||||||
---
|
|
||||||
|
|
||||||
# Модули
|
|
||||||
|
|
||||||
Раздел описывает модули SLM: что такое модуль, из чего он состоит и как взаимодействует с остальным кодом.
|
|
||||||
|
|
||||||
## Определение
|
|
||||||
|
|
||||||
**Модуль — универсальный строительный блок архитектуры. Живёт на слое и содержит всё необходимое для своей работы: компоненты, хуки, сторы, сервисы, типы, стили. Набор содержимого не фиксирован — включаются только нужные части.**
|
|
||||||
|
|
||||||
## Модуль vs компонент
|
|
||||||
|
|
||||||
**Компонент** — один `.tsx` файл. Не имеет своих сегментов, использует сегменты родительского модуля. Живёт в корне или `ui/` сегменте модуля.
|
|
||||||
|
|
||||||
**Модуль** — папка, которая может содержать корневой компонент, сегменты (`hooks/`, `types/`, `styles/`, `ui/`, `parts/` и т.д.) и публичный API (`index.ts`).
|
|
||||||
|
|
||||||
```text
|
|
||||||
auth/
|
|
||||||
├── ui/
|
|
||||||
│ ├── auth-guard.tsx
|
|
||||||
│ └── logout-button.tsx
|
|
||||||
├── parts/
|
|
||||||
│ ├── login-form/
|
|
||||||
│ ├── registration-form/
|
|
||||||
│ └── restore-form/
|
|
||||||
├── hooks/
|
|
||||||
├── stores/
|
|
||||||
├── types/
|
|
||||||
├── auth.tsx # корневой компонент (опционален)
|
|
||||||
└── index.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
## Структура
|
|
||||||
|
|
||||||
Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль может состоять даже из одного `index.ts` с реэкспортом типов.
|
|
||||||
|
|
||||||
```text
|
|
||||||
{module-name}/
|
|
||||||
├── {module-name}.tsx # корневой компонент (опционален)
|
|
||||||
├── ui/ # компоненты модуля (только .tsx)
|
|
||||||
├── parts/ # вложенные модули (со своими сегментами)
|
|
||||||
├── hooks/ # хуки
|
|
||||||
├── stores/ # сторы состояния
|
|
||||||
├── services/ # внешние источники данных
|
|
||||||
├── mappers/ # трансформация данных между форматами
|
|
||||||
├── types/ # типы
|
|
||||||
├── styles/ # стили
|
|
||||||
├── lib/ # утилиты модуля
|
|
||||||
├── config/ # константы
|
|
||||||
└── index.ts # публичный API
|
|
||||||
```
|
|
||||||
|
|
||||||
Подробное описание каждого сегмента — в разделе [Сегменты](/reference/segments).
|
|
||||||
|
|
||||||
## Публичный API
|
|
||||||
|
|
||||||
Модуль экспортирует наружу только то, что нужно другим. Всё остальное — внутреннее.
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// business/auth/index.ts
|
|
||||||
export type { User, Session } from './types/user.types'
|
|
||||||
export { useAuth } from './hooks/use-auth.hook'
|
|
||||||
export { AuthGuard } from './ui/auth-guard'
|
|
||||||
```
|
|
||||||
|
|
||||||
Импорт в обход `index.ts` запрещён:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// Плохо
|
|
||||||
import { validateToken } from '@/business/auth/lib/tokens'
|
|
||||||
|
|
||||||
// Хорошо
|
|
||||||
import { useAuth } from '@/business/auth'
|
|
||||||
```
|
|
||||||
|
|
||||||
## Фабрика
|
|
||||||
|
|
||||||
Если модуль зависит от кода другого бизнес-домена — он экспортирует фабрику. Фабрика декларирует необходимые зависимости и возвращает API модуля. Точка использования (screen, widget, layout) предоставляет зависимости при вызове.
|
|
||||||
|
|
||||||
Модуль без cross-domain зависимостей экспортирует API напрямую. Типы всегда экспортируются напрямую — `import type` не является runtime-зависимостью.
|
|
||||||
|
|
||||||
### Модуль без зависимостей — прямой экспорт:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// business/auth/index.ts
|
|
||||||
export { useAuth } from './hooks/use-auth'
|
|
||||||
export { useCurrentUser } from './hooks/use-current-user'
|
|
||||||
export type { User, Session } from './types'
|
|
||||||
```
|
|
||||||
|
|
||||||
### Модуль с зависимостями — фабрика:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// business/chat/types/deps.ts
|
|
||||||
import type { User } from '@/business/auth'
|
|
||||||
|
|
||||||
export interface ChatDeps {
|
|
||||||
useCurrentUser: () => User | null
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// business/chat/index.ts
|
|
||||||
import type { ChatDeps } from './types/deps'
|
|
||||||
|
|
||||||
export function chatFactory(deps: ChatDeps) {
|
|
||||||
return {
|
|
||||||
useMessages: (roomId: string) => {
|
|
||||||
const user = deps.useCurrentUser()
|
|
||||||
// ...
|
|
||||||
},
|
|
||||||
useSendMessage: (roomId: string) => {
|
|
||||||
const user = deps.useCurrentUser()
|
|
||||||
return (text: string) => { /* ... */ }
|
|
||||||
},
|
|
||||||
useChatRooms: () => {
|
|
||||||
const user = deps.useCurrentUser()
|
|
||||||
// ...
|
|
||||||
},
|
|
||||||
ChatBadge: ({ count }: { count: number }) => { /* ... */ },
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
export type { Message, ChatRoom } from './types'
|
|
||||||
export type { ChatDeps } from './types/deps'
|
|
||||||
```
|
|
||||||
|
|
||||||
### Использование на странице:
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
// screens/support/support.tsx
|
|
||||||
import { useCurrentUser } from '@/business/auth'
|
|
||||||
import { chatFactory } from '@/business/chat'
|
|
||||||
|
|
||||||
const chat = chatFactory({ useCurrentUser })
|
|
||||||
|
|
||||||
export function SupportScreen() {
|
|
||||||
const { useMessages, useSendMessage, ChatBadge } = chat
|
|
||||||
const messages = useMessages('support')
|
|
||||||
const sendMessage = useSendMessage('support')
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div>
|
|
||||||
<ChatBadge count={messages.length} />
|
|
||||||
{messages.map(m => <MessageBubble key={m.id} {...m} />)}
|
|
||||||
<MessageInput onSend={sendMessage} />
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Жизненный цикл
|
|
||||||
|
|
||||||
Модуль рождается на самом низком уровне использования и поднимается выше только при реальной потребности.
|
|
||||||
|
|
||||||
- Нужен на одной странице → `screens/{name}/parts/`
|
|
||||||
- Появился в 2+ местах → поднимается по природе:
|
|
||||||
- абстрактный UI → `ui/`
|
|
||||||
- блок с данными/логикой → `widgets/`
|
|
||||||
- представление бизнес-домена → `business/{area}/parts/`
|
|
||||||
|
|
||||||
Подъём — обычный рефакторинг в рамках задачи, а не отдельная активность.
|
|
||||||
282
generate.ts
Normal file
282
generate.ts
Normal file
@@ -0,0 +1,282 @@
|
|||||||
|
import path from "path";
|
||||||
|
import fs from "fs";
|
||||||
|
import os from "os";
|
||||||
|
import { execFileSync } from "child_process";
|
||||||
|
|
||||||
|
const SRC_DIR = "./docs";
|
||||||
|
const PUBLIC_DIR = "./public";
|
||||||
|
const DOCS_PUBLIC_DIR = path.join(SRC_DIR, "public");
|
||||||
|
const DOC_ROUTE_PREFIX = "/docs";
|
||||||
|
const PUBLIC_ARCHITECTURE_FILE = "ARCHITECTURE.md";
|
||||||
|
const PUBLIC_ARCHITECTURE_NOTICE = `> Локальная копия канонической спецификации SLM Design.
|
||||||
|
> Источник: https://slm-design.gromlab.ru/ARCHITECTURE.md
|
||||||
|
> Не редактировать вручную в этом проекте.`;
|
||||||
|
|
||||||
|
interface SidebarItem {
|
||||||
|
text: string;
|
||||||
|
link: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
interface SidebarGroup {
|
||||||
|
text: string;
|
||||||
|
items: SidebarItem[];
|
||||||
|
}
|
||||||
|
|
||||||
|
function parseSidebar(): SidebarGroup[] {
|
||||||
|
const configPath = path.join(".vitepress", "config.ts");
|
||||||
|
const raw = fs.readFileSync(configPath, "utf8");
|
||||||
|
const start = raw.indexOf("const sidebar = [");
|
||||||
|
const end = raw.indexOf("];", start) + 2;
|
||||||
|
const section = raw.substring(start, end);
|
||||||
|
|
||||||
|
const groups: SidebarGroup[] = [];
|
||||||
|
const groupParts = section.split(/\n\s*\}\s*,?\s*\n/).filter(Boolean);
|
||||||
|
|
||||||
|
for (const part of groupParts) {
|
||||||
|
const textMatch = part.match(/text:\s*'([^']*)'/);
|
||||||
|
if (!textMatch) continue;
|
||||||
|
const items: SidebarItem[] = [];
|
||||||
|
const itemRe = /\{\s*text:\s*'([^']*)'\s*,\s*link:\s*'([^']*)'\s*\}/g;
|
||||||
|
let im: RegExpExecArray | null;
|
||||||
|
while ((im = itemRe.exec(part)) !== null) {
|
||||||
|
items.push({ text: im[1], link: im[2] });
|
||||||
|
}
|
||||||
|
if (items.length > 0) groups.push({ text: textMatch[1], items });
|
||||||
|
}
|
||||||
|
return groups;
|
||||||
|
}
|
||||||
|
|
||||||
|
const SIDEBAR = parseSidebar();
|
||||||
|
|
||||||
|
function linkToFileRel(link: string): string {
|
||||||
|
const rel = link.replace(/^\//, "");
|
||||||
|
if (rel === "" || rel.endsWith("/")) return `${rel}index.md`;
|
||||||
|
return `${rel}.md`;
|
||||||
|
}
|
||||||
|
|
||||||
|
function fileRelToRoute(file: string): string {
|
||||||
|
const route = file.endsWith("/index.md")
|
||||||
|
? file.replace(/index\.md$/, "")
|
||||||
|
: file.replace(/\.md$/, "");
|
||||||
|
return `${DOC_ROUTE_PREFIX}/${route}`;
|
||||||
|
}
|
||||||
|
|
||||||
|
function fileRelToMdUrl(file: string): string {
|
||||||
|
return `${DOC_ROUTE_PREFIX}/${file}`;
|
||||||
|
}
|
||||||
|
|
||||||
|
const ARCHITECTURE_LINK_RE = /\]\((\/architecture(?:\/[^)\s#]*)?)(#[^)\s]*)?\)/g;
|
||||||
|
|
||||||
|
function architectureRouteToFileRel(route: string): string {
|
||||||
|
if (route.replace(/\/$/, "") === "/architecture") return "architecture/index.md";
|
||||||
|
return linkToFileRel(route);
|
||||||
|
}
|
||||||
|
|
||||||
|
function transformArchitectureLinks(
|
||||||
|
content: string,
|
||||||
|
toHref: (route: string, hash: string) => string,
|
||||||
|
): string {
|
||||||
|
return content.replace(ARCHITECTURE_LINK_RE, (_match, route: string, hash = "") => {
|
||||||
|
return `](${toHref(route, hash)})`;
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function transformArchiveLinks(content: string): string {
|
||||||
|
return transformArchitectureLinks(content, (route, hash) => {
|
||||||
|
const fileName = path.basename(architectureRouteToFileRel(route));
|
||||||
|
return `./${fileName}${hash}`;
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function transformSiteMarkdownLinks(content: string): string {
|
||||||
|
return transformArchitectureLinks(content, (route, hash) => {
|
||||||
|
return `${fileRelToMdUrl(architectureRouteToFileRel(route))}${hash}`;
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function getAllFiles(): string[] {
|
||||||
|
return SIDEBAR.flatMap((g) => g.items.map((item) => linkToFileRel(item.link)));
|
||||||
|
}
|
||||||
|
|
||||||
|
const stripFrontmatter = (content: string) =>
|
||||||
|
content.replace(/^---[\s\S]*?---\n*/m, "");
|
||||||
|
|
||||||
|
const stripRulesLink = (content: string) =>
|
||||||
|
content.replace(/<!-- rules-link -->[\s\S]*?<!-- \/rules-link -->\n*/g, "");
|
||||||
|
|
||||||
|
function slugifyHeading(heading: string): string {
|
||||||
|
return heading
|
||||||
|
.trim()
|
||||||
|
.replace(/[`*_~[\]()]/g, "")
|
||||||
|
.toLowerCase()
|
||||||
|
.replace(/[^\p{L}\p{N}\s-]/gu, "")
|
||||||
|
.trim()
|
||||||
|
.replace(/\s+/g, "-");
|
||||||
|
}
|
||||||
|
|
||||||
|
function fileRelToSingleFileAnchor(file: string): string {
|
||||||
|
const filePath = path.join(SRC_DIR, file);
|
||||||
|
if (!fs.existsSync(filePath)) return slugifyHeading(path.basename(file, ".md"));
|
||||||
|
|
||||||
|
const raw = stripFrontmatter(fs.readFileSync(filePath, "utf8"));
|
||||||
|
const title = raw.match(/^#\s+(.+)$/m)?.[1];
|
||||||
|
return slugifyHeading(title ?? path.basename(file, ".md"));
|
||||||
|
}
|
||||||
|
|
||||||
|
function transformSingleFileLinks(content: string): string {
|
||||||
|
return transformArchitectureLinks(content, (route, hash) => {
|
||||||
|
if (hash) return hash;
|
||||||
|
return `#${fileRelToSingleFileAnchor(architectureRouteToFileRel(route))}`;
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function transformReadmeLinks(content: string): string {
|
||||||
|
return transformArchitectureLinks(content, (route, hash) => {
|
||||||
|
return `docs/${architectureRouteToFileRel(route)}${hash}`;
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
const shiftHeadings = (content: string) => {
|
||||||
|
const lines = content.split("\n");
|
||||||
|
let inCodeBlock = false;
|
||||||
|
return lines
|
||||||
|
.map((line) => {
|
||||||
|
if (line.startsWith("```")) inCodeBlock = !inCodeBlock;
|
||||||
|
if (inCodeBlock) return line;
|
||||||
|
if (/^#{1,5}\s/.test(line)) return "#" + line;
|
||||||
|
return line;
|
||||||
|
})
|
||||||
|
.join("\n");
|
||||||
|
};
|
||||||
|
|
||||||
|
const buildArchitectureMarkdown = (routePrefix: string) => {
|
||||||
|
const files = getAllFiles();
|
||||||
|
const parts: string[] = [];
|
||||||
|
|
||||||
|
for (const file of files) {
|
||||||
|
const filePath = path.join(SRC_DIR, file);
|
||||||
|
if (!fs.existsSync(filePath)) continue;
|
||||||
|
const raw = fs.readFileSync(filePath, "utf8");
|
||||||
|
const content = stripRulesLink(stripFrontmatter(raw)).trim();
|
||||||
|
if (!content) continue;
|
||||||
|
|
||||||
|
const route = routePrefix + fileRelToRoute(file).replace(DOC_ROUTE_PREFIX, "");
|
||||||
|
const shifted = file.endsWith("index.md") ? content : shiftHeadings(content);
|
||||||
|
const processed = transformSingleFileLinks(shifted);
|
||||||
|
parts.push(`<!-- ${route} -->\n${processed}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
return parts.join("\n\n");
|
||||||
|
};
|
||||||
|
|
||||||
|
function buildLlms() {
|
||||||
|
const parts: string[] = [`# SLM Design\n`];
|
||||||
|
parts.push(`> Scoped Layered Module Design — модульная архитектура фронтенд-приложений\n`);
|
||||||
|
|
||||||
|
for (const group of SIDEBAR) {
|
||||||
|
parts.push(`## ${group.text}`);
|
||||||
|
for (const item of group.items) {
|
||||||
|
const fileRel = linkToFileRel(item.link);
|
||||||
|
const filePath = path.join(SRC_DIR, fileRel);
|
||||||
|
let desc = "";
|
||||||
|
if (fs.existsSync(filePath)) {
|
||||||
|
const raw = fs.readFileSync(filePath, "utf8");
|
||||||
|
const fm = raw.match(/^---[\s\S]*?---\n*/m);
|
||||||
|
desc = fm ? fm[0].match(/description:\s*(.+)/)?.[1] || "" : "";
|
||||||
|
}
|
||||||
|
const route = fileRelToMdUrl(fileRel);
|
||||||
|
const line = desc
|
||||||
|
? `- [${item.text}](${route}): ${desc}`
|
||||||
|
: `- [${item.text}](${route})`;
|
||||||
|
parts.push(line);
|
||||||
|
}
|
||||||
|
parts.push("");
|
||||||
|
}
|
||||||
|
|
||||||
|
const outPath = path.join(PUBLIC_DIR, "llms.txt");
|
||||||
|
fs.mkdirSync(PUBLIC_DIR, { recursive: true });
|
||||||
|
fs.writeFileSync(outPath, parts.join("\n"), "utf8");
|
||||||
|
console.log(`llms.txt создан: ${outPath}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
function buildLlmsFull() {
|
||||||
|
const outPath = path.join(PUBLIC_DIR, "llms-full.txt");
|
||||||
|
fs.writeFileSync(outPath, buildArchitectureMarkdown("/docs"), "utf8");
|
||||||
|
console.log(`llms-full.txt создан: ${outPath}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
function copyMarkdownFiles() {
|
||||||
|
fs.rmSync(DOCS_PUBLIC_DIR, { recursive: true, force: true });
|
||||||
|
|
||||||
|
let copied = 0;
|
||||||
|
for (const file of getAllFiles()) {
|
||||||
|
const src = path.join(SRC_DIR, file);
|
||||||
|
if (!fs.existsSync(src)) continue;
|
||||||
|
|
||||||
|
const content = transformSiteMarkdownLinks(fs.readFileSync(src, "utf8"));
|
||||||
|
const dest = path.join(DOCS_PUBLIC_DIR, file);
|
||||||
|
fs.mkdirSync(path.dirname(dest), { recursive: true });
|
||||||
|
fs.writeFileSync(dest, content, "utf8");
|
||||||
|
copied++;
|
||||||
|
}
|
||||||
|
|
||||||
|
console.log(`скопировано ${copied} .md-файлов в ${DOCS_PUBLIC_DIR}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
function buildPublicArchitecture() {
|
||||||
|
const outPath = path.join(PUBLIC_DIR, PUBLIC_ARCHITECTURE_FILE);
|
||||||
|
const content = `${PUBLIC_ARCHITECTURE_NOTICE}\n\n${buildArchitectureMarkdown("/docs")}`;
|
||||||
|
fs.mkdirSync(PUBLIC_DIR, { recursive: true });
|
||||||
|
fs.writeFileSync(outPath, content, "utf8");
|
||||||
|
console.log(`${PUBLIC_ARCHITECTURE_FILE} создан: ${outPath}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
function buildZip() {
|
||||||
|
const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "slm-"));
|
||||||
|
const tmpDir = path.join(tmpRoot, "slm-design");
|
||||||
|
fs.mkdirSync(tmpDir, { recursive: true });
|
||||||
|
|
||||||
|
const files = getAllFiles();
|
||||||
|
for (const file of files) {
|
||||||
|
const src = path.join(SRC_DIR, file);
|
||||||
|
if (!fs.existsSync(src)) continue;
|
||||||
|
let content = fs.readFileSync(src, "utf8");
|
||||||
|
content = stripRulesLink(stripFrontmatter(content)).trim();
|
||||||
|
content = transformArchiveLinks(content);
|
||||||
|
const destName = path.basename(file);
|
||||||
|
fs.writeFileSync(path.join(tmpDir, destName), content, "utf8");
|
||||||
|
}
|
||||||
|
|
||||||
|
const pkg = JSON.parse(fs.readFileSync("./package.json", "utf8"));
|
||||||
|
const version = `v${pkg.version}`;
|
||||||
|
fs.writeFileSync(path.join(tmpDir, "VERSION"), `${version}\n${new Date().toISOString()}\n`, "utf8");
|
||||||
|
|
||||||
|
const outPath = path.resolve(PUBLIC_DIR, "slm-design.zip");
|
||||||
|
fs.mkdirSync(PUBLIC_DIR, { recursive: true });
|
||||||
|
if (fs.existsSync(outPath)) fs.unlinkSync(outPath);
|
||||||
|
|
||||||
|
execFileSync("zip", ["-rq", outPath, "slm-design"], { cwd: tmpRoot });
|
||||||
|
fs.rmSync(tmpRoot, { recursive: true });
|
||||||
|
console.log(`slm-design.zip создан: ${outPath}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
function buildReadme() {
|
||||||
|
const indexPath = path.join(SRC_DIR, "architecture/index.md");
|
||||||
|
if (!fs.existsSync(indexPath)) {
|
||||||
|
console.log("Пропуск README: index.md не найден");
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
let content = stripFrontmatter(fs.readFileSync(indexPath, "utf8"));
|
||||||
|
content = content.replace(/<!-- rules-link -->[\s\S]*?<!-- \/rules-link -->\n*/g, "");
|
||||||
|
content = transformReadmeLinks(content);
|
||||||
|
fs.writeFileSync("./README.md", content, "utf8");
|
||||||
|
console.log("README.md создан");
|
||||||
|
}
|
||||||
|
|
||||||
|
buildLlms();
|
||||||
|
buildLlmsFull();
|
||||||
|
copyMarkdownFiles();
|
||||||
|
buildPublicArchitecture();
|
||||||
|
buildZip();
|
||||||
|
buildReadme();
|
||||||
@@ -1,8 +0,0 @@
|
|||||||
<!-- /index -->
|
|
||||||
# SLM Design
|
|
||||||
|
|
||||||
Project architecture rules and standards.
|
|
||||||
|
|
||||||
## For Assistants
|
|
||||||
|
|
||||||
Full documentation in a single MD file: https://gromlab.ru/docs/frontend-style-guide/raw/branch/main/generated/en/RULES.md
|
|
||||||
32
index.html
Normal file
32
index.html
Normal file
@@ -0,0 +1,32 @@
|
|||||||
|
<!doctype html>
|
||||||
|
<html lang="ru">
|
||||||
|
<head>
|
||||||
|
<meta charset="UTF-8" />
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||||
|
<title>SLM Design</title>
|
||||||
|
<meta name="description" content="Scoped Layered Module Design — модульная архитектура фронтенд-приложений" />
|
||||||
|
<meta name="llms" content="/llms.txt" />
|
||||||
|
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
|
||||||
|
<link rel="alternate llms" type="text/plain" href="/llms.txt" title="llms.txt" />
|
||||||
|
<link rel="alternate" type="text/plain" href="/llms-full.txt" title="llms-full.txt" />
|
||||||
|
<link rel="alternate" type="text/markdown" href="/ARCHITECTURE.md" title="ARCHITECTURE.md" />
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div id="root">
|
||||||
|
<main>
|
||||||
|
<h1>SLM Design</h1>
|
||||||
|
<p>Scoped Layered Module Design — модульная архитектура фронтенд-приложений.</p>
|
||||||
|
<nav aria-label="Карта сайта и AI-артефакты">
|
||||||
|
<ul>
|
||||||
|
<li><a href="/docs/">Документация</a></li>
|
||||||
|
<li><a href="/llms.txt" rel="alternate" type="text/plain">llms.txt</a></li>
|
||||||
|
<li><a href="/llms-full.txt" rel="alternate" type="text/plain">llms-full.txt</a></li>
|
||||||
|
<li><a href="/ARCHITECTURE.md" rel="alternate" type="text/markdown">ARCHITECTURE.md</a></li>
|
||||||
|
<li><a href="/slm-design.zip" download>slm-design.zip</a></li>
|
||||||
|
</ul>
|
||||||
|
</nav>
|
||||||
|
</main>
|
||||||
|
</div>
|
||||||
|
<script type="module" src="/src/main.tsx"></script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
2840
package-lock.json
generated
2840
package-lock.json
generated
File diff suppressed because it is too large
Load Diff
21
package.json
21
package.json
@@ -2,15 +2,24 @@
|
|||||||
"name": "slm-design",
|
"name": "slm-design",
|
||||||
"private": true,
|
"private": true,
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"version": "0.0.0",
|
"version": "0.1.5",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"docs": "node ./concat-md.js",
|
"dev": "vite",
|
||||||
"dev": "vitepress dev .",
|
"build": "vite build",
|
||||||
"build": "vitepress build .",
|
"preview": "vite preview",
|
||||||
"serve": "vitepress serve ."
|
"docs:dev": "vitepress dev . --port 5174",
|
||||||
|
"docs:build": "vitepress build .",
|
||||||
|
"generate": "tsx ./generate.ts"
|
||||||
},
|
},
|
||||||
"dependencies": {},
|
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
|
"@types/react": "^19.2.14",
|
||||||
|
"@types/react-dom": "^19.2.3",
|
||||||
|
"@vitejs/plugin-react": "^6.0.1",
|
||||||
|
"tsx": "^4.21.0",
|
||||||
"vitepress": "^1.6.3"
|
"vitepress": "^1.6.3"
|
||||||
|
},
|
||||||
|
"dependencies": {
|
||||||
|
"react": "^18.3.1",
|
||||||
|
"react-dom": "^18.3.1"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,16 +1,34 @@
|
|||||||
<!-- /index -->
|
> Локальная копия канонической спецификации SLM Design.
|
||||||
|
> Источник: https://slm-design.gromlab.ru/ARCHITECTURE.md
|
||||||
|
> Не редактировать вручную в этом проекте.
|
||||||
|
|
||||||
|
<!-- /docs/architecture/ -->
|
||||||
# SLM Design
|
# SLM Design
|
||||||
Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
|
Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
|
||||||
|
|
||||||
|
## Разделы спецификации
|
||||||
|
|
||||||
|
Спецификация SLM Design состоит из нескольких связанных разделов. Этот обзор даёт общий контекст, а детальные правила описаны дальше:
|
||||||
|
|
||||||
|
- [Слои](#слои) — уровни организации `src/`, направление зависимостей и зона ответственности каждого слоя.
|
||||||
|
- [Модули](#модули) — границы ответственности, публичный API, типы модулей и отличие модуля от компонента.
|
||||||
|
- [Сегменты](#сегменты) — внутренние папки модуля (`ui/`, `parts/`, `hooks/`, `types/` и другие) и правила размещения файлов.
|
||||||
|
|
||||||
|
Рекомендуемый порядок чтения: обзор → слои → модули → сегменты.
|
||||||
|
|
||||||
## Преимущества
|
## Преимущества
|
||||||
|
|
||||||
### Вертикальная организация домена
|
### Вертикальная организация домена
|
||||||
|
|
||||||
Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
|
Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
|
||||||
|
|
||||||
|
### Dependency Injection без фреймворков
|
||||||
|
|
||||||
|
Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
|
||||||
|
|
||||||
### Разделение ответственности без перегрузки слоёв
|
### Разделение ответственности без перегрузки слоёв
|
||||||
|
|
||||||
Сервисы приложения (`infrastructure/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
|
Сервисы приложения (`infra/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
|
||||||
|
|
||||||
### Горизонтальная инкапсуляция
|
### Горизонтальная инкапсуляция
|
||||||
|
|
||||||
@@ -28,10 +46,6 @@ Scoped Layered Module Design — модульная архитектура фр
|
|||||||
|
|
||||||
При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
|
При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
|
||||||
|
|
||||||
### Dependency Injection без фреймворков
|
|
||||||
|
|
||||||
Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
|
|
||||||
|
|
||||||
## Происхождение
|
## Происхождение
|
||||||
|
|
||||||
SLM Design вырос на основе:
|
SLM Design вырос на основе:
|
||||||
@@ -68,7 +82,7 @@ src/
|
|||||||
│ ├── orders/
|
│ ├── orders/
|
||||||
│ └── chat/
|
│ └── chat/
|
||||||
│
|
│
|
||||||
├── infrastructure/
|
├── infra/
|
||||||
│ ├── theme/
|
│ ├── theme/
|
||||||
│ ├── i18n/
|
│ ├── i18n/
|
||||||
│ ├── backend-api/
|
│ ├── backend-api/
|
||||||
@@ -94,7 +108,7 @@ src/
|
|||||||
- **Зависимости однонаправлены.** Импорты только сверху вниз, только через публичный API.
|
- **Зависимости однонаправлены.** Импорты только сверху вниз, только через публичный API.
|
||||||
- **Архитектура — каркас, не клетка.** Правила фиксируют направление зависимостей и структуру модуля, остальное определяет команда.
|
- **Архитектура — каркас, не клетка.** Правила фиксируют направление зависимостей и структуру модуля, остальное определяет команда.
|
||||||
|
|
||||||
<!-- /reference/layers -->
|
<!-- /docs/architecture/layers -->
|
||||||
## Слои
|
## Слои
|
||||||
|
|
||||||
Раздел описывает слои SLM: что такое слой, какие бывают, как между ними направлены зависимости и какие правила действуют на каждом.
|
Раздел описывает слои SLM: что такое слой, какие бывают, как между ними направлены зависимости и какие правила действуют на каждом.
|
||||||
@@ -110,7 +124,7 @@ src/
|
|||||||
| Группа | Слои | Описание |
|
| Группа | Слои | Описание |
|
||||||
|--------|------|----------|
|
|--------|------|----------|
|
||||||
| Композиция | `app`, `layouts`, `screens`, `widgets` | Собирают интерфейс из готовых блоков: маршруты, каркасы, страницы |
|
| Композиция | `app`, `layouts`, `screens`, `widgets` | Собирают интерфейс из готовых блоков: маршруты, каркасы, страницы |
|
||||||
| Ядро | `business`, `infrastructure`, `ui` | Реализация продукта: бизнес-домены, техсервисы, UI-кит |
|
| Ядро | `business`, `infra`, `ui` | Реализация продукта: бизнес-домены, техсервисы, UI-кит |
|
||||||
| Фундамент | `shared` | Общие ресурсы: утилиты, хелперы, стили, конфиги |
|
| Фундамент | `shared` | Общие ресурсы: утилиты, хелперы, стили, конфиги |
|
||||||
|
|
||||||
### Направление зависимостей
|
### Направление зависимостей
|
||||||
@@ -118,12 +132,12 @@ src/
|
|||||||
Любой импорт между модулями — только через публичный API.
|
Любой импорт между модулями — только через публичный API.
|
||||||
|
|
||||||
```
|
```
|
||||||
app → [ layouts | screens ] → widgets → business → infrastructure → ui → shared
|
app → [ layouts | screens ] → widgets → business → infra → ui → shared
|
||||||
```
|
```
|
||||||
|
|
||||||
- `layouts` и `screens` — параллельные слои, не импортируют друг друга
|
- `layouts` и `screens` — параллельные слои, не импортируют друг друга
|
||||||
- Модули одного слоя в группе «Композиция» изолированы друг от друга
|
- Модули одного слоя в группе «Композиция» изолированы друг от друга
|
||||||
- Модули одного слоя `infrastructure` и `ui` могут импортировать друг друга через публичный API
|
- Модули одного слоя `infra` и `ui` могут импортировать друг друга через публичный API
|
||||||
- Модули `business` — cross-domain зависимости по коду через фабрику, `import type` напрямую
|
- Модули `business` — cross-domain зависимости по коду через фабрику, `import type` напрямую
|
||||||
- Импорт типов (`import type`) в «Ядре» разрешён в обоих направлениях
|
- Импорт типов (`import type`) в «Ядре» разрешён в обоих направлениях
|
||||||
|
|
||||||
@@ -221,7 +235,7 @@ src/widgets/
|
|||||||
|
|
||||||
Бизнес-домены приложения: auth, catalog, orders, checkout, chat. Каждый домен — отдельный модуль со своими типами, логикой, UI и сервисами.
|
Бизнес-домены приложения: auth, catalog, orders, checkout, chat. Каждый домен — отдельный модуль со своими типами, логикой, UI и сервисами.
|
||||||
|
|
||||||
Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`. Cross-domain зависимости по коду реализуются через фабрику. `import type` между доменами разрешён напрямую.
|
Слой входит в группу «Ядро». Импортирует `infra/`, `ui/`, `shared/`. Каждый бизнес-модуль создаёт публичный runtime API через фабрику в корне. Cross-domain зависимости: runtime — через аргументы фабрики, типы — напрямую через `import type`.
|
||||||
|
|
||||||
Business объединяет то, что в FSD разделено на `features` и `entities`: пользовательские сценарии и бизнес-сущности живут вместе, внутри одного домена. Внутри домена сегменты разделяют ответственность: `types/` — доменная модель, `hooks/` и `services/` — сценарии и логика, `mappers/` — трансформация данных, `parts/` — составные блоки.
|
Business объединяет то, что в FSD разделено на `features` и `entities`: пользовательские сценарии и бизнес-сущности живут вместе, внутри одного домена. Внутри домена сегменты разделяют ответственность: `types/` — доменная модель, `hooks/` и `services/` — сценарии и логика, `mappers/` — трансформация данных, `parts/` — составные блоки.
|
||||||
|
|
||||||
@@ -252,19 +266,20 @@ src/business/
|
|||||||
|
|
||||||
- Один модуль = один бизнес-домен
|
- Один модуль = один бизнес-домен
|
||||||
- Циклические зависимости между доменами запрещены
|
- Циклические зависимости между доменами запрещены
|
||||||
- Импорт кода между доменами — через фабрику. `import type` — напрямую
|
- Публичный runtime API — через фабрику в корне модуля (`{name}.factory.ts`). `index.ts` экспортирует только фабрику и type-only экспорты
|
||||||
|
- Импорт runtime-кода между доменами — через фабрику. `import type` — напрямую
|
||||||
- Доменные типы (`User`, `Product`) живут здесь, не в `shared/`
|
- Доменные типы (`User`, `Product`) живут здесь, не в `shared/`
|
||||||
|
|
||||||
### Слой Infrastructure
|
### Слой infra
|
||||||
|
|
||||||
Техсервисы приложения: theme, i18n, API-адаптеры, logger, realtime. Каждый сервис — отдельный модуль.
|
Техсервисы приложения: theme, i18n, API-адаптеры, logger, realtime. Каждый сервис — отдельный модуль.
|
||||||
|
|
||||||
Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`.
|
Слой входит в группу «Ядро». Импортирует `infra/`, `ui/`, `shared/`.
|
||||||
|
|
||||||
Отличие от `shared/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
Отличие от `shared/`: infra — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
||||||
|
|
||||||
```text
|
```text
|
||||||
src/infrastructure/
|
src/infra/
|
||||||
├── theme/
|
├── theme/
|
||||||
├── i18n/
|
├── i18n/
|
||||||
├── backend-api/
|
├── backend-api/
|
||||||
@@ -277,7 +292,7 @@ src/infrastructure/
|
|||||||
#### Требования
|
#### Требования
|
||||||
|
|
||||||
- Один модуль = один техсервис
|
- Один модуль = один техсервис
|
||||||
- Импортирует `infrastructure/`, `ui/`, `shared/`
|
- Импортирует `infra/`, `ui/`, `shared/`
|
||||||
|
|
||||||
### Слой UI
|
### Слой UI
|
||||||
|
|
||||||
@@ -328,7 +343,7 @@ src/ui/
|
|||||||
|
|
||||||
Слой входит в группу «Фундамент» — ни о ком не знает, никого не импортирует.
|
Слой входит в группу «Фундамент» — ни о ком не знает, никого не импортирует.
|
||||||
|
|
||||||
Отличие от `infrastructure/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
Отличие от `infra/`: infra — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
||||||
|
|
||||||
Отличие от `ui/`: UI-компоненты (button, carousel, modal) живут в слое `ui/`, а не здесь.
|
Отличие от `ui/`: UI-компоненты (button, carousel, modal) живут в слое `ui/`, а не здесь.
|
||||||
|
|
||||||
@@ -344,46 +359,144 @@ src/shared/
|
|||||||
|
|
||||||
- Не имеет runtime-состояния
|
- Не имеет runtime-состояния
|
||||||
|
|
||||||
<!-- /reference/modules -->
|
<!-- /docs/architecture/modules -->
|
||||||
## Модули
|
## Модули
|
||||||
|
|
||||||
Раздел описывает модули SLM: что такое модуль, из чего он состоит и как взаимодействует с остальным кодом.
|
Раздел описывает модуль как границу ответственности в SLM: что считается модулем, что такое компонент внутри модуля и как модуль взаимодействует с остальным кодом.
|
||||||
|
|
||||||
### Определение
|
### Определение
|
||||||
|
|
||||||
**Модуль — универсальный строительный блок архитектуры. Живёт на слое и содержит всё необходимое для своей работы: компоненты, хуки, сторы, сервисы, типы, стили. Набор содержимого не фиксирован — включаются только нужные части.**
|
**Модуль — минимальная архитектурная единица SLM. Он живёт на одном из слоёв, владеет конкретной областью ответственности и предоставляет наружу только публичный API.**
|
||||||
|
|
||||||
### Модуль vs компонент
|
Модуль может содержать всё, что нужно этой области: компоненты, вложенные модули, хуки, сторы, сервисы, типы, стили, конфиги и утилиты. Набор сегментов не фиксирован — модуль включает только то, что реально нужно.
|
||||||
|
|
||||||
**Компонент** — один `.tsx` файл. Не имеет своих сегментов, использует сегменты родительского модуля. Живёт в корне или `ui/` сегменте модуля.
|
Модуль не обязан быть UI-блоком. Это может быть страница, виджет, бизнес-домен, инфраструктурный сервис или UI-kit сущность.
|
||||||
|
|
||||||
**Модуль** — папка, которая может содержать корневой компонент, сегменты (`hooks/`, `types/`, `styles/`, `ui/`, `parts/` и т.д.) и публичный API (`index.ts`).
|
Главная граница модуля — не папка, а ответственность.
|
||||||
|
|
||||||
|
### Компонент
|
||||||
|
|
||||||
|
**Компонент — презентационная единица модуля, которая находится только в `ui/` своего родительского модуля и отвечает за отображение части интерфейса.**
|
||||||
|
|
||||||
|
Компонент не является архитектурной единицей: он не владеет сценарием, зависимостями, данными или внутренней структурой. Он работает только внутри границы родительского модуля.
|
||||||
|
|
||||||
|
> Компонент отображает. Модуль организует.
|
||||||
|
|
||||||
|
Компонент не может:
|
||||||
|
|
||||||
|
- Импортировать код проекта за пределами родительского модуля.
|
||||||
|
- Владеть архитектурными зависимостями.
|
||||||
|
- Содержать любые компоненты.
|
||||||
|
- Содержать любые модули.
|
||||||
|
- Делать внешние запросы.
|
||||||
|
- Самостоятельно получать данные.
|
||||||
|
- Выбирать источник данных.
|
||||||
|
- Композировать данные.
|
||||||
|
- Вызывать сценарные хуки.
|
||||||
|
- Оркестрировать сценарий.
|
||||||
|
- Композировать модули.
|
||||||
|
- Решать, как устроен процесс.
|
||||||
|
- Содержать бизнес-логику.
|
||||||
|
- Содержать сценарную логику.
|
||||||
|
|
||||||
|
Если компоненту требуется что-то из этого списка, он перестаёт быть компонентом и должен быть оформлен как модуль.
|
||||||
|
|
||||||
```text
|
```text
|
||||||
auth/
|
auth/
|
||||||
├── ui/
|
├── ui/
|
||||||
│ ├── auth-guard.tsx
|
│ └── logout-button/
|
||||||
│ └── logout-button.tsx
|
│ ├── logout-button.tsx
|
||||||
├── parts/
|
│ ├── styles/
|
||||||
│ ├── login-form/
|
│ │ └── logout-button.module.css
|
||||||
│ ├── registration-form/
|
│ ├── types/
|
||||||
│ └── restore-form/
|
│ │ └── logout-button-props.type.ts
|
||||||
|
│ └── index.ts
|
||||||
|
└── index.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
### Что считается модулем
|
||||||
|
|
||||||
|
Модулем считается папка, которая представляет самостоятельную область ответственности и имеет публичную границу.
|
||||||
|
|
||||||
|
Примеры модулей:
|
||||||
|
|
||||||
|
- `screens/home/` — модуль страницы.
|
||||||
|
- `widgets/page-heading/` — модуль виджета.
|
||||||
|
- `business/auth/` — модуль бизнес-домена.
|
||||||
|
- `infra/theme/` — модуль инфраструктурного сервиса.
|
||||||
|
- `ui/button/` — модуль UI-kit сущности.
|
||||||
|
- `screens/home/parts/hero-section/` — вложенный модуль страницы.
|
||||||
|
|
||||||
|
Не считаются модулями:
|
||||||
|
|
||||||
|
- `ui/`, `parts/`, `hooks/`, `types/`, `styles/`, `config/` — это сегменты.
|
||||||
|
- `screens/shop/`, `business/commerce/` — это группы, если в них нет `index.ts`.
|
||||||
|
- `screens/home/ui/user-card/` — это компонент, если он находится в `ui/` и соблюдает ограничения компонента.
|
||||||
|
|
||||||
|
### Типы модулей
|
||||||
|
|
||||||
|
Тип модуля определяет обязательный корневой файл и стартовую структуру.
|
||||||
|
|
||||||
|
#### UI-модуль
|
||||||
|
|
||||||
|
Модуль строится вокруг основного UI-компонента и обязан иметь основной `.tsx` файл в корне:
|
||||||
|
|
||||||
|
```text
|
||||||
|
header/
|
||||||
|
├── header.tsx
|
||||||
|
└── index.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
`ui/` внутри такого модуля используется только для компонентов, которые помогают корневому `.tsx` файлу.
|
||||||
|
|
||||||
|
#### Бизнес-модуль
|
||||||
|
|
||||||
|
Бизнес-модуль — модуль, который строится вокруг публичного runtime API.
|
||||||
|
|
||||||
|
Бизнес-модуль обязан иметь фабрику в корне:
|
||||||
|
|
||||||
|
```text
|
||||||
|
auth/
|
||||||
|
├── auth.factory.ts
|
||||||
|
├── index.ts
|
||||||
|
└── types/
|
||||||
|
```
|
||||||
|
|
||||||
|
Фабрика возвращает публичный runtime API модуля.
|
||||||
|
|
||||||
|
#### Инфраструктурный модуль
|
||||||
|
|
||||||
|
Инфраструктурный модуль — модуль, который строится вокруг технического сервиса или интеграции.
|
||||||
|
|
||||||
|
Инфраструктурный модуль не обязан иметь фиксированный корневой файл. Его структура определяется природой сервиса.
|
||||||
|
|
||||||
|
```text
|
||||||
|
theme/
|
||||||
|
├── index.ts
|
||||||
|
├── config/
|
||||||
├── hooks/
|
├── hooks/
|
||||||
├── stores/
|
├── styles/
|
||||||
|
└── ui/
|
||||||
|
```
|
||||||
|
|
||||||
|
```text
|
||||||
|
backend-api/
|
||||||
|
├── backend-api.client.ts
|
||||||
|
├── config/
|
||||||
├── types/
|
├── types/
|
||||||
├── auth.tsx # корневой компонент (опционален)
|
|
||||||
└── index.ts
|
└── index.ts
|
||||||
```
|
```
|
||||||
|
|
||||||
### Структура
|
### Структура
|
||||||
|
|
||||||
Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль может состоять даже из одного `index.ts` с реэкспортом типов.
|
Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль включает только те части, которые нужны его ответственности.
|
||||||
|
|
||||||
```text
|
```text
|
||||||
{module-name}/
|
{module-name}/
|
||||||
├── {module-name}.tsx # корневой компонент (опционален)
|
├── {module-name}.factory.ts # фабрика (для business-модулей)
|
||||||
├── ui/ # компоненты модуля (только .tsx)
|
├── {module-name}.tsx # корневой файл модуля (опционален)
|
||||||
├── parts/ # вложенные модули (со своими сегментами)
|
├── ui/ # компоненты модуля
|
||||||
|
├── parts/ # вложенные модули
|
||||||
├── hooks/ # хуки
|
├── hooks/ # хуки
|
||||||
├── stores/ # сторы состояния
|
├── stores/ # сторы состояния
|
||||||
├── services/ # внешние источники данных
|
├── services/ # внешние источники данных
|
||||||
@@ -391,106 +504,132 @@ auth/
|
|||||||
├── types/ # типы
|
├── types/ # типы
|
||||||
├── styles/ # стили
|
├── styles/ # стили
|
||||||
├── lib/ # утилиты модуля
|
├── lib/ # утилиты модуля
|
||||||
├── config/ # константы
|
├── config/ # константы и конфигурация
|
||||||
└── index.ts # публичный API
|
└── index.ts # публичный API
|
||||||
```
|
```
|
||||||
|
|
||||||
Подробное описание каждого сегмента — в разделе [Сегменты](/reference/segments).
|
Подробное описание сегментов — в разделе [Сегменты](#сегменты).
|
||||||
|
|
||||||
### Публичный API
|
### Публичный API
|
||||||
|
|
||||||
Модуль экспортирует наружу только то, что нужно другим. Всё остальное — внутреннее.
|
Внешний код импортирует модуль только через публичный API.
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
// business/auth/index.ts
|
// Хорошо
|
||||||
export type { User, Session } from './types/user.types'
|
import { customerFactory } from '@/business/customer'
|
||||||
export { useAuth } from './hooks/use-auth.hook'
|
import type { Customer } from '@/business/customer'
|
||||||
export { AuthGuard } from './ui/auth-guard'
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Импорт в обход `index.ts` запрещён:
|
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
// Плохо
|
// Плохо
|
||||||
import { validateToken } from '@/business/auth/lib/tokens'
|
import { validateToken } from '@/business/auth/lib/tokens'
|
||||||
|
```
|
||||||
|
|
||||||
// Хорошо
|
`index.ts` модуля не обязан экспортировать всё содержимое. Он экспортирует только то, что действительно нужно снаружи.
|
||||||
import { useAuth } from '@/business/auth'
|
|
||||||
|
Внутренние сегменты модуля остаются деталями реализации.
|
||||||
|
|
||||||
|
Business-модуль экспортирует из `index.ts` только фабрику и type-only экспорты. Хуки, компоненты, сервисы, мапперы и утилиты напрямую из `index.ts` не экспортируются — они доступны через API, который возвращает фабрика.
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// business/customer/index.ts
|
||||||
|
export { customerFactory } from './customer.factory'
|
||||||
|
|
||||||
|
export type { Customer } from './types/customer.type'
|
||||||
|
export type { CustomerApi } from './types/customer-api.type'
|
||||||
|
export type { CustomerDeps } from './types/customer-deps.type'
|
||||||
|
export type { CustomerFactory } from './types/customer-factory.type'
|
||||||
```
|
```
|
||||||
|
|
||||||
### Фабрика
|
### Фабрика
|
||||||
|
|
||||||
Если модуль зависит от кода другого бизнес-домена — он экспортирует фабрику. Фабрика декларирует необходимые зависимости и возвращает API модуля. Точка использования (screen, widget, layout) предоставляет зависимости при вызове.
|
Business-модуль всегда экспортирует фабрику. Фабрика лежит в корне модуля (`{name}.factory.ts`), типизируется через `{Name}Factory` и возвращает публичный runtime API модуля.
|
||||||
|
|
||||||
Модуль без cross-domain зависимостей экспортирует API напрямую. Типы всегда экспортируются напрямую — `import type` не является runtime-зависимостью.
|
Всё, что нужно внешнему коду в runtime, должно быть частью API, который возвращает фабрика.
|
||||||
|
|
||||||
#### Модуль без зависимостей — прямой экспорт:
|
Модуль без cross-domain зависимостей экспортирует фабрику без аргументов. Модуль с зависимостями — фабрику, принимающую зависимости доменными именами. Типы всегда экспортируются напрямую через `export type` — `import type` не является runtime-зависимостью.
|
||||||
|
|
||||||
```ts
|
Компоновка фабрик происходит на уровне модуля-потребителя: screen, layout, widget или любой другой модуль группы «Композиция».
|
||||||
// business/auth/index.ts
|
|
||||||
export { useAuth } from './hooks/use-auth'
|
#### Структура business-модуля
|
||||||
export { useCurrentUser } from './hooks/use-current-user'
|
|
||||||
export type { User, Session } from './types'
|
```text
|
||||||
|
business/customer/
|
||||||
|
├── customer.factory.ts
|
||||||
|
├── index.ts
|
||||||
|
└── types/
|
||||||
|
├── customer.type.ts
|
||||||
|
├── customer-api.type.ts
|
||||||
|
├── customer-deps.type.ts
|
||||||
|
└── customer-factory.type.ts
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Модуль с зависимостями — фабрика:
|
#### Типы
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
// business/chat/types/deps.ts
|
// business/customer/types/customer-api.type.ts
|
||||||
import type { User } from '@/business/auth'
|
export type CustomerApi = {
|
||||||
|
useCustomer: () => Customer
|
||||||
export interface ChatDeps {
|
CustomerCard: (props: CustomerCardProps) => ReactNode
|
||||||
useCurrentUser: () => User | null
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
// business/chat/index.ts
|
// business/order/types/order-deps.type.ts
|
||||||
import type { ChatDeps } from './types/deps'
|
export type OrderDeps = {
|
||||||
|
customer: Pick<CustomerApi, 'useCustomer'>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
export function chatFactory(deps: ChatDeps) {
|
```ts
|
||||||
|
// business/order/types/order-factory.type.ts
|
||||||
|
export type OrderFactory = (deps: OrderDeps) => OrderApi
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Фабрика без зависимостей
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// business/customer/customer.factory.ts
|
||||||
|
import type { CustomerFactory } from './types/customer-factory.type'
|
||||||
|
|
||||||
|
export const customerFactory: CustomerFactory = () => {
|
||||||
return {
|
return {
|
||||||
useMessages: (roomId: string) => {
|
useCustomer,
|
||||||
const user = deps.useCurrentUser()
|
CustomerCard,
|
||||||
// ...
|
|
||||||
},
|
|
||||||
useSendMessage: (roomId: string) => {
|
|
||||||
const user = deps.useCurrentUser()
|
|
||||||
return (text: string) => { /* ... */ }
|
|
||||||
},
|
|
||||||
useChatRooms: () => {
|
|
||||||
const user = deps.useCurrentUser()
|
|
||||||
// ...
|
|
||||||
},
|
|
||||||
ChatBadge: ({ count }: { count: number }) => { /* ... */ },
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
export type { Message, ChatRoom } from './types'
|
|
||||||
export type { ChatDeps } from './types/deps'
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Использование на странице:
|
#### Фабрика с зависимостями
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// business/order/order.factory.ts
|
||||||
|
import type { OrderFactory } from './types/order-factory.type'
|
||||||
|
|
||||||
|
export const orderFactory: OrderFactory = (deps) => {
|
||||||
|
return {
|
||||||
|
useOrder,
|
||||||
|
OrderCard,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Композиция на уровне screen
|
||||||
|
|
||||||
```tsx
|
```tsx
|
||||||
// screens/support/support.tsx
|
// screens/home/home.screen.tsx
|
||||||
import { useCurrentUser } from '@/business/auth'
|
import { customerFactory } from '@/business/customer'
|
||||||
import { chatFactory } from '@/business/chat'
|
import { orderFactory } from '@/business/order'
|
||||||
|
|
||||||
const chat = chatFactory({ useCurrentUser })
|
const customer = customerFactory()
|
||||||
|
const order = orderFactory({ customer })
|
||||||
|
|
||||||
export function SupportScreen() {
|
const { useOrder, OrderCard } = order
|
||||||
const { useMessages, useSendMessage, ChatBadge } = chat
|
|
||||||
const messages = useMessages('support')
|
|
||||||
const sendMessage = useSendMessage('support')
|
|
||||||
|
|
||||||
return (
|
export const HomeScreen = () => {
|
||||||
<div>
|
const currentOrder = useOrder()
|
||||||
<ChatBadge count={messages.length} />
|
|
||||||
{messages.map(m => <MessageBubble key={m.id} {...m} />)}
|
return <OrderCard order={currentOrder} />
|
||||||
<MessageInput onSend={sendMessage} />
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -506,7 +645,7 @@ export function SupportScreen() {
|
|||||||
|
|
||||||
Подъём — обычный рефакторинг в рамках задачи, а не отдельная активность.
|
Подъём — обычный рефакторинг в рамках задачи, а не отдельная активность.
|
||||||
|
|
||||||
<!-- /reference/segments -->
|
<!-- /docs/architecture/segments -->
|
||||||
## Сегменты
|
## Сегменты
|
||||||
|
|
||||||
Раздел описывает сегменты SLM: что такое сегмент, какие бывают и что в каждом из них лежит.
|
Раздел описывает сегменты SLM: что такое сегмент, какие бывают и что в каждом из них лежит.
|
||||||
@@ -519,7 +658,7 @@ export function SupportScreen() {
|
|||||||
|
|
||||||
| Сегмент | Содержимое |
|
| Сегмент | Содержимое |
|
||||||
|---------|------------|
|
|---------|------------|
|
||||||
| `ui/` | Компоненты модуля — только `.tsx` файлы |
|
| `ui/` | Презентационные компоненты родительского модуля |
|
||||||
| `parts/` | Вложенные модули со своими сегментами |
|
| `parts/` | Вложенные модули со своими сегментами |
|
||||||
| `hooks/` | React-хуки |
|
| `hooks/` | React-хуки |
|
||||||
| `stores/` | Сторы состояния |
|
| `stores/` | Сторы состояния |
|
||||||
@@ -532,24 +671,48 @@ export function SupportScreen() {
|
|||||||
|
|
||||||
### Сегмент ui/
|
### Сегмент ui/
|
||||||
|
|
||||||
Компоненты, принадлежащие модулю. Содержит только `.tsx` файлы — без своих сегментов, стилей, типов, хуков. Использует сегменты родительского модуля.
|
Презентационные компоненты родительского модуля. `ui/` содержит только компоненты, которые отвечают за отображение части интерфейса и не выходят за границы своего модуля.
|
||||||
|
|
||||||
|
Компонент в `ui/`:
|
||||||
|
|
||||||
|
- Находится в собственной папке.
|
||||||
|
- Может содержать только `{name}.tsx`, `index.ts`, `styles/`, `types/`.
|
||||||
|
- Не содержит любые компоненты.
|
||||||
|
- Не содержит любые модули.
|
||||||
|
- Не импортирует код проекта за пределами родительского модуля.
|
||||||
|
- Не делает внешние запросы.
|
||||||
|
- Не вызывает сценарные хуки.
|
||||||
|
- Не получает данные самостоятельно, не выбирает источник данных и не композирует данные.
|
||||||
|
- Не содержит бизнес-логику или сценарную логику.
|
||||||
|
|
||||||
|
Если UI-сущности нужно что-то за пределами этих ограничений, она должна быть оформлена как модуль. Полная граница описана в разделе [Компонент](#компонент).
|
||||||
|
|
||||||
|
Корневой файл модуля в `ui/` не размещается. Он лежит в корне модуля: `{module-name}.tsx`.
|
||||||
|
|
||||||
```text
|
```text
|
||||||
auth/
|
user/
|
||||||
├── ui/
|
├── ui/
|
||||||
│ ├── auth-provider.tsx
|
│ ├── user-avatar/
|
||||||
│ ├── auth-guard.tsx
|
│ │ ├── user-avatar.tsx
|
||||||
│ └── logout-button.tsx
|
│ │ ├── styles/
|
||||||
|
│ │ │ └── user-avatar.module.css
|
||||||
|
│ │ ├── types/
|
||||||
|
│ │ │ └── user-avatar-props.type.ts
|
||||||
|
│ │ └── index.ts
|
||||||
|
│ └── user-status/
|
||||||
|
│ ├── user-status.tsx
|
||||||
|
│ └── index.ts
|
||||||
├── types/
|
├── types/
|
||||||
├── hooks/
|
├── hooks/
|
||||||
|
├── user.tsx
|
||||||
└── index.ts
|
└── index.ts
|
||||||
```
|
```
|
||||||
|
|
||||||
Если компоненту нужны собственные сегменты — это уже не `ui/`, а `parts/`.
|
Если UI-сущности нужна внутренняя декомпозиция, сценарная логика, получение данных или собственные архитектурные зависимости — это уже не компонент в `ui/`, а модуль в `parts/`.
|
||||||
|
|
||||||
### Сегмент parts/
|
### Сегмент parts/
|
||||||
|
|
||||||
Вложенные модули со своими сегментами. Каждый элемент `parts/` — полноценный модуль: папка с компонентом, хуками, стилями, типами и т.д.
|
Вложенные модули со своими сегментами. `parts/` содержит только модули: каждый элемент `parts/` — папка полноценного модуля с собственным публичным API. Отдельные `.tsx`, стили, хуки или произвольные файлы в `parts/` не размещаются.
|
||||||
|
|
||||||
```text
|
```text
|
||||||
home/
|
home/
|
||||||
@@ -557,17 +720,20 @@ home/
|
|||||||
│ ├── hero-section/
|
│ ├── hero-section/
|
||||||
│ │ ├── hero-section.tsx
|
│ │ ├── hero-section.tsx
|
||||||
│ │ ├── styles/
|
│ │ ├── styles/
|
||||||
│ │ └── parts/
|
│ │ ├── parts/
|
||||||
│ │ └── top-banner/
|
│ │ │ └── top-banner/
|
||||||
│ │ └── top-banner.tsx
|
│ │ │ ├── top-banner.tsx
|
||||||
|
│ │ │ └── index.ts
|
||||||
|
│ │ └── index.ts
|
||||||
│ └── features-section/
|
│ └── features-section/
|
||||||
│ ├── features-section.tsx
|
│ ├── features-section.tsx
|
||||||
│ └── hooks/
|
│ ├── hooks/
|
||||||
|
│ └── index.ts
|
||||||
├── home.screen.tsx
|
├── home.screen.tsx
|
||||||
└── index.ts
|
└── index.ts
|
||||||
```
|
```
|
||||||
|
|
||||||
Отличие от `ui/`: элемент `parts/` — модуль со своими сегментами. Элемент `ui/` — компонент, один `.tsx` файл.
|
Отличие от `ui/`: элемент `parts/` — модульная папка со своими сегментами. Элемент `ui/` — компонент родительского модуля без собственной архитектурной ответственности.
|
||||||
|
|
||||||
Вложенность `parts/` инкапсулирует область разработки горизонтально: каждый разработчик работает в своём `parts/`-модуле, не затрагивая чужие. Это снижает конфликты при параллельной разработке.
|
Вложенность `parts/` инкапсулирует область разработки горизонтально: каждый разработчик работает в своём `parts/`-модуле, не затрагивая чужие. Это снижает конфликты при параллельной разработке.
|
||||||
|
|
||||||
5
src/App.tsx
Normal file
5
src/App.tsx
Normal file
@@ -0,0 +1,5 @@
|
|||||||
|
import { HomeScreen } from './screens/home'
|
||||||
|
|
||||||
|
export default function App() {
|
||||||
|
return <HomeScreen />
|
||||||
|
}
|
||||||
1
src/env.d.ts
vendored
Normal file
1
src/env.d.ts
vendored
Normal file
@@ -0,0 +1 @@
|
|||||||
|
declare const __BUILD_VERSION__: string
|
||||||
20
src/infra/theme/config/theme.config.ts
Normal file
20
src/infra/theme/config/theme.config.ts
Normal file
@@ -0,0 +1,20 @@
|
|||||||
|
import type { ThemeMode } from '../types/theme-mode.type'
|
||||||
|
|
||||||
|
export const THEME_STORAGE_KEY = 'slm-theme'
|
||||||
|
|
||||||
|
export const THEME_TOGGLE_OPTIONS: ReadonlyArray<{
|
||||||
|
value: Exclude<ThemeMode, 'system'>
|
||||||
|
ariaLabel: string
|
||||||
|
title: string
|
||||||
|
}> = [
|
||||||
|
{
|
||||||
|
value: 'light',
|
||||||
|
ariaLabel: 'Включить светлую тему',
|
||||||
|
title: 'Светлая',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
value: 'dark',
|
||||||
|
ariaLabel: 'Включить тёмную тему',
|
||||||
|
title: 'Тёмная',
|
||||||
|
},
|
||||||
|
]
|
||||||
79
src/infra/theme/hooks/use-theme.hook.ts
Normal file
79
src/infra/theme/hooks/use-theme.hook.ts
Normal file
@@ -0,0 +1,79 @@
|
|||||||
|
import { useEffect, useLayoutEffect, useState } from 'react'
|
||||||
|
|
||||||
|
import { THEME_STORAGE_KEY } from '../config/theme.config'
|
||||||
|
import type { ResolvedTheme, ThemeMode } from '../types/theme-mode.type'
|
||||||
|
|
||||||
|
const DARK_THEME_QUERY = '(prefers-color-scheme: dark)'
|
||||||
|
|
||||||
|
const canUseDom = () => typeof window !== 'undefined' && typeof document !== 'undefined'
|
||||||
|
|
||||||
|
const isThemeMode = (value: string | null): value is ThemeMode => {
|
||||||
|
return value === 'system' || value === 'dark' || value === 'light'
|
||||||
|
}
|
||||||
|
|
||||||
|
const getSystemTheme = (): ResolvedTheme => {
|
||||||
|
if (!canUseDom()) return 'light'
|
||||||
|
|
||||||
|
return window.matchMedia(DARK_THEME_QUERY).matches ? 'dark' : 'light'
|
||||||
|
}
|
||||||
|
|
||||||
|
const resolveTheme = (theme: ThemeMode): ResolvedTheme => {
|
||||||
|
return theme === 'system' ? getSystemTheme() : theme
|
||||||
|
}
|
||||||
|
|
||||||
|
const getStoredTheme = (): ThemeMode => {
|
||||||
|
if (!canUseDom()) return 'system'
|
||||||
|
|
||||||
|
const storedTheme = window.localStorage.getItem(THEME_STORAGE_KEY)
|
||||||
|
|
||||||
|
return isThemeMode(storedTheme) ? storedTheme : 'system'
|
||||||
|
}
|
||||||
|
|
||||||
|
const applyTheme = (theme: ThemeMode) => {
|
||||||
|
if (!canUseDom()) return
|
||||||
|
|
||||||
|
const resolvedTheme = resolveTheme(theme)
|
||||||
|
|
||||||
|
document.documentElement.dataset.theme = theme
|
||||||
|
document.documentElement.style.colorScheme = resolvedTheme
|
||||||
|
|
||||||
|
if (theme === 'system') {
|
||||||
|
window.localStorage.removeItem(THEME_STORAGE_KEY)
|
||||||
|
return
|
||||||
|
}
|
||||||
|
|
||||||
|
window.localStorage.setItem(THEME_STORAGE_KEY, theme)
|
||||||
|
}
|
||||||
|
|
||||||
|
export function useTheme() {
|
||||||
|
const [theme, setTheme] = useState<ThemeMode>(getStoredTheme)
|
||||||
|
const [resolvedTheme, setResolvedTheme] = useState<ResolvedTheme>(() => resolveTheme(getStoredTheme()))
|
||||||
|
|
||||||
|
useLayoutEffect(() => {
|
||||||
|
applyTheme(theme)
|
||||||
|
setResolvedTheme(resolveTheme(theme))
|
||||||
|
}, [theme])
|
||||||
|
|
||||||
|
useEffect(() => {
|
||||||
|
if (!canUseDom()) return undefined
|
||||||
|
|
||||||
|
const mediaQuery = window.matchMedia(DARK_THEME_QUERY)
|
||||||
|
const handleSystemThemeChange = () => {
|
||||||
|
if (theme !== 'system') return
|
||||||
|
|
||||||
|
const nextResolvedTheme = resolveTheme(theme)
|
||||||
|
document.documentElement.style.colorScheme = nextResolvedTheme
|
||||||
|
setResolvedTheme(nextResolvedTheme)
|
||||||
|
}
|
||||||
|
|
||||||
|
mediaQuery.addEventListener('change', handleSystemThemeChange)
|
||||||
|
|
||||||
|
return () => mediaQuery.removeEventListener('change', handleSystemThemeChange)
|
||||||
|
}, [theme])
|
||||||
|
|
||||||
|
return {
|
||||||
|
theme,
|
||||||
|
resolvedTheme,
|
||||||
|
setTheme,
|
||||||
|
}
|
||||||
|
}
|
||||||
6
src/infra/theme/index.ts
Normal file
6
src/infra/theme/index.ts
Normal file
@@ -0,0 +1,6 @@
|
|||||||
|
import './styles/theme.css'
|
||||||
|
|
||||||
|
export { ThemeToggle } from './ui/theme-toggle'
|
||||||
|
export { useTheme } from './hooks/use-theme.hook'
|
||||||
|
|
||||||
|
export type { ResolvedTheme, ThemeMode } from './types/theme-mode.type'
|
||||||
55
src/infra/theme/styles/theme-toggle.module.css
Normal file
55
src/infra/theme/styles/theme-toggle.module.css
Normal file
@@ -0,0 +1,55 @@
|
|||||||
|
.root {
|
||||||
|
display: inline-flex;
|
||||||
|
align-items: stretch;
|
||||||
|
gap: 2px;
|
||||||
|
height: 36px;
|
||||||
|
padding: 4px;
|
||||||
|
border: 1px solid var(--border-soft);
|
||||||
|
border-radius: 999px;
|
||||||
|
background: var(--surface-soft);
|
||||||
|
}
|
||||||
|
|
||||||
|
.option {
|
||||||
|
appearance: none;
|
||||||
|
display: inline-flex;
|
||||||
|
align-items: center;
|
||||||
|
justify-content: center;
|
||||||
|
width: 28px;
|
||||||
|
padding: 0;
|
||||||
|
border: 0;
|
||||||
|
border-radius: 999px;
|
||||||
|
color: var(--text-muted);
|
||||||
|
background: transparent;
|
||||||
|
font: inherit;
|
||||||
|
font-size: 13px;
|
||||||
|
font-weight: 700;
|
||||||
|
letter-spacing: -0.01em;
|
||||||
|
cursor: pointer;
|
||||||
|
transition: background-color 150ms ease, color 150ms ease, box-shadow 150ms ease;
|
||||||
|
}
|
||||||
|
|
||||||
|
.option:hover {
|
||||||
|
color: var(--text-primary);
|
||||||
|
}
|
||||||
|
|
||||||
|
.option:focus-visible {
|
||||||
|
outline: 2px solid var(--focus-ring);
|
||||||
|
outline-offset: 3px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.option[data-active='true'] {
|
||||||
|
color: var(--text-primary);
|
||||||
|
background: var(--page-bg);
|
||||||
|
box-shadow: 0 1px 2px var(--shadow-subtle);
|
||||||
|
}
|
||||||
|
|
||||||
|
.icon {
|
||||||
|
display: inline-flex;
|
||||||
|
width: 16px;
|
||||||
|
height: 16px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.icon svg {
|
||||||
|
width: 100%;
|
||||||
|
height: 100%;
|
||||||
|
}
|
||||||
85
src/infra/theme/styles/theme.css
Normal file
85
src/infra/theme/styles/theme.css
Normal file
@@ -0,0 +1,85 @@
|
|||||||
|
:root {
|
||||||
|
color-scheme: light;
|
||||||
|
font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
|
||||||
|
font-synthesis: none;
|
||||||
|
text-rendering: optimizeLegibility;
|
||||||
|
-webkit-font-smoothing: antialiased;
|
||||||
|
--page-bg: #f7f7fa;
|
||||||
|
--surface: #f0f1f5;
|
||||||
|
--surface-soft: #ffffff;
|
||||||
|
--surface-strong: #ffffff;
|
||||||
|
--surface-raised: #ffffff;
|
||||||
|
--surface-muted: #eef0ff;
|
||||||
|
--text-primary: #181a22;
|
||||||
|
--text-secondary: #5d6474;
|
||||||
|
--text-muted: #8b93a5;
|
||||||
|
--border-soft: #dfe2ea;
|
||||||
|
--border-strong: #c8ceda;
|
||||||
|
--accent-cool: #6677ff;
|
||||||
|
--focus-ring: rgba(102, 119, 255, 0.56);
|
||||||
|
--shadow-subtle: rgba(25, 31, 54, 0.1);
|
||||||
|
}
|
||||||
|
|
||||||
|
:root[data-theme='dark'] {
|
||||||
|
color-scheme: dark;
|
||||||
|
--page-bg: #1b1c21;
|
||||||
|
--surface: #24262d;
|
||||||
|
--surface-soft: #202229;
|
||||||
|
--surface-strong: #2a2c34;
|
||||||
|
--surface-raised: #202229;
|
||||||
|
--surface-muted: #2b2e3b;
|
||||||
|
--text-primary: #f1f3f8;
|
||||||
|
--text-secondary: #a9afbf;
|
||||||
|
--text-muted: #747c90;
|
||||||
|
--border-soft: #343741;
|
||||||
|
--border-strong: #454957;
|
||||||
|
--accent-cool: #8492ff;
|
||||||
|
--focus-ring: rgba(132, 146, 255, 0.66);
|
||||||
|
--shadow-subtle: rgba(0, 0, 0, 0.24);
|
||||||
|
}
|
||||||
|
|
||||||
|
@media (prefers-color-scheme: dark) {
|
||||||
|
:root:not([data-theme='light']) {
|
||||||
|
color-scheme: dark;
|
||||||
|
--page-bg: #1b1c21;
|
||||||
|
--surface: #24262d;
|
||||||
|
--surface-soft: #202229;
|
||||||
|
--surface-strong: #2a2c34;
|
||||||
|
--surface-raised: #202229;
|
||||||
|
--surface-muted: #2b2e3b;
|
||||||
|
--text-primary: #f1f3f8;
|
||||||
|
--text-secondary: #a9afbf;
|
||||||
|
--text-muted: #747c90;
|
||||||
|
--border-soft: #343741;
|
||||||
|
--border-strong: #454957;
|
||||||
|
--accent-cool: #8492ff;
|
||||||
|
--focus-ring: rgba(132, 146, 255, 0.66);
|
||||||
|
--shadow-subtle: rgba(0, 0, 0, 0.24);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
* {
|
||||||
|
box-sizing: border-box;
|
||||||
|
}
|
||||||
|
|
||||||
|
html {
|
||||||
|
min-height: 100%;
|
||||||
|
background: var(--page-bg);
|
||||||
|
}
|
||||||
|
|
||||||
|
body {
|
||||||
|
min-width: 320px;
|
||||||
|
min-height: 100vh;
|
||||||
|
margin: 0;
|
||||||
|
background: var(--page-bg);
|
||||||
|
color: var(--text-primary);
|
||||||
|
}
|
||||||
|
|
||||||
|
button,
|
||||||
|
a {
|
||||||
|
-webkit-tap-highlight-color: transparent;
|
||||||
|
}
|
||||||
|
|
||||||
|
a {
|
||||||
|
color: inherit;
|
||||||
|
}
|
||||||
3
src/infra/theme/types/theme-mode.type.ts
Normal file
3
src/infra/theme/types/theme-mode.type.ts
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
export type ThemeMode = 'system' | 'dark' | 'light'
|
||||||
|
|
||||||
|
export type ResolvedTheme = 'dark' | 'light'
|
||||||
61
src/infra/theme/ui/theme-toggle.tsx
Normal file
61
src/infra/theme/ui/theme-toggle.tsx
Normal file
@@ -0,0 +1,61 @@
|
|||||||
|
import { THEME_TOGGLE_OPTIONS } from '../config/theme.config'
|
||||||
|
import { useTheme } from '../hooks/use-theme.hook'
|
||||||
|
import type { ThemeMode } from '../types/theme-mode.type'
|
||||||
|
import type { ReactNode } from 'react'
|
||||||
|
import styles from '../styles/theme-toggle.module.css'
|
||||||
|
|
||||||
|
const iconByTheme: Record<Exclude<ThemeMode, 'system'>, ReactNode> = {
|
||||||
|
light: (
|
||||||
|
<svg aria-hidden="true" viewBox="0 0 24 24" fill="none">
|
||||||
|
<circle cx="12" cy="12" r="4" stroke="currentColor" strokeWidth="2" />
|
||||||
|
<path
|
||||||
|
d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41"
|
||||||
|
stroke="currentColor"
|
||||||
|
strokeWidth="2"
|
||||||
|
strokeLinecap="round"
|
||||||
|
/>
|
||||||
|
</svg>
|
||||||
|
),
|
||||||
|
dark: (
|
||||||
|
<svg aria-hidden="true" viewBox="0 0 24 24" fill="none">
|
||||||
|
<path
|
||||||
|
d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"
|
||||||
|
stroke="currentColor"
|
||||||
|
strokeWidth="2"
|
||||||
|
strokeLinecap="round"
|
||||||
|
strokeLinejoin="round"
|
||||||
|
/>
|
||||||
|
</svg>
|
||||||
|
),
|
||||||
|
}
|
||||||
|
|
||||||
|
type ThemeToggleProps = {
|
||||||
|
className?: string
|
||||||
|
}
|
||||||
|
|
||||||
|
export function ThemeToggle({ className }: ThemeToggleProps) {
|
||||||
|
const { theme, resolvedTheme, setTheme } = useTheme()
|
||||||
|
const rootClassName = className ? `${styles.root} ${className}` : styles.root
|
||||||
|
const toggleTheme = (value: Exclude<ThemeMode, 'system'>) => {
|
||||||
|
setTheme(theme === value ? 'system' : value)
|
||||||
|
}
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div className={rootClassName} role="group" aria-label="Тема" data-resolved-theme={resolvedTheme}>
|
||||||
|
{THEME_TOGGLE_OPTIONS.map((option) => (
|
||||||
|
<button
|
||||||
|
className={styles.option}
|
||||||
|
type="button"
|
||||||
|
aria-pressed={theme === option.value}
|
||||||
|
aria-label={option.ariaLabel}
|
||||||
|
title={option.title}
|
||||||
|
data-active={theme === option.value}
|
||||||
|
key={option.value}
|
||||||
|
onClick={() => toggleTheme(option.value)}
|
||||||
|
>
|
||||||
|
<span className={styles.icon}>{iconByTheme[option.value]}</span>
|
||||||
|
</button>
|
||||||
|
))}
|
||||||
|
</div>
|
||||||
|
)
|
||||||
|
}
|
||||||
9
src/main.tsx
Normal file
9
src/main.tsx
Normal file
@@ -0,0 +1,9 @@
|
|||||||
|
import { StrictMode } from 'react'
|
||||||
|
import { createRoot } from 'react-dom/client'
|
||||||
|
import App from './App'
|
||||||
|
|
||||||
|
createRoot(document.getElementById('root')!).render(
|
||||||
|
<StrictMode>
|
||||||
|
<App />
|
||||||
|
</StrictMode>,
|
||||||
|
)
|
||||||
39
src/screens/home/config/home-screen.config.ts
Normal file
39
src/screens/home/config/home-screen.config.ts
Normal file
@@ -0,0 +1,39 @@
|
|||||||
|
export const repositoryUrl = 'https://gromlab.ru/gromov/slm-design'
|
||||||
|
|
||||||
|
export const homeCards = [
|
||||||
|
{
|
||||||
|
title: 'Документация',
|
||||||
|
description: 'Слои, модули, сегменты и правила зависимостей для frontend-проектов.',
|
||||||
|
href: '/docs/',
|
||||||
|
cta: 'Открыть →',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
title: 'Скачать',
|
||||||
|
description: 'Локальная копия спецификации и архив документации.',
|
||||||
|
actions: [
|
||||||
|
{
|
||||||
|
href: '/ARCHITECTURE.md',
|
||||||
|
label: 'ARCHITECTURE.md',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
href: '/slm-design.zip',
|
||||||
|
label: 'slm-design.zip',
|
||||||
|
download: true,
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
title: 'Ассистенту',
|
||||||
|
description: 'Карта документации для AI-агентов:',
|
||||||
|
actions: [
|
||||||
|
{
|
||||||
|
href: '/llms.txt',
|
||||||
|
label: 'llms.txt',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
href: '/llms-full.txt',
|
||||||
|
label: 'llms-full.txt',
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
] as const
|
||||||
71
src/screens/home/home.screen.tsx
Normal file
71
src/screens/home/home.screen.tsx
Normal file
@@ -0,0 +1,71 @@
|
|||||||
|
import { ThemeToggle } from '../../infra/theme'
|
||||||
|
import { homeCards, repositoryUrl } from './config/home-screen.config'
|
||||||
|
import styles from './styles/home-screen.module.css'
|
||||||
|
|
||||||
|
const version = __BUILD_VERSION__ as string
|
||||||
|
|
||||||
|
export function HomeScreen() {
|
||||||
|
return (
|
||||||
|
<main className={styles.page}>
|
||||||
|
<section className={styles.hero}>
|
||||||
|
<h1 className={styles.title}>SLM Design</h1>
|
||||||
|
<p className={styles.lead}>
|
||||||
|
Scoped Layered Module Design — соглашения по архитектуре frontend-приложений:
|
||||||
|
слои, модули, сегменты, публичные API и направление зависимостей.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<div className={styles.controls}>
|
||||||
|
<a className={styles.repoLink} href={repositoryUrl} target="_blank" rel="noopener noreferrer">
|
||||||
|
<svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
|
||||||
|
<path d="M12 .3a12 12 0 0 0-3.8 23.38c.6.12.83-.26.83-.57L9 21.07c-3.34.72-4.04-1.61-4.04-1.61-.55-1.39-1.34-1.76-1.34-1.76-1.08-.74.09-.73.09-.73 1.2.09 1.83 1.24 1.83 1.24 1.08 1.83 2.81 1.3 3.5 1 .1-.78.42-1.31.76-1.61-2.67-.3-5.47-1.33-5.47-5.93 0-1.31.47-2.38 1.24-3.22-.14-.3-.54-1.52.1-3.18 0 0 1-.32 3.3 1.23a11.5 11.5 0 0 1 6 0c2.28-1.55 3.29-1.23 3.29-1.23.64 1.66.24 2.88.12 3.18a4.65 4.65 0 0 1 1.23 3.22c0 4.61-2.8 5.63-5.48 5.92.42.36.81 1.1.81 2.22l-.01 3.29c0 .31.2.69.82.57A12 12 0 0 0 12 .3Z" />
|
||||||
|
</svg>
|
||||||
|
<span>Репозиторий</span>
|
||||||
|
</a>
|
||||||
|
<ThemeToggle className={styles.themeToggle} />
|
||||||
|
</div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section className={styles.cards} aria-label="Быстрые переходы">
|
||||||
|
{homeCards.map((card) => {
|
||||||
|
if ('href' in card) {
|
||||||
|
return (
|
||||||
|
<a
|
||||||
|
className={`${styles.card} ${styles.cardLink}`}
|
||||||
|
href={card.href}
|
||||||
|
download={'download' in card ? card.download : undefined}
|
||||||
|
key={card.title}
|
||||||
|
>
|
||||||
|
<h2>{card.title}</h2>
|
||||||
|
<p>{card.description}</p>
|
||||||
|
<span className={styles.cardCta}>{card.cta}</span>
|
||||||
|
</a>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
return (
|
||||||
|
<article className={styles.card} key={card.title}>
|
||||||
|
<h2>{card.title}</h2>
|
||||||
|
<p>{card.description}</p>
|
||||||
|
<div className={styles.cardActions}>
|
||||||
|
{card.actions.map((action) => (
|
||||||
|
<a
|
||||||
|
className={styles.cardAction}
|
||||||
|
download={'download' in action ? action.download : undefined}
|
||||||
|
href={action.href}
|
||||||
|
key={action.href}
|
||||||
|
>
|
||||||
|
{action.label}
|
||||||
|
</a>
|
||||||
|
))}
|
||||||
|
</div>
|
||||||
|
</article>
|
||||||
|
)
|
||||||
|
})}
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<footer className={styles.footer}>
|
||||||
|
<span>{version}</span>
|
||||||
|
</footer>
|
||||||
|
</main>
|
||||||
|
)
|
||||||
|
}
|
||||||
1
src/screens/home/index.ts
Normal file
1
src/screens/home/index.ts
Normal file
@@ -0,0 +1 @@
|
|||||||
|
export { HomeScreen } from './home.screen'
|
||||||
216
src/screens/home/styles/home-screen.module.css
Normal file
216
src/screens/home/styles/home-screen.module.css
Normal file
@@ -0,0 +1,216 @@
|
|||||||
|
.page {
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
justify-content: center;
|
||||||
|
gap: 64px;
|
||||||
|
min-height: 100vh;
|
||||||
|
padding: 48px 32px;
|
||||||
|
background: var(--page-bg);
|
||||||
|
color: var(--text-primary);
|
||||||
|
}
|
||||||
|
|
||||||
|
.hero {
|
||||||
|
text-align: center;
|
||||||
|
}
|
||||||
|
|
||||||
|
.title {
|
||||||
|
margin: 0 0 16px;
|
||||||
|
color: var(--accent-cool);
|
||||||
|
font-size: 56px;
|
||||||
|
font-weight: 750;
|
||||||
|
letter-spacing: -0.035em;
|
||||||
|
line-height: 1;
|
||||||
|
}
|
||||||
|
|
||||||
|
.lead {
|
||||||
|
max-width: 740px;
|
||||||
|
margin: 0 auto;
|
||||||
|
color: var(--text-secondary);
|
||||||
|
font-size: 18px;
|
||||||
|
line-height: 1.55;
|
||||||
|
}
|
||||||
|
|
||||||
|
.controls {
|
||||||
|
display: flex;
|
||||||
|
flex-wrap: wrap;
|
||||||
|
align-items: center;
|
||||||
|
justify-content: center;
|
||||||
|
gap: 12px;
|
||||||
|
margin-top: 28px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.controls > * {
|
||||||
|
box-sizing: border-box;
|
||||||
|
height: 36px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.repoLink {
|
||||||
|
display: inline-flex;
|
||||||
|
align-items: center;
|
||||||
|
gap: 8px;
|
||||||
|
padding: 0 14px;
|
||||||
|
border: 1px solid var(--border-soft);
|
||||||
|
border-radius: 999px;
|
||||||
|
color: var(--text-secondary);
|
||||||
|
background: var(--surface-soft);
|
||||||
|
font-size: 13px;
|
||||||
|
font-weight: 600;
|
||||||
|
text-decoration: none;
|
||||||
|
transition: border-color 150ms ease, color 150ms ease;
|
||||||
|
}
|
||||||
|
|
||||||
|
.repoLink:hover {
|
||||||
|
border-color: var(--accent-cool);
|
||||||
|
color: var(--text-primary);
|
||||||
|
}
|
||||||
|
|
||||||
|
.repoLink svg {
|
||||||
|
flex-shrink: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.themeToggle {
|
||||||
|
flex-shrink: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.cards {
|
||||||
|
display: grid;
|
||||||
|
grid-template-columns: repeat(3, minmax(0, 1fr));
|
||||||
|
gap: 16px;
|
||||||
|
width: 100%;
|
||||||
|
max-width: 1100px;
|
||||||
|
margin: 0 auto;
|
||||||
|
}
|
||||||
|
|
||||||
|
.card {
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
gap: 8px;
|
||||||
|
min-height: 178px;
|
||||||
|
padding: 24px;
|
||||||
|
border: 1px solid var(--border-soft);
|
||||||
|
border-radius: 12px;
|
||||||
|
color: inherit;
|
||||||
|
background: var(--surface-soft);
|
||||||
|
text-decoration: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.cardLink {
|
||||||
|
transition: border-color 200ms ease, transform 200ms ease;
|
||||||
|
}
|
||||||
|
|
||||||
|
.cardLink:hover {
|
||||||
|
border-color: var(--accent-cool);
|
||||||
|
transform: translateY(-2px);
|
||||||
|
}
|
||||||
|
|
||||||
|
.card h2 {
|
||||||
|
margin: 0;
|
||||||
|
color: var(--text-primary);
|
||||||
|
font-size: 18px;
|
||||||
|
font-weight: 650;
|
||||||
|
line-height: 1.3;
|
||||||
|
}
|
||||||
|
|
||||||
|
.card p {
|
||||||
|
margin: 0;
|
||||||
|
color: var(--text-secondary);
|
||||||
|
font-size: 14px;
|
||||||
|
line-height: 1.5;
|
||||||
|
}
|
||||||
|
|
||||||
|
.cardActions {
|
||||||
|
display: flex;
|
||||||
|
flex-wrap: wrap;
|
||||||
|
gap: 8px;
|
||||||
|
margin-top: auto;
|
||||||
|
}
|
||||||
|
|
||||||
|
.cardCta {
|
||||||
|
margin-top: auto;
|
||||||
|
color: var(--accent-cool);
|
||||||
|
font-size: 14px;
|
||||||
|
font-weight: 500;
|
||||||
|
}
|
||||||
|
|
||||||
|
.cardAction {
|
||||||
|
display: inline-flex;
|
||||||
|
align-items: center;
|
||||||
|
padding: 6px 12px;
|
||||||
|
border: 1px solid var(--border-soft);
|
||||||
|
border-radius: 8px;
|
||||||
|
color: var(--text-primary);
|
||||||
|
background: var(--page-bg);
|
||||||
|
font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
|
||||||
|
font-size: 13px;
|
||||||
|
font-weight: 500;
|
||||||
|
text-decoration: none;
|
||||||
|
transition: border-color 150ms ease, color 150ms ease;
|
||||||
|
}
|
||||||
|
|
||||||
|
.cardAction:hover {
|
||||||
|
border-color: var(--accent-cool);
|
||||||
|
color: var(--accent-cool);
|
||||||
|
}
|
||||||
|
|
||||||
|
.footer {
|
||||||
|
margin: 0;
|
||||||
|
color: var(--text-muted);
|
||||||
|
font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
|
||||||
|
font-size: 12px;
|
||||||
|
text-align: center;
|
||||||
|
}
|
||||||
|
|
||||||
|
@media (max-width: 768px) {
|
||||||
|
.page {
|
||||||
|
justify-content: flex-start;
|
||||||
|
gap: 40px;
|
||||||
|
padding: 48px 20px 56px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.title {
|
||||||
|
font-size: 38px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.lead {
|
||||||
|
font-size: 16px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.cards {
|
||||||
|
grid-template-columns: 1fr;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@media (max-width: 480px) {
|
||||||
|
.page {
|
||||||
|
gap: 36px;
|
||||||
|
padding: 44px 16px 48px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.title {
|
||||||
|
font-size: 32px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.lead {
|
||||||
|
font-size: 15px;
|
||||||
|
line-height: 1.5;
|
||||||
|
}
|
||||||
|
|
||||||
|
.controls {
|
||||||
|
margin-top: 32px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.repoLink {
|
||||||
|
width: 36px;
|
||||||
|
justify-content: center;
|
||||||
|
padding: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.repoLink span {
|
||||||
|
display: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.card {
|
||||||
|
min-height: 160px;
|
||||||
|
padding: 20px;
|
||||||
|
}
|
||||||
|
}
|
||||||
79
vite.config.ts
Normal file
79
vite.config.ts
Normal file
@@ -0,0 +1,79 @@
|
|||||||
|
import { defineConfig, Plugin } from 'vite'
|
||||||
|
import react from '@vitejs/plugin-react'
|
||||||
|
import { readFileSync, existsSync } from 'fs'
|
||||||
|
import { resolve } from 'path'
|
||||||
|
|
||||||
|
const pkg = JSON.parse(readFileSync('./package.json', 'utf8'))
|
||||||
|
|
||||||
|
const textArtifacts: Record<string, string> = {
|
||||||
|
'/llms.txt': 'text/plain; charset=utf-8',
|
||||||
|
'/llms-full.txt': 'text/plain; charset=utf-8',
|
||||||
|
'/ARCHITECTURE.md': 'text/markdown; charset=utf-8',
|
||||||
|
}
|
||||||
|
|
||||||
|
function serveTextArtifacts(): Plugin {
|
||||||
|
return {
|
||||||
|
name: 'serve-text-artifacts',
|
||||||
|
configureServer(server) {
|
||||||
|
const publicDir = resolve('public')
|
||||||
|
|
||||||
|
server.middlewares.use((req, res, next) => {
|
||||||
|
const url = req.url?.split('?')[0]
|
||||||
|
const contentType = url ? textArtifacts[url] : undefined
|
||||||
|
if (!url || !contentType) return next()
|
||||||
|
|
||||||
|
const filePath = resolve(publicDir, url.slice(1))
|
||||||
|
if (!existsSync(filePath)) return next()
|
||||||
|
|
||||||
|
res.setHeader('Content-Type', contentType)
|
||||||
|
res.end(readFileSync(filePath))
|
||||||
|
})
|
||||||
|
},
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function serveDocs(): Plugin {
|
||||||
|
return {
|
||||||
|
name: 'serve-docs',
|
||||||
|
configureServer(server) {
|
||||||
|
const publicDir = resolve('public')
|
||||||
|
|
||||||
|
server.middlewares.use((req, _res, next) => {
|
||||||
|
const url = req.url?.split('?')[0]
|
||||||
|
if (!url?.startsWith('/docs')) return next()
|
||||||
|
|
||||||
|
const filePath = resolve(publicDir, url.slice(1))
|
||||||
|
|
||||||
|
if (url === '/docs') {
|
||||||
|
if (existsSync(resolve(filePath, 'index.html'))) {
|
||||||
|
req.url = '/docs/index.html'
|
||||||
|
return next()
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (url.endsWith('/')) {
|
||||||
|
if (existsSync(resolve(filePath, 'index.html'))) {
|
||||||
|
req.url = url + 'index.html'
|
||||||
|
return next()
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!url.split('/').pop()?.includes('.')) {
|
||||||
|
if (existsSync(filePath + '.html')) {
|
||||||
|
req.url = url + '.html'
|
||||||
|
return next()
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
next()
|
||||||
|
})
|
||||||
|
},
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export default defineConfig({
|
||||||
|
plugins: [react(), serveTextArtifacts(), serveDocs()],
|
||||||
|
define: {
|
||||||
|
__BUILD_VERSION__: JSON.stringify(`v${pkg.version}`),
|
||||||
|
},
|
||||||
|
})
|
||||||
Reference in New Issue
Block a user