📚 BookShare - Plateforme de Partage de Livres

BookShare est une plateforme collaborative de partage de livres développée avec Laravel 12, permettant aux utilisateurs de partager, emprunter et découvrir des livres dans leur communauté.

🌟 Fonctionnalités

Gestion des Livres et Contenu

• Gestion des Livres : Ajout, modification, suppression et recherche de livres
• Système de Catégories : Organisation des livres par catégories avec icônes FontAwesome
• Auteurs : Gestion des auteurs avec biographies et photos
• Emprunts : Système complet de gestion des emprunts (pending, approved, returned, cancelled)
• Avis et Notes : Reviews avec système de notation 5 étoiles et commentaires

Communauté et Social

• Book Clubs : Création et gestion de clubs de lecture
• Événements : Organisation d'événements (discussions, rencontres d'auteurs, etc.)
• Défis de Lecture : Reading challenges avec objectifs et suivi
• Sondages : Création de polls pour les membres des clubs
• Système de Messagerie : Communication entre utilisateurs avec support PDF

Administration et Analytics

• Interface d'Administration : Dashboard complet avec statistiques et notifications
• 🤖 Rapport AI Analytique : Génération automatique de rapports avec Mistral AI
• 📄 Export PDF Professionnel : Rapports PDF avec branding ESPRIT optimisés pour impression
• Actualités Littéraires : Récupération automatique de news depuis des sources externes
• Gestion des Utilisateurs : Système de rôles (Admin, Modérateur, Utilisateur)

Technique

• Interface Multilingue : Support français et anglais
• Design Responsive : Interface adaptée à tous les écrans
• Localisation : Gestion des emplacements pour échanges de livres

🛠️ Technologies Utilisées

• Backend : Laravel 12, PHP 8.2
• Frontend : Blade, Bootstrap 5, JavaScript, Vite
• Base de données : MySQL 8.0
• Cache : Redis
• Serveur Web : Nginx
• Containerisation : Docker & Docker Compose
• IA : Mistral AI pour l'analyse de données
• PDF : DomPDF pour la génération de rapports
• APIs Externes : New York Times, The Guardian, BBC Culture (actualités littéraires)

🚀 Installation et Démarrage

Option 1 : Exécution avec Docker (Recommandée)

Prérequis

• Docker Desktop installé
• Git

Étapes d'installation

1. Cloner le projet

git clone <votre-repo>
cd bookshare

2. Démarrer avec Docker

# Arrêter les conteneurs existants
docker-compose down

# Construire et démarrer les services
docker-compose build --no-cache
docker-compose up -d

# Vérifier le statut
docker-compose ps

3. Exécuter les migrations et seeders

# Exécuter les migrations
docker-compose exec app php artisan migrate

# Créer les utilisateurs de test
docker-compose exec app php artisan db:seed --class=AdminUserSeeder

# Exécuter tous les seeders pour les données complètes
docker-compose exec app php artisan db:seed

# Récupérer les actualités littéraires (optionnel)
docker-compose exec app php artisan news:fetch

4. Accéder à l'application

• Application : http://localhost:8000
• Base de données : localhost:3306
• Redis : localhost:6379

Commandes Docker utiles

# Voir les logs
docker-compose logs -f app

# Accéder au shell du conteneur
docker-compose exec app bash

# Arrêter les services
docker-compose down

# Redémarrer les services
docker-compose restart

# Nettoyer complètement
docker-compose down -v

Option 2 : Exécution Locale

Prérequis

• PHP 8.2+
• Composer
• Node.js 18+
• MySQL 8.0+
• Redis

Étapes d'installation

1. Cloner et installer les dépendances

git clone <votre-repo>
cd bookshare
composer install
npm install

2. Configuration de l'environnement

# Copier le fichier d'environnement
cp .env.example .env

# Générer la clé d'application
php artisan key:generate

# Configurer la base de données dans .env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=bookshare
DB_USERNAME=root
DB_PASSWORD=your_password

# Configurer Redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

3. Base de données et assets

# Créer la base de données
php artisan migrate

# Construire les assets
npm run build

# Exécuter les seeders pour les données complètes
php artisan db:seed

# Récupérer les actualités littéraires (optionnel)
php artisan news:fetch

4. Démarrer l'application

# Serveur de développement
php artisan serve

# En arrière-plan (optionnel)
php artisan queue:work

👥 Utilisateurs de Test

Après avoir exécuté les seeders, vous pouvez vous connecter avec :

Rôle	Email	Mot de passe
👑 Administrateur	hamdikbaier8@gmail.com	admin123
🛡️ Modérateur	moderator@bookshare.com	moderator123
👤 Utilisateur	user@bookshare.com	user123

📋 Commandes de Gestion

Seeders disponibles

# Créer uniquement les utilisateurs de test
php artisan db:seed --class=AdminUserSeeder

# Exécuter tous les seeders (recommandé)
php artisan db:seed

# Seeders individuels pour données spécifiques
php artisan db:seed --class=BookSeeder
php artisan db:seed --class=CategorySeeder
php artisan db:seed --class=AuthorSeeder
php artisan db:seed --class=LocationSeeder
php artisan db:seed --class=BookClubSeeder
php artisan db:seed --class=EventSeeder
php artisan db:seed --class=ReadingChallengeSeeder
php artisan db:seed --class=PollSeeder
php artisan db:seed --class=ReviewSeeder
php artisan db:seed --class=BorrowingSeeder

# Commandes pour actualités littéraires
php artisan news:fetch          # Récupérer les news depuis les APIs externes
php artisan news:clear          # Nettoyer les news anciennes

Commandes Laravel utiles

# Voir le statut des migrations
php artisan migrate:status

# Exécuter les migrations
php artisan migrate

# Annuler la dernière migration
php artisan migrate:rollback

# Nettoyer le cache
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# Voir les routes
php artisan route:list

# Accéder à Tinker
php artisan tinker

# Commandes spécifiques BookShare
php artisan news:fetch          # Récupérer actualités littéraires
php artisan news:clear          # Nettoyer news anciennes
php artisan queue:work          # Traiter les tâches en arrière-plan
php artisan schedule:run        # Exécuter les tâches programmées

# Commandes Docker spécifiques
docker-compose exec app php artisan migrate:fresh --seed    # Reset complet DB + seeders
docker-compose exec app php artisan config:cache           # Cache config en production
docker-compose exec app php artisan route:cache            # Cache routes en production

🗂️ Structure du Projet

bookshare/
├── app/
│   ├── Http/Controllers/     # Contrôleurs (Admin, API, etc.)
│   │   └── AdminReportController.php  # 🤖 Rapport AI Analytique
│   ├── Models/              # Modèles Eloquent
│   ├── Helpers/             # Helpers (MarkdownHelper, etc.)
│   ├── Console/Commands/    # Commandes Artisan (news:fetch)
│   └── ...
├── database/
│   ├── migrations/          # Migrations de base de données
│   └── seeders/            # Seeders pour les données de test
│       ├── AdminUserSeeder.php
│       ├── BookClubSeeder.php
│       ├── EventSeeder.php
│       ├── ReadingChallengeSeeder.php
│       ├── PollSeeder.php
│       ├── ReviewSeeder.php
│       ├── BorrowingSeeder.php
│       └── ...
├── resources/
│   ├── views/              # Vues Blade
│   │   └── admin/reports/  # 📄 Templates pour rapports PDF
│   ├── components/         # Composants Blade réutilisables
│   └── sass/              # Styles SCSS
├── public/
│   ├── assets/img/        # Logos (esprit-logo.png, bookshare-logo.svg)
│   └── assets/css/        # CSS personnalisé (sb-admin-2.css)
├── docker/                 # Configuration Docker
├── Dockerfile             # Image Docker
├── docker-compose.yml     # Orchestration Docker
└── README.md             # Ce fichier

🔧 Configuration Docker

Services inclus

• app : Application Laravel (PHP 8.2-FPM)
• nginx : Serveur web (port 8000)
• db : Base de données MySQL 8.0 (port 3306)
• redis : Cache Redis (port 6379)

Variables d'environnement Docker

APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000
DB_HOST=db
DB_DATABASE=bookshare
DB_USERNAME=root
DB_PASSWORD=password
REDIS_HOST=redis
CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

# Configuration Mistral AI (pour rapports analytiques)
MISTRAL_API_KEY=your_mistral_api_key_here
MISTRAL_API_URL=https://api.mistral.ai/v1/chat/completions

# APIs pour actualités littéraires
NYT_API_KEY=your_nyt_api_key_here
GUARDIAN_API_KEY=your_guardian_api_key_here
BBC_API_KEY=your_bbc_api_key_here

🐛 Dépannage

Problèmes courants

1. Erreur "Class Redis not found"

   • L'extension Redis n'est pas installée ou configurée
   • Solution : Reconstruire l'image Docker ou utiliser SESSION_DRIVER=file

2. Erreur de connexion à la base de données

   • Vérifier que MySQL est démarré
   • Vérifier les paramètres de connexion dans .env
   • En Docker : s'assurer que .env correspond aux variables du docker-compose.yml

3. Assets non chargés

   • Exécuter npm run build ou npm run dev
   • Vérifier que Vite est configuré correctement

4. Permissions insuffisantes

   • Vérifier les permissions sur le dossier storage/
   • Exécuter chmod -R 755 storage bootstrap/cache

5. Erreur "Access denied for user 'root'" en Docker

   • Le fichier .env dans le conteneur ne correspond pas au docker-compose.yml
   • Solution : Vérifier les variables d'environnement dans le conteneur

6. Rapport AI ne se génère pas

   • Vérifier que MISTRAL_API_KEY est configuré dans .env
   • Vérifier la connectivité internet pour l'API Mistral

7. Erreur "Maximum execution time exceeded"

   • Le script prend trop de temps (déjà résolu avec set_time_limit(120))
   • Si persistant, augmenter max_execution_time dans php.ini

Logs et débogage

# Logs Docker
docker-compose logs -f app
docker-compose logs -f nginx
docker-compose logs -f db

# Logs Laravel
tail -f storage/logs/laravel.log

# Vérifier la configuration
php artisan config:show

📚 Documentation API

API REST

L'API REST est disponible sur /api/ avec les endpoints suivants :

• GET /api/books - Liste des livres
• POST /api/books - Créer un livre
• GET /api/categories - Liste des catégories
• POST /api/categories - Créer une catégorie

Routes d'Administration

• GET /admin/reports/ai-analytics - 🤖 Génération du rapport AI analytique
• GET /admin/reports/download-pdf - 📄 Téléchargement du rapport PDF

Commandes Artisan

• php artisan news:fetch - Récupération des actualités littéraires
• php artisan news:clear - Nettoyage des actualités anciennes

🆕 Nouvelles Fonctionnalités

🤖 Rapport AI Analytique

Le système génère automatiquement des rapports d'analyse avec Mistral AI :

1. Accès : Dashboard Admin → "Generate AI Report"
2. Fonctionnalités :
   • Analyse complète de toutes les données (13 modules)
   • Génération en anglais avec insights professionnels
   • Export PDF optimisé pour impression
   • Branding ESPRIT intégré

📄 Export PDF Professionnel

• Templates optimisés : Marges professionnelles (25mm), numérotation
• Branding : Logo ESPRIT et BookShare intégrés
• Contenu : Table des matières, métriques clés, analyse détaillée
• Format : A4, prêt pour impression

🏢 Données Complètes

13 modules de données :

• Books, Users, Borrowings, Reviews, Authors
• Categories, Locations, News, Challenges
• Book Clubs, Events, Polls, Messages

Seeders optimisés :

• Données réalistes pour tous les modules
• Respect des contraintes d'intégrité
• Évite les doublons et erreurs

🎨 Interface Améliorée

• Thème marron : Couleurs personnalisées (brown #8B4513)
• Modal de chargement : Animation pendant génération AI
• Responsive : Optimisé pour tous les écrans

🤝 Contribution

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

📄 Licence

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

👨‍💻 Auteur

Hamdi Kbaier

• Email: hamdikbaier8@gmail.com
• GitHub: @hamdikbaier

🙏 Remerciements

• Laravel Framework
• Bootstrap
• FontAwesome
• Tous les contributeurs du projet

---

BookShare - Partagez vos livres, partagez vos connaissances ! 📚✨