commit ee305edd5a284e58fb6bf0ce2e3dcaee5486c1bd Author: David Date: Sun Aug 3 00:46:32 2025 +0000 Upload files to "/" diff --git a/README.md b/README.md new file mode 100644 index 0000000..87a98f8 --- /dev/null +++ b/README.md @@ -0,0 +1,421 @@ +```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*)