🛒 E-Commerce Backend API

API REST complète pour une application e-commerce moderne avec Spring Boot

📋 Table des matières

• Vue d'ensemble
• Fonctionnalités
• Technologies
• Prérequis
• Installation
• Configuration
• Utilisation
• API Endpoints
• Base de données
• Sécurité
• Tests
• Déploiement
• Contribution
• Licence

🎯 Vue d'ensemble

Backend REST API pour une plateforme e-commerce complète offrant :

• Gestion des utilisateurs avec authentification JWT
• Catalogue de produits avec attributs personnalisables
• Système de panier et commandes
• Intégration paiement Stripe
• Codes promo et réductions
• Système d'avis clients
• Interface d'administration complète

✨ Fonctionnalités

👥 Gestion des Utilisateurs

• ✅ Inscription et connexion (JWT)
• ✅ OAuth2 (Google, Facebook)
• ✅ Gestion des profils
• ✅ Upload de photos de profil
• ✅ Système de rôles (ADMIN, CLIENT)
• ✅ Réinitialisation de mot de passe

📦 Gestion des Produits

• ✅ CRUD complet des produits
• ✅ Catégorisation
• ✅ Galerie d'images multiples
• ✅ Gestion du stock en temps réel
• ✅ Attributs personnalisés (taille, couleur, etc.)
  • Types : select, radio, checkbox
  • Prix supplémentaires par option
  • Stock par option
  • Validation obligatoire/optionnelle
• ✅ Caractéristiques techniques
• ✅ Archivage logique

🛒 Panier et Commandes

• ✅ Panier persistant en base de données
• ✅ Sauvegarde des attributs sélectionnés
• ✅ Calcul automatique des prix avec suppléments
• ✅ Création de commandes
• ✅ Historique des commandes avec détails complets
• ✅ Mise à jour automatique du stock

💳 Paiement

• ✅ Intégration Stripe Payment Intent
• ✅ Paiement sécurisé par carte bancaire
• ✅ Confirmation de paiement
• ✅ Gestion des erreurs de paiement

🎟️ Codes Promo

• ✅ Création et gestion des codes (interface admin)
• ✅ Réduction en pourcentage ou montant fixe
• ✅ Conditions d'utilisation :
  • Montant minimum d'achat
  • Dates de validité (début/fin)
  • Nombre maximum d'utilisations
• ✅ Validation automatique en temps réel
• ✅ Compteur d'utilisations
• ✅ Activation/désactivation
• ✅ Statistiques d'utilisation

⭐ Avis Clients

• ✅ Système de notation (1-5 étoiles)
• ✅ Commentaires détaillés
• ✅ Calcul automatique de la note moyenne
• ✅ Système de votes "utile"
• ✅ Contraintes d'unicité :
  • 1 seul avis par utilisateur/produit
  • 1 seul vote par utilisateur/avis
• ✅ Tri par date décroissante
• ✅ Affichage du nombre d'avis

👥 Gestion Avancée des Utilisateurs

• ✅ Création d'administrateurs par les admins
• ✅ Endpoint sécurisé /api/auth/register-admin
• ✅ Gestion des rôles (ROLE_USER, ROLE_ADMIN)
• ✅ Interface admin de gestion des utilisateurs
• ✅ Statistiques utilisateurs
• ✅ Archivage et restauration de comptes

📧 Notifications

• ✅ Emails de confirmation de commande avec détails complets
• ✅ Emails de bienvenue
• ✅ Vérification d'email
• ✅ Réinitialisation de mot de passe
• ✅ Notifications de changement de statut
• ✅ Templates HTML personnalisés

🛠️ Technologies

Core

• Java 17 - Langage de programmation
• Spring Boot 3.x - Framework principal
• Spring Data JPA - Accès aux données
• Hibernate - ORM
• MySQL 8.0 - Base de données

Sécurité

• Spring Security - Sécurisation de l'API
• JWT (JSON Web Tokens) - Authentification
• BCrypt - Hashage des mots de passe
• OAuth2 - Authentification sociale

Outils

• Maven - Gestion des dépendances
• Lombok - Réduction du code boilerplate
• MapStruct - Mapping entités/DTOs
• Stripe API - Paiement en ligne
• JavaMail - Envoi d'emails

📋 Prérequis

• Java 17 ou supérieur
• Maven 3.6+
• MySQL 8.0+
• Compte Stripe (pour les paiements)
• Serveur SMTP (pour les emails)

🚀 Installation

1. Cloner le repository

git clone https://github.com/BahaManai/backend-ecommerce.git
cd backend-ecommerce

2. Créer la base de données

CREATE DATABASE ecommerce_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

3. Configurer l'application

Créer un fichier application.properties dans src/main/resources/ :

# Base de données
spring.datasource.url=jdbc:mysql://localhost:3306/ecommerce_db
spring.datasource.username=votre_username
spring.datasource.password=votre_password

# JPA/Hibernate
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

# JWT
jwt.secret=votre_secret_key_tres_longue_et_securisee
jwt.expiration=86400000

# Stripe
stripe.api.key=votre_cle_stripe

# Email
spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username=votre_email@gmail.com
spring.mail.password=votre_mot_de_passe_app

# Upload
file.upload-dir=./uploads

4. Installer les dépendances

mvn clean install

5. Exécuter les scripts SQL

mysql -u root -p ecommerce_db < add-attributs-selections-columns.sql

6. Lancer l'application

mvn spring-boot:run

L'API sera accessible sur http://localhost:9092

⚙️ Configuration

Variables d'environnement

Pour la production, utilisez des variables d'environnement :

export DB_URL=jdbc:mysql://localhost:3306/ecommerce_db
export DB_USERNAME=username
export DB_PASSWORD=password
export JWT_SECRET=your_secret_key
export STRIPE_API_KEY=your_stripe_key

CORS

Configuré pour accepter les requêtes depuis http://localhost:4200 (Angular). Modifier dans CorsConfiguration.java pour d'autres origines.

📡 API Endpoints

Authentification

POST   /api/auth/register          - Inscription
POST   /api/auth/login             - Connexion
POST   /api/auth/refresh           - Rafraîchir le token
POST   /api/auth/logout            - Déconnexion
POST   /api/auth/forgot-password   - Mot de passe oublié

Produits

GET    /api/produits               - Liste des produits
GET    /api/produits/{id}          - Détails d'un produit
GET    /api/produits/{id}/complet  - Produit avec attributs
POST   /api/produits               - Créer un produit (ADMIN)
PUT    /api/produits/{id}          - Modifier un produit (ADMIN)
DELETE /api/produits/{id}          - Archiver un produit (ADMIN)

Attributs Produits

GET    /api/produits/{id}/attributs              - Liste des attributs
POST   /api/produits/{id}/attributs              - Ajouter un attribut (ADMIN)
PUT    /api/produits/attributs/{id}              - Modifier un attribut (ADMIN)
DELETE /api/produits/attributs/{id}              - Supprimer un attribut (ADMIN)
POST   /api/produits/attributs/{id}/options      - Ajouter une option (ADMIN)
PUT    /api/produits/attributs/options/{id}      - Modifier une option (ADMIN)
DELETE /api/produits/attributs/options/{id}      - Supprimer une option (ADMIN)

Panier

GET    /api/panier/{userId}                      - Obtenir le panier
POST   /api/panier/{userId}/{produitId}/{qty}    - Ajouter au panier
DELETE /api/panier/{userId}/{produitId}          - Retirer du panier
DELETE /api/panier/{userId}/vider                - Vider le panier

Commandes

GET    /api/commandes/{userId}                   - Historique des commandes
POST   /api/commandes/{userId}/validerCommande   - Créer une commande
GET    /api/commandes/admin/all                  - Toutes les commandes (ADMIN)

Codes Promo

GET    /api/promo-codes                          - Liste des codes (ADMIN)
POST   /api/promo-codes                          - Créer un code (ADMIN)
PUT    /api/promo-codes/{id}                     - Modifier un code (ADMIN)
DELETE /api/promo-codes/{id}                     - Supprimer un code (ADMIN)
POST   /api/promo-codes/validate                 - Valider un code

Paiement

POST   /api/paiements/creer-intention            - Créer une intention de paiement
POST   /api/paiements/confirmer-paiement         - Confirmer le paiement

Avis

GET    /api/avis/produit/{produitId}             - Avis d'un produit
POST   /api/avis                                 - Créer un avis
PUT    /api/avis/{id}                            - Modifier un avis
DELETE /api/avis/{id}                            - Supprimer un avis

Upload

POST   /api/upload/image                         - Upload une image
POST   /api/upload/produit/{id}/images           - Upload images produit
DELETE /api/upload/image/{filename}              - Supprimer une image

🗄️ Base de données

Schéma principal

utilisateurs
├── id
├── email
├── password
├── nom
├── prenom
├── role
└── photo_url

produits
├── id
├── nom
├── description
├── prix
├── stock
├── categorie_id
├── img_url
└── a_attributs

produit_attributs
├── id
├── produit_id
├── nom
├── type
├── obligatoire
└── ordre

produit_attribut_options
├── id
├── attribut_id
├── valeur
├── prix_supplement
├── stock
└── active

articles_panier
├── id
├── panier_id
├── product_id
├── quantity
└── attributs_selections (JSON)

commandes
├── id
├── user_id
├── date_created
└── total

lignes_commande
├── id
├── id_commande
├── id_produit
├── quantity
├── price
└── attributs_selections (JSON)

Scripts SQL

Les scripts de création sont dans le dossier racine :

• add-attributs-selections-columns.sql - Ajout des colonnes pour attributs

🔒 Sécurité

Authentification JWT

Toutes les routes (sauf /api/auth/** et /api/produits en lecture) nécessitent un token JWT :

Authorization: Bearer <votre_token_jwt>

Rôles et Permissions

• CLIENT : Accès aux produits, panier, commandes personnelles
• ADMIN : Accès complet + gestion des produits, utilisateurs, commandes

Protection

• ✅ Hashage BCrypt des mots de passe
• ✅ Validation des entrées
• ✅ Protection CSRF
• ✅ CORS configuré
• ✅ SQL Injection protégé (JPA)
• ✅ XSS protégé

🧪 Tests

Lancer les tests

mvn test

Tests avec Postman

Une collection Postman est disponible dans /postman/ecommerce-api.json

Tests manuels

1. Créer un utilisateur admin
2. Se connecter et récupérer le token
3. Créer un produit avec attributs
4. Tester l'ajout au panier avec attributs
5. Créer une commande
6. Vérifier l'historique

📦 Déploiement

Build de production

mvn clean package -DskipTests

Le JAR sera dans target/backend-ecommerce-0.0.1-SNAPSHOT.jar

Exécution

java -jar target/backend-ecommerce-0.0.1-SNAPSHOT.jar

Docker (optionnel)

FROM openjdk:17-jdk-slim
COPY target/*.jar app.jar
EXPOSE 9092
ENTRYPOINT ["java","-jar","/app.jar"]

docker build -t ecommerce-backend .
docker run -p 9092:9092 ecommerce-backend

📁 Structure du projet

backend-ecommerce/
├── src/
│   ├── main/
│   │   ├── java/com/iset/backend_ecommerce/
│   │   │   ├── configuration/      # Configuration Spring
│   │   │   ├── controller/         # REST Controllers
│   │   │   ├── dao/                # Repositories
│   │   │   ├── dto/                # Data Transfer Objects
│   │   │   ├── entity/             # Entités JPA
│   │   │   ├── exceptions/         # Gestion des erreurs
│   │   │   ├── mapper/             # MapStruct mappers
│   │   │   └── service/            # Logique métier
│   │   └── resources/
│   │       ├── application.properties
│   │       └── static/
│   └── test/                       # Tests unitaires
├── uploads/                        # Fichiers uploadés
├── pom.xml                         # Dépendances Maven
└── README.md

🤝 Contribution

Les contributions sont les bienvenues !

1. Fork le projet
2. Créer une branche (git checkout -b feature/AmazingFeature)
3. Commit les changements (git commit -m 'Add AmazingFeature')
4. Push vers la branche (git push origin feature/AmazingFeature)
5. Ouvrir une Pull Request

📝 Changelog

Version 2.0.0 (Version Finale - Décembre 2024)

🎨 Nouvelles Fonctionnalités Majeures

• ✨ Système d'attributs personnalisés complet
  • Création d'attributs dynamiques (taille, couleur, matériau, etc.)
  • Options avec prix supplémentaires et stock indépendant
  • Types d'affichage : SELECT, RADIO, COLOR, CHECKBOX
  • Validation obligatoire/optionnelle
  • Ordre d'affichage personnalisable
• ✨ Gestion avancée du panier
  • Sauvegarde des attributs sélectionnés en JSON
  • Calcul automatique des prix avec suppléments
  • Persistance complète en base de données
  • Validation du stock par option
• ✨ Système de commandes enrichi
  • Transfert des attributs vers les lignes de commande
  • Historique détaillé avec attributs sélectionnés
  • Mise à jour automatique du stock par option
  • Emails de confirmation avec détails complets
• ✨ Codes promo avancés
  • Réduction en pourcentage ou montant fixe
  • Conditions multiples (montant minimum, dates, utilisations)
  • Validation en temps réel
  • Statistiques d'utilisation
  • Interface admin complète
• ✨ Système d'avis clients
  • Notation 1-5 étoiles
  • Commentaires détaillés
  • Calcul de moyenne automatique
  • Système de votes "utile"
  • Contraintes d'unicité (1 avis par user/produit)
• ✨ Gestion des utilisateurs admin
  • Création d'administrateurs par les admins
  • Endpoint sécurisé /api/auth/register-admin
  • Validation des rôles ROLE_USER et ROLE_ADMIN
  • Interface de gestion complète
• ✨ Upload d'images optimisé
  • Upload multiple pour les produits
  • Galerie d'images avec ordre
  • Photos de profil utilisateur
  • Validation de type et taille
  • Stockage local avec URLs accessibles

🔧 Améliorations Techniques

• 🔒 Sécurité renforcée
  • Endpoint register-admin protégé (ADMIN only)
  • Validation stricte des rôles
  • Protection contre les doublons (avis, votes)
  • Contraintes UNIQUE en base de données
• 📊 Base de données optimisée
  • Nouvelles tables : produit_attributs, produit_attribut_options
  • Colonnes JSON pour attributs_selections
  • Index sur les clés étrangères
  • Cascade DELETE configuré
• 🎯 API REST complète
  • 50+ endpoints documentés
  • DTOs pour toutes les opérations
  • Validation avec annotations
  • Gestion d'erreurs centralisée
• 📧 Système d'emails
  • Confirmation de commande avec détails
  • Vérification d'email
  • Réinitialisation de mot de passe
  • Notifications de statut

🐛 Corrections

• ✅ Correction du rôle USER lors de l'inscription
• ✅ Ajout de la méthode existsByEmail dans UtilisateurRepository
• ✅ Gestion correcte des attributs dans le panier
• ✅ Calcul précis des prix avec suppléments
• ✅ Validation du stock par option
• ✅ Gestion des erreurs de paiement Stripe

Version 1.2.0

• ✨ Ajout du système d'attributs personnalisés
• ✨ Sauvegarde des attributs dans le panier
• ✨ Transfert des attributs vers les commandes

Version 1.1.0

• ✨ Intégration Stripe
• ✨ Système de codes promo
• ✨ Emails automatiques

Version 1.0.0

• 🎉 Version initiale
• ✨ CRUD produits et utilisateurs
• ✨ Authentification JWT
• ✨ Panier et commandes

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

👨‍💻 Auteur

Votre Nom

• GitHub: @BahaManai
• Email: bahaeddinmanai7@gmail.com

🙏 Remerciements

• Spring Boot Team
• Stripe
• Tous les contributeurs

📞 Support

Pour toute question ou problème :

• Ouvrir une issue
• Contacter par email

---

⭐ Si ce projet vous a aidé, n'hésitez pas à lui donner une étoile !