diff --git a/docs/design/mood-first.md b/docs/design/mood-first.md new file mode 100644 index 0000000..fac0c31 --- /dev/null +++ b/docs/design/mood-first.md @@ -0,0 +1,602 @@ +# Mood-first redesign — decisions and implementation handoff + +Status: **approved design, implementation not started** (2026-11-15). +This document supersedes the mounted-library, local-search and longform parts +of the previous design. It is the source of truth for the next development +cycle; update it as implementation details are settled. + +Repos: +- server: `/home/taptap/AudioManager` (Kotlin/Ktor, SQLite, Exposed, Flyway) +- client: `/home/taptap/AudioManagerClient` (Compose Multiplatform) + +## 1. Product model + +- Users have **moods only**. There is no mounted music directory, no file + upload and no longform/podcast content. +- All content enters the server by downloading from YouTube through `yt-dlp`. +- Search is a remote YouTube-Music-style search. Results are shown before + anything is added. +- A mood contains: + - **Songs** — the user's collection. Added from search, from a recommendation, + or by attaching an already-downloaded song. + - **Recommendations** — candidates derived from the collection and mood + options. They are downloaded automatically so they can take part in radio + playback, but they are not part of the collection until the user adds them. +- A mood needs **at least one song** before it can be played. +- Playback builds each queue slot at random: with probability + `collectionPercent` it comes from the collection, otherwise from the ready + recommendations. An empty pool falls back to the other pool. +- `recommendationCount` (0–30, default 10) is the number of **active** + recommendations per mood: states `downloading`, `ready`, `failed`. `new` + candidates are a hidden pool used to refill slots. `added` and `rejected` are + decisions and do not count. +- Adding a recommendation turns it into a permanent mood song. Rejecting it is + permanent for that mood. Both free a slot and trigger a top-up. +- A failed recommendation download stays visible as `failed` with Retry / Not + interested; it counts as a slot until the user acts. It is never silently + replaced. +- `refreshHours` is the minimum interval for **automatic** discovery passes. + It never replaces a ready recommendation the user has not acted on. +- Removing a song only detaches it from the mood. Files are deleted only when + no mood references them. +- Songs are stored once server-wide, keyed by YouTube video id and + deduplicated. Moods are strictly per-user: a user never sees another user's + moods or collection, but the same file can serve several users. +- No per-song owner, no storage quota. + +## 2. Resolved decisions + +1. `recommendationCount` counts downloading + ready + failed; add/reject frees + a slot and the server refills it. +2. Adding turns a recommendation into a collection song and removes it from the + recommendation list. Rejecting is permanent per mood and deletes the file + when unreferenced. +3. Failed downloads stay visible with Retry / Not interested. +4. `refreshHours` only throttles automatic discovery/top-up; it never replaces a + ready recommendation. +5. Small pools loop/replay least-recently played instead of going silent. +6. `seedPercent` becomes `collectionPercent`; recommendation plays count in + history and affinity like songs. +7. Mood options: name, description, query, genres, collectionPercent, + recommendationCount (default 10, max 30), refreshHours. `targetSize`, + `ytEnabled` are removed. +8. No accept step. Rows show download state, Add to mood, Not interested; failed + rows add Retry. +9. Search is one track at a time plus paste-a-URL; multi-select later. Results + longer than **10 minutes** are hidden. Already downloaded/in-mood results are + marked, and attaching an existing song is instant. Search exists inside a + mood and globally with a mood picker. +10. Library and Longform tabs are removed; Downloads stays for offline files. + Global Shuffle all is removed; playback stays per mood. +11. **Migration: full wipe.** Songs, moods, recommendations, downloads and + longform data are dropped. No import from the old mount. +12. Existing moods are wiped with the content. +13. Chart uses a PVC for `/data` (media at `/data/media`); music hostPath, + `library.yaml`, user folder lists, `DOWNLOADS_ENABLED` and + `DOWNLOAD_FOLDER_ID` disappear. +14. One song per YouTube video id; the same track from two videos is two songs. + Manual downloads outrank automatic recommendation downloads. Detach only; + GC deletes unreferenced files. A removed playing track finishes and drops + from future queues. +15. Recommendations are downloaded up to the configured count even if the mood + is never played. +16. Backups are external; no export/import feature and no offline CLI import. +17. Client: remove Library/Longform; keep Downloads for offline; add flow is + search -> download -> attach to mood; existing downloads attach instantly; + downloads run server-side with optional device downloads for offline. +18. Metadata is kept for display and search (title, artist, album, duration, + thumbnail). Separate album/artist/genre browse tables are removed. + +## 3. What exists today (server) + +Current files and responsibilities, and what happens to them: + +| File | Today | New | +|---|---|---| +| `config/AppConfig.kt` | data dir, library/users paths, downloads flags | drop library path and download flags; add `MEDIA_DIR` | +| `config/LibraryConfig.kt` | folders, `FolderType` | delete | +| `config/UsersConfig.kt` | users + folder IDs | users only; ignore/remove `folders` | +| `db/ConfigRepository.kt` | sync folders + users | sync users only | +| `db/Tables.kt` | folders, artists/albums/genres, songs, moods, seeds, recommendations, jobs, sessions, affinity, longform, tombstones | rewrite for the new schema | +| `db/MediaRepository.kt` | scan upsert, album/artist aggregates, orphan delete | simplify to song upsert by video id + GC | +| `db/LibraryRepository.kt` | folder-scoped browse/search/delta/random | delete; replace with `SongRepository` | +| `db/MoodRepository.kt` | moods, seeds, recommendations | rewrite around `mood_songs` + recommendation lifecycle | +| `db/RadioRepository.kt` | sessions, items, affinity | keep, minus folder/library assumptions | +| `db/DownloadRepository.kt` | per-user/mood jobs, longform progress | rewrite job model; move longform repository out | +| `discovery/DiscoveryService.kt` | seeds + genres/query -> candidates, review | same inputs from collection; store `new` candidates; no `matchedSongId` library matching | +| `discovery/YtSearch.kt` | yt-dlp flat search | keep; change music length to 45..600s; add URL resolve | +| `download/DownloadService.kt` | accept -> import folder -> scan -> seed | index directly into media store; attach song/recommendation; GC on failure | +| `download/YtDlpDownloader.kt` | MP3 + embedded metadata | keep; target `/.mp3` | +| `scanner/MediaScanner.kt` | walks folder config | walks `MEDIA_DIR`; derive video id from path | +| `scanner/Mp3TagExtractor.kt` | tags/cover/lyrics | keep tags+cover; drop album/artist IDs and lyrics use | +| `scanner/CoverArtService.kt` | album-keyed covers | song-keyed covers | +| `radio/RadioService.kt` | library + seeds pool | collection + ready recommendations pool | +| `api/LibraryApi.kt` | library sync/search/stream/covers | keep stream; cover by song; delete sync/search | +| `api/LongformApi.kt` | progress | delete | +| `api/MoodApi.kt` | seeds + accept/reject | songs + add/reject/retry + top-up | +| `api/SessionApi.kt` | sessions, events, add-to-mood | keep sessions/events; adapt add-to-mood | +| `api/ApiModels.kt` | old DTOs | rewrite | +| `api/ApiRoutes.kt` | wiring + scan | wire new services; users only | +| `Application.kt` | library/users/scan/download/discovery loops | media/users/download/top-up/GC loops | + +Current tests (server): `ApiRoutesTest`, `DatabaseFactoryTest`, +`DownloadServiceTest`, `MediaScannerTest`, `Mp3TagExtractorTest`, +`CoverArtServiceTest`, `DiscoveryServiceTest`, `RadioServiceTest`, +`AppConfigTest`, etc. They must be rewritten around the new model; keep useful +cases (auth, ownership, streaming, transcription, permissions). + +## 4. Target server architecture + +### 4.1 Media store + +- One server-owned root: `MEDIA_DIR` (default `<data>/media`; chart PVC at + `/data`, `DATA_DIR=/data`, `MEDIA_DIR=/data/media`). +- Download temp/work dir: `<data>/downloads` or `<media>/.tmp`; must be on the + same filesystem as the final path for atomic moves. +- Layout: `<media>/<videoId>/<sanitized-title>.mp3` plus + `<media>/cover-cache/...` or a song-keyed cover derived from embedded art. + The first path segment is the YouTube video id, which makes startup scans + deterministic and independent of tags. +- Song id: `sg-` + SHA-256 prefix of `"yt:<videoId>"`. +- MP3 only (`yt-dlp -x --audio-format mp3 --audio-quality 0`), embedded + metadata and thumbnail. +- The scanner walks `MEDIA_DIR`, extracts `videoId` from the top-level folder, + reads tags/cover, and upserts the song. The downloader can call the same + indexer for one file to avoid waiting for a full scan. +- Orphan cleanup keeps the old safety guard: never wipe when the media root is + missing/unreadable. GC is reference-based (see 4.6). + +### 4.2 Schema (V8) + +Keep `users` and `api_tokens`. Drop and recreate everything else. + +```sql +songs( + id TEXT PRIMARY KEY, + video_id TEXT NOT NULL UNIQUE, + title TEXT NOT NULL, + artist TEXT NOT NULL, + album TEXT, + duration INTEGER NOT NULL DEFAULT 0, + bit_rate INTEGER NOT NULL DEFAULT 0, + size INTEGER NOT NULL DEFAULT 0, + suffix TEXT NOT NULL DEFAULT 'mp3', + content_type TEXT NOT NULL DEFAULT 'audio/mpeg', + relative_path TEXT NOT NULL, + file_mtime INTEGER NOT NULL DEFAULT 0, + thumbnail TEXT, + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL +) + +moods( + id TEXT PRIMARY KEY, + owner TEXT NOT NULL REFERENCES users(name) ON DELETE CASCADE, + name TEXT NOT NULL, + description TEXT, + query TEXT, + genres TEXT NOT NULL DEFAULT '[]', + collection_percent INTEGER NOT NULL DEFAULT 50, + recommendation_count INTEGER NOT NULL DEFAULT 10 + CHECK (recommendation_count BETWEEN 0 AND 30), + refresh_hours INTEGER NOT NULL DEFAULT 24, + last_discovery_at TEXT, + created_at TEXT NOT NULL, + changed_at TEXT NOT NULL, + last_error TEXT +) + +mood_songs( + mood_id TEXT NOT NULL REFERENCES moods(id) ON DELETE CASCADE, + song_id TEXT NOT NULL REFERENCES songs(id) ON DELETE CASCADE, + origin TEXT NOT NULL DEFAULT 'search' + CHECK (origin IN ('search', 'recommendation', 'url')), + added_at TEXT NOT NULL, + PRIMARY KEY (mood_id, song_id) +) + +mood_recommendations( + mood_id TEXT NOT NULL REFERENCES moods(id) ON DELETE CASCADE, + video_id TEXT NOT NULL, + title TEXT NOT NULL, + artist TEXT NOT NULL, + album TEXT, + duration INTEGER, + thumbnail TEXT, + state TEXT NOT NULL DEFAULT 'new' + CHECK (state IN ('new', 'downloading', 'ready', 'failed', 'added', 'rejected')), + song_id TEXT REFERENCES songs(id) ON DELETE SET NULL, + attempts INTEGER NOT NULL DEFAULT 0, + error TEXT, + first_seen TEXT NOT NULL, + last_seen TEXT NOT NULL, + PRIMARY KEY (mood_id, video_id) +) + +download_jobs( + id TEXT PRIMARY KEY, + video_id TEXT NOT NULL, + mood_id TEXT NOT NULL REFERENCES moods(id) ON DELETE CASCADE, + kind TEXT NOT NULL CHECK (kind IN ('song', 'recommendation')), + state TEXT NOT NULL DEFAULT 'queued' + CHECK (state IN ('queued', 'downloading', 'done', 'failed')), + priority INTEGER NOT NULL DEFAULT 0, + attempts INTEGER NOT NULL DEFAULT 0, + error TEXT, + song_id TEXT REFERENCES songs(id) ON DELETE SET NULL, + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL +) + +playback_sessions(id, user_name, mood_id, next_position, created_at, last_seen_at, closed_at) +playback_session_items(session_id, position, song_id, state, queued_at, updated_at) +song_affinity(user_name, song_id, completions, skips, last_event_at) +``` + +Drop: `music_folders`, `artists`, `albums`, `album_artists`, `song_artists`, +`song_genres`, `album_genres`, `artist_genres`, `mood_seeds`, +`library_tombstones`, `longform_progress`, `user_song_state`, `user_stars`, +`bookmarks`, old `download_jobs`, old `mood_recommendations`, old `moods`, +old `songs`. + +`DatabaseFactory.normalizeLegacyMoodStates` stays: an old V4 DB must still pass +V5/V6/V7 before V8 can wipe it. + +### 4.3 Recommendation lifecycle + +States: `new` (hidden candidate pool), `downloading`, `ready`, `failed`, +`added`, `rejected`. + +- Discovery stores up to a bounded pool of `new` candidates (e.g. 60) from the + collection's artists/titles + `query` + `genres` + mood name. Exclude video + ids already in `mood_songs`, `added` or `rejected`. +- `topUp(mood, force)`: + 1. Count active = `downloading + ready + failed`. + 2. If `active >= recommendationCount`, stop. + 3. Promote the best `new` candidates to `downloading` and enqueue + `download_jobs` until the count is met. + 4. If more slots remain and (`force || discoveryDue(mood)`), run discovery, + then promote again. +- `force = true` on user add/reject/retry and on the explicit refresh action. + Coalesce per-mood discovery with an in-flight guard. Background passes use + `force = false` and respect `refreshHours`. +- `recommendationCount = 0` stops discovery and downloads for the mood. +- On download success: + - `downloading` -> `ready` with `song_id`. + - `added` (user added while downloading) -> insert `mood_songs`, keep + `added`, do not create a duplicate. + - `rejected` -> delete the file if unreferenced. +- On final download failure: `failed` with `error`; keep the slot. +- Add: if `ready`, attach the song; if `downloading`, mark `added` and attach + when the job completes; insert `mood_songs` with origin `recommendation`; + top up. +- Reject: mark `rejected`, cancel the job, GC, top up. +- Retry: `failed` -> `downloading`, reset the job, top up. +- `new` candidates are not shown in the client. + +### 4.4 Download pipeline + +- `download_jobs` are global; `kind=song` (manual add) has higher priority than + `kind=recommendation`. Claim by `priority DESC, created_at ASC`. +- Before downloading, check `songs.video_id`: + - if the song exists and the file is present, attach immediately; + - otherwise download. +- A per-video download is effectively deduplicated by the existence check; two + moods may queue the same video, but only the first downloads and the second + completes instantly. +- Worker steps: + 1. Claim a job. + 2. Resolve target `<media>/<videoId>/<title>.mp3`. + 3. If the song exists, finish. + 4. Download to temp with yt-dlp; move atomically into the target dir; index + the file (tags/cover) and upsert the song by video id. + 5. Apply the job outcome (song attach or recommendation state). + 6. On permanent failure, remove the partial file and set `failed`. +- Keep the 3-attempt retry, stale-job recovery, permission classification and + UTF-8 filename truncation from the current implementation. +- Rejected/cancelled jobs must not later attach the track. + +### 4.5 Playback / radio + +- Inputs: collection songs (`mood_songs`) and `ready` recommendation songs. +- 0 collection songs -> API rejects session start with a clear error; the client + shows "Add at least one song". +- Candidate scoring: affinity (`completions - 3*skips`), recent-play penalty, + jitter, plus artist/album spacing in `pickMixed`. No genre/artist library + matching. +- `pickMixed(collection, recommendations, limit, collectionPercent)`: + each slot rolls the percentage; an empty pool falls back to the other one. +- Session de-duplication: exclude songs already queued in the session. +- Exhaustion: allow replay of the least-recently queued songs, but never + duplicate within one batch. A one-song mood returns one track per batch and + the client loops it. +- Persist session items and playback events exactly as today. +- Recommendation plays count in history/affinity. +- Remove `pickDiverse` if it becomes dead code. + +### 4.6 File GC + +A song is referenced by: +- any `mood_songs` row; +- any `mood_recommendations` row with `song_id = song` and state in + `downloading|ready|added|failed` (`added` also has `mood_songs`); +- an open playback session item (avoid deleting a track currently streaming). + +When the reference count is zero, delete the song row, the `<videoId>` media +directory and the cover. Run GC: +- after removing a song; +- after rejecting a recommendation; +- after deleting a mood; +- after a cancelled/failed job with no references; +- periodically (hourly) to catch leftovers. + +### 4.7 Search and URL adds + +- `GET /api/v1/search?q=...&limit=...` -> YT results with `videoId,title, + artist,album,duration,thumbnail,songId?,downloaded`. +- Hide results with `duration > 600` seconds (and probably `< 30`). +- `POST /api/v1/moods/{id}/songs` accepts either `songId` (existing download) + or download metadata, or `url`. A URL is resolved with yt-dlp + (`--dump-single-json --no-playlist`) before enqueueing. +- Search requires auth; it is a server-side yt-dlp call, so use a 120s client + timeout and return 502 with the yt-dlp error on failure. + +### 4.8 API surface + +``` +POST /api/v1/auth/login +POST /api/v1/auth/logout +GET /api/v1/me +GET /api/v1/moods +POST /api/v1/moods +GET /api/v1/moods/{id} +PATCH /api/v1/moods/{id} +DELETE /api/v1/moods/{id} +GET /api/v1/moods/{id}/preview +GET /api/v1/moods/{id}/recommendations +POST /api/v1/moods/{id}/recommendations/refresh +POST /api/v1/moods/{id}/recommendations/{videoId}/add +POST /api/v1/moods/{id}/recommendations/{videoId}/reject +POST /api/v1/moods/{id}/recommendations/{videoId}/retry +POST /api/v1/moods/{id}/songs +DELETE /api/v1/moods/{id}/songs/{songId} +POST /api/v1/moods/{id}/sessions +GET /api/v1/sessions/{id} +POST /api/v1/sessions/{id}/next +POST /api/v1/sessions/{id}/events +DELETE /api/v1/sessions/{id} +GET /api/v1/search +GET /api/v1/songs/{id}/stream (Range/transcoding as today) +GET /api/v1/songs/{id}/cover +GET /api/v1/scan (admin diagnostic; optional) +POST /api/v1/scan (admin; optional) +``` + +DTO sketch: + +```text +UserDto(name, admin) +SongDto(id, videoId, title, artist, album, duration, bitRate, size, suffix, + thumbnail) +MoodDto(id, name, description, query, genres, collectionPercent, + recommendationPercent, recommendationCount, refreshHours, + lastDiscoveryAt, createdAt, changedAt, lastError, songCount, + recommendationReady, recommendationDownloading, recommendationFailed) +MoodSongDto(song, origin, addedAt) +MoodDetailDto(mood, songs, recommendations, downloads) +RecommendationDto(videoId, title, artist, album, duration, thumbnail, state, + song?, download?, firstSeen, lastSeen) +SearchResultDto(videoId, title, artist, album, duration, thumbnail, songId?, + downloaded) +``` + +Remove: `LibraryPage`, `SearchResponse` of local songs, all longform DTOs, +`SeedDto`, `AddSeedRequest`, `targetSize`, `ytEnabled`, folder fields. + +### 4.9 Auth and users + +- `users.yaml` keeps `name`, `password`, `admin`. Remove `folders`; accept and + ignore existing `folders` keys for compatibility. +- No folder validation, no `musicFolderIds`/`longformFolderIds`. +- `ConfigRepository.sync(users)` only reconciles users. +- Admin remains for optional scan/maintenance endpoints. + +## 5. Client design + +### 5.1 Screens + +`Screen = Moods | MoodDetail | Search | Downloads | Settings` + +- **Moods**: mood grid/list, create, global search icon. +- **MoodDetail**: + - header/play/settings; + - **Songs** collection with play/remove; + - **Add music** -> Search targeted at this mood; + - **Recommendations**: active rows with thumbnail, state/progress, Add to + mood, Not interested, Retry (failed); + - **Next batch** preview; + - mood options: name, description, query, genres, collectionPercent, + recommendationCount (0–30, default 10), refreshHours. +- **Search**: query field, debounced remote search, results (hide >10min done + server-side), Add; if opened globally, choose a mood; badges for downloaded / + already in mood; paste-a-URL action. +- **Downloads**: device-side downloaded songs, play/delete/clear, storage usage. +- **Settings**: server/account/devices/logout; remove scan UI. +- Remove `LibraryScreen` and all longform UI. + +### 5.2 State and store + +- `AppState` remove: `library`, `longform`, `longformResults`, + `longformProgress`, `musicResults`, `searchResults` (replace with + `searchResults: List<SearchResult>` + `searchTargetMoodId`), longform + progress. +- `CachedState` version 2: `serverUrl`, `userName`, `moods`, `moodDetails` + (each including songs/recommendations). No revision/longform. Invalidate old + caches on version mismatch. +- `AppStore`: + - bootstrap restores session, moods/details, playback snapshot and position; + - `refreshAll` fetches moods only; selected mood detail on open/refresh; + - create/update/delete mood; + - `addSong`, `removeSong`, `addRecommendation`, `rejectRecommendation`, + `retryRecommendation`, `refreshRecommendations`; + - `searchRemote(query)` with debounce and cancellation; + - `playMood` uses sessions; clear error when the mood has no songs; offline + fallback = cached mood songs filtered by device downloads; + - remove `playAll`, `playLongform*`, `resumeLongform`, `savedPosition`, + longform progress reporting; + - keep playback snapshot/history/previous/sleep timer/queue editing; + - keep device downloads (`toggleDownload`, `clearDownloads`) and artwork; + - `addCurrentToMood` works for collection songs via `songId`. +- `ApiClient`: new models/routes; remove library/longform; `coverUrl(songId)`. +- Mood detail polling while recommendations/downloads are active (bounded, with + backoff; no infinite loop). + +### 5.3 Playback + +Keep `AudioPlayer`, desktop seek, Android media session, notification, sleep +timer, history and queue snapshot. Only the server content model changes. +Offline playback uses device downloads; online mood playback uses sessions. + +## 6. Migration + +- **V8 drops all content**, keeps users and tokens. +- The old mounted music directory is no longer mounted; the operator must + delete old files manually. The new media root starts empty. +- The chart's old music/longform mounts and `library.yaml` are removed; add a + PVC. +- Client cache version bump clears old library/longform data. +- No CLI import and no app export (external backups only). + +## 7. Ops + +- `AppConfig`: `port`, `dataDir`, `usersFile`, `ffmpegPath`, `ytDlpPath`, + `mediaDir` (`MEDIA_DIR`, default `<dataDir>/media`), `downloadDir` + (`<dataDir>/downloads`). Remove `libraryConfigPath`, `downloadsEnabled`, + `downloadFolderId`. +- `Application.kt`: users only; scanner over `mediaDir`; download worker; + discovery/top-up loop; GC loop. No library scan-at-start for empty DB (scan + media root at startup is fine). +- Chart: + - one PVC for `/data`, `fsGroup` 10001, no hostPath/library ConfigMap, no + `prepare-imports` init container; + - `DATA_DIR=/data`, `MEDIA_DIR=/data/media`; + - keep users Secret, probes, resources; add persistence values; + - README deployment section rewritten. +- Nix shell: no library config; `DATA_DIR=./data`. +- Docker: no extra packages; `yt-dlp` and `ffmpeg` already present. +- Smoke test: rewrite for mood creation, search stub or seeded songs, add, + recommendations, playback. A fake `yt-dlp` script can return deterministic + search JSON and a tiny MP3 fixture for downloads. + +## 8. Implementation plan + +### Phase 1 — server schema and repositories +- V8 migration. +- Rewrite `Tables.kt`. +- `SongRepository` (upsert by video id, get by video id/id, list by mood, + attach/detach, refcount, delete). +- `MoodRepository` (CRUD, songs, recommendations lifecycle, top-up helpers). +- `DownloadRepository` (jobs, priority, claim, recovery, cancel, retry). +- GC service/repository. +- Tests: migration wipe, song dedupe, mood songs, recommendation state machine, + refcount/GC. + +### Phase 2 — media store and downloader +- `AppConfig`/users cleanup. +- Path layout + indexer shared by scanner and downloader. +- `MediaScanner` over media root, video id from path. +- `CoverArtService` song-keyed. +- `YtDlpDownloader` target path; direct indexing after move. +- `DownloadService` attach-to-song/recommendation; failure cleanup; priority. +- Tests: manual add, existing song attach, shared file across moods/users, + reject during download, retry, GC, UTF-8 names, scan recovery. + +### Phase 3 — discovery, top-up, radio +- `DiscoveryService` inputs from collection; store `new`; no library matching; + 10-minute filter. +- `RecommendationTopUpService` (or methods in `MoodRepository`/`DiscoveryService`). +- `RadioService` collection + ready recommendations. +- Background loops: top-up hourly, GC hourly. +- Tests: N active, refill on add/reject, failed stays, refresh top-up only, + 0/50/100 percent, small-pool repeat, no duplicates per batch, 0 songs error. + +### Phase 4 — API +- New DTOs and routes; remove library/longform/seed endpoints. +- Search endpoint + URL resolve. +- Cover by song id. +- Session start guard. +- Tests: ownership, add/reject/retry, search filter, streaming, 400s, auth. + +### Phase 5 — server ops +- Chart PVC, env, ConfigMap removal, init container removal. +- Nix/README/smoke. +- Chart check. + +### Phase 6 — client data layer +- Models/ApiClient/cache version/store rewrite. +- Remove longform/library code paths. +- Tests: search/add, recommendation actions, play empty mood, offline fallback, + cache migration, playback snapshot. + +### Phase 7 — client UI +- Moods/MoodDetail/Search/Downloads/Settings. +- Remove Library/Longform screens; adapt PlayerBar. +- Tests/builds: desktopTest, assembleDebug, Wasm. + +### Phase 8 — integration +- Full server tests, smoke, chart check. +- Client tests/builds. +- Commit/push both repos, CI green. +- Optional: deploy, wipe DB/media, validate real downloads. + +## 9. Test plan (high signal) + +Server: +- V7 -> V8 migration keeps users/tokens, drops content, creates schema. +- Song upsert dedupes by video id; same video different moods/users -> one file. +- Manual add: new download -> attach; existing -> instant attach. +- Recommendation top-up: N active; add/reject refills; failed stays; refresh + does not replace ready; `recommendationCount=0` disables discovery. +- Reject during download cancels and GCs. +- GC keeps files referenced by another mood/session and deletes unreferenced. +- Radio: collection-only, recommendation-only mix, fallback, 1-song replay, + no duplicate in a batch, 0-song start error. +- Search: duration >10min hidden, malformed yt-dlp output, URL resolve. +- Auth/ownership regressions. + +Client: +- Search results/add flow, existing song instant, badges. +- Recommendation add/reject/retry UI state. +- Play mood with zero songs shows error; queue and history still work. +- Offline playback from device downloads; cache version reset. +- Device download/delete/clear. + +## 10. Current repo and deployment state + +- Server latest commit: `4be502b` (plus this uncommitted doc). Image + `sha-4be502b`/`latest`; chart `0.2.4-sha.4be502b`. +- Client latest commit: `d9976a6`; CI green; Play internal release + `v0.1.1`, versionCode 2, package `win.tap_tap.audiomanager.client`. +- Client release automation: Gradle Play Publisher 3.13.0, tag `v*` -> + `publishBundle` to internal, `ResolutionStrategy.AUTO`; Gitea secrets set. +- Server deployment still uses the old mounted-library design; upgrading wipes + content and needs a PVC. +- Play App Signing is active (Google-generated key). + +## 11. Risks / implementation notes + +- Auto-download of up to 30 recommendations per mood can consume significant + disk/bandwidth even if the mood is never played. This is accepted. +- yt-dlp bot checks can fail downloads/searches; failed states and retry must + be robust, and search must return a clear 502. +- The 10-minute filter must apply to both search and discovery; longform is + gone. +- Cover art becomes song-keyed; the client must use `coverUrl(songId)`. +- Streaming must still support Range and transcoding for the Wasm/desktop + clients. +- Don't delete a file that an open playback session or another mood references. +- `recommendationCount` is clamped 0..30; `collectionPercent` 0..100. +- Search results are transient; no DB rows until add. +- A recommendation that is `added` while downloading must not turn into a + duplicate collection row. +- The migration is destructive by design; document it prominently.