Upgrade Guides - Products Manager - Products Manager Docs

Procédures de migration pas-à-pas pour chaque version majeure de Products Manager.

Avant de commencer

Quel que soit le chemin de migration, appliquer systématiquement ces étapes préliminaires :

Sauvegarde complète : dump de toutes les bases de données PostgreSQL + export S3/MinIO
Snapshot Docker : docker commit des containers en production avant toute modification
Lire les breaking changes : consulter cette page pour chaque version intermédiaire si vous sautez plusieurs versions
Tester sur staging : déployer et valider sur l'environnement de staging avant la production
Fenêtre de maintenance : prévoir une fenêtre de maintenance pour les migrations avec breaking changes

# Sauvegarde rapide toutes les DBs
for DB in catalog analytics code2asin core imports media suppliers; do
  pg_dump $DB_URL > backup_${DB}_$(date +%Y%m%d).sql
done

v5.6 → v5.7

Durée estimée : 10 minutes — Downtime : aucun (migrations non destructives)

Breaking changes

Aucun breaking change dans cette version.

Nouvelles variables d'environnement (optionnelles)

# Pondération fusion hybride search (0.0 = full sémantique, 1.0 = full lexical, défaut : 0.7)
SEARCH_HYBRID_ALPHA=0.7

Procédure

# 1. Mettre à jour le code
git pull origin main
git checkout v5.7.0

# 2. Appliquer les migrations Alembic
cd api && alembic upgrade head

# 3. Redémarrer les services
docker-compose up -d --build

# 4. Vérifier les logs
docker-compose logs -f api worker

Notes de migration

Repricing Engine : les règles existantes (v5.6) fonctionnent sans modification. Les nouvelles stratégies bundle_margin et channel_specific sont optionnelles.
Synchronisation différentielle : activée automatiquement pour tous les connecteurs après redémarrage. Aucune action requise.
Recherche hybride : activée par défaut. Pour revenir au comportement v5.6 (full lexical), définir SEARCH_HYBRID_ALPHA=1.0.

v5.x → v5.7 (saut de plusieurs versions)

Si vous êtes sur une version v5.x antérieure à v5.6, appliquez les upgrades dans l'ordre séquentiel — ne jamais sauter de version.

Ordre obligatoire : v5.0 → v5.1 → v5.2 → v5.3 → v5.4 → v5.5 → v5.6 → v5.7

Points d'attention par version

Version	Point critique
v5.0	Migration tenant obligatoire — voir section dédiée ci-dessous
v5.2	Nouveau schéma infra DB — PostgreSQL bare metal + PgBouncer recommandés
v5.3	Nouveau `docker-compose.yml` self-hosted — remplacer l'ancien fichier
v5.6	Nouvelles tables `repricing_rules` et `repricing_history` — migration Alembic requise
v5.7	Recherche hybride activée par défaut — voir `SEARCH_HYBRID_ALPHA` si comportement à ajuster

Pour chaque saut de version, exécuter :

git checkout vX.Y.0
cd api && alembic upgrade head
docker-compose up -d --build
# Valider les logs et les health checks avant de passer à la version suivante

v4.9.x → v5.0 (migration majeure — Tenant Management)

Il s'agit de la migration la plus importante du cycle de vie de Products Manager. Le passage à v5.0 introduit l'architecture multi-tenant SaaS et nécessite une préparation rigoureuse.

Durée estimée : 2 à 4 heures selon le volume de données — Downtime : requis

1. Prérequis

# Sauvegarde complète obligatoire
pg_dump $DATABASE_URL > backup_pre_v5_$(date +%Y%m%d_%H%M).sql
docker-compose down
docker commit $(docker ps -aq) backup-pre-v5

2. Création du tenant initial

Les données existantes doivent être rattachées à un tenant. Un script de migration est fourni :

# Créer le tenant "default" pour les données existantes
python scripts/migrate_to_tenant.py --tenant-name "Default" --tenant-slug "default"

Ce script crée l'entrée dans la table tenants et met à jour toutes les foreign keys des tables existantes.

3. Migration des utilisateurs existants

# Associer tous les utilisateurs existants au tenant default
python scripts/migrate_users_to_tenant.py --tenant-slug "default"

4. Assignation du plan

Assigner temporairement le plan "enterprise" au tenant initial pour éviter les restrictions de quota pendant la migration :

python scripts/assign_plan.py --tenant-slug "default" --plan enterprise --temporary

5. Nouvelles variables d'environnement

Ajouter obligatoirement avant le démarrage :

# Stripe Billing (requis même en self-hosted pour le module tenant)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Plan par défaut pour les nouveaux tenants
TENANT_DEFAULT_PLAN=starter

6. Breaking changes

Tous les endpoints API ajoutent désormais le contexte tenant. Les appels API directs doivent inclure le header X-Tenant-ID ou utiliser des tokens JWT tenant-scoped.

Endpoints modifiés : /api/products/*, /api/suppliers/*, /api/imports/*, /api/media/*, /api/connectors/*

# Avant v5.0
GET /api/products/

# Depuis v5.0
GET /api/products/
Headers: X-Tenant-ID: tenant_slug
# ou via JWT avec claim tenant_id

7. Procédure de déploiement

git checkout v5.0.0
cd api && alembic upgrade head
docker-compose up -d --build
# Exécuter les scripts de migration dans l'ordre
python scripts/migrate_to_tenant.py --tenant-name "Default" --tenant-slug "default"
python scripts/migrate_users_to_tenant.py --tenant-slug "default"
python scripts/assign_plan.py --tenant-slug "default" --plan enterprise --temporary

8. Rollback v5.0

docker-compose down
# Restaurer le snapshot Docker pré-migration
docker restore backup-pre-v5
# Restaurer la DB
psql $DATABASE_URL < backup_pre_v5_*.sql
# Redémarrer sur v4.9.x
git checkout v4.9.6
docker-compose up -d

v3.x → v4.0 (architecture EAN-centric)

La v4.0 a introduit une refonte majeure du schéma de données autour de l'EAN comme identifiant métier unique.

Durée estimée : 1 à 3 heures — Downtime : requis

Breaking changes

products.sku supprimé — utiliser supplier_products.supplier_sku
products.supplier_id supprimé — utiliser la junction table supplier_products
products.ean : maintenant NOT NULL et UNIQUE (8 ou 13 chiffres)
Architecture Multi-DB : passage de 1 à 7 bases PostgreSQL séparées

Procédure

# 1. Backup
pg_dump $DATABASE_URL > backup_pre_v4_$(date +%Y%m%d).sql

# 2. Migrer les produits sans EAN (script fourni)
python scripts/migrate_products_without_ean.py --report  # audit d'abord
python scripts/migrate_products_without_ean.py --apply   # puis application

# 3. Mettre à jour le code applicatif
# Remplacer product.sku → supplier_product.supplier_sku
# Remplacer WHERE sku = ? → WHERE ean = ?

# 4. Déployer
git checkout v4.0.0
alembic upgrade head
docker-compose up -d --build

Nouvelles variables d'environnement (multi-DB)

DATABASE_URL=postgresql://...staging_db_catalog
DB_ANALYTICS_URL=postgresql://...staging_db_analytics
DB_CATALOG_URL=postgresql://...staging_db_catalog
DB_CODE2ASIN_URL=postgresql://...staging_db_code2asin
DB_CORE_URL=postgresql://...staging_db_core
DB_IMPORTS_URL=postgresql://...staging_db_imports
DB_MEDIA_URL=postgresql://...staging_db_media
DB_SUPPLIERS_URL=postgresql://...staging_db_suppliers

Procédure de rollback générale

En cas de problème après un upgrade, procédure standard :

# 1. Arrêter les services
docker-compose down

# 2. Revenir à la version précédente via Alembic
cd api && alembic downgrade -1
# ou revenir à une révision spécifique
alembic downgrade <revision_id>

# 3. Restaurer le snapshot Docker si nécessaire
docker restore backup-pre-upgrade

# 4. Restaurer S3/MinIO si des fichiers ont été modifiés
aws s3 sync s3://backup-bucket/pre-upgrade/ s3://production-bucket/

# 5. Redémarrer sur l'ancienne version
git checkout vX.Y.Z
docker-compose up -d --build

Important : pour les migrations v5.0 (tenant) et v4.0 (EAN-centric), le rollback est complexe. Toujours tester sur staging d'abord et conserver les snapshots Docker jusqu'à validation complète en production.

Ressources associées

Nouveautés v5.7 : /docs/releases/whats-new
Historique complet : /docs/releases/changelog
Configuration des connecteurs : /docs/features/connectors