pipu-music/docs/IDEA.md

Pipu Music — исходная идея продукта

Документ описывает что должно быть в приложении с точки зрения пользователя. Используется как входные данные для создания дизайна. Технические решения — в README документации.

Суть

Закрытое (self-hosted) музыкальное приложение для прослушивания музыки с собственного сервера. Есть веб-версия и мобильное приложение для Android. Главная фишка — «Моя волна»: бесконечный умный поток музыки, который подстраивается под вкус пользователя и под выбранное настроение или занятие.

Масштаб: до ~100 пользователей, библиотека от 11 000 треков и больше.

Интерфейс двуязычный — русский и английский, с возможностью добавить другие языки позже. Переключатель языка — в профиле / настройках (и на экране входа).

Доступ и учётные записи

• При первом открытии приложение показывает экран входа (логин + пароль). В мобильном приложении на этом экране также указывается адрес сервера.
• Регистрации нет. Учётные записи создаёт администрация.
• Роли:
  • Администратор — полный доступ; единственный, кто может создавать и назначать модераторов и управлять хранилищами музыки.
  • Модератор (заместитель администратора) — доступ к админке, может создавать обычных пользователей и предлагать новые треки на добавление в библиотеку.
  • Пользователь — слушает музыку.
• Первый вход администратора: система сразу предлагает сменить стандартные логин и пароль администратора (обязательный шаг, пока он не пройден, дальше не пустит).
• Любой пользователь может сменить свой пароль (в профиле / настройках).
• Если администратор сбросил пароль пользователю, тот при следующем входе обязан задать новый.

Каркас интерфейса (на всех экранах)

┌──────────────────────────────────────────────────────────────┐
│  [Логотип]        [ 🔍  Поиск ...................... ]  [👤] │  ← верхняя панель
├────────────┬─────────────────────────────────────────────────┤
│  Главная   │                                                 │
│  Коллекция │              Основной контент                   │
│   История  │                                                 │
│   Лайки    │                                                 │
│   Дизлайки │                                                 │
│   Скачанное│                                                 │
│            │                                                 │
│  Админка   │                                                 │
├────────────┴─────────────────────────────────────────────────┤
│ [обл.] Трек — Исполнитель  ⏮ ⏯ ⏭  ━━━━●━━━━ 1:23/3:45 🔊 ♥ 👎 │  ← плеер
└──────────────────────────────────────────────────────────────┘

Поиск (всегда виден вверху)

• При вводе появляется выпадающий список результатов, сгруппированный по типам: исполнители, альбомы, треки. Клик по результату сразу открывает исполнителя / альбом / запускает трек.
• По нажатию Enter открывается полная страница поиска со всеми результатами.
• Поиск прощает опечатки и неправильную раскладку.

Левая панель навигации

• Главная
• Коллекция — с подкатегориями:
  • История — прослушанные треки;
  • Лайки — понравившиеся треки;
  • Дизлайки — треки, которые пользователь не хочет слышать (можно убрать дизлайк);
  • Скачанное — только в мобильном приложении, треки, сохранённые для офлайна.
• Админка — видна только администраторам и модераторам.
• Список будет расширяться в будущем (плейлисты и т.п.), дизайн должен это допускать.

На мобильном вместо левой панели — нижняя навигация (Главная / Поиск / Коллекция / Профиль), плеер — мини-полоска над навигацией, разворачивается в полноэкранный плеер.

Плеер (всегда внизу)

• Полноценный плеер в виде полоски: обложка, название трека, исполнитель, назад / пауза / вперёд, прогресс-бар с перемоткой, время, громкость, лайк и дизлайк, открыть очередь.
• Запоминает последний трек и момент, на котором остановились: после перезахода / перезагрузки и даже на другом устройстве можно продолжить с того же места.
• Если играет «Моя волна», плеер показывает это (и выбранное настроение / занятие).
• Дизлайк в волне сразу переключает на следующий трек.

Главная страница

• В центре — большая кнопка «Моя волна». Это главный элемент приложения:
  • анимированная — живая, «дышащая» волновая анимация; во время воспроизведения пульсирует в такт музыке (темп и энергия текущего трека);
  • интерактивная — реагирует на наведение и нажатие; видно, играет волна или нет; повторное нажатие — пауза.
• Рядом с волной — выбор занятия и настроения, по которым волна корректируется:
  • занятие: бегаю, просыпаюсь, работаю / фокус, тренировка, в дороге, отдыхаю, засыпаю;
  • настроение: энергичное, весёлое, спокойное, грустное;
  • можно не выбирать ничего — тогда волна просто «под вас».
• Волна постоянно учится: лайки, дизлайки, пропуски, сколько раз и насколько долго слушался трек, жанры и звучание — всё влияет на то, что будет дальше.

Страницы

Страница	Содержимое
Вход	(мобильное: адрес сервера), логин, пароль, «Войти», выбор языка. Без регистрации.
Смена учётных данных админа	Обязательный экран при первом входе: новый логин, новый пароль, подтверждение.
Обязательная смена пароля	После сброса пароля администрацией.
Главная	Кнопка «Моя волна», выбор занятия / настроения.
Коллекция → История	Прослушанные треки, сгруппированные по дням; можно запустить любой.
Коллекция → Лайки	Понравившиеся треки, можно запустить все / перемешать.
Коллекция → Дизлайки	Скрытые из рекомендаций треки, можно снять дизлайк.
Коллекция → Скачанное	(мобильное) офлайн-треки, занимаемое место, удалить.
Поиск	Полные результаты: исполнители, альбомы, треки.
Исполнитель	Фото / обложка, альбомы, популярные треки, «волна по исполнителю».
Альбом	Обложка, год, список треков, «скачать альбом» (мобильное).
Профиль / настройки	Смена пароля, язык, качество звука (мобильное: для сети и для скачивания), проверка обновлений (мобильное), выход.
Админка → Пользователи	Список, создание, роли, сброс пароля, блокировка.
Админка → Хранилища	(только админ) Подключение хранилищ музыки, шаблоны структуры папок, запуск сканирования, статус.
Админка → Библиотека	Статистика: число треков, ход сканирования и анализа звука, ошибки.
Админка → Предложить треки	(модератор и админ) Загрузка файлов и папок перетаскиванием, индикатор заполненности очереди, список своих предложений со статусами.
Админка → Очередь на добавление	(только админ) Рассмотрение предложенных треков: прослушать, поправить данные, увидеть, куда файл ляжет, одобрить / отклонить.
Админка → Настройки	(только админ) Лимит очереди на добавление, хранилище для новых треков.

Админка

• Модератор: видит пользователей, создаёт обычных пользователей, сбрасывает им пароль, блокирует.
• Администратор: всё то же + создание модераторов, назначение / снятие роли модератора, управление хранилищами.
• Хранилища (только админ):
  • добавить хранилище: сетевая папка NFS (адрес сервера + путь) или уже подключённая папка на сервере;
  • проверить подключение;
  • задать один или несколько шаблонов (регулярных выражений), по которым из пути к файлу извлекаются исполнитель, альбом, год, номер трека, название — например Исполнитель/Год - Альбом/01 - Название.flac;
  • предпросмотр: показать, как шаблоны разберут несколько реальных файлов, до сохранения;
  • выбрать, что важнее — теги файла или структура папок;
  • запустить пересканирование, видеть прогресс и ошибки.
• Предложение треков (модератор и админ):
  • модератор загружает новые треки (файлы или целые папки альбомов) в очередь на добавление;
  • у очереди есть общий лимит размера (например, 10 ГБ), его задаёт админ; виден индикатор «занято X из Y ГБ»;
  • треки, которые уже есть в библиотеке (или уже лежат в очереди), сразу отклоняются — ещё до загрузки, если это можно понять заранее, — и не занимают место в очереди; модератор видит, с каким треком совпало;
  • модератор видит свои предложения и их статус (загружается, на рассмотрении, одобрено, добавлено, отклонено + причина), может отозвать предложение до рассмотрения.
• Очередь на добавление (только админ):
  • список предложенных треков, сгруппированных по альбомам: можно прослушать, посмотреть качество, поправить исполнителя / альбом / название / год / обложку;
  • пометка «возможно, уже есть» для похожих треков (другая версия, ремастер) — решает админ;
  • показан путь, по которому файл ляжет в хранилище, — в том же виде, как уже разложена музыка на сервере;
  • одобрить / отклонить (с причиной), в том числе пачкой;
  • после одобрения файл сам укладывается на файловый сервер и появляется в библиотеке.
• Небольшая, утилитарная — не главная часть продукта.

Рекомендации («Моя волна»)

Максимально умная система, которая учитывает:

• жанры, а также звучание трека (темп, энергия, настроение) — даже если трек никто не слушал;
• лайки и дизлайки;
• сколько раз и как долго слушался каждый трек, пропуски;
• выбранное занятие / настроение;
• вкусы похожих пользователей;
• постепенно обучается на поведении пользователей.

Мобильное приложение (Android)

• Тот же функционал, что и веб: вход, главная с волной, поиск, коллекция, плеер.
• Фоновое воспроизведение, управление с экрана блокировки / шторки / наушников.
• Офлайн по выбору пользователя: скачать трек / альбом / лайки; прослушивания без сети учитываются и отправляются на сервер позже.
• Самообновление: приложение проверяет новые релизы в репозитории, предлагает обновиться и скачивает новую версию.

Инфраструктура (для контекста)

• Музыка хранится на сервере, подключение к хранилищу по NFS; хранилища подключает админ из админки.
• Одобренные новые треки приложение само записывает на файловый сервер, соблюдая принятую там структуру папок.
• Один репозиторий: веб, мобильное приложение, бэкенд, тесты, CI/CD.
• CI/CD на Gitea: по тегу собирается релиз.