Médiathèque

Vue D'Ensemble

La médiathèque est le magasin partagé de ressources d'organisation pour les workflows de contenu. Elle est disponible depuis:

• /dashboard/content/media

Les ressources média sont bornées par organisation. Elles sont utilisées par l'éditeur de page, Page AI et les workflows de contenu qui ont besoin d'URL durables pour images, vidéos, audio, PDF ou autres fichiers supportés.

Rôle CMS

Les médias sont la couche de ressources du CMS. Elle possède les fichiers binaires, miniatures générées, images générées, URL publiques, l'application des quotas et l'organisation en dossiers. Les données CMS structurées peuvent référencer des URL média, et les pages ou sections peuvent lier des champs média à des ressources sélectionnées, mais la ressource elle-même reste dans la médiathèque.

Utilisez les médias lorsqu'un workflow a besoin d'un fichier stocké. Utilisez les données CMS pour le contenu typé, les sections pour le layout réutilisable et les documents de page pour la composition.

Modèle De Données

Les médias utilisent deux tables système:

• media_folders
• media_assets

Les ressources stockent:

• organization_id propriétaire
• folder_id optionnel
• nom d'affichage et nom d'affichage normalisé
• type MIME et kind de ressource
• taille en octets
• bucket de stockage objet et clé de stockage
• URL publique
• métadonnées optionnelles de miniature
• métadonnées de téléversement ou génération

La propriété des dossiers est bornée à la même organisation que la ressource. Les actions serveur doivent rejeter les mutations de dossiers ou ressources inter-organisations.

Stockage

Le stockage média utilise un petit contrat fournisseur. Le chemin hébergé par défaut reste Supabase storage, et les déploiements auto-hébergés peuvent utiliser un fournisseur compatible S3 comme MinIO, AWS S3 ou R2. Les clés de stockage suivent la convention de chemin d'organisation:

organizations/<organizationId>/media/<asset>
organizations/<organizationId>/media/thumbnails/<assetId>.webp
global/site-variables/<asset>.<content-hash>.<ext>

La base stocke publicUrl parce que les pages publiées et le contenu rendu par le CMS ont besoin d'URL publiques stables. Les URL média existantes ne sont pas réécrites lorsque STORAGE_PROVIDER change; les opérateurs doivent donc garder les anciennes URL publiques joignables ou prévoir une migration ultérieure.

Sélection fournisseur:

• STORAGE_PROVIDER=supabase|s3
• STORAGE_PROVIDER vide sélectionne Supabase si les variables Supabase sont présentes
• STORAGE_PROVIDER vide sélectionne S3 si l'ensemble de variables compatibles S3 est complet

Le stockage Supabase requiert:

• NEXT_PUBLIC_SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY

Le stockage compatible S3 requiert:

• STORAGE_MEDIA_BUCKET
• STORAGE_PUBLIC_BASE_URL
• S3_ENDPOINT
• S3_REGION
• S3_ACCESS_KEY_ID
• S3_SECRET_ACCESS_KEY
• S3_FORCE_PATH_STYLE

La médiathèque écrit dans le bucket média configuré, et les uploads de logo d'organisation utilisent le bucket organization-logos. Lorsque l'URL publique de base est l'origine app ou CDN, les deux préfixes de bucket doivent être routés vers le stockage objet compatible S3 avant le repli vers l'app.

Le script seed téléverse les ressources par défaut de variables globales de site, comme le logo et l'image sociale, dans le bucket média configuré avant de publier l'entrée de données globales site-variables/main. Les URL de ressources personnalisées existantes sont préservées; seuls les anciens défauts seed ou les anciennes URL de stockage possédées par le seed sont réparés.

Voir Configuration de l'environnement de déploiement pour les étapes de setup fournisseur.

Types De Ressources Supportés

Le kind de ressource est dérivé du type MIME:

• image
• video
• audio
• pdf
• document
• archive
• other

Les ressources visuelles peuvent recevoir des miniatures WebP. Les miniatures manquantes sont renseignées opportunément lors du listing média si la ressource est éligible et que le délai de nouvelle tentative le permet.

Permissions

Les opérations média sont bornées par organisation.

Accès typique:

• les membres d'organisation peuvent lister/lire les ressources
• les managers/admins/propriétaires peuvent téléverser, éditer, déplacer et supprimer des ressources
• les superadmins peuvent opérer globalement lorsque l'autorisation sous-jacente le permet

Toutes les actions serveur doivent inclure le périmètre d'organisation active. La visibilité navigation ou UI ne remplace pas l'autorisation serveur.

Quotas

Les quotas de téléversement viennent des limites runtime du plan de facturation. Les défauts sont définis dans la configuration de facturation et peuvent être surchargés via les données de plan:

Les contrôles de quota ont lieu avant la persistance. Les images générées par IA utilisent le même chemin de quota que les uploads manuels, donc la génération IA ne peut pas contourner les limites du plan.

UX Dashboard

Le dashboard média prend en charge:

• navigation par dossiers
• téléversement
• renommage et édition de métadonnées
• suppression
• aperçus adaptés au kind
• tri déterministe
• affichage de miniatures pour les ressources visuelles
• insertion d'images générées depuis les workflows de contenu supportés

Gardez l'interface dense et opérationnelle. La médiathèque est une bibliothèque de travail, pas une galerie marketing.

Intégration Page Builder

L'éditeur de page peut lier des champs média à des ressources existantes de l'organisation. Les bindings gardent le publicUrl original de la ressource afin que les pages publiées résolvent le même fichier que celui sélectionné dans le picker.

Page AI peut générer au plus une image pour un prompt qui demande un média ou implique fortement un visuel riche de landing page. L'image générée est persistée par le pipeline médiathèque puis liée à un champ de section générée compatible comme heroImage.

Les pages publiques globales peuvent utiliser des ressources générées depuis la médiathèque privée de l'organisation active parce que l'URL stockée est publique. Si aucune organisation active ou permission média n'est disponible, la génération d'image est ignorée avec un avertissement et le brouillon de page réussit quand même.

Pipeline De Miniatures

La génération de miniature:

• télécharge la ressource visuelle source
• convertit en WebP
• téléverse dans le bucket media sous le chemin de miniatures
• stocke l'URL et les métadonnées de stockage de miniature sur media_assets
• enregistre les métadonnées d'échec en cas d'erreur de conversion ou upload

Les échecs de miniature ne doivent pas bloquer le listing ni le rendu de la ressource originale. Le cooldown de retry évite les tentatives coûteuses répétées sur la même source cassée.

Génération D'Images IA

La génération d'images est gardée par:

• OPENAI_API_KEY
• OPENAI_IMAGE_GENERATION_ENABLED
• le réglage de site géré media-image-generation-enabled
• permissions et quotas média

Les images générées utilisent le modèle configuré via OPENAI_IMAGE_MODEL et sont sauvegardées comme ressources média WebP.

Points D'Entrée Serveur

Fichiers clés:

• src/blocks/dashboard/content/media/index.tsx
• src/lib/server/actions/media/media-library-actions.ts
• src/lib/server/actions/media/media-library-permissions.ts
• src/lib/server/services/media/media-asset-storage.ts
• src/lib/server/services/media/media-asset-thumbnails.ts
• src/lib/server/services/media/media-image-asset-generation.ts
• src/lib/server/services/media/media-quotas.ts

Notes Opérationnelles

• Ne stockez pas les binaires média dans Postgres.
• N'utilisez pas d'URL privée pour les ressources de pages publiées sauf si le runtime implémente aussi le renouvellement d'URL signées.
• Ne comptez pas les miniatures générées dans le quota d'upload utilisateur.
• Ne laissez pas une organisation sélectionner, muter ou supprimer le dossier ou la ressource d'une autre organisation.
• Gardez les clés service-role Supabase et les identifiants S3 server-only.

Validation

Checks utiles après des changements média:

bun test src/lib/server/services/media/media-mappers.test.ts
bun test src/lib/server/services/media/media-quotas.test.ts
bun test src/lib/server/services/media/media-asset-storage.test.ts
bun test src/lib/server/services/media/media-asset-thumbnails.test.ts
bun run check
bunx tsc --noEmit