feat(playlists): owner-facing /tracks read endpoint (phase 1.j.c)

[InstaZDLL]

Summary

• New GET /api/v1/profiles/{profile_id}/playlists/{id}/tracks so the web client can list a playlist's tracks (Sprint 4.c.4 — was blocked because the server didn't expose the join table on the read side).
• Same tenant chain as get_playlist. 404 blurs "no such playlist" / "wrong profile" / "wrong user" — no existence leak.
• Owner read does NOT filter NULL snapshots (the public share preview is the only surface that does); pre-1.j.b desktop rows surface to the owner so they don't disappear from their own UI.

Design notes

• fetch_for_owner is two queries by design: a single CTE conflates "not owned" with "owned but empty" in the result set, and we need the 404-vs-[] distinction at the HTTP boundary. The race window is benign because playlist_track.playlist_id is ON DELETE CASCADE — documented in the helper's doc-comment so it doesn't rot.
• Ordering is (position ASC, track_id ASC) — the PK guarantees uniqueness so the tiebreaker is deterministic. Tests exercise it with two rows that share a position.
• seed_playlist_track test helper does a direct SQL insert rather than going through the apply pipeline, so the assertion surface stays on the owner endpoint's contract.

Test plan

• Empty playlist returns 200 [], not 404.
• Tracks come back in (position ASC, track_id ASC) order with added_at and snapshot fields passed through verbatim — including NULL snapshots for pre-1.j.b rows.
• Foreign-tenant proxy attack via both profile ids returns 404; owner's own GET still succeeds (proves the 404 wasn't because the row was missing).
• Unknown playlist id returns 404.
• Anonymous request returns 401 (JWT middleware fires before the handler).
• OpenAPI spec advertises the new path (tests/openapi.rs guard).

CC @InstaZDLL.

Summary by CodeRabbit

Release Notes

• New Features

  • Ajout d'un nouvel endpoint permettant aux propriétaires de consulter la liste des tracks d'une playlist, triée par position et identifiant.

• Documentation

  • Mise à jour de la documentation pour spécifier les règles d'accès et les contrôles de sécurité multi-tenant de l'endpoint.

• Tests

  • Ajout de tests end-to-end validant l'endpoint, l'isolation des données et les protections d'authentification.

[coderabbitai]

📝 Walkthrough

Walkthrough

Ce PR ajoute un endpoint /api/v1/profiles/{profile_id}/playlists/{id}/tracks permettant aux propriétaires de consulter les tracks d'une playlist avec validation de possession, tri ordonné, isolation multi-tenant et gestion des snapshots optionnels. Tests E2E exhaustifs inclus.

Changes

Playlist track listing feature

Layer / File(s)	Summary
Database contract and ownership-aware track retrieval src/db.rs	OwnerTrackRow capture les métadonnées de track incluant snapshots optionnels. fetch_for_owner valide la possession via requête séparée (playlist → profile → user), puis récupère les tracks ordonnés (position ASC, track_id ASC). Retourne None si non autorisé, Some(vec) même vide pour distinction HTTP.
API response contract and endpoint handler src/api/playlists.rs	PlaylistTrackResponse DTO pour la sérialisation. Handler list_playlist_tracks appelle fetch_for_owner, mappe les résultats, retourne 200 (liste), 404 (non trouvé/non autorisé), 500 (erreur DB avec log). Routeur OpenAPI enregistre le nouvel endpoint.
End-to-end integration tests and validation tests/openapi.rs, tests/playlists.rs	Helper seed_playlist_track insère les lignes de track pour tests. Suite : playlist vide → 200 + tableau vide (pas 404), ordre (position, track_id) validé via insertion inversée + tie-break track_id, snapshots NULL et non-NULL, isolation multi-tenant (utilisateur B → 404 sur playlist A), unknown ID → 404, sans JWT → 401. OpenAPI spec vérifie l'enregistrement.
Feature specification documentation CLAUDE.md	"Owner read surface (Phase 1.j.c)" : endpoint, tri, visibilité des snapshots, sémantique 404 sans fuite d'existence, justification des deux requêtes DB pour préserver distinction HTTP.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant API as list_playlist_tracks
  participant DBFn as fetch_for_owner
  participant Postgres
  Client->>API: GET /api/v1/profiles/{profile_id}/playlists/{id}/tracks
  API->>DBFn: fetch_for_owner(id, profile_id, user_id)
  DBFn->>Postgres: verify ownership chain
  Postgres-->>DBFn: ownership result
  alt Not owner or playlist missing
    DBFn-->>API: None
    API-->>Client: 404 playlist not found
  else Owner verified
    DBFn->>Postgres: select tracks ordered by position then track_id
    Postgres-->>DBFn: rows
    DBFn-->>API: Some rows
    API-->>Client: 200 track list
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• InstaZDLL/waveflow-server#32: Introduit la table playlist_track et la lecture côté partage via fetch_for_share ; ce PR ajoute la lecture côté propriétaire symétrique avec même modèle DB et ordonnancement.
• InstaZDLL/waveflow-server#17: Refactorise le modèle d'authentification JWT et mise à jour des tests pour Authorization: Bearer ; ce PR s'appuie sur ce modèle et touche les mêmes fichiers src/api/playlists.rs et tests/playlists.rs.

Poem

🎵 Les tracks désormais classés par ordre et position,
Le propriétaire peut vérifier sa création,
Deux requêtes DB pour la sécurité fine,
Multi-tenant, snapshots, validation : musique machine !
✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Le titre décrit précisément la fonctionnalité principale : un nouvel endpoint /tracks côté propriétaire pour les playlists, avec référence à la phase du projet.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/1-j-c-playlist-tracks-owner-endpoint

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/playlists.rs`:
- Around line 637-913: Update the tests to return anyhow::Result<()> and replace
all unwrap()/expect() chains with ? so failures produce rich errors: change the
signatures of list_tracks_empty_playlist_returns_empty_array,
list_tracks_returns_position_order_with_snapshots,
list_tracks_foreign_tenant_returns_404, list_tracks_unknown_playlist_is_404, and
list_tracks_without_auth_is_401 to return anyhow::Result<()>, replace
occurrences like .send().await.unwrap(), .error_for_status().unwrap(),
.json().await.unwrap(), and any other unwrap()/expect() in those functions with
the ? operator (propagating errors), and add a final Ok(()) at the end of each
test; keep existing attributes (e.g. #[sqlx::test]) and adjust imports to
include anyhow if not already present.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 8b22cc65-c432-4809-aa86-0f2141ecf969

📥 Commits

Reviewing files that changed from the base of the PR and between 4508d9b and 26d9838.

📒 Files selected for processing (5)

• CLAUDE.md
• src/api/playlists.rs
• src/db.rs
• tests/openapi.rs
• tests/playlists.rs