COMPONENTS — Библиотека переиспользуемых компонентов

Версия: 1.0
Дата создания: 2025-11-10
Архитектура: Feature-Sliced Design (FSD)
Статус: Production ready

ЧТО ЭТО?

Библиотека переиспользуемых компонентов, организованная по Feature-Sliced Design.

Проблема:
Генерация компонентов с нуля → 1000-5000 tokens

Решение:
Копировать готовый компонент → Адаптировать → 200-500 tokens (экономия 80-90%)

АРХИТЕКТУРА: Feature-Sliced Design

Принцип FSD:

Организация по слоям (layers), каждый слой может использовать только слои ниже (one-way flow).

┌─────────────────────────────────────────┐
│ widgets/        Сложные UI блоки        │ ← Самый высокий уровень
├─────────────────────────────────────────┤
│ features/       Бизнес-фичи             │
├─────────────────────────────────────────┤
│ entities/       Бизнес-сущности         │
├─────────────────────────────────────────┤
│ shared/         Переиспользуемый код    │ ← Самый низкий уровень
└─────────────────────────────────────────┘

Правило: widgets может использовать features, entities, shared
Правило: features может использовать entities, shared
Правило: entities может использовать только shared

СТРУКТУРА

components/
│
├── entities/                 # Бизнес-сущности
│   ├── user/
│   │   ├── model.py         # Модель User
│   │   ├── api.py           # API для работы с User
│   │   └── ui.py            # UI компоненты (UserCard, UserAvatar)
│   │
│   ├── order/
│   │   ├── model.py
│   │   ├── api.py
│   │   └── ui.py
│   │
│   └── product/
│       ├── model.py
│       ├── api.py
│       └── ui.py
│
├── features/                 # Бизнес-фичи (действия пользователя)
│   ├── auth/
│   │   ├── login/           # Фича: вход в систему
│   │   │   ├── ui.py        # LoginForm
│   │   │   └── model.py     # login logic
│   │   │
│   │   └── logout/          # Фича: выход
│   │       └── ui.py
│   │
│   ├── order-create/
│   │   ├── ui.py            # CreateOrderForm
│   │   └── model.py         # create order logic
│   │
│   └── filter-table/
│       ├── ui.py            # FilterPanel
│       └── model.py         # filtering logic
│
├── widgets/                  # Сложные UI блоки (композиты)
│   ├── header/
│   │   └── ui.py            # Header (logo + nav + user menu)
│   │
│   ├── sidebar/
│   │   └── ui.py            # Sidebar (navigation)
│   │
│   └── order-table/
│       └── ui.py            # OrderTable (table + filters + export)
│
└── shared/                   # Переиспользуемый код (низший уровень)
    ├── ui/                   # UI примитивы (atoms)
    │   ├── button.py
    │   ├── input.py
    │   ├── card.py
    │   └── modal.py
    │
    ├── lib/                  # Утилиты
    │   ├── formatters.py     # format_currency, format_date
    │   ├── validators.py     # validate_email, validate_phone
    │   └── helpers.py        # common helpers
    │
    ├── api/                  # API клиенты
    │   ├── base_client.py    # BaseAPIClient
    │   └── http.py           # HTTP utilities
    │
    └── config/               # Конфигурация
        ├── constants.py
        └── settings.py

УРОВНИ ДЕТАЛЬНО

1. shared/ — Переиспользуемый код

Назначение: Базовые утилиты, UI примитивы, конфигурация

Примеры:
- shared/ui/button.py — кнопка
- shared/lib/formatters.py — format_currency()
- shared/api/base_client.py — базовый API клиент

Правило: НЕ зависит ни от чего выше

2. entities/ — Бизнес-сущности

Назначение: Модели данных и базовые операции

Примеры:
- entities/user/model.py — User model (SQLAlchemy)
- entities/user/api.py — get_user(), update_user()
- entities/user/ui.py — UserCard, UserAvatar

Правило: Может использовать только shared/

3. features/ — Бизнес-фичи

Назначение: Действия пользователя, use cases

Примеры:
- features/auth/login/ — вход в систему
- features/order-create/ — создание заказа
- features/filter-table/ — фильтрация таблицы

Правило: Может использовать entities/ и shared/

4. widgets/ — Сложные UI блоки

Назначение: Композитные компоненты из features + entities

Примеры:
- widgets/header/ — Header (navigation + user menu)
- widgets/order-table/ — OrderTable (table + filters + actions)

Правило: Может использовать features/, entities/, shared/

ИСПОЛЬЗОВАНИЕ

Пример 1: Использовать Button из shared

# В любом компоненте
from components.shared.ui.button import Button

# Использование
Button(text="Сохранить", type="primary", on_click=save_handler)

Пример 2: Использовать User entity

# В feature или widget
from components.entities.user.model import User
from components.entities.user.api import get_user

user = get_user(user_id=123)

Пример 3: Использовать LoginForm feature

# На странице авторизации
from components.features.auth.login.ui import LoginForm

LoginForm(on_success=handle_login_success)

Пример 4: Использовать OrderTable widget

# На странице заказов
from components.widgets.order_table.ui import OrderTable

OrderTable(filters=filters, on_export=handle_export)

ПРАВИЛА РАЗРАБОТКИ

✅ DO:

1. Следовать FSD слоям — не нарушать направление зависимостей
2. Один компонент = одна ответственность
3. Параметризовать — использовать props/parameters
4. Документировать — docstrings для всех публичных функций
5. Тестировать — unit тесты для logic, E2E для UI

❌ DON'T:

1. Не нарушать иерархию — shared не может импортировать entities
2. Не смешивать слои — не класть entity код в feature
3. Не дублировать — если компонент используется 2+ раза → вынести в shared
4. Не делать "god components" — разбивать большие компоненты

WORKFLOW: Создание нового компонента

Шаг 1: Определить уровень

Вопросы:
- Это базовая утилита? → shared/
- Это модель данных? → entities/
- Это действие пользователя? → features/
- Это композитный UI блок? → widgets/

Шаг 2: Создать структуру

# Пример: новая фича "экспорт заказов"
mkdir -p components/features/order-export
touch components/features/order-export/{ui.py,model.py,__init__.py}

Шаг 3: Реализовать

# components/features/order-export/model.py
def export_orders_to_excel(orders):
    """Экспортировать заказы в Excel"""
    # логика экспорта
    pass

# components/features/order-export/ui.py
def ExportButton(orders, filename):
    """Кнопка экспорта заказов"""
    # UI компонент
    pass

Шаг 4: Обновить catalog

Добавить в components/catalog.yaml

Шаг 5: Написать тесты

# tests/components/features/test_order_export.py
def test_export_orders_to_excel():
    orders = [...]
    result = export_orders_to_excel(orders)
    assert result.endswith('.xlsx')

ИНТЕГРАЦИЯ С КАСКАДОМ

Components = уровень L4 в каскаде поиска.

L1: Platform rules (85%)
L2: External libraries (98%)
L3: Templates (99.5%)
L4: Components (99.8%)        ← ВЫ ЗДЕСЬ
L5: Projects code (99.95%)
L6: Archive (100%)
L7: Generate (последний вариант)

Workflow:
1. Нужен компонент → искать в components/catalog.yaml
2. Нашёл → копировать и адаптировать
3. Не нашёл → искать в templates/ или projects/
4. Всё равно нет → генерировать с нуля

ЭКОНОМИЯ ТОКЕНОВ

Сравнение: генерация vs переиспользование

Средняя экономия: 80-85%

СТАТИСТИКА

Текущее состояние:
- Entities: 0 (TODO)
- Features: 0 (TODO)
- Widgets: 0 (TODO)
- Shared: 0 (TODO)

План:
- Извлечь 10+ компонентов из marketplace
- Создать базовые shared/ui компоненты
- Задокументировать все компоненты

ПРИМЕРЫ ИЗ ИНДУСТРИИ

Material UI (React):

@mui/material/
├── Button/
├── TextField/
├── Card/
└── ...

Ant Design (React):

antd/
├── button/
├── form/
├── table/
└── ...

Наш подход (FSD):

components/
├── shared/ui/button.py        ← аналог Button
├── entities/user/             ← бизнес-модель
├── features/auth/login/       ← use case
└── widgets/header/            ← композит

Отличие: Мы не только UI, но и business logic, API, models.

СВЯЗАННЫЕ РЕСУРСЫ

• Каталог: components/catalog.yaml
• FSD Docs: https://feature-sliced.design/
• Registry: registry/INDEX.yaml (external libraries)
• Templates: templates/ (project templates)
• Tests: tests/library/ (component tests)

СЛЕДУЮЩИЕ ШАГИ

Приоритет #1:

• [ ] Извлечь первые 5 компонентов из marketplace
• [ ] Создать базовые shared/ui (Button, Input, Card)
• [ ] Создать catalog.yaml

Приоритет #2:

• [ ] Извлечь entities (User, Order, Product)
• [ ] Извлечь features (login, filter-table)
• [ ] Создать widgets (Header, OrderTable)

Приоритет #3:

• [ ] Написать тесты для всех компонентов
• [ ] Создать Storybook (опционально)
• [ ] Документировать best practices

Версия: 1.0
Дата: 2025-11-10
Статус: Infrastructure ready, components TODO