Runbooks
Выбор компонентов
Пошаговая инструкция по выбору готовых решений перед началом разработки страницы.
Применимо для: feature, change — при разработке нового функционала или изменении существующего.
Prerequisites
- Доступ к интернету для поиска
- Понимание требований к странице
- Макет или описание страницы
Шаги
1. Декомпозиция страницы
Разбить страницу на логические блоки:
Пример: Страница списка заказов
Блоки:
- Header с фильтрами
- Таблица данных
- Пагинация
- Модальное окно деталей
- Графики статистики
2. Поиск в shared-модулях (ПЕРВЫЙ ПРИОРИТЕТ)
Вдруг уже решали эту задачу!
Проверить существующие компоненты и composables:
# Проверить ui-kit
ls packages/ui/components/
# Проверить helpers
ls packages/helpers/
# Проверить types
ls packages/types/
Типичные компоненты в UI layer:
- Доменные компоненты (OrderCard, ServiceBadge и т.д.)
- Кастомизированные обёртки над Nuxt UI
- Специфичные формы
3. Поиск в Nuxt UI
URL: https://ui.nuxt.com/components
Для каждого блока проверить наличие компонента:
| Блок | Компонент Nuxt UI |
|---|---|
| Кнопки | UButton |
| Текстовые поля | UInput |
| Выпадающие списки | USelect, USelectMenu |
| Таблицы | UTable |
| Пагинация | UPagination |
| Модальные окна | UModal |
| Карточки | UCard |
| Табы | UTabs |
| Формы | UForm, UFormGroup |
| Алерты | UAlert |
| Бейджи | UBadge |
| Дропдауны | UDropdown |
| Тосты | useToast() |
4. Поиск в Nuxt Charts
Если нужны графики:
| Тип графика | Компонент |
|---|---|
| Линейный | <Chart type="line" /> |
| Столбчатый | <Chart type="bar" /> |
| Круговой | <Chart type="pie" /> |
| Кольцевой | <Chart type="doughnut" /> |
| Точечный | <Chart type="scatter" /> |
5. Поиск в Nuxt Modules
Ключевые слова для поиска:
| Функционал | Поисковый запрос |
|---|---|
| Календарь | calendar, date |
| Карта | map, leaflet |
| Редактор | editor, wysiwyg |
| Загрузка файлов | upload, dropzone |
| Маски ввода | mask, maska |
| Иконки | icon, icons |
| Анимации | motion, animation |
Критерии выбора модуля:
- Обновлялся < 6 месяцев
- TypeScript поддержка
- > 100 GitHub stars
- MIT/Apache лицензия
- Совместим с Nuxt 4
6. Принятие решения
Заполнить таблицу решений:
| Блок | Решение | Источник |
|---|---|---|
| Статус заказа | OrderStatusBadge | UI layer |
| Фильтры | UInput, USelect | Nuxt UI |
| Таблица | UTable | Nuxt UI |
| Пагинация | UPagination | Nuxt UI |
| Графики | Chart | Nuxt Charts |
| Модалка | UModal | Nuxt UI |
7. Обоснование кастомной разработки
Если готового решения нет, задокументировать:
Кастомный компонент: Название
Причина:
- Почему не подошёл UI layer
- Почему не подошёл Nuxt UI
- Почему не подошёл Nuxt Modules
- Уникальные требования
Проверено:
- Shared-модули: результат поиска
- Nuxt UI: результат поиска
- Nuxt Modules: результат поиска
- npm: результат поиска
8. Документирование в MR
В описании MR указать использованные решения:
UI layer
- OrderStatusBadge — статус заказа
- ServiceCard — карточка услуги
Nuxt UI
- UTable — таблица заказов
- UPagination — пагинация
- UModal — детали заказа
- UButton, UInput — элементы форм
Nuxt Charts
- Chart (bar) — статистика по дням
Nuxt Modules
- @nuxt/image — оптимизация изображений
Кастомные компоненты
- Нет
Примеры
Пример 1: Страница Dashboard
Декомпозиция:
- Статистические карточки
- График продаж
- Таблица последних заказов
- Список уведомлений
Решения:
| Блок | Компонент | Источник |
|---|---|---|
| Карточки | UCard | Nuxt UI |
| График | Chart (line) | Nuxt Charts |
| Таблица | UTable | Nuxt UI |
| Уведомления | UAlert | Nuxt UI |
Кастомные: 0
Пример 2: Страница создания заказа
Декомпозиция:
- Форма с полями
- Выбор услуги
- Выбор даты
- Загрузка файлов
- Кнопка отправки
Решения:
| Блок | Компонент | Источник |
|---|---|---|
| Форма | UForm, UFormGroup | Nuxt UI |
| Поля | UInput, UTextarea | Nuxt UI |
| Выбор услуги | USelectMenu | Nuxt UI |
| Выбор даты | VCalendar | @nuxt/calendar |
| Загрузка | FileUpload | UI layer |
| Кнопка | UButton | Nuxt UI |
Кастомные: 0 (FileUpload уже в ui-kit)
Пример 3: Страница отчётов
Декомпозиция:
- Фильтры периода
- Графики (3 типа)
- Таблица с экспортом
- Сводка
Решения:
| Блок | Компонент | Источник |
|---|---|---|
| Фильтры | UInput, USelect | Nuxt UI |
| Линейный график | Chart (line) | Nuxt Charts |
| Столбчатый график | Chart (bar) | Nuxt Charts |
| Круговая диаграмма | Chart (pie) | Nuxt Charts |
| Таблица | UTable | Nuxt UI |
| Экспорт | UButton + xlsx | npm xlsx |
| Сводка | UCard | Nuxt UI |
Кастомные: 0
Troubleshooting
Компонент не найден в Nuxt UI
- Проверить название: https://ui.nuxt.com/components
- Проверить версию @nuxt/ui в package.json
- Проверить импорт модуля в nuxt.config.ts
Модуль не совместим с Nuxt 4
- Проверить issues на GitHub
- Искать альтернативу: https://nuxt.com/modules
- Рассмотреть npm-пакет без Nuxt-обёртки
Нет подходящего готового решения
- Задокументировать поиск
- Создать issue в UI layer репозитории
- Реализовать минимальный кастомный компонент
- После стабилизации — вынести в ui-kit