music-orchestrator/docs/WIREFRAME.md

Music Orchestrator — Вайрфреймы и описание UI

Содержание

1. Общая архитектура UI
2. Навигация
3. Страница: Home (Главная)
4. Страница: Search (Поиск)
5. Страница: Library (Библиотека)
6. Страница: Playlists (Плейлисты)
7. Страница: Playlist Detail (Детали плейлиста)
8. Страница: Player (Плеер)
9. Страница: Settings (Настройки)
10. Компоненты
11. Mobile-first layout
12. Цветовая схема и стили

---

1. Общая архитектура UI

Layout (мобильный, portrait)

┌─────────────────────────────┐
│         Header Bar          │  ← logo, search icon, settings
├─────────────────────────────┤
│                             │
│         Content Area        │  ← текущая страница
│         (scrollable)        │
│                             │
│                             │
├─────────────────────────────┤
│    Mini Player (sticky)     │  ← artwork, title, play/pause
├─────────────────────────────┤
│     Bottom Navigation       │  ← Home, Search, Library, Playlists
└─────────────────────────────┘

Layout (desktop, ≥768px)

┌────────┬────────────────────────────────────────┐
│        │          Header Bar (search)            │
│  Side  ├────────────────────────────────────────┤
│  bar   │                                        │
│        │           Content Area                 │
│  Nav   │           (scrollable)                 │
│        │                                        │
│        ├────────────────────────────────────────┤
│        │       Mini Player (fixed bottom)       │
└────────┴────────────────────────────────────────┘

---

2. Навигация

Bottom nav / Sidebar nav

Иконка	Label	Страница	Описание
🏠	Главная	Home	Рекомендации, недавно прослушанное
🔍	Поиск	Search	Поисковая строка + результаты
📚	Библиотека	Library	Избранное + все плейлисты
🎵	Плейлисты	Playlists	Управление плейлистами
⚙️	Настройки	Settings	API key, провайдеры, theme

Навигационные потоки

Home ──→ Search (по клику на search bar)
      ──→ Track detail ──→ Player
      ──→ Playlist detail

Search ──→ Track detail ──→ Player
       ──→ Add to favorites / playlist (bottom sheet)

Library ──→ Favorites list ──→ Player
        ──→ Playlist detail ──→ Player

Playlists ──→ Create playlist
          ──→ Playlist detail ──→ Player

Settings ──→ API key input
         ──→ Provider status

---

3. Страница: Home (Главная)

Описание

Стартовый экран. Показывает приветствие, быстрый доступ к поиску, недавно прослушанным трекам и рекомендациям.

Компоненты

1. Hero / Search CTA — большая карточка "Найди любую музыку" с полем ввода → переход на Search.

2. Recently Played (горизонтальный scroll)

   • Карточки: обложка (64×64), название, исполнитель
   • Клик → воспроизведение
   • Если нет истории → скрыть секцию

3. Your Favorites (горизонтальный scroll)

   • Первые 5–10 избранных треков
   • "Показать все" → Library → Favorites

4. Your Playlists (горизонтальный scroll)

   • Карточки: название, количество треков
   • Клик → Playlist detail

5. Provider Status (info-блок)

   • Список подключённых провайдеров с бейджами
   • Green dot = configured, grey = not configured

Wireframe

┌─────────────────────────────────────┐
│ 🎵 Music Orchestrator       ⚙️     │
├─────────────────────────────────────┤
│                                     │
│  ┌─────────────────────────────┐    │
│  │ 🔍  Найди любую музыку...  │    │
│  └─────────────────────────────┘    │
│                                     │
│  Недавно прослушанное          →   │
│  ┌──────┐ ┌──────┐ ┌──────┐       │
│  │ 🎵   │ │ 🎵   │ │ 🎵   │       │
│  │ Song │ │ Song │ │ Song │       │
│  └──────┘ └──────┘ └──────┘       │
│                                     │
│  Избранное                      →  │
│  ┌──────┐ ┌──────┐ ┌──────┐       │
│  │ ❤️   │ │ ❤️   │ │ ❤️   │       │
│  │ Song │ │ Song │ │ Song │       │
│  └──────┘ └──────┘ └──────┘       │
│                                     │
├─────────────────────────────────────┤
│  [artwork] Song Title    ▶ ⏭      │
├─────────────────────────────────────┤
│  🏠     🔍     📚     🎵     ⚙️   │
└─────────────────────────────────────┘

---

4. Страница: Search (Поиск)

Описание

Основной экран для поиска музыки. Показывает результаты из всех провайдеров.

Компоненты

1. Search Bar (sticky top)

   • Поле ввода с debounce 300мс
   • Кнопка очистки (×)
   • Иконка фильтра провайдеров (dropdown с чекбоксами)

2. Provider Filter (опциональный dropdown/chips)

   • Чекбоксы: Local, YouTube, SoundCloud
   • По умолчанию все включены

3. Results List

   • Каждый трек — карточка:
     • Обложка (48×48 или placeholder)
     • Название, Исполнитель, Альбом
     • Длительность (формат mm:ss)
     • Provider badges (цветные иконки: 🟢 local, 🔴 YouTube, 🟡 SoundCloud)
     • Risk badge (🟢 compliant, 🟡 constrained, 🔴 risky)
     • Кнопки: ▶ Play, ❤️ Favorite, + Playlist
   • Infinite scroll или "Загрузить ещё"

4. Empty State — "Введите запрос для поиска"

5. No Results — "Ничего не найдено по запросу ..."

Wireframe

┌─────────────────────────────────────┐
│ 🔍  Enter song name...         ✕   │
│ [Local ✓] [YouTube ✓] [SoundCloud ✓]│
├─────────────────────────────────────┤
│                                     │
│  ┌─────────────────────────────┐    │
│  │ 🎵  Demo Song               │    │
│  │     Local Artist • 3:00     │    │
│  │     🟢local  🟢compliant    │    │
│  │            ▶  ❤️  +         │    │
│  └─────────────────────────────┘    │
│                                     │
│  ┌─────────────────────────────┐    │
│  │ 🎵  Another Track           │    │
│  │     YouTube Artist • 4:22   │    │
│  │     🔴youtube  🟢compliant  │    │
│  │            ▶  ❤️  +         │    │
│  └─────────────────────────────┘    │
│                                     │
│  ┌─────────────────────────────┐    │
│  │ 🎵  SoundCloud Track        │    │
│  │     SC Artist • 2:45        │    │
│  │     🟡soundcloud 🟡constrained│   │
│  │     ⚠️ attribution required  │    │
│  │            ▶  ❤️  +         │    │
│  └─────────────────────────────┘    │
│                                     │
│        [Загрузить ещё]              │
│                                     │
├─────────────────────────────────────┤
│  [artwork] Song Title    ▶ ⏭      │
├─────────────────────────────────────┤
│  🏠     🔍     📚     🎵     ⚙️   │
└─────────────────────────────────────┘

Track Card — детальная структура

┌──────────────────────────────────────┐
│ ┌──────┐  Song Title                 │
│ │      │  Artist Name                │
│ │ art  │  Album • 3:45               │
│ │ work │  [🟢local] [🟢compliant]    │
│ └──────┘                             │
│                         ▶   ❤️   ⋮  │
└──────────────────────────────────────┘

Кнопка ⋮ (more) → Bottom sheet:

• Добавить в плейлист
• Перейти к источнику
• Информация о треке

---

5. Страница: Library (Библиотека)

Описание

Единый экран библиотеки: избранное + плейлисты. Вкладки или секции.

Компоненты

1. Tab Bar: Избранное | Плейлисты

2. Вкладка "Избранное"

   • Список треков (аналогичен search results, но без provider filter)
   • Каждый трек: обложка, название, исполнитель, длительность, ▶, ⋮
   • Кнопка ⋮ → "Удалить из избранного", "Добавить в плейлист"
   • Empty state: "Нет избранных треков. Ищите музыку и добавляйте ❤️"

3. Вкладка "Плейлисты"

   • Список плейлистов (карточки)
   • Каждая: название, описание, количество треков
   • FAB (floating action button): "+ Новый плейлист"
   • Empty state: "Нет плейлистов. Создайте первый 🎵"

Wireframe

┌─────────────────────────────────────┐
│  📚 Библиотека                      │
├─────────────────────────────────────┤
│  [Избранное]  [Плейлисты]           │
├─────────────────────────────────────┤
│                                     │
│  ┌─────────────────────────────┐    │
│  │ 🎵  Favorite Song 1         │    │
│  │     Artist • 3:00     ▶ ⋮  │    │
│  └─────────────────────────────┘    │
│  ┌─────────────────────────────┐    │
│  │ 🎵  Favorite Song 2         │    │
│  │     Artist • 4:15     ▶ ⋮  │    │
│  └─────────────────────────────┘    │
│                                     │
│                    ┌────┐           │
│                    │ +  │  ← FAB    │
│                    └────┘           │
├─────────────────────────────────────┤
│  [artwork] Song Title    ▶ ⏭      │
├─────────────────────────────────────┤
│  🏠     🔍     📚     🎵     ⚙️   │
└─────────────────────────────────────┘

---

6. Страница: Playlists (Плейлисты)

Описание

Отдельный экран управления плейлистами (альтернативно может быть вкладкой в Library).

Компоненты

1. Playlist Cards (grid или list)

   • Каждая: название, описание (обрезать до 2 строк), "X треков", дата создания
   • Клик → Playlist Detail

2. Create Playlist Button (FAB или header button)

   • Открывает модальное окно:
     • Название (обязательно, 1–120 символов)
     • Описание (опционально, до 500 символов)
     • Кнопки: Отмена, Создать

---

7. Страница: Playlist Detail

Описание

Детальный вид плейлиста с треками.

Компоненты

1. Playlist Header

   • Название, описание
   • Количество треков, общая длительность (вычислить из track.duration_seconds)
   • Кнопка ▶ Все (воспроизвести весь плейлист)

2. Track List

   • Нумерованный список треков
   • Каждый: #, обложка, название, исполнитель, длительность, ▶, ⋮
   • Порядок по position

3. Empty State: "Плейлист пуст. Добавьте треки из поиска."

Wireframe

┌─────────────────────────────────────┐
│  ←  Chill Vibes                     │
│      Relaxing music                 │
│      12 треков • 45 мин    [▶ Все] │
├─────────────────────────────────────┤
│                                     │
│  1  🎵  Song One            3:00 ⋮ │
│  2  🎵  Song Two            4:15 ⋮ │
│  3  🎵  Song Three          2:30 ⋮ │
│  4  🎵  Song Four           5:00 ⋮ │
│  ...                                │
│                                     │
├─────────────────────────────────────┤
│  [artwork] Song Title    ▶ ⏭      │
├─────────────────────────────────────┤
│  🏠     🔍     📚     🎵     ⚙️   │
└─────────────────────────────────────┘

---

8. Страница: Player (Плеер)

Описание

Полноэкранный плеер. Открывается по свайпу вверх от Mini Player или клику на него.

Компоненты

1. Artwork — большое изображение обложки (по центру, адаптивное)

2. Track Info — Название (bold), Исполнитель, Альбом

3. Provider Badge — иконка провайдера + risk level

4. Progress Bar

   • Полоса прогресса (seekable для local_stream)
   • Текущее время / Общая длительность

5. Playback Controls

   • ⏮ Previous (для плейлиста)
   • ▶/⏸ Play/Pause
   • ⏭ Next (для плейлиста)
   • 🔀 Shuffle (опционально)
   • 🔁 Repeat (опционально)

6. Action Buttons

   • ❤️ Favorite toggle
   • ➕ Add to playlist (bottom sheet)
   • ⬇️ Download (только если policy.download_allowed)

7. Attribution (если policy.requires_attribution)

   • Показать attribution text

Playback Rendering

В зависимости от playback_type:

playback_type	Что рендерить
local_stream	<audio src="{stream_url}"> — стандартный HTML5 audio
embed	<iframe src="{embed_url}"> — YouTube embed player
official_stream	<audio src="{stream_url}"> — с отслеживанием expires_in_seconds
unavailable	Блок с сообщением "Невоспроизводимо"

Mini Player (sticky bottom, виден на всех страницах)

┌─────────────────────────────────────┐
│ [🎵 art]  Song Title       ▶  ⏭   │
│           Artist Name               │
│ ════════════════░░░░░░░░░░░░░░░░░  │ ← progress bar
└─────────────────────────────────────┘

Full Player (по свайпу вверх)

┌─────────────────────────────────────┐
│         ─── (drag handle) ───       │
│                                     │
│        ┌───────────────────┐        │
│        │                   │        │
│        │                   │        │
│        │    ARTWORK        │        │
│        │    (square)       │        │
│        │                   │        │
│        │                   │        │
│        └───────────────────┘        │
│                                     │
│        Song Title                   │
│        Artist Name                  │
│        🟢 local • compliant         │
│                                     │
│   1:23 ━━━━━━━━━━░━━━━━━━ 3:00     │
│                                     │
│        ⏮    ▶/⏸    ⏭              │
│        🔀               🔁          │
│                                     │
│    ❤️       ➕        ⬇️             │
│                                     │
│    Source: Local library             │
│                                     │
└─────────────────────────────────────┘

---

9. Страница: Settings (Настройки)

Описание

Экран настроек: API key, провайдеры, тема.

Компоненты

1. API Key (секция)

   • Поле ввода API key (password type, с toggle visibility)
   • Кнопка "Проверить" → вызывает GET /health или GET /v1/providers с ключом
   • Статус: ✅ Подключено / ❌ Ошибка

2. Провайдеры (секция)

   • Список провайдеров из GET /v1/providers
   • Каждый: название, иконка, status badge
     • 🟢 Configured & enabled
     • 🟡 Enabled but not configured (нужны credentials)
     • ⚪ Disabled
   • Capabilities summary (icons: stream ✓, cache ✗, embed ✓, download ✗)

3. Тема (секция)

   • Toggle: Светлая / Тёмная / Системная

4. О приложении (секция)

   • Версия, ссылки на документацию, OpenAPI schema

---

10. Компоненты

10.1 Track Card

Универсальная карточка трека, используется в Search, Library, Playlist Detail.

Props:
- track: TrackRead (или FavoriteRead + загрузка трека)
- showProviderBadge: bool (default true)
- showRiskBadge: bool (default true)
- compact: bool (default false, для mini player context)

Actions:
- onPlay: (trackId) → void
- onFavorite: (trackId) → void
- onAddToPlaylist: (trackId) → void
- onMore: (trackId) → void (bottom sheet)

10.2 Playlist Card

Props:
- playlist: PlaylistSummary

Displays:
- name
- description (truncated)
- track_count
- created_at (relative: "2 дня назад")

10.3 Provider Badge

Props:
- providerId: string ("local" | "youtube_official" | "soundcloud_official")

Rendering:
- local → 🟢 "Local"
- youtube_official → 🔴 "YouTube"
- soundcloud_official → 🟡 "SoundCloud"

10.4 Risk Badge

Props:
- riskLevel: RiskLevel

Rendering:
- compliant → 🟢 "Compliant"
- constrained → 🟡 "Constrained"
- risky → 🔴 "Risky"

10.5 Bottom Sheet (Add to Playlist)

Content:
- Список существующих плейлистов (клик → добавить)
- Кнопка "Создать новый плейлист" → inline form
- Кнопка "Закрыть"

10.6 Toast / Notification

Types:
- success: "Добавлено в избранное ❤️"
- error: "Ошибка: {message}"
- info: "Трек недоступен для скачивания"

10.7 Search Input

Props:
- value: string
- onChange: (value) → void
- onClear: () → void
- debounce: 300ms
- placeholder: "Найди любую музыку..."

10.8 Empty State

Props:
- icon: string (emoji)
- title: string
- subtitle: string
- action?: { label: string, onClick: () → void }

---

11. Mobile-first layout

Breakpoints

Breakpoint	Layout
< 768px	Single column, bottom nav, mini player
768–1023px	Sidebar nav, 2-column grid для карточек
≥ 1024px	Sidebar nav, 3-column grid, expanded player

Размеры и отступы

Элемент	Размер
Header bar height	56px
Bottom nav height	64px
Mini player height	72px
Content padding	16px
Card gap	12px
Artwork (search result)	48×48 px
Artwork (player)	min(80vw, 400px)

Touch targets

• Минимальный touch target: 44×44 px
• Кнопки воспроизведения: 48×48 px
• Отступ между кнопками: минимум 8px

Скролл поведение

• Content area: overflow-y: auto, -webkit-overflow-scrolling: touch
• Mini player: position: sticky; bottom: 0 (или fixed)
• Bottom nav: position: fixed; bottom: 0
• Mini player показывает progress bar как тонкую полоску сверху

Swipe gestures

• Свайп вверх от Mini Player → Full Player
• Свайп вниз от Full Player → Mini Player
• Свайп влево по треку в списке → action buttons (delete, add to playlist)

---

12. Цветовая схема и стили

Тёмная тема (primary)

Элемент	Цвет
Background	#121212
Surface	#1E1E1E
Card	#282828
Primary	#1DB954 (Spotify-green)
Text primary	#FFFFFF
Text secondary	#B3B3B3
Accent	#1DB954
Error	#E53935
Warning	#FFA726
Success	#66BB6A

Светлая тема

Элемент	Цвет
Background	#FAFAFA
Surface	#FFFFFF
Card	#F5F5F5
Primary	#1DB954
Text primary	#212121
Text secondary	#757575

Типографика

Элемент	Размер	Weight
H1 (page title)	28px	700
H2 (section title)	22px	600
H3 (card title)	18px	600
Body	16px	400
Caption	14px	400
Small (badges)	12px	500

Иконки

Рекомендуемый набор: Material Icons или Phosphor Icons.

Действие	Иконка
Play	▶️ (play)
Pause	⏸ (pause)
Next	⏭ (skip_next)
Previous	⏮ (skip_previous)
Favorite	❤️ (heart) / 🤍 (heart_outline)
Add to playlist	➕ (playlist_add)
Download	⬇️ (download)
More	⋮ (more_vert)
Search	🔍 (search)
Settings	⚙️ (settings)
Home	🏠 (home)
Library	📚 (library_music)
Playlist	🎵 (queue_music)