Musify/frontend/docs/paginas.md

Musify — Guía de páginas

Documento vivo de qué debe contener cada página del frontend web. Sirve como mapa para priorizar features. El sistema de diseño (tokens, recetas, componentes) vive en el skill musify-web; aquí describimos contenido y estructura, no estilos.

Leyenda de estado: ✅ hecho · 🟡 parcial / maqueta · ⬜ pendiente.

Nota (rediseño app): se está portando el prototipo Musify.dc.html (app: sidebar + vistas + player persistente con acento dinámico por pista). La landing de marketing se eliminó. Las secciones de abajo describen el diseño anterior y quedan pendientes de actualizar a las vistas de la app (Inicio, Buscar, Biblioteca, Subir, Importar, Descargas, Playlists). El player ya está hecho por componentes en $lib/components/player/ con el tema en $lib/theme/ (theme.css paleta + color.ts acento/gradiente).

Inicio (app) / 🟡

• Hero: saludo + "Tu música. Sin límites." con color-wash del hue de la pista actual.
• Acceso rápido = escuchado recientemente (player.recentlyPlayed, hoy en cliente). Estado vacío con icono + CTA «Explorar».
• Tus playlists: tarjetas mosaico de las playlists (hoy datos de muestra). Estado vacío.

Backend pendiente (ASP.NET) para Inicio

• Escuchado recientemente: registrar reproducciones por usuario (tabla de historial: userId, trackId, playedAt) y exponer GET /me/recently-played?limit= (o /users/{id}/recently-played) devolviendo pistas ordenadas por playedAt desc, sin duplicados. El front lo cargaría en un load y lo pasaría al store en vez de recentlyPlayed.
• Playlists por última escucha: añadir lastPlayedAt a la playlist (hoy el schema solo tiene createdAt/updatedAt) y permitir ordenar GET /playlists/users/{userId} por ese campo (p. ej. ?sort=lastPlayed), para mostrar «tus últimas escuchadas».
• Las pistas necesitarán artista y un color/hue (o portada real de la que extraerlo) para el arte y el acento dinámico; hoy TrackApplicationResponse no trae artista ni color.

Estructura de rutas

Rutas agrupadas para separar lo público de lo autenticado (los grupos no cambian la URL):

src/routes/
  (marketing)/        Público, sin sesión obligatoria
    +page.svelte        /            Landing            ✅
  (app)/              Experiencia de la app
    explore/            /explore     Explorar / buscar  ✅
    upload/             /upload      Subir música       🟡 maqueta
    library/            /library     Tu biblioteca      ⬜
    playlists/          /playlists   Tus playlists      ⬜
      [id]/             /playlists/:id  Detalle playlist ⬜
  login  logout  auth/callback       Auth (endpoints)   ✅
  api/tracks/[id]/stream             Proxy de stream    ✅

Componentes globales (en todas las páginas): Navbar, Footer y PlayerBar (barra de reproducción fija, aparece al reproducir).

---

1. Landing / ✅ (marketing)

Página de entrada para no autenticados. Vender el producto y llevar a registro/explorar.

• Hero: badge de estado (beta), título, subtítulo, CTAs primario (Empezar gratis → registro) y secundario (Explorar canciones).
• Features: 3 cards (escuchar, playlists, subir).
• Pendiente sugerido: sección de capturas/demo, prueba social, FAQ corta.

2. Login / Auth ✅ (endpoints)

No es una página visual propia: /login inicia el flujo OIDC de Zitadel y redirige. ?mode=register arranca en registro; ?returnTo= vuelve a la ruta pedida tras entrar. /logout cierra sesión. /auth/callback intercambia el código y crea la cookie cifrada mf_session. La UI de credenciales la sirve Zitadel, no Musify.

3. Explorar / Buscar /explore ✅ (app)

Descubrimiento y búsqueda de canciones del catálogo.

• Buscador: input de texto (?q=) que filtra por nombre en el backend.
• Contador de resultados y grid de tracks (2→4 columnas): portada, título, fecha, botón play/pausa en hover que encola y reproduce vía el player global.
• Paginación anterior/siguiente (?page=, 24 por página).
• Estado vacío: sin resultados / catálogo vacío.
• Pendiente sugerido: filtros (más recientes, por usuario), skeletons de carga, portada real del track (hoy la API de listado no devuelve la key de imagen).

4. Subir música /upload 🟡 maqueta (app)

Alta de una canción nueva. Flujo real de backend (para cuando se cablee):

1. POST /tracks/upload-urls → URLs presignadas para portada y audio + intentIds.
2. PUT de cada archivo a su URL presignada (subida directa al almacenamiento).
3. POST /tracks con title, pictureIntentId, audioIntentId.
4. El backend procesa el audio (transcodifica a DASH) de forma asíncrona.

Contenido de la página:

• Zona de audio: drag & drop o selector; muestra nombre y tamaño del archivo, validación de tipo (audio) y tamaño.
• Portada: selector de imagen con vista previa cuadrada.
• Metadatos: título (obligatorio). Espacio para futuros campos (descripción, etc.).
• Pipeline visible: pasos Subir → Procesar → Publicar con su estado.
• Barra de progreso de subida y estado de procesado.
• Estados: vacío, archivo seleccionado, subiendo, procesando, publicado, error.
• Requiere sesión (al cablear: redirigir a /login?returnTo=/upload).

5. Tu biblioteca /library ⬜ (app)

Panel personal del usuario autenticado: lo suyo en un sitio.

• Tabs / secciones: «Tus canciones» (GET /tracks/users/{userId}) y «Tus playlists» (GET /playlists/users/{userId}).
• Tus canciones: lista con play, y acciones de gestión (borrar DELETE /tracks/{id}, añadir a playlist).
• Tus playlists: grid de portadas + botón «Crear playlist».
• Estado vacío con CTA a subir / crear.
• Requiere sesión.

6. Playlists /playlists ⬜ (app)

Listado de las playlists del usuario.

• Grid de playlists (portada, nombre, nº de tracks) → enlaza al detalle.
• Crear playlist: modal/página con nombre, descripción y portada (POST /playlists, portada vía POST /playlists/upload-picture).
• Estado vacío con CTA.
• Requiere sesión.

7. Detalle de playlist /playlists/[id] ⬜ (app)

• Cabecera: portada grande, nombre, descripción, nº de tracks, botón «Reproducir todo».
• Lista de tracks (GET /playlists/{id}/tracks, paginada): índice, título, fecha, play, quitar de la playlist (DELETE /playlists/{id}/tracks/{trackId}).
• Acciones del dueño: editar (PUT), borrar (DELETE) la playlist, reordenar (futuro).
• Añadir tracks: desde explorar/biblioteca (POST /playlists/{id}/tracks/{trackId}).

8. Perfil de usuario /users/[id] ⬜ (futuro)

Vista pública de un usuario: avatar, nombre, sus canciones y playlists públicas (GET /users/{id}, GET /tracks/users/{id}, GET /playlists/users/{id}).

---

Player global (PlayerBar) ✅

Barra fija inferior visible al reproducir. Info de la pista, transporte (anterior/play-pausa/siguiente), barra de progreso y control de volumen. Encola listas desde cualquier grid (player.playQueue). Reproduce DASH vía el proxy /api/tracks/:id/stream, que pide manifiesto + ticket firmado al backend.

Backend disponible (resumen)

Recurso	Endpoints
Tracks	listar/buscar, detalle, por usuario, stream, crear, borrar, upload-urls
Playlists	CRUD, tracks de la playlist, add/remove track, upload-picture
Users	listar/buscar, detalle, crear

Cliente tipado en $lib/server/api.ts (openapi-fetch, estilo ErrorOr). Consumir en load/actions server, nunca desde cliente. Tipos en src/lib/api/schema.d.ts.