422 lines
12 KiB
Markdown
422 lines
12 KiB
Markdown
```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*)
|