mirror of
https://github.com/Dvorinka/swingmusic-extended.git
synced 2026-06-03 20:13:02 +00:00
Tomas Dvorak
cbf646e25b
## Major Changes - Fixed all TypeScript errors in web client for successful compilation - Resolved 82+ Python lint errors across backend services - Updated Flutter SDK compatibility for mobile app - Fixed security workflow configuration ## Web Client Fixes - Fixed import path in DragonflyDashboard.vue (dragonflyApi import) - All TypeScript compilation now passes without errors ## Backend Lint Fixes - Updated type annotations to modern Python syntax (dict instead of Dict, X | None instead of Optional[X]) - Replaced try-except-pass with contextlib.suppress(Exception) - Removed unused imports (Dict, Optional, Any, Iterator, etc.) - Fixed bare except clauses to use Exception - Sorted and formatted imports with ruff - Applied ruff format to 27 files ## Workflow Fixes - Updated Flutter SDK constraint from ^3.10.4 to ^3.5.0 (compatible with Flutter 3.24.0) - Changed pip-audit format from github to json in security.yml - Added comprehensive CI workflows (readiness-gate.yml, security.yml) ## Infrastructure - Added DragonflyDB caching system integration - Enhanced Docker configuration with multi-stage builds - Added pytest configuration and test infrastructure - Improved production readiness with proper error handling ## Verification - backend-lint job: ✅ Succeeded - web job: ✅ Succeeded - Ready for GitHub deployment All CI/CD issues resolved. Codebase now passes all quality checks.
78 lines
5.8 KiB
Markdown
78 lines
5.8 KiB
Markdown
### SwingMusic Production Readiness Plan: Multi-User, Download-First Artist Experience
|
||
|
||
**Summary**
|
||
- Deliver a production workflow from first launch to daily usage: owner bootstrap, invite-based users, root directory setup, recommendation-driven home, and fully actionable artist pages.
|
||
- Make all library behavior user-isolated at the profile level while deduplicating physical files on disk, with explicit opt-in import prompts when another user already has matching songs.
|
||
- Replace placeholder downloader behavior with a real server-side job pipeline, fix current downloader API/service mismatches, and unify status/quality reporting in UI.
|
||
- Make lyrics auto-download fully enabled by default, remove experimental gating, and add robust synced/unsynced retrieval + storage.
|
||
- Add personalized radio and “This Is Artist” generation that starts heuristic and becomes user-adaptive via listening data; include optional Last.fm sync.
|
||
|
||
**Implementation Changes**
|
||
- Authentication and tenancy:
|
||
- Add first-run owner bootstrap flow (only when no users exist), then invite/admin user creation only.
|
||
- Introduce strict user scoping on all user-facing resources (library views, recommendations, stats, queues, settings).
|
||
- Migrate existing single-user installs by assigning current library/root-dir ownership to the owner account automatically.
|
||
- Library model and cross-user import:
|
||
- Split data into physical file registry (global dedup) and per-user library ownership/projection tables.
|
||
- Mark track availability per user (`available`, `missing`, `queued`, `failed`) and expose this state everywhere tracks are rendered.
|
||
- Implement “another user already has this song” detection; always show consent popup with choices to import existing file or continue with new download.
|
||
- Download system hardening:
|
||
- Replace simulated universal queue with real async download workers and durable job states.
|
||
- Standardize a single downloader service interface and align Spotify API handlers to it (fix current contract mismatch).
|
||
- Enforce source strategy: Spotify-first metadata + fallback provider adapters for media acquisition.
|
||
- Persist source, codec/quality, destination path, and failure reasons for UI badges and retry flows.
|
||
- Home, navigation, and artist UX:
|
||
- Home/Dashboard default content: random recommended artists from available catalog APIs for newly initialized users.
|
||
- Ensure click-throughs resolve correctly to artist/song/album/playlist/radio pages; repair current route-name inconsistencies and wire missing global views.
|
||
- Artist page behavior:
|
||
- Show top 15 popular songs.
|
||
- Show full discography sections.
|
||
- Render available tracks as normal and missing tracks grayed with active download action.
|
||
- Keep quality badges visible using existing badge language/colors.
|
||
- Add “Artist Radio” (similar artists/tracks) and “This Is {Artist}” (artist-only set).
|
||
- Personalization and listening analytics:
|
||
- Keep per-user local scrobbling as primary and add optional Last.fm sync per user account.
|
||
- Ensure all counters/rankers are user-scoped; remove any cross-user aggregation leakage.
|
||
- Ranking engine: deterministic heuristic at cold start, then blend with user listening signals over time.
|
||
- Lyrics by default:
|
||
- Remove experimental toggle and force auto-lyrics retrieval on by default.
|
||
- Implement SpotiFLAC-style LRCLIB-first retrieval with fallback query strategy.
|
||
- Save lyrics as embedded tags when format supports it and also write sidecar `.lrc` files.
|
||
- Backfill missing lyrics after downloads and during scan/import cycles.
|
||
|
||
**Public API / Interface Changes**
|
||
- Add bootstrap/invite endpoints for owner-first provisioning and user onboarding.
|
||
- Extend artist/home/catalog responses to include per-user availability, download action metadata, and recommendation blocks.
|
||
- Add import-candidate and import-confirm endpoints for cross-user local reuse flow.
|
||
- Unify download job endpoints around one job schema (`state`, `source`, `quality`, `target_path`, `error`, `progress`).
|
||
- Add user-scoped external scrobble integration endpoints (connect/disconnect/sync status for Last.fm).
|
||
|
||
**Test Plan**
|
||
- First-run scenarios:
|
||
- Empty install -> owner creation -> root directory setup -> home recommendations visible.
|
||
- Existing install upgrade -> auto migration to owner with no lost library visibility.
|
||
- Multi-user isolation:
|
||
- Two users with separate dashboards, stats, queues, and library projections.
|
||
- No accidental cross-user data in recommendations, playcounts, or settings.
|
||
- Cross-user import behavior:
|
||
- Candidate detected -> popup shown -> accept imports without copy.
|
||
- Candidate detected -> decline keeps item missing and allows independent download.
|
||
- Artist page acceptance:
|
||
- Top 15 tracks displayed, full discography visible, correct available/missing styling, download actions functional, quality badges accurate.
|
||
- “Artist Radio” and “This Is Artist” render on cold start and improve after listening history accumulates.
|
||
- Downloader reliability:
|
||
- Queue, retry, failure states, progress updates, and destination writes validated under concurrent jobs.
|
||
- Lyrics:
|
||
- Auto-fetch runs by default; embed + `.lrc` both generated when possible; fallback paths validated.
|
||
- Responsive UI:
|
||
- Mobile/tablet/desktop checks for onboarding, home, artist, downloader, and import-popup flows.
|
||
|
||
**Assumptions and Defaults**
|
||
- Signup model: owner bootstrap + invite/admin management.
|
||
- Storage model: user-isolated libraries with shared deduplicated physical files.
|
||
- Import policy: always ask user before importing songs from another user’s local files.
|
||
- Download strategy: Spotify-first with fallback providers.
|
||
- Mix generation: heuristic first, then personalization.
|
||
- Lyrics strategy: embed + sidecar `.lrc`, auto-enabled globally.
|
||
- Listen tracking: local tracking plus optional Last.fm sync.
|