xpeditis2.0/WINDOWS-INSTALLATION.md

# 🪟 Installation sur Windows - Xpeditis

## Problème avec npm Workspaces sur Windows

Sur Windows, les workspaces npm peuvent rencontrer des problèmes de symlinks (`EISDIR` error). Voici la solution.

---

## ✅ Solution : Installation Séparée par App

Au lieu d'utiliser `npm install` à la racine, installez les dépendances dans chaque app séparément.

### Étape 1 : Supprimer le node_modules racine (si existe)

```bash
# Si node_modules existe à la racine
rm -rf node_modules
```

### Étape 2 : Installer les dépendances Backend

```bash
cd apps/backend
npm install
cd ../..
```

**Durée** : 2-3 minutes
**Packages installés** : ~50 packages NestJS, TypeORM, etc.

### Étape 3 : Installer les dépendances Frontend

```bash
cd apps/frontend
npm install
cd ../..
```

**Durée** : 2-3 minutes
**Packages installés** : ~30 packages Next.js, React, Tailwind, etc.

### Étape 4 : Installer les dépendances racine (optionnel)

```bash
npm install --no-workspaces
```

**Packages installés** : prettier, typescript (partagés)

---

## ✅ Vérification de l'Installation

### Vérifier Backend

```bash
cd apps/backend

# Vérifier que node_modules existe
ls node_modules

# Vérifier des packages clés
ls node_modules/@nestjs
ls node_modules/typeorm
ls node_modules/pg

# Essayer de démarrer
npm run dev
```

**Attendu** : Le serveur démarre sur le port 4000

### Vérifier Frontend

```bash
cd apps/frontend

# Vérifier que node_modules existe
ls node_modules

# Vérifier des packages clés
ls node_modules/next
ls node_modules/react
ls node_modules/tailwindcss

# Essayer de démarrer
npm run dev
```

**Attendu** : Le serveur démarre sur le port 3000

---

## 🚀 Démarrage Après Installation

### 1. Démarrer l'infrastructure Docker

```bash
docker-compose up -d
```

### 2. Configurer l'environnement

```bash
# Backend
cp apps/backend/.env.example apps/backend/.env

# Frontend
cp apps/frontend/.env.example apps/frontend/.env
```

### 3. Démarrer le Backend

```bash
cd apps/backend
npm run dev
```

**URL** : http://localhost:4000/api/v1/health

### 4. Démarrer le Frontend (nouveau terminal)

```bash
cd apps/frontend
npm run dev
```

**URL** : http://localhost:3000

---

## 📝 Scripts Modifiés pour Windows

Comme les workspaces ne fonctionnent pas, utilisez ces commandes :

### Backend

```bash
# Au lieu de: npm run backend:dev
cd apps/backend && npm run dev

# Au lieu de: npm run backend:test
cd apps/backend && npm test

# Au lieu de: npm run backend:build
cd apps/backend && npm run build
```

### Frontend

```bash
# Au lieu de: npm run frontend:dev
cd apps/frontend && npm run dev

# Au lieu de: npm run frontend:test
cd apps/frontend && npm test

# Au lieu de: npm run frontend:build
cd apps/frontend && npm run build
```

### Les deux en parallèle

**Option 1** : Deux terminaux

Terminal 1 :
```bash
cd apps/backend
npm run dev
```

Terminal 2 :
```bash
cd apps/frontend
npm run dev
```

**Option 2** : PowerShell avec Start-Process

```powershell
# Backend
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd apps/backend; npm run dev"

# Frontend
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd apps/frontend; npm run dev"
```

---

## 🔧 Alternative : Utiliser pnpm ou yarn

Si npm continue à poser problème, utilisez pnpm (meilleur support Windows) :

### Avec pnpm

```bash
# Installer pnpm globalement
npm install -g pnpm

# Installer les dépendances
pnpm install

# Démarrer backend
pnpm --filter backend dev

# Démarrer frontend
pnpm --filter frontend dev
```

### Avec yarn

```bash
# Installer yarn globalement
npm install -g yarn

# Installer les dépendances
yarn install

# Démarrer backend
yarn workspace backend dev

# Démarrer frontend
yarn workspace frontend dev
```

---

## ✅ Checklist d'Installation Windows

- [ ] Docker Desktop installé et démarré
- [ ] Node.js v20+ installé
- [ ] `cd apps/backend && npm install` terminé
- [ ] `cd apps/frontend && npm install` terminé
- [ ] `docker-compose up -d` exécuté
- [ ] Containers PostgreSQL et Redis en cours d'exécution
- [ ] `.env` files copiés
- [ ] Backend démarre sur port 4000
- [ ] Frontend démarre sur port 3000
- [ ] Health endpoint répond : http://localhost:4000/api/v1/health

---

## 🐛 Dépannage Windows

### Erreur : EBUSY (resource busy or locked)

**Cause** : Fichiers verrouillés par un processus Windows (antivirus, Windows Defender, etc.)

**Solutions** :
1. Fermer VSCode et tous les terminals
2. Désactiver temporairement l'antivirus
3. Exclure le dossier `node_modules` de Windows Defender
4. Réessayer l'installation

### Erreur : EISDIR (illegal operation on directory)

**Cause** : Windows ne supporte pas bien les symlinks npm workspaces

**Solution** : Utiliser l'installation séparée (cette page)

### Erreur : EPERM (operation not permitted)

**Cause** : Permissions insuffisantes

**Solutions** :
1. Exécuter PowerShell/CMD en tant qu'administrateur
2. Ou utiliser l'installation séparée (pas besoin d'admin)

### Backend ne démarre pas - "Cannot find module"

**Cause** : node_modules manquant ou incomplet

**Solution** :
```bash
cd apps/backend
rm -rf node_modules package-lock.json
npm install
```

### Frontend ne démarre pas - "Cannot find module 'next'"

**Cause** : node_modules manquant ou incomplet

**Solution** :
```bash
cd apps/frontend
rm -rf node_modules package-lock.json
npm install
```

### Frontend build fail - "EISDIR: illegal operation on directory, readlink"

**Cause** : Next.js rencontre un problème avec les symlinks sur Windows lors du build

**Erreur complète** :
```
Error: EISDIR: illegal operation on a directory, readlink 'D:\xpeditis2.0\apps\frontend\node_modules\next\dist\pages\_app.js'
```

**Solutions** :

**Option 1** : Utiliser le mode développement (recommandé pour le développement)
```bash
cd apps/frontend
npm run dev  # Fonctionne sans problème
```

**Option 2** : Utiliser WSL2 pour le build de production
```bash
# Dans WSL2
cd /mnt/d/xpeditis2.0/apps/frontend
npm run build  # Fonctionne correctement
```

**Option 3** : Build depuis PowerShell avec mode développeur activé
```powershell
# Activer le mode développeur Windows (une seule fois)
# Paramètres > Mise à jour et sécurité > Pour les développeurs > Mode développeur

# Ensuite:
cd apps/frontend
npm run build
```

**Note** : Pour le développement quotidien, utilisez `npm run dev` qui n'a pas ce problème. Le build de production n'est nécessaire que pour le déploiement.

---

## 💡 Recommandations pour Windows

### 1. Utiliser PowerShell Core (v7+)

Plus moderne et meilleur support des outils Node.js :
- [Télécharger PowerShell](https://github.com/PowerShell/PowerShell)

### 2. Utiliser Windows Terminal

Meilleure expérience terminal :
- [Télécharger Windows Terminal](https://aka.ms/terminal)

### 3. Considérer WSL2 (Windows Subsystem for Linux)

Pour une expérience Linux native sur Windows :

```bash
# Installer WSL2
wsl --install

# Installer Ubuntu
wsl --install -d Ubuntu

# Utiliser WSL2 pour le développement
cd /mnt/d/xpeditis2.0
npm install  # Fonctionne comme sur Linux
```

### 4. Exclure node_modules de l'antivirus

Pour améliorer les performances :

**Windows Defender** :
1. Paramètres Windows > Mise à jour et sécurité > Sécurité Windows
2. Protection contre les virus et menaces > Gérer les paramètres
3. Exclusions > Ajouter une exclusion > Dossier
4. Ajouter : `D:\xpeditis2.0\node_modules`
5. Ajouter : `D:\xpeditis2.0\apps\backend\node_modules`
6. Ajouter : `D:\xpeditis2.0\apps\frontend\node_modules`

---

## ✅ Installation Réussie !

Une fois les dépendances installées dans chaque app :

```bash
# Backend
cd apps/backend
npm run dev
# Visiter: http://localhost:4000/api/docs

# Frontend (nouveau terminal)
cd apps/frontend
npm run dev
# Visiter: http://localhost:3000
```

**Tout fonctionne ? Excellent ! 🎉**

Passez à [NEXT-STEPS.md](NEXT-STEPS.md) pour commencer le développement.

---

## 📞 Besoin d'Aide ?

Si les problèmes persistent :

1. Vérifier Node.js version : `node --version` (doit être v20+)
2. Vérifier npm version : `npm --version` (doit être v10+)
3. Essayer avec pnpm : `npm install -g pnpm && pnpm install`
4. Utiliser WSL2 pour une expérience Linux
5. Consulter [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md)

---

*Xpeditis - Installation Windows*
*Solution pour npm workspaces sur Windows*