mrleo1nidandClaude Opus 5.5
9eb1c25147
- 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>
170 lines
17 KiB
Markdown
170 lines
17 KiB
Markdown
# 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: по тегу собирается релиз.
|