xpeditis2.0/docs/README.md

📚 Documentation Xpeditis

Bienvenue dans la documentation centralisée de Xpeditis !

Toute la documentation technique du projet a été réorganisée et consolidée dans ce dossier pour faciliter la navigation et la maintenance.

---

📂 Structure de la Documentation

docs/
├── README.md                          # Ce fichier (index de la documentation)
├── architecture.md                    # ⭐ Architecture globale
├── AUDIT-FINAL-REPORT.md             # ⭐ Rapport d'audit complet
├── decisions.md                       # ⭐ Architecture Decision Records (ADRs)
│
├── installation/                      # 🔧 Guides d'installation
│   ├── INSTALLATION-STEPS.md         # Guide pas à pas d'installation
│   ├── INSTALLATION-COMPLETE.md      # Confirmation d'installation complète
│   ├── QUICK-START.md                # Démarrage rapide
│   ├── START-HERE.md                 # Point de départ pour nouveaux utilisateurs
│   └── WINDOWS-INSTALLATION.md       # Guide spécifique Windows
│
├── deployment/                        # 🚀 Déploiement et Infrastructure
│   ├── DEPLOYMENT.md                 # Guide principal de déploiement
│   ├── DEPLOYMENT_CHECKLIST.md       # Checklist pré-déploiement
│   ├── DEPLOYMENT_READY.md           # Validation déploiement
│   ├── DEPLOYMENT_FIX.md             # Corrections déploiement
│   ├── DEPLOY_README.md              # README déploiement
│   ├── REGISTRY_PUSH_GUIDE.md        # Guide push vers registry
│   ├── CI_CD_MULTI_ENV.md            # CI/CD multi-environnements
│   ├── CICD_REGISTRY_SETUP.md        # Setup registry CI/CD
│   ├── ARM64_SUPPORT.md              # Support architecture ARM64
│   │
│   ├── Docker/                        # Configuration Docker
│   │   ├── DOCKER_FIXES_SUMMARY.md
│   │   ├── DOCKER_CSS_FIX.md
│   │   ├── DOCKER_ARM64_FIX.md
│   │   ├── FIX_DOCKER_PROXY.md
│   │   └── FIX_404_SWARM.md
│   │
│   └── Portainer/                     # Déploiement Portainer
│       ├── PORTAINER_DEPLOY_FINAL.md
│       ├── PORTAINER_MIGRATION_AUTO.md
│       ├── PORTAINER_CHECKLIST.md
│       ├── PORTAINER_DEBUG.md
│       ├── PORTAINER_DEBUG_COMMANDS.md
│       ├── PORTAINER_CRASH_DEBUG.md
│       ├── PORTAINER_FIX_QUICK.md
│       ├── PORTAINER_ENV_FIX.md
│       ├── PORTAINER_REGISTRY_NAMING.md
│       ├── PORTAINER_TRAEFIK_404.md
│       └── PORTAINER_YAML_FIX.md
│
├── phases/                            # 📈 Historique des phases de développement
│   ├── SPRINT-0-SUMMARY.md
│   ├── SPRINT-0-COMPLETE.md
│   ├── SPRINT-0-FINAL.md
│   ├── PHASE-1-PROGRESS.md
│   ├── PHASE-1-WEEK5-COMPLETE.md
│   ├── PHASE2_AUTHENTICATION_SUMMARY.md
│   ├── PHASE2_BACKEND_COMPLETE.md
│   ├── PHASE2_COMPLETE.md
│   ├── PHASE2_COMPLETE_FINAL.md
│   ├── PHASE2_FINAL_PAGES.md
│   ├── PHASE2_FRONTEND_PROGRESS.md
│   ├── PHASE3_COMPLETE.md
│   ├── PHASE4_SUMMARY.md
│   ├── PHASE4_REMAINING_TASKS.md
│   ├── PROGRESS.md                    # Progrès général du projet
│   ├── CHANGES_SUMMARY.md
│   ├── COMPLETION-REPORT.md
│   ├── IMPLEMENTATION_COMPLETE.md
│   ├── IMPLEMENTATION_SUMMARY.md
│   ├── READY.md
│   ├── READY_FOR_TESTING.md
│   ├── SESSION_SUMMARY.md
│   ├── INDEX.md
│   └── NEXT-STEPS.md
│
├── testing/                           # 🧪 Tests et Qualité
│   ├── TEST_EXECUTION_GUIDE.md       # Guide d'exécution des tests
│   ├── TEST_COVERAGE_REPORT.md       # Rapport de couverture
│   ├── GUIDE_TESTS_POSTMAN.md        # Tests API avec Postman
│   ├── MANUAL_TEST_INSTRUCTIONS.md   # Instructions de tests manuels
│   └── LOCAL_TESTING.md              # Tests en environnement local
│
├── architecture/                      # 🏗️ Architecture Technique
│   ├── ARCHITECTURE.md               # Documentation architecture complète
│   ├── BOOKING_WORKFLOW_TODO.md      # Workflow de réservation
│   ├── DASHBOARD_API_INTEGRATION.md  # Intégration API dashboard
│   ├── EMAIL_IMPLEMENTATION_STATUS.md # Statut implémentation emails
│   ├── DISCORD_NOTIFICATIONS.md      # Notifications Discord
│   └── RESUME_FRANCAIS.md            # Résumé en français
│
├── carrier-portal/                    # 🚢 Portail Transporteur
│   ├── CARRIER_PORTAL_IMPLEMENTATION_PLAN.md
│   └── CARRIER_API_RESEARCH.md
│
├── csv-system/                        # 📊 Système CSV
│   ├── CSV_RATE_SYSTEM.md
│   ├── CSV_API_TEST_GUIDE.md
│   ├── CSV_BOOKING_WORKFLOW_TEST_PLAN.md
│   ├── ALGO_BOOKING_CSV_IMPLEMENTATION.md
│   └── ALGO_BOOKING_SUMMARY.md
│
├── debug/                             # 🐛 Debug et Résolution de Problèmes
│   ├── USER_DISPLAY_SOLUTION.md
│   ├── USER_INFO_DEBUG_ANALYSIS.md
│   ├── NOTIFICATION_IMPROVEMENTS.md
│   └── elementmissingphase2.md
│
├── backend/                           # 🔧 Documentation Backend
│   └── cleanup-report.md
│
└── frontend/                          # 🎨 Documentation Frontend
    └── cleanup-report.md

---

🎯 Par où commencer ?

1️⃣ Nouveau sur le projet ?

Commencez par ces fichiers dans cet ordre:

1. 📖 ../README.md - Vue d'ensemble du projet
2. 📘 ../CLAUDE.md - Guide complet d'implémentation (1000+ lignes)
3. 🏗️ architecture.md - Architecture technique
4. 🔧 installation/QUICK-START.md - Démarrage rapide

2️⃣ Installation du projet ?

Suivez ces guides:

1. installation/INSTALLATION-STEPS.md - Guide complet
2. installation/QUICK-START.md - Démarrage rapide
3. installation/WINDOWS-INSTALLATION.md - Spécifique Windows

3️⃣ Déploiement en production ?

Documentation de déploiement:

1. deployment/DEPLOYMENT.md - Guide principal
2. deployment/DEPLOYMENT_CHECKLIST.md - Checklist
3. deployment/PORTAINER_DEPLOY_FINAL.md - Portainer

4️⃣ Corriger les problèmes identifiés ?

Plan d'action:

1. AUDIT-FINAL-REPORT.md - Résumé exécutif
2. backend/cleanup-report.md - Actions backend
3. frontend/cleanup-report.md - Actions frontend
4. decisions.md - ADRs (Architecture Decision Records)

5️⃣ Travailler sur une fonctionnalité spécifique ?

Par domaine:

• 🚢 Portail Transporteur: carrier-portal/
• 📊 Système CSV: csv-system/
• 🧪 Tests: testing/
• 🏗️ Architecture: architecture/

---

📚 Documentation Clé

⭐ Fichiers Essentiels (à lire en priorité)

Fichier	Description	Quand le lire
architecture.md	Architecture globale du système	Onboarding, création module
AUDIT-FINAL-REPORT.md	Rapport d'audit complet	Immédiatement si problèmes
decisions.md	Décisions architecturales (ADRs)	Avant décision importante
backend/cleanup-report.md	Plan de nettoyage backend	Travail sur backend
frontend/cleanup-report.md	Plan de nettoyage frontend	Travail sur frontend

---

🔍 Recherche Rapide par Thème

Installation & Setup

• Installation complète
• Démarrage rapide
• Windows

Déploiement

• Guide déploiement
• Checklist
• Portainer
• Docker
• CI/CD

Architecture & Développement

• Architecture hexagonale
• Workflow réservation
• API Dashboard
• Emails

Tests

• Guide d'exécution
• Couverture de code
• Tests Postman
• Tests manuels

Fonctionnalités Spécifiques

• Portail Transporteur
• Système CSV
• Notifications Discord

Historique du Projet

• Phases de développement
• Progrès général
• Résumés de phases

---

🚀 Commandes Rapides

Vérification Conformité Backend

# Aucun import NestJS dans domain
grep -r "from '@nestjs" apps/backend/src/domain/
# Résultat attendu: Aucun résultat

# Tous les tests passent
cd apps/backend && npm test

# Coverage
npm run test:cov

Vérification Frontend

cd apps/frontend

# Vérification TypeScript
npm run type-check

# Analyser bundle
npm run build
npx @next/bundle-analyzer

# Détecter code mort
npx depcheck

Tests

# Backend
cd apps/backend
npm test                      # Unit tests
npm run test:integration      # Integration tests
npm run test:e2e              # E2E tests

# Frontend
cd apps/frontend
npm test                      # Component tests
npx playwright test           # E2E tests

---

📊 Métriques Clés

Backend

Métrique	Valeur Actuelle	Cible
Conformité hexagonale	95%	100%
Coverage tests domain	90%+	90%+
Violations critiques	1	0
Code mort	2-3 fichiers	0

Frontend

Métrique	Valeur Actuelle	Cible
TypeScript strict	❌	✅
Code mort	8-10 fichiers	0
Pagination	Client (1000)	Serveur (20)
Temps chargement	2-3s	300ms

---

🆘 Questions Fréquentes

Q: Par où commencer pour corriger les problèmes ? A: Lire AUDIT-FINAL-REPORT.md section "Priorité 1"

Q: Comment vérifier que j'ai tout corrigé ? A: Utiliser les checklists dans cleanup-report.md et commandes de vérification

Q: Je veux comprendre pourquoi cette décision ? A: Consulter decisions.md pour l'ADR correspondant

Q: C'est quoi l'architecture hexagonale ? A: Lire architecture.md section "Architecture Hexagonale"

Q: Je dois créer un nouveau module, comment faire ? A: Suivre ../CLAUDE.md section "Adding a New Feature"

Q: Comment déployer en production ? A: Suivre deployment/DEPLOYMENT.md et la checklist

---

🔗 Liens Externes Utiles

Références Techniques

• Hexagonal Architecture - Alistair Cockburn
• Clean Architecture - Uncle Bob
• Architecture Decision Records
• React Query Best Practices
• TypeScript Strict Mode

Documentation Projet

• README Principal
• CLAUDE.md - Guide Complet
• Product Requirements (PRD)
• TODO du Projet

---

📝 Maintenance de la Documentation

Quand Mettre à Jour

architecture.md:

• Ajout/suppression de modules
• Changement de pattern architectural majeur
• Nouveau pattern de sécurité

AUDIT-FINAL-REPORT.md:

• Après chaque audit complet (trimestriel recommandé)
• Après corrections majeures
• Changement de scores/métriques

cleanup-report.md (backend/frontend):

• Après nettoyage du code mort
• Après résolution violations
• Nouvelles violations identifiées

decisions.md:

• Chaque décision architecturale importante
• Utiliser template fourni
• Maintenir l'index à jour

Comment Contribuer

1. Suivre la structure de dossiers établie
2. Utiliser des noms de fichiers descriptifs en SCREAMING_CASE
3. Inclure une section "Dernière mise à jour" dans chaque document
4. Mettre à jour ce README.md si nouvelle catégorie ajoutée

---

📅 Historique

• 2025-12-22: Réorganisation complète de la documentation en dossiers thématiques
• 2025-12-22: Création rapport d'audit complet et cleanup reports
• 2024-11-XX: Phases 1-4 de développement complétées

---

Version: 2.0.0 Dernière mise à jour: 2025-12-22 Maintenance: Architecture Team

Bon développement ! 🚀