path: root/DOC_IMPORT_PRODUITS.md

# Import CSV Produits (Medusa)

## FR - Objectif
Importer des produits depuis un CSV dans Medusa en mode upsert (creation ou mise a jour) sur le champ `external_id`.

## FR - Prerequis
- Backend Medusa operationnel
- Dependances installees (`npm install` dans `backend/`)
- Fichier CSV present dans `backend/data/products-import.csv` (ou un autre chemin)

## FR - Commande rapide
Depuis `backend/` :
```
npm run import:products
```

Options:
```
node scripts/import-products.js --file ./data/products-import.csv --report ./data/import-report.json
node scripts/import-products.js --file ./data/products-import.csv --dry-run
node scripts/import-products.js --file ./data/products-import.csv --currency eur
```

## FR - Schema CSV
Colonnes minimales:
- `external_id` (obligatoire, cle d'upsert)
- `title` (obligatoire)
- `handle` (optionnel, genere depuis title si absent)
- `description` (optionnel)
- `thumbnail` (optionnel)
- `option_title` (optionnel, defaut: Taille)
- `option_value` (optionnel, defaut: variant_title)
- `variant_title` (optionnel, defaut: option_value)
- `variant_sku` (optionnel)
- `price_amount` (obligatoire, entier en centimes)
- `currency_code` (optionnel, defaut: eur)
- `inventory_quantity` (optionnel, defaut: 0)
- `manage_inventory` (optionnel, true/false)

Colonnes attributs (optionnelles, stockees dans `product.metadata`):
- `volume` (ex: 200ml, 500ml)
- `type_meche` (ex: bois, coton)
- `parfum` (ex: lavande, vanille)
- `couleur` (ex: blanche, bleue)
- `type_cire` (ex: soja, colza, abeille)

Ces attributs sont descriptifs (pas de variantes). Ils sont affiches sur la
fiche produit du storefront. Si une colonne est vide, l'attribut n'est pas affiche.

Exemple:
```
external_id,title,handle,description,thumbnail,option_title,option_value,variant_title,variant_sku,price_amount,currency_code,inventory_quantity,manage_inventory,volume,type_meche,parfum,couleur,type_cire
prod-001,Bougie Lavande,bougie-lavande,"Bougie artisanale a la lavande.",,Taille,200ml,200ml,SKU-BOU-LAV-200,1200,eur,50,true,200ml,coton,lavande,blanche,soja
```

## FR - Comportement
- Un produit est trouve par `external_id`.
- Si `external_id` existe: mise a jour du produit.
- Si `external_id` n'existe pas: creation du produit.
- Une ligne CSV = une variante. Regrouper plusieurs variantes avec le meme `external_id`.
- Une seule option produit est supportee dans ce script (ex: Taille).

## FR - Git flow (branche + push)
Nom de branche suggere: `feature/import-csv-produits`

### Creer et developper la feature
```
git flow feature start import-csv-produits
git status
git add -A
git commit -m "feat: attributs bougies (metadata) + import CSV"
git push -u origin feature/import-csv-produits
```

### Tester sur huitral (avant de finir la feature)
```
# Sur huitral
cd /var/www/lucien-sens-bon
git fetch origin
git checkout feature/import-csv-produits
git reset --hard origin/feature/import-csv-produits

# Dry-run (test sans ecriture en base)
docker compose run --rm backend npm run import:products -- --dry-run

# Import reel
docker compose run --rm backend npm run import:products

# Rebuild storefront (pour afficher les attributs metadata)
docker compose up -d --build storefront

# Verifier
curl -s http://localhost:9000/store/products | python3 -m json.tool | head -30
```

### Finir la feature et merger dans develop
```
# Sur le poste de dev
git flow feature finish import-csv-produits
git push origin develop
git push origin --delete feature/import-csv-produits
```

### Deployer develop sur huitral
```
# Sur huitral
cd /var/www/lucien-sens-bon
git fetch origin
git checkout develop
git reset --hard origin/develop
docker compose up -d --build storefront
```

## FR - Alternative : remettre la branche feature dans main (sans git-flow)
Si tu veux ramener le contenu de la feature vers `main` directement :
```
git checkout main
git merge feature/import-csv-produits
git push origin main
```

Si tu veux utiliser la branche distante directement :
```
git checkout main
git merge origin/feature/import-csv-produits
git push origin main
```

## FR - Cas courant: commit fait sur main avant la feature
Si un commit a ete fait sur `main` avant la creation de la feature, il faut le recuperer:
```
git log --oneline main -n 5
git cherry-pick <hash_du_commit>
```
Alternative si plusieurs commits:
```
git cherry-pick <hash1> <hash2>
```
Ou merger `main` (si votre process l'autorise):
```
git merge main
```

## FR - Troubleshoot git-flow
**Erreur**: `Fatal: Working tree contains unstaged changes. Aborting.`

Cause: git-flow exige un working tree propre.

Actions:
```
git status
git add -A
git commit -m "WIP: prepare import CSV"
git flow init -d
```

Alternative (mettre de cote):
```
git stash -u
git flow init -d
git stash pop
```

**Erreur**: `git: 'flow' is not a git command`

Installe git-flow:
```
sudo apt update
sudo apt install git-flow
```

---

## DE - Ziel
Produkte per CSV in Medusa importieren, mit Upsert per `external_id` (anlegen oder aktualisieren).

## DE - Voraussetzungen
- Medusa Backend laeuft
- Abhaengigkeiten installiert (`npm install` in `backend/`)
- CSV Datei in `backend/data/products-import.csv` (oder eigener Pfad)

## DE - Schnellstart
Aus `backend/`:
```
npm run import:products
```

Optionen:
```
node scripts/import-products.js --file ./data/products-import.csv --report ./data/import-report.json
node scripts/import-products.js --file ./data/products-import.csv --dry-run
node scripts/import-products.js --file ./data/products-import.csv --currency eur
```

## DE - CSV Schema
Pflichtspalten:
- `external_id` (Pflicht, Upsert-Schluessel)
- `title` (Pflicht)
- `handle` (optional, wird aus title erzeugt)
- `description` (optional)
- `thumbnail` (optional)
- `option_title` (optional, Default: Taille)
- `option_value` (optional, Default: variant_title)
- `variant_title` (optional, Default: option_value)
- `variant_sku` (optional)
- `price_amount` (Pflicht, integer in Cent)
- `currency_code` (optional, Default: eur)
- `inventory_quantity` (optional, Default: 0)
- `manage_inventory` (optional, true/false)

Attribut-Spalten (optional, in `product.metadata` gespeichert):
- `volume` (z.B. 200ml, 500ml)
- `type_meche` (z.B. bois, coton)
- `parfum` (z.B. lavande, vanille)
- `couleur` (z.B. blanche, bleue)
- `type_cire` (z.B. soja, colza, abeille)

Diese Attribute sind beschreibend (keine Varianten). Sie werden auf der
Produktseite im Storefront angezeigt. Leere Spalten werden nicht angezeigt.

Beispiel:
```
external_id,title,handle,description,thumbnail,option_title,option_value,variant_title,variant_sku,price_amount,currency_code,inventory_quantity,manage_inventory,volume,type_meche,parfum,couleur,type_cire
prod-001,Bougie Lavande,bougie-lavande,"Bougie artisanale a la lavande.",,Taille,200ml,200ml,SKU-BOU-LAV-200,1200,eur,50,true,200ml,coton,lavande,blanche,soja
```

## DE - Verhalten
- Produkt wird per `external_id` gefunden.
- Wenn `external_id` existiert: Produkt wird aktualisiert.
- Wenn `external_id` nicht existiert: Produkt wird angelegt.
- Eine CSV Zeile = eine Variante. Mehrere Varianten mit gleichem `external_id` gruppieren.
- Nur eine Produktoption ist in diesem Script vorgesehen (z.B. Taille).

## DE - Git flow (Branch + Push)
Branch Vorschlag: `feature/import-csv-produits`

### Feature erstellen und entwickeln
```
git flow feature start import-csv-produits
git status
git add -A
git commit -m "feat: Kerzen-Attribute (metadata) + CSV Import"
git push -u origin feature/import-csv-produits
```

### Auf huitral testen (vor Feature-Abschluss)
```
# Auf huitral
cd /var/www/lucien-sens-bon
git fetch origin
git checkout feature/import-csv-produits
git reset --hard origin/feature/import-csv-produits

# Dry-run (Test ohne DB-Schreibvorgang)
docker compose run --rm backend npm run import:products -- --dry-run

# Echter Import
docker compose run --rm backend npm run import:products

# Storefront neu bauen (fuer Metadata-Attribute)
docker compose up -d --build storefront
```

### Feature abschliessen und in develop mergen
```
# Auf dem Entwicklungsrechner
git flow feature finish import-csv-produits
git push origin develop
git push origin --delete feature/import-csv-produits
```

### Develop auf huitral deployen
```
# Auf huitral
cd /var/www/lucien-sens-bon
git fetch origin
git checkout develop
git reset --hard origin/develop
docker compose up -d --build storefront
```

## DE - Alternative: Feature-Branch direkt in main (ohne git-flow)
Wenn du den Feature-Branch direkt nach `main` holen willst:
```
git checkout main
git merge feature/import-csv-produits
git push origin main
```

Wenn du direkt den Remote-Branch verwenden willst:
```
git checkout main
git merge origin/feature/import-csv-produits
git push origin main
```

## DE - Typisch: Commit auf main vor der Feature
Wenn ein Commit bereits auf `main` erstellt wurde, muss er in die Feature:
```
git log --oneline main -n 5
git cherry-pick <commit_hash>
```
Alternative fuer mehrere Commits:
```
git cherry-pick <hash1> <hash2>
```
Oder `main` mergen (falls erlaubt):
```
git merge main
```

## DE - Troubleshooting git-flow
**Fehler**: `Fatal: Working tree contains unstaged changes. Aborting.`

Ursache: git-flow braucht ein sauberes Working Tree.

Schritte:
```
git status
git add -A
git commit -m "WIP: prepare import CSV"
git flow init -d
```

Alternative (parken):
```
git stash -u
git flow init -d
git stash pop
```

**Fehler**: `git: 'flow' is not a git command`

git-flow installieren:
```
sudo apt update
sudo apt install git-flow
```