docs: add product idea, design prototypes and development documentation

- IDEA.md: product vision from the user's perspective (input for design) - Architecture, ADRs, data model, REST API overview - Auth and roles, library storage (NFS, path regexes, scanner, search), playback, recommendation system ("My Wave"), track upload queue - Web, Android (offline, self-update), i18n, design system - Testing strategy, Gitea Actions CI/CD, deployment, conventions, roadmap - Clickable web/Android design prototypes and wave button variants - .claude/launch.json to serve the prototypes locally Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 23:21:31 +03:00
1 parent 36e99fe960
commit 9eb1c25147
@@ -0,0 +1,169 @@
+# Pipu Music — исходная идея продукта
+
+> Документ описывает **что** должно быть в приложении с точки зрения пользователя.
+> Используется как входные данные для создания дизайна. Технические решения — в [README документации](README.md).
+
+## Суть
+
+Закрытое (self-hosted) музыкальное приложение для прослушивания музыки с собственного сервера.
+Есть веб-версия и мобильное приложение для Android. Главная фишка — **«Моя волна»**: бесконечный умный поток
+музыки, который подстраивается под вкус пользователя и под выбранное настроение или занятие.
+
+Масштаб: до ~100 пользователей, библиотека от 11 000 треков и больше.
+
+Интерфейс двуязычный — **русский и английский**, с возможностью добавить другие языки позже.
+Переключатель языка — в профиле / настройках (и на экране входа).
+
+## Доступ и учётные записи
+
+- При первом открытии приложение показывает **экран входа** (логин + пароль).
+  В мобильном приложении на этом экране также указывается **адрес сервера**.
+- **Регистрации нет.** Учётные записи создаёт администрация.
+- Роли:
+  - **Администратор** — полный доступ; единственный, кто может создавать и назначать модераторов
+    и управлять хранилищами музыки.
+  - **Модератор** (заместитель администратора) — доступ к админке, может создавать обычных пользователей
+    и предлагать новые треки на добавление в библиотеку.
+  - **Пользователь** — слушает музыку.
+- **Первый вход администратора:** система сразу предлагает сменить стандартные логин и пароль администратора
+  (обязательный шаг, пока он не пройден, дальше не пустит).
+- **Любой пользователь** может сменить свой пароль (в профиле / настройках).
+- Если администратор сбросил пароль пользователю, тот при следующем входе обязан задать новый.
+
+## Каркас интерфейса (на всех экранах)
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  [Логотип]        [ 🔍  Поиск ...................... ]  [👤] │  ← верхняя панель
+├────────────┬─────────────────────────────────────────────────┤
+│  Главная   │                                                 │
+│  Коллекция │              Основной контент                   │
+│   История  │                                                 │
+│   Лайки    │                                                 │
+│   Дизлайки │                                                 │
+│   Скачанное│                                                 │
+│            │                                                 │
+│  Админка   │                                                 │
+├────────────┴─────────────────────────────────────────────────┤
+│ [обл.] Трек — Исполнитель  ⏮ ⏯ ⏭  ━━━━●━━━━ 1:23/3:45 🔊 ♥ 👎 │  ← плеер
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Поиск (всегда виден вверху)
+- При вводе появляется **выпадающий список** результатов, сгруппированный по типам:
+  **исполнители, альбомы, треки**. Клик по результату сразу открывает исполнителя / альбом / запускает трек.
+- По нажатию **Enter** открывается **полная страница поиска** со всеми результатами.
+- Поиск прощает опечатки и неправильную раскладку.
+
+### Левая панель навигации
+- **Главная**
+- **Коллекция** — с подкатегориями:
+  - **История** — прослушанные треки;
+  - **Лайки** — понравившиеся треки;
+  - **Дизлайки** — треки, которые пользователь не хочет слышать (можно убрать дизлайк);
+  - **Скачанное** — только в мобильном приложении, треки, сохранённые для офлайна.
+- **Админка** — видна только администраторам и модераторам.
+- Список будет расширяться в будущем (плейлисты и т.п.), дизайн должен это допускать.
+
+На мобильном вместо левой панели — нижняя навигация (Главная / Поиск / Коллекция / Профиль),
+плеер — мини-полоска над навигацией, разворачивается в полноэкранный плеер.
+
+### Плеер (всегда внизу)
+- Полноценный плеер в виде полоски: обложка, название трека, исполнитель, назад / пауза / вперёд,
+  прогресс-бар с перемоткой, время, громкость, **лайк** и **дизлайк**, открыть очередь.
+- **Запоминает последний трек и момент**, на котором остановились: после перезахода / перезагрузки
+  и даже на другом устройстве можно продолжить с того же места.
+- Если играет «Моя волна», плеер показывает это (и выбранное настроение / занятие).
+- Дизлайк в волне сразу переключает на следующий трек.
+
+## Главная страница
+
+- В центре — **большая кнопка «Моя волна»**. Это главный элемент приложения:
+  - **анимированная** — живая, «дышащая» волновая анимация; во время воспроизведения пульсирует
+    в такт музыке (темп и энергия текущего трека);
+  - **интерактивная** — реагирует на наведение и нажатие; видно, играет волна или нет; повторное нажатие — пауза.
+- Рядом с волной — выбор **занятия** и **настроения**, по которым волна корректируется:
+  - занятие: бегаю, просыпаюсь, работаю / фокус, тренировка, в дороге, отдыхаю, засыпаю;
+  - настроение: энергичное, весёлое, спокойное, грустное;
+  - можно не выбирать ничего — тогда волна просто «под вас».
+- Волна постоянно учится: лайки, дизлайки, пропуски, сколько раз и насколько долго слушался трек,
+  жанры и звучание — всё влияет на то, что будет дальше.
+
+## Страницы
+
+| Страница | Содержимое |
+|---|---|
+| Вход | (мобильное: адрес сервера), логин, пароль, «Войти», выбор языка. Без регистрации. |
+| Смена учётных данных админа | Обязательный экран при первом входе: новый логин, новый пароль, подтверждение. |
+| Обязательная смена пароля | После сброса пароля администрацией. |
+| Главная | Кнопка «Моя волна», выбор занятия / настроения. |
+| Коллекция → История | Прослушанные треки, сгруппированные по дням; можно запустить любой. |
+| Коллекция → Лайки | Понравившиеся треки, можно запустить все / перемешать. |
+| Коллекция → Дизлайки | Скрытые из рекомендаций треки, можно снять дизлайк. |
+| Коллекция → Скачанное | (мобильное) офлайн-треки, занимаемое место, удалить. |
+| Поиск | Полные результаты: исполнители, альбомы, треки. |
+| Исполнитель | Фото / обложка, альбомы, популярные треки, «волна по исполнителю». |
+| Альбом | Обложка, год, список треков, «скачать альбом» (мобильное). |
+| Профиль / настройки | Смена пароля, язык, качество звука (мобильное: для сети и для скачивания), проверка обновлений (мобильное), выход. |
+| Админка → Пользователи | Список, создание, роли, сброс пароля, блокировка. |
+| Админка → Хранилища | (только админ) Подключение хранилищ музыки, шаблоны структуры папок, запуск сканирования, статус. |
+| Админка → Библиотека | Статистика: число треков, ход сканирования и анализа звука, ошибки. |
+| Админка → Предложить треки | (модератор и админ) Загрузка файлов и папок перетаскиванием, индикатор заполненности очереди, список своих предложений со статусами. |
+| Админка → Очередь на добавление | (только админ) Рассмотрение предложенных треков: прослушать, поправить данные, увидеть, куда файл ляжет, одобрить / отклонить. |
+| Админка → Настройки | (только админ) Лимит очереди на добавление, хранилище для новых треков. |
+
+## Админка
+
+- **Модератор**: видит пользователей, создаёт обычных пользователей, сбрасывает им пароль, блокирует.
+- **Администратор**: всё то же + создание модераторов, назначение / снятие роли модератора,
+  **управление хранилищами**.
+- **Хранилища** (только админ):
+  - добавить хранилище: сетевая папка NFS (адрес сервера + путь) или уже подключённая папка на сервере;
+  - проверить подключение;
+  - задать **один или несколько шаблонов (регулярных выражений)**, по которым из пути к файлу
+    извлекаются исполнитель, альбом, год, номер трека, название — например
+    `Исполнитель/Год - Альбом/01 - Название.flac`;
+  - **предпросмотр**: показать, как шаблоны разберут несколько реальных файлов, до сохранения;
+  - выбрать, что важнее — теги файла или структура папок;
+  - запустить пересканирование, видеть прогресс и ошибки.
+- **Предложение треков** (модератор и админ):
+  - модератор загружает новые треки (файлы или целые папки альбомов) в **очередь на добавление**;
+  - у очереди есть **общий лимит размера** (например, 10 ГБ), его задаёт админ; виден индикатор «занято X из Y ГБ»;
+  - треки, которые **уже есть** в библиотеке (или уже лежат в очереди), **сразу отклоняются** — ещё до загрузки,
+    если это можно понять заранее, — и **не занимают место** в очереди; модератор видит, с каким треком совпало;
+  - модератор видит свои предложения и их статус (загружается, на рассмотрении, одобрено, добавлено, отклонено + причина),
+    может отозвать предложение до рассмотрения.
+- **Очередь на добавление** (только админ):
+  - список предложенных треков, сгруппированных по альбомам: можно прослушать, посмотреть качество,
+    поправить исполнителя / альбом / название / год / обложку;
+  - пометка «возможно, уже есть» для похожих треков (другая версия, ремастер) — решает админ;
+  - показан **путь, по которому файл ляжет** в хранилище, — в том же виде, как уже разложена музыка на сервере;
+  - одобрить / отклонить (с причиной), в том числе пачкой;
+  - после одобрения файл сам укладывается на файловый сервер и появляется в библиотеке.
+- Небольшая, утилитарная — не главная часть продукта.
+
+## Рекомендации («Моя волна»)
+
+Максимально умная система, которая учитывает:
+- жанры, а также **звучание** трека (темп, энергия, настроение) — даже если трек никто не слушал;
+- лайки и дизлайки;
+- сколько раз и как долго слушался каждый трек, пропуски;
+- выбранное занятие / настроение;
+- вкусы похожих пользователей;
+- постепенно обучается на поведении пользователей.
+
+## Мобильное приложение (Android)
+
+- Тот же функционал, что и веб: вход, главная с волной, поиск, коллекция, плеер.
+- Фоновое воспроизведение, управление с экрана блокировки / шторки / наушников.
+- **Офлайн по выбору пользователя**: скачать трек / альбом / лайки; прослушивания без сети
+  учитываются и отправляются на сервер позже.
+- **Самообновление**: приложение проверяет новые релизы в репозитории, предлагает обновиться
+  и скачивает новую версию.
+
+## Инфраструктура (для контекста)
+
+- Музыка хранится на сервере, подключение к хранилищу по NFS; хранилища подключает админ из админки.
+- Одобренные новые треки приложение само записывает на файловый сервер, соблюдая принятую там структуру папок.
+- Один репозиторий: веб, мобильное приложение, бэкенд, тесты, CI/CD.
+- CI/CD на Gitea: по тегу собирается релиз.