Refactoring du pmoaudiocache

pmoaudiocache/src/openapi.rs

@@ -2,22 +2,124 @@
 
 use utoipa::OpenApi;
 
+/// Documentation OpenAPI pour l'API PMOMusic Audio Cache
+///
+/// L'API réutilise les handlers génériques de pmocache.
 #[derive(OpenApi)]
 #[openapi(
-    info(
-        title = "PMOMusic Audio Cache API",
-        version = "0.1.0",
-        description = "API de gestion du cache de pistes audio avec conversion FLAC asynchrone"
-    ),
     components(
         schemas(
-            crate::db::AudioCacheEntry,
-            crate::metadata::AudioMetadata,
-            crate::api::AddTrackRequest,
+            pmocache::CacheEntry,
+            pmocache::api::AddItemRequest,
+            pmocache::api::AddItemResponse,
+            pmocache::api::DeleteItemResponse,
+            pmocache::api::ErrorResponse,
+            pmocache::api::DownloadStatus,
         )
     ),
     tags(
-        (name = "audio", description = "Gestion des pistes audio")
+        (name = "audio", description = "Gestion du cache de pistes audio")
+    ),
+    info(
+        title = "PMOMusic Audio Cache API",
+        version = "0.1.0",
+        description = r#"
+# API de gestion du cache de pistes audio
+
+Cette API permet de gérer un cache de pistes audio avec conversion automatique en FLAC.
+
+## Fonctionnalités
+
+- **Ajout de pistes** : Téléchargement depuis une URL avec conversion automatique en FLAC
+- **Métadonnées** : Extraction et stockage automatique des métadonnées audio en JSON
+- **Collections** : Organisation par artiste/album
+- **Consultation** : Liste des pistes avec statistiques d'utilisation
+- **Suppression** : Suppression individuelle ou purge complète
+- **Maintenance** : Consolidation du cache pour réparer les incohérences
+- **Statut** : Suivi des téléchargements et conversions en cours
+- **Streaming progressif** : Les fichiers sont streamés dès qu'ils sont disponibles
+
+## Endpoints principaux
+
+### GET /api/audio
+Liste toutes les pistes en cache avec leurs statistiques
+
+### POST /api/audio
+Ajoute une piste depuis une URL (conversion FLAC automatique)
+
+### GET /api/audio/{pk}
+Récupère les informations complètes d'une piste (avec metadata_json)
+
+### DELETE /api/audio/{pk}
+Supprime une piste
+
+### GET /api/audio/{pk}/status
+Récupère le statut du téléchargement et de la conversion
+
+### DELETE /api/audio
+Purge complètement le cache
+
+### POST /api/audio/consolidate
+Consolide le cache (répare les incohérences)
+
+## Servir les fichiers
+
+### GET /audio/tracks/{pk}
+Récupère le fichier FLAC (streaming progressif si en cours de téléchargement)
+
+### GET /audio/tracks/{pk}/orig
+Alias pour le fichier original
+
+## Format des fichiers
+
+Les pistes sont stockées au format FLAC avec :
+- Une version convertie (`{pk}.orig.flac`)
+- Métadonnées stockées en JSON dans la base de données
+
+## Métadonnées
+
+Les métadonnées suivantes sont extraites et stockées :
+- Titre, artiste, album
+- Année, genre
+- Numéro de piste/disque, total de pistes/disques
+- Durée, taux d'échantillonnage, bitrate
+- Nombre de canaux
+
+## Collections
+
+Les collections sont identifiées par une clé au format `"artist:album"` :
+- Conversion en minuscules
+- Remplacement des espaces par des underscores
+- Exemple : `"Pink Floyd - Wish You Were Here"` → `"pink_floyd:wish_you_were_here"`
+
+## Clés (pk)
+
+Chaque piste est identifiée par une clé (pk) unique :
+- Hash SHA1 des 8 premiers octets de l'URL source
+- Encodage hexadécimal
+- Exemple : `1a2b3c4d5e6f7a8b`
+
+## Statistiques
+
+Le système suit automatiquement :
+- Le nombre d'accès (hits)
+- La date du dernier accès
+- L'URL source originale
+- Les métadonnées JSON (accessible via CacheEntry.metadata_json)
+
+## Streaming progressif
+
+Les fichiers en cours de téléchargement sont automatiquement streamés dès que possible :
+- Téléchargement asynchrone en arrière-plan
+- Conversion FLAC progressive
+- Accès aux métadonnées dès le début du téléchargement
+        "#,
+        contact(
+            name = "PMOMusic",
+        ),
+        license(
+            name = "MIT",
+        ),
     )
 )]
 pub struct ApiDoc;