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 :

# 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)

docker-compose up -d

Vérifier :

docker-compose ps
# Doit afficher postgres et redis "Up (healthy)"

3️⃣ Configurer l'Environnement (30 sec)

# 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)

# 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

# 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 (10 min)

   • Référence rapide des commandes

2. 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 (30 min)

   • Quoi faire ensuite
   • Exemples de code pour démarrer
   • Phase 1 expliquée

4. 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 pour des exemples de code complets !

---

🛠️ Commandes Utiles

Développement

# 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

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

# 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

Backend ne démarre pas

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

Frontend ne démarre pas

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

Docker ne démarre pas

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

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

Port déjà utilisé

# 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 ⭐ - Ce fichier
• QUICK-START.md - Guide rapide
• INSTALLATION-STEPS.md - Installation détaillée
• WINDOWS-INSTALLATION.md - Spécifique Windows
• NEXT-STEPS.md - Quoi faire ensuite

Architecture

• CLAUDE.md 🔥 - À LIRE ABSOLUMENT
• apps/backend/README.md - Backend
• apps/frontend/README.md - Frontend

Project Planning

• PRD.md - Exigences produit
• TODO.md - Roadmap 30 semaines
• SPRINT-0-FINAL.md - Rapport Sprint 0
• SPRINT-0-SUMMARY.md - Résumé
• 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 - 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