```ascii ██╗ ██╗██████╗ ███████╗██████╗ ██╗████████╗██╗███████╗ ╚██╗██╔╝██╔══██╗██╔════╝██╔══██╗██║╚══██╔══╝██║██╔════╝ ╚███╔╝ ██████╔╝█████╗ ██║ ██║██║ ██║ ██║███████╗ ██╔██╗ ██╔═══╝ ██╔══╝ ██║ ██║██║ ██║ ██║╚════██║ ██╔╝ ██╗██║ ███████╗██████╔╝██║ ██║ ██║███████║ ╚═╝ ╚═╝╚═╝ ╚══════╝╚═════╝ ╚═╝ ╚═╝ ╚═╝╚══════╝ ``` > *"Navigating the Digital Ocean with Maritime Excellence"* # Xpeditis - Plateforme SaaS de Transport International > Plateforme B2B/B2C spécialisée dans le transport maritime et routier international ## Vue d'ensemble Xpeditis est une plateforme SaaS moderne inspirée de searates.com, offrant des services complets de transport international avec devis instantanés, suivi en temps réel, et gestion documentaire automatisée. ### Domaines - **Principal** : xpeditis.fr - **API** : api.xpeditis.fr - **Staging** : staging.xpeditis.fr ## Architecture ### Structure Multi-Repository ``` xpeditis/ ├── backend/ # API Spring Boot (Java 17) ├── frontend/ # Interface React TypeScript ├── mobile/ # Application mobile (React Native) ├── docs/ # Documentation technique ├── infrastructure/ # Configuration DevOps └── shared/ # Ressources partagées ``` ### Stack Technique #### Backend - **Framework** : Spring Boot 3.2+ - **Langage** : Java 23 - **Architecture** : Hexagonale (Ports & Adapters) - **Base de données** : PostgreSQL 15 - **Sécurité** : Spring Security + JWT - **Documentation** : OpenAPI 3 (Swagger) - **Build** : Maven #### Frontend - **Framework** : React 18 + TypeScript - **Build** : Vite - **Styling** : TailwindCSS + shadcn/ui - **State Management** : React Query - **Routing** : React Router - **Package Manager** : pnpm #### DevOps - **Conteneurisation** : Docker + Docker Compose - **Orchestration** : Kubernetes + Helm - **CI/CD** : GitHub Actions - **Monitoring** : Prometheus + Grafana - **Logs** : ELK Stack ## Fonctionnalités Principales ### Implémentées 1. **Devis Instantané Multi-Offres** - Génération automatique (Express, Standard, Éco) - Calcul basé sur grilles tarifaires - Validation et acceptation en ligne - API REST complète avec endpoints CRUD 2. **Interface Utilisateur Complète** - Landing page responsive avec statistiques - Formulaire de devis interactif avec validation - Dashboard avec métriques en temps réel - Pages de réservation et suivi d'expéditions - Planning des navires avec filtres - Composants UI modernes (shadcn/ui) 3. **API REST Sécurisée** - Authentification JWT avec intercepteurs - Documentation OpenAPI/Swagger - Gestion CORS multi-environnements - Architecture hexagonale complète - Mapping automatique avec MapStruct 4. **Infrastructure DevOps Complète** - Docker multi-stage builds optimisés - Kubernetes avec auto-scaling (HPA) - CI/CD automatisé avec GitHub Actions - Certificats SSL automatiques (cert-manager) - Scripts de déploiement intelligents - Monitoring et health checks ### En Développement - Track & Trace temps réel avec WebSocket - Dossier d'export automatisé - Facturation PDF avec génération automatique - Centre d'aide avec recherche - Notifications push ## Installation et Démarrage ### Prérequis - Docker & Docker Compose - Node.js 18+ & pnpm - Java 17+ & Maven - kubectl (pour la production) ### Démarrage Rapide ```bash # Cloner le repository git clone https://github.com/your-username/xpeditis.git cd xpeditis # Démarrage avec Docker Compose (recommandé) ./scripts/deploy.sh dev all # Ou démarrage manuel # Backend cd backend mvn spring-boot:run # Frontend (nouveau terminal) cd frontend pnpm install pnpm dev ``` ### Accès aux Services - **Frontend** : http://localhost:3000 - **Backend API** : http://localhost:8080/api - **Swagger UI** : http://localhost:8080/swagger-ui.html - **Base de données** : localhost:5432 - **Actuator** : http://localhost:8080/api/actuator ## Structure du Projet ### Backend (Architecture Hexagonale) ``` backend/src/main/java/com/xpeditis/ ├── application/ # Controllers REST & DTOs │ ├── controller/ # Contrôleurs REST │ └── dto/ # Data Transfer Objects ├── bootstrap/ # Configuration & Main class ├── common/ # Exceptions & Utilities ├── domain/ # Modèles métier & Services │ ├── model/ # Entités métier (Quote, Shipment) │ └── service/ # Services métier ├── infrastructure/ # Repositories & Adaptateurs │ ├── persistence/ # JPA Entities & Repositories │ └── config/ # Configuration Spring └── logs/ # Logging & Audit ``` ### Frontend (React TypeScript) ``` frontend/src/ ├── components/ # Composants réutilisables │ ├── ui/ # Composants de base (shadcn/ui) │ ├── layout/ # Layout & Navigation │ └── quote/ # Composants spécifiques devis ├── pages/ # Pages de l'application │ ├── HomePage.tsx # Page d'accueil │ ├── QuotePage.tsx # Formulaire de devis │ ├── DashboardPage.tsx # Tableau de bord │ └── TrackingPage.tsx # Suivi d'expéditions ├── lib/ # Utilitaires & API client ├── hooks/ # Hooks React personnalisés └── types/ # Types TypeScript ``` ## Configuration ### Variables d'Environnement #### Backend (`application.yml`) ```yaml spring: profiles: active: ${SPRING_PROFILES_ACTIVE:dev} datasource: url: ${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/xpeditis_dev} username: ${SPRING_DATASOURCE_USERNAME:xpeditis_user} password: ${SPRING_DATASOURCE_PASSWORD:xpeditis_password} jpa: hibernate: ddl-auto: ${SPRING_JPA_HIBERNATE_DDL_AUTO:update} show-sql: ${SPRING_JPA_SHOW_SQL:false} jwt: secret: ${JWT_SECRET:dev-secret-key} expiration: ${JWT_EXPIRATION:86400} cors: allowed-origins: ${CORS_ALLOWED_ORIGINS:http://localhost:3000} management: endpoints: web: exposure: include: health,info,metrics,prometheus ``` #### Frontend (`.env`) ```bash VITE_API_URL=http://localhost:8080/api VITE_APP_NAME=Xpeditis VITE_APP_VERSION=1.0.0 ``` ## Déploiement ### Script de Déploiement Intelligent ```bash # Développement complet ./scripts/deploy.sh dev all # Staging avec build automatique ./scripts/deploy.sh staging all # Production avec confirmation ./scripts/deploy.sh prod all # Composant spécifique ./scripts/deploy.sh dev backend ./scripts/deploy.sh prod frontend # Rollback automatique ./scripts/deploy.sh --rollback # Aide détaillée ./scripts/deploy.sh --help ``` ### Kubernetes Production ```bash # Déploiement complet avec secrets kubectl apply -f k8s/namespace.yaml kubectl apply -f k8s/postgres.yaml kubectl apply -f k8s/backend.yaml kubectl apply -f k8s/frontend.yaml kubectl apply -f k8s/ingress.yaml # Vérification du déploiement kubectl get pods -n xpeditis kubectl get services -n xpeditis kubectl get ingress -n xpeditis # Monitoring des logs kubectl logs -f deployment/backend -n xpeditis ``` ## Tests ### Backend ```bash cd backend mvn test # Tests unitaires mvn verify # Tests d'intégration mvn jacoco:report # Couverture de code mvn spring-boot:run -Dspring.profiles.active=test ``` ### Frontend ```bash cd frontend pnpm test # Tests unitaires pnpm test:coverage # Couverture de code pnpm lint # Linting ESLint pnpm type-check # Vérification TypeScript pnpm build # Build de production ``` ## Monitoring et Observabilité ### Health Checks - **Backend** : `/api/actuator/health` - **Frontend** : `/health` - **Database** : Intégré dans Spring Boot Actuator - **Kubernetes** : Liveness et Readiness probes ### Métriques - **Prometheus** : `/api/actuator/prometheus` - **Grafana** : Dashboards pré-configurés - **Logs** : Centralisés via ELK Stack - **APM** : Traces distribuées ### Auto-scaling - **HPA Backend** : CPU 70%, Memory 80%, 2-10 replicas - **HPA Frontend** : CPU 70%, 2-5 replicas - **Database** : Scaling vertical automatique ## Sécurité ### Authentification - JWT avec refresh tokens - OAuth2 Resource Server - Gestion des rôles et permissions - Intercepteurs automatiques côté client ### HTTPS et SSL - Certificats SSL automatiques (Let's Encrypt) - Redirection HTTP → HTTPS forcée - HSTS headers configurés - TLS 1.2+ uniquement ### CORS et Sécurité API - Configuration multi-environnements - Origines autorisées dynamiques - Headers sécurisés (CSP, X-Frame-Options) - Rate limiting (100 req/min) ## Contribution ### Workflow Git ```bash # Créer une branche feature git checkout -b feature/nouvelle-fonctionnalite # Développer et tester git add . git commit -m "feat: ajouter nouvelle fonctionnalité" # Push et créer une PR git push origin feature/nouvelle-fonctionnalite ``` ### Standards de Code - **Backend** : Google Java Style Guide + Checkstyle - **Frontend** : ESLint + Prettier + TypeScript strict - **Commits** : Conventional Commits - **Tests** : Couverture > 80% - **Documentation** : JSDoc/JavaDoc obligatoire ## Documentation - **API Interactive** : http://localhost:8080/swagger-ui.html - **Architecture** : `/docs/architecture.md` - **Déploiement** : `/docs/deployment.md` - **Contribution** : `/docs/contributing.md` - **API Reference** : Documentation OpenAPI 3.0 ## Support et Debugging ### Logs en Temps Réel ```bash # Docker Compose docker-compose logs -f backend docker-compose logs -f frontend docker-compose logs -f postgres # Kubernetes kubectl logs -f deployment/backend -n xpeditis kubectl logs -f deployment/frontend -n xpeditis ``` ### Debugging Avancé ```bash # Backend debug mode avec profiler SPRING_PROFILES_ACTIVE=dev,debug mvn spring-boot:run # Frontend avec source maps DEBUG=true pnpm dev # Base de données docker exec -it xpeditis-postgres psql -U xpeditis_user -d xpeditis_dev ``` ### Commandes Utiles ```bash # Restart des services docker-compose restart backend kubectl rollout restart deployment/backend -n xpeditis # Nettoyage docker system prune -a kubectl delete pods --field-selector=status.phase=Failed -n xpeditis # Monitoring des ressources docker stats kubectl top pods -n xpeditis ``` ## Roadmap ### Version 1.1 (Q1 2024) - [ ] Authentification complète avec OAuth2 - [ ] Track & Trace en temps réel - [ ] Notifications push - [ ] Export PDF des devis ### Version 1.2 (Q2 2024) - [ ] Application mobile React Native - [ ] API GraphQL - [ ] Intégration paiements Stripe - [ ] Multi-langues (EN, FR, ES) ### Version 2.0 (Q3 2024) - [ ] IA pour optimisation des routes - [ ] Blockchain pour traçabilité - [ ] Marketplace des transporteurs - [ ] Analytics avancées ## Licence Ce projet est sous licence MIT. Voir le fichier [LICENSE](LICENSE) pour plus de détails. ## Équipe - **Lead Developer** : [Votre nom] - **DevOps Engineer** : [Nom DevOps] - **UI/UX Designer** : [Nom Designer] - **Product Owner** : [Nom PO] --- **Xpeditis** - Révolutionner le transport international *Dernière mise à jour : Décembre 2024*)