Feature: Explain Recommendation Rationale and Capture Track Feedback

Summary

Add an explanation and feedback layer to Moodify recommendations so users can understand why each track was suggested and use explicit feedback to improve future recommendation quality.

Problem / Opportunity

Moodify currently returns Deezer tracks for a detected emotion and can blend recent mood history into the recommendation request. The UI supports sorting, filtering, saved recommendations, previews, and listening-history logging, but users do not see the reason a specific track appeared and cannot provide structured feedback beyond opening or ignoring a track.

This limits trust in emotion-based recommendations and leaves the recommender with mostly implicit signals. A lightweight rationale + feedback loop would make recommendations more transparent while creating a concrete path toward preference-aware ranking without overlapping the existing mood journal, weekly recap, or real-time blending issues.

Proposed Feature

Introduce per-track recommendation metadata and user feedback capture across web and mobile:

• Return explanation metadata from the recommendation service, such as matched emotion, blended-history contribution, genre/query source, popularity signal, novelty signal, and fallback/degraded status.
• Show a concise rationale on track cards and result detail surfaces, for example "matched your calm mood + recent late-night listening".
• Add explicit feedback actions such as like, dislike, too intense, too slow, wrong mood, already know this, and save for later.
• Persist feedback against the authenticated profile and use it in future recommendation requests as a compact preference summary.
• Add a profile surface where users can review and clear recommendation feedback independently from mood/listening history.

Scope

• Backend/data model for track feedback records or embedded feedback events on the user profile.
• API endpoints for creating, listing, and deleting feedback.
• Modal/Django recommendation contract update for explanation metadata and optional feedback-derived preferences.
• Web Results/Profile UI updates for rationale display and feedback actions.
• Mobile Results/Profile UI parity for core feedback actions.
• Tests for feedback persistence, API validation, and UI rendering of rationale/fallback states.

Acceptance Criteria

• Each recommendation can include machine-readable explanation metadata without breaking clients that do not render it.
• Web and mobile Results screens show a concise rationale for tracks when metadata is available.
• Authenticated users can submit structured feedback on an individual recommendation.
• Feedback is persisted and can be fetched with the user profile or a dedicated feedback endpoint.
• Users can clear recommendation feedback without deleting mood history, listening history, or saved recommendations.
• Recommendation requests can optionally include a compact preference summary derived from prior feedback.
• Fallback/degraded recommendation results are visibly marked so users can distinguish lower-confidence results.
• Unit or integration tests cover feedback creation, invalid payload handling, and rationale rendering.

Non-Goals

• Replacing the existing emotion classifier models.
• Building a full collaborative-filtering recommender.
• Adding social sharing or public ratings.
• Changing Deezer playback behavior.

Dependencies / Risks

• Requires a stable normalized track identity, since Deezer search results may vary between requests.
• Feedback data should stay bounded or aggregated so user profiles do not grow without limit.
• Explanation metadata should be honest about heuristic signals and avoid overstating model certainty.

Open Questions

• Should feedback be stored as raw events, aggregated preference summaries, or both?
• Which feedback options should be included in the first release?
• Should anonymous users get local-only feedback during a session, or should feedback require authentication?