pipu-music/docs/playlists.md

Личные плейлисты

Плейлисты хранятся в PostgreSQL и доступны владельцу на вебе и в React Native-клиенте. В вебе раздел находится в коллекции; на узком экране — в меню «Ещё». В мобильном клиенте — кнопка «Плейлисты» в коллекции.

Можно создать плейлист, изменить название и описание, добавить трек из поиска, альбома или коллекции, убрать трек и переместить его выше/ниже. В вебе можно добавить целый альбом. Один трек встречается в плейлисте один раз: повторное добавление не создаёт дубль. Воспроизведение доступно в сохранённом или случайном порядке; недоступные треки остаются видимыми, но пропускаются при запуске всего плейлиста. Удаление плейлиста требует подтверждения и не удаляет музыку из каталога.

API

• GET /api/v1/me/playlists — сводки личных плейлистов, последние изменённые первыми.
• POST /api/v1/me/playlists — создание: name, description, track_ids.
• GET /api/v1/me/playlists/{id} — метаданные и упорядоченные треки с персональными реакциями и подписанными ссылками.
• PUT /api/v1/me/playlists/{id} — атомарная замена метаданных и порядка треков; дополнительно требуется revision из прочитанного плейлиста.
• DELETE /api/v1/me/playlists/{id} — удаление.

Все операции требуют авторизации. Чужой и отсутствующий плейлист возвращают одинаковый 404. Изменения блокируют строку плейлиста в транзакции; устаревшая версия возвращает 409 playlist.conflict. Редактор сохраняет исходную версию до закрытия, даже если фоновый запрос получил новую. Ошибка трека откатывает изменение целиком. Ввод ограничен 120 символами названия, 2000 символами описания и 2000 уникальными треками.

Миграция 00013_playlists.sql создаёт таблицы playlists, playlist_tracks и индексы. Удаление пользователя очищает его плейлисты; удаление трека из каталога очищает его членство. Таблицы не затрагивают музыкальные файлы.

Плейлисты личные; публичные ссылки, совместное редактирование и загрузка пользовательских обложек не входят в эту реализацию. Карточки имеют градиентную обложку, страница использует обложку первого трека. Контекст воспроизведения — collection с UUID и названием плейлиста.

Проверки

• pnpm --filter @pipu/web test src/App.test.tsx -t playlists
• pnpm --filter @pipu/web test:e2e e2e/playlists.spec.ts
• pnpm --filter @pipu/web build
• pnpm --filter @pipu/mobile typecheck
• В services/api: go test ./internal/playback ./internal/server
• С отдельной тестовой PostgreSQL/pgvector: TEST_DATABASE_URL=… go test -tags integration ./internal/playback -run TestPlaylistPersistenceAndIsolation -v. Проверяет сохранение порядка, изоляцию владельцев, откат при несуществующем треке, конфликт конкурентных записей и каскадное удаление членства.