xpeditis2.0/docs/installation/START-HERE.md

# 🚀 START HERE - Xpeditis MVP

## ✅ Sprint 0 Complete!

Tout le code et la configuration sont prêts. Suivez ces étapes pour démarrer.

---

## 📋 Étape par Étape (10 minutes)

### 1️⃣ Installer les Dépendances (5 min)

⚠️ **IMPORTANT pour Windows** : Les workspaces npm ne fonctionnent pas bien sur Windows.
Utilisez cette commande pour installer dans chaque app séparément :

```bash
# Option A: Script automatique
npm run install:all

# Option B: Manuel (recommandé si Option A échoue)
# 1. Racine
npm install

# 2. Backend
cd apps/backend
npm install
cd ../..

# 3. Frontend
cd apps/frontend
npm install
cd ../..
```

**Durée**: 3-5 minutes
**Packages**: ~80 packages au total

### 2️⃣ Démarrer Docker (1 min)

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

**Vérifier** :
```bash
docker-compose ps
# Doit afficher postgres et redis "Up (healthy)"
```

### 3️⃣ Configurer l'Environnement (30 sec)

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

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

✅ **Les valeurs par défaut fonctionnent** - pas besoin de modifier !

### 4️⃣ Démarrer le Backend (1 min)

```bash
# Option A: Depuis la racine
npm run backend:dev

# Option B: Depuis apps/backend
cd apps/backend
npm run dev
```

**Attendu** :
```
╔═══════════════════════════════════════╗
║   🚢 Xpeditis API Server Running     ║
║   API: http://localhost:4000/api/v1  ║
║   Docs: http://localhost:4000/api/docs  ║
╚═══════════════════════════════════════╝
```

**Vérifier** : http://localhost:4000/api/v1/health

### 5️⃣ Démarrer le Frontend (1 min) - Nouveau Terminal

```bash
# Option A: Depuis la racine
npm run frontend:dev

# Option B: Depuis apps/frontend
cd apps/frontend
npm run dev
```

**Attendu** :
```
▲ Next.js 14.0.4
- Local: http://localhost:3000
✓ Ready in 2.3s
```

**Vérifier** : http://localhost:3000

---

## ✅ Checklist de Vérification

Avant de continuer, vérifiez que tout fonctionne :

- [ ] Backend démarre sans erreur
- [ ] Frontend démarre sans erreur
- [ ] http://localhost:4000/api/v1/health renvoie `{"status":"ok"}`
- [ ] http://localhost:4000/api/docs affiche Swagger UI
- [ ] http://localhost:3000 affiche la page Xpeditis
- [ ] `docker-compose ps` montre postgres et redis "healthy"

**Tout est vert ? Excellent ! 🎉**

---

## 📚 Prochaines Étapes

### Lire la Documentation (2 heures)

**Obligatoire** (dans cet ordre) :

1. **[QUICK-START.md](QUICK-START.md)** (10 min)
   - Référence rapide des commandes

2. **[CLAUDE.md](CLAUDE.md)** (60 min) 🔥 **TRÈS IMPORTANT**
   - **Architecture hexagonale complète**
   - Règles pour chaque couche
   - Exemples de code
   - **À LIRE ABSOLUMENT avant de coder**

3. **[NEXT-STEPS.md](NEXT-STEPS.md)** (30 min)
   - Quoi faire ensuite
   - Exemples de code pour démarrer
   - Phase 1 expliquée

4. **[TODO.md](TODO.md)** - Section Sprint 1-2 (30 min)
   - Tâches détaillées
   - Critères d'acceptation

### Commencer le Développement

**Sprint 1-2 : Domain Layer** (2 semaines)

Créer les fichiers dans `apps/backend/src/domain/` :

**Entités** (`entities/`) :
- `organization.entity.ts`
- `user.entity.ts`
- `rate-quote.entity.ts`
- `carrier.entity.ts`
- `port.entity.ts`
- `container.entity.ts`
- `booking.entity.ts`

**Value Objects** (`value-objects/`) :
- `email.vo.ts`
- `port-code.vo.ts`
- `money.vo.ts`
- `container-type.vo.ts`
- `booking-number.vo.ts`

**Ports** :
- `ports/in/` - API ports (SearchRatesPort, CreateBookingPort, etc.)
- `ports/out/` - SPI ports (Repositories, CarrierConnectorPort, CachePort, etc.)

**Services** (`services/`) :
- `rate-search.service.ts`
- `booking.service.ts`
- `user.service.ts`

**Tests** :
- `*.spec.ts` pour chaque service
- **Cible : 90%+ de couverture**

Voir [NEXT-STEPS.md](NEXT-STEPS.md) pour des exemples de code complets !

---

## 🛠️ Commandes Utiles

### Développement

```bash
# Backend
npm run backend:dev      # Démarrer
npm run backend:test     # Tests
npm run backend:lint     # Linter

# Frontend
npm run frontend:dev     # Démarrer
npm run frontend:test    # Tests
npm run frontend:lint    # Linter

# Les deux
npm run format           # Formater le code
npm run format:check     # Vérifier le formatage
```

### Docker

```bash
docker-compose up -d       # Démarrer
docker-compose down        # Arrêter
docker-compose logs -f     # Voir les logs
docker-compose ps          # Status
```

### Base de données

```bash
# Se connecter à PostgreSQL
docker-compose exec postgres psql -U xpeditis -d xpeditis_dev

# Se connecter à Redis
docker-compose exec redis redis-cli -a xpeditis_redis_password
```

---

## 🐛 Problèmes Courants

### npm install échoue

**Solution** : Voir [WINDOWS-INSTALLATION.md](WINDOWS-INSTALLATION.md)

### Backend ne démarre pas

```bash
cd apps/backend
rm -rf node_modules package-lock.json
npm install
npm run dev
```

### Frontend ne démarre pas

```bash
cd apps/frontend
rm -rf node_modules package-lock.json
npm install
npm run dev
```

### Docker ne démarre pas

```bash
# Vérifier que Docker Desktop est lancé
docker --version

# Redémarrer les containers
docker-compose down
docker-compose up -d
```

### Port déjà utilisé

```bash
# Trouver le processus sur le port 4000
netstat -ano | findstr :4000

# Ou changer le port dans apps/backend/.env
PORT=4001
```

---

## 📖 Documentation Complète

Tous les fichiers de documentation :

### Getting Started
- **[START-HERE.md](START-HERE.md)** ⭐ - Ce fichier
- [QUICK-START.md](QUICK-START.md) - Guide rapide
- [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md) - Installation détaillée
- [WINDOWS-INSTALLATION.md](WINDOWS-INSTALLATION.md) - Spécifique Windows
- [NEXT-STEPS.md](NEXT-STEPS.md) - Quoi faire ensuite

### Architecture
- **[CLAUDE.md](CLAUDE.md)** 🔥 - **À LIRE ABSOLUMENT**
- [apps/backend/README.md](apps/backend/README.md) - Backend
- [apps/frontend/README.md](apps/frontend/README.md) - Frontend

### Project Planning
- [PRD.md](PRD.md) - Exigences produit
- [TODO.md](TODO.md) - Roadmap 30 semaines
- [SPRINT-0-FINAL.md](SPRINT-0-FINAL.md) - Rapport Sprint 0
- [SPRINT-0-SUMMARY.md](SPRINT-0-SUMMARY.md) - Résumé
- [INDEX.md](INDEX.md) - Index complet

---

## 🎯 Objectifs Phase 1 (6-8 semaines)

**Sprint 1-2** : Domain Layer
- Créer toutes les entités métier
- Définir tous les ports (API & SPI)
- Implémenter les services métier
- Tests unitaires (90%+)

**Sprint 3-4** : Infrastructure Layer
- Schéma de base de données
- Repositories TypeORM
- Adapter Redis cache
- Connecteur Maersk

**Sprint 5-6** : Application Layer
- API rate search
- Controllers & DTOs
- Documentation OpenAPI
- Tests E2E

**Sprint 7-8** : Frontend UI
- Interface de recherche
- Affichage des résultats
- Filtres et tri
- Tests frontend

---

## 💡 Conseils Importants

### ⚠️ À LIRE ABSOLUMENT

**[CLAUDE.md](CLAUDE.md)** - Contient toutes les règles d'architecture :
- Comment organiser le code
- Quoi mettre dans chaque couche
- Ce qu'il faut éviter
- Exemples complets

**Sans lire CLAUDE.md, vous risquez de violer l'architecture hexagonale !**

### ✅ Bonnes Pratiques

- **Tests first** : Écrire les tests avant le code
- **Commits fréquents** : Petits commits, souvent
- **Lire les specs** : Vérifier TODO.md pour les critères d'acceptation
- **Suivre l'archi** : Respecter Domain → Application → Infrastructure

---

## 🎉 Vous êtes Prêt !

**Sprint 0** : ✅ Complete
**Installation** : ✅ Fonctionnelle
**Documentation** : ✅ Disponible
**Prochaine étape** : Lire CLAUDE.md et commencer Sprint 1

**Bon développement ! 🚀**

---

*Xpeditis MVP - Maritime Freight Booking Platform*
*Démarrez ici pour le développement Phase 1*