mrleo1nid/pipu-music
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 30 Wiki Activity
Files
6a67c27f5095e320041cebb24b2c165ce362a73e
pipu-music/docs/mobile.md
T
mrleo1nidandClaude Opus 5.5 9fd616da57
ci / mobile / mobile (Metro-бандл Android) (push) Successful in 1m39s
Details
ci / contract / contract (сгенерированный код совпадает с openapi.yaml) (push) Successful in 1m2s
Details
ci / ts / ts (packages + web) (push) Successful in 1m5s
Details
ci / docker / docker (образы собираются — их сервер собирает сам при обновлении) (push) Successful in 39s
Details
feat(mobile): sign-in, tabs, search, collection and background player (M5) 
- expo-router app in src/app: connect (server check, recent servers),
  login, mandatory credential / password change, tabs Home / Search /
  Collection / Profile, album and artist pages, full-screen player
- AuthSession per server with the refresh token in expo-secure-store
  (Android Keystore); language from the profile
- player on react-native-track-player: ExoPlayer queue with a
  notification and lock-screen controls via a playback service, 500 MB
  stream cache, quality by network (Wi-Fi high, cellular medium),
  play events with played time, reactions, playback state restore and
  the endless My Wave with feedback
- home: pulsing wave circle driven by BPM / energy in the cover
  palette, activity and mood chips that switch the wave on the fly
- New Architecture is off until react-native-track-player supports it;
  the release build runs codegen only when it is on; query-string is a
  direct dependency because expo-router 5.1 imports it undeclared

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 12:48:55 +03:00

9.6 KiB
Raw Blame History

Android-приложение (apps/mobile)

Стек

Задача Выбор
Фреймворк React Native + Expo SDK, prebuild / dev client (нативный код под контролем). New Architecture выключена, пока react-native-track-player её не поддерживает
Навигация expo-router (файловые маршруты)
Аудио react-native-track-player v4 — ExoPlayer, MediaSession, уведомление, экран блокировки, Android Auto-совместимость
Анимация волны Сейчас — Animated (пульс по BPM / energy, палитра обложки); дальше — @shopify/react-native-skia (порт wave.js)
Серверное состояние TanStack Query (+ persist в MMKV)
Клиентское состояние Zustand (общие сторы из packages/core)
Хранилище expo-secure-store (refresh-токены, список серверов, недавние запросы); expo-sqlite — офлайн-каталог и очередь событий (вместе с загрузками)
Загрузки expo-file-system (фоновые загрузки, resumable)
Сеть @react-native-community/netinfo (Wi-Fi / сотовая → качество)
i18n i18next, словари из packages/i18n
Минимальная версия Android 8.0 (API 26), target — актуальный API

Экраны

Макет — Pipu Android.dc.html, сводка решений — design.md.

  • Подключение и вход: адрес сервера (проверка GET /server-info: версия сервера, HTTPS, поддерживается ли эта версия приложения), список сохранённых серверов, затем логин, пароль, язык. Далее те же setup-экраны, что и в вебе.
  • Нижняя навигация: Главная · Поиск · Коллекция · Профиль. Мини-плеер над навигацией; свайп вверх — полноэкранный плеер в одном из двух видов (выбор в профиле): cover — крупная обложка (по умолчанию) или wave — визуализация волны; прогресс, лайк / дизлайк, скачать, очередь (нижний лист).
  • Поиск: недавние запросы (хранятся локально), подсказка про опечатки и раскладку, значок «скачано» у треков.
  • Главная: кнопка «Моя волна» (orb или liquid по настройке, тот же алгоритм, что в вебе, на Skia; пульс в такт BPM / energy из features трека — на Android спектр недоступен из ExoPlayer без нативного модуля, поэтому анимация управляется метаданными и позицией трека), выбор занятия / настроения.
  • Коллекция: История, Лайки, Дизлайки, Скачанное.
  • Коллекция → Скачанное: занято на устройстве / свободно в телефоне, «Скачивать новые лайки», «Скачать все лайки», очередь загрузок с пометкой «по Wi-Fi».
  • Профиль: смена пароля (лист), язык, тема, вид волны, вид плеера, качество звука (лист: Wi-Fi / сотовая / загрузки), «только Wi-Fi для загрузок», кэш недавних треков (размер + «Очистить»), проверка обновлений (точка, если есть новая версия), текущий сервер, «Админка — откроется в браузере» (для admin / moderator), выход.
  • Офлайн-баннер вверху, когда нет связи с сервером.
  • Админку в мобильном не делаем на первом этапе (ссылка «открыть в браузере»).

Воспроизведение

  • packages/core содержит общую логику очереди, событий и сохранения позиции; мобильный реализует адаптер AudioEngine поверх react-native-track-player.
  • Фоновый сервис плеера (PlaybackService) обрабатывает кнопки уведомления / гарнитуры и шлёт события, даже когда UI выгружен.
  • Если трек скачан — играется локальный файл, иначе стрим с качеством по типу сети.
  • Встроенный кэш ExoPlayer (maxCacheSize 500 МБ) для недавних стримов.
  • Аудиофокус: пауза при звонке, приглушение при навигационных подсказках.

Офлайн

  • Пользователь скачивает трек, альбом, «все лайки» (опционально — авто-загрузка новых лайков).
  • Файлы — во внутреннем хранилище приложения (documentDirectory/offline/<trackId>.opus), не видны другим приложениям.
  • SQLite хранит метаданные скачанных треков (название, исполнитель, обложка-файл, длительность, features) — раздел «Скачанное» и плеер работают полностью без сети.
  • Очередь загрузок: не более 2 параллельно, возобновление после обрыва, «только по Wi-Fi» по умолчанию.
  • Без сети:
    • доступны «Скачанное» и офлайн-волна (локальный упрощённый алгоритм: перемешивание скачанных с учётом лайков и энергии под выбранный контекст);
    • события пишутся в SQLite-очередь и отправляются при появлении сети (POST /events, идемпотентно);
    • реакции (лайк / дизлайк) — оптимистично локально + очередь мутаций.
  • Подписанные ссылки не кэшируются — при восстановлении сети запрашиваются заново.

Самообновление

Приложение распространяется только через Gitea Releases (не Google Play).

Поток:

  1. При запуске (не чаще раза в 6 ч) и вручную в профиле: GET /api/v1/app/android/latest на сервере Pipu. Сервер сам опрашивает Gitea API (GET /api/v1/repos/{owner}/{repo}/releases/latest) с серверным токеном, кэширует ответ на 10 мин и APK на диске. Так:
    • мобильному приложению не нужен доступ к Gitea и токен (репозиторий может быть приватным);
    • версия приложения согласована с версией сервера (min_supported из server-info).
  2. Если version_code новее — диалог с changelog (Markdown из релиза), кнопки «Обновить» / «Позже». Если текущая версия ниже min_supported — обновление обязательно.
  3. Загрузка APK через expo-file-system в cacheDirectory с прогрессом; проверка SHA-256 (значение из релиза).
  4. Установка: Intent.ACTION_VIEW с content:// URI через FileProvider и флагом FLAG_GRANT_READ_URI_PERMISSION (небольшой локальный Expo-модуль modules/apk-installer на Kotlin; при необходимости — PackageInstaller session API).
  5. Если нет разрешения «установка из неизвестных источников» — открываем Settings.ACTION_MANAGE_UNKNOWN_APP_SOURCES для нашего пакета с пояснением.

Требования:

  • В манифесте: REQUEST_INSTALL_PACKAGES, FileProvider.
  • Все релизы подписываются одним и тем же ключом (keystore в секретах CI) — иначе Android откажет в обновлении.
  • versionCode монотонно растёт: major·1 000 000 + minor·10 000 + patch·100 + (99 | rc) (см. ci-cd.md).
  • Ассеты релиза: pipu-music-<version>.apk, pipu-music-<version>.apk.sha256.

Безопасность

  • Refresh-токен — expo-secure-store (Android Keystore).
  • HTTPS обязателен; для self-signed сертификатов — возможность добавить пользовательский CA через network_security_config (собирается в CI по флагу) или пиннинг отпечатка, введённого при подключении к серверу.
  • android:allowBackup="false" для данных с токенами.
Reference in new issue View Git Blame Copy Permalink