QwikPress - Session Complète 29/12/2024

Date : 29 décembre 2024 Durée : Session longue (plusieurs heures) Objectif : Refactoring architecture + préparation déploiement multi-instance

RÉSUMÉ EXÉCUTIF

Session majeure de refactoring de QwikPress pour :

1. Unifier le storage (local + Supabase)
2. Sécuriser l'architecture (credentials isolés dans plugins)
3. Préparer le multi-instance (un QwikPress pour chaque projet)
4. Implémenter la synchronisation Cloud ↔ Local

1. ARCHITECTURE PLUGIN/SHAREDMAP

Problème résolu

Les credentials Supabase étaient accessibles dans plusieurs fichiers, risque de fuite vers le frontend.

Solution implémentée

Plugin@data.ts (SEUL accès aux credentials)
       ↓
sharedMap.set('storage', StorageService)
       ↓
server$ accède via this.sharedMap.get('storage')

Fichiers modifiés

• src/routes/plugin@data.ts - Refactorisé pour isolation credentials
• src/services/storage/supabase-storage.service.ts - Reçoit client injecté
• src/services/data/supabase-data.service.ts - Deprecated, redirige vers storage

2. UNIFICATION STORAGE

Problème résolu

Deux systèmes parallèles : IDataService (ancien, 56 fichiers) et StorageService (nouveau).

Solution implémentée

• StorageService = Interface unique
• DataServiceAdapter = Compatibilité ancien code
• Les deux injectés dans sharedMap

Fichiers créés

• src/services/storage/data-service-adapter.ts - Adaptateur IDataService → StorageService
• src/services/storage/index.ts - Exports unifiés

Interface StorageService (32 méthodes)

// Pages
getPage, getPageBySlug, getAllPages, getChildPages, savePage, deletePage, slugExists

// Config
getConfig, saveConfig

// Connectors
getConnector, getAllConnectors, saveConnector, deleteConnector

// Common Modules
getCommonModule, getAllCommonModules, saveCommonModule, deleteCommonModule

// Redirections
getRedirection, getAllRedirections, saveRedirection, deleteRedirection
getRedirectionConfig, saveRedirectionConfig, getRedirectionLogs, addRedirectionLog

// Media
listMedia, getMedia, uploadMedia, deleteMedia, getMediaUrl

3. MEDIAREF - PATTERN IMAGES

Problème résolu

Images passées comme string = le frontend découvre la taille = CLS, mauvais SSR.

Solution implémentée

interface MediaRef {
  src: string;
  width: number;
  height: number;
  ratio: number;
  mimeType: string;
  alt: string;  // Obligatoire accessibilité
  dominantColor?: string;
  srcset?: string;
}

Helpers créés

• createMediaRef() - Créer un MediaRef
• getResizedUrl() - URL avec params resize
• getResizedDimensions() - Calcul dimensions
• getResizedMediaRef() - MediaRef redimensionné

Fichier créé

• src/types/media.ts - Types et helpers médias

4. SYNCHRONISATION CLOUD ↔ LOCAL

Fonctionnalités

1. Export : Télécharger archive ZIP complète du storage
2. Import : Restaurer archive vers storage (avec backup auto)
3. Pull : Cloud → Local
4. Push : Local → Cloud (backup auto si pas vide)

Fichiers créés

• src/services/storage/sync.service.ts - Service de sync
• src/routes/api/sync/export/index.ts - API GET téléchargement ZIP
• src/routes/api/sync/import/index.ts - API POST upload ZIP

API Endpoints

GET  /api/sync/export              → Télécharger ZIP
GET  /api/sync/export?includeMedias=false
POST /api/sync/import              → Importer ZIP (backup auto)

5. DÉPLOIEMENT MULTI-INSTANCE

Concept

QwikPress = moteur réutilisable pour tous les projets :

• qwikpress:needfinder → Dashboard NeedFinder
• qwikpress:spacemessage → Site SpaceMessage
• etc.

Isolation Supabase (CRITIQUE)

Chaque projet a son propre SCHÉMA et BUCKET :

Schéma: qwikpress_needfinder
Bucket: medias-needfinder

Schéma: qwikpress_spacemessage
Bucket: medias-spacemessage

Aucune interférence possible entre projets.

Fichiers créés

• conf.prod.gouroubleu.yml - Config déploiement PROD
• conf.dev.gouroubleu.yml - Config déploiement DEV
• conf.template.gouroubleu.yml - Template multi-instance
• Dockerfile - Multi-stage optimisé (Alpine)
• src/routes/api/health/index.ts - Endpoint healthcheck
• scripts/supabase-new-project.sql - Script création schéma

Ports assignés

Commandes

mets en prod qwikpress:needfinder
mets en dev qwikpress:spacemessage

6. VERSIONING ET SWAP

Concept

Avec l'isolation par schéma, on peut avoir plusieurs versions :

qwikpress_needfinder       → Production
qwikpress_needfinder_v2    → Staging
qwikpress_needfinder_backup → Sauvegarde

Swap instantané

Changer SUPABASE_SCHEMA dans l'environnement = switch de version.

7. MODIFICATIONS CLAUDE.MD

Sections ajoutées/mises à jour :

• Architecture Storage plugin/sharedMap
• Médias (MediaRef obligatoire)
• Synchronisation Cloud ↔ Local
• Déploiement multi-instance
• Versioning et Swap

FICHIERS MODIFIÉS/CRÉÉS (RÉCAPITULATIF)

Créés

Modifiés

PROCHAINES ÉTAPES

1. Tester le container sur dev-portainer
2. Créer le schéma Supabase pour un premier projet (needfinder ?)
3. Déployer une première instance : mets en prod qwikpress:needfinder
4. Valider la synchronisation export/import

NOTES TECHNIQUES

Pattern Error-First (rappel)

// ✅ BON
const result = await something();
if (!result) {
  return { success: false, error: 'Message' };
}
return { success: true, data: result };

// ❌ INTERDIT
try { ... } catch { ... }

Schéma Supabase par projet

qwikpress_{slug}/
├── config (1 ligne)
├── pages
├── common_modules
├── connectors
├── redirections
├── redirection_config
├── redirection_logs
└── medias (métadonnées)

Variables d'environnement clés

SITE_SLUG=needfinder
SUPABASE_SCHEMA=qwikpress_needfinder  # Auto si non défini
SUPABASE_BUCKET=medias-needfinder      # Auto si non défini
DATA_MODE=supabase                     # ou 'file'

Session terminée avec succès. QwikPress est prêt pour le multi-instance !