ansiblenginx/app/bricolociaac/docs/roadmap.md

# 🗺️ Roadmap du Projet BricoLoc Architecture Evolution

**Période** : 10 semaines (Octobre - Décembre 2025)  
**Effort estimé** : 215 heures  
**Équipe** : 1-2 développeurs

---

## 📋 Vue d'Ensemble

### Objectif Principal

Créer **deux applications complètes** démontrant l'évolution architecturale de BricoLoc :
- **Legacy** : Monolithe Node.js/Express avec bugs intentionnels
- **Moderne** : Architecture microservices hybride avec Next.js/Supabase

### Livrables Clés

1. ✅ **Documentation Architecture** (Semaines 1-2)
2. 🚧 **Application Legacy** (Semaines 3-4)
3. 🚧 **Application Moderne** (Semaines 5-9)
4. 🚧 **Comparaison & Présentation** (Semaine 10)

---

## 📅 Planning par Sprints

### Sprint 0 : Fondations (Semaines 1-2) - 40h

**Objectif** : Poser les bases documentaires et techniques

#### Semaine 1 : Documentation Architecture (20h)

- [x] ✅ Structurer le mono-repo
- [x] ✅ Rédiger README.md et ARCHITECTURE.md
- [x] ✅ Créer Cahier des Charges
- [x] ✅ Rédiger ADR (5 documents)
- [x] ✅ Créer diagrammes C4 (Mermaid)
- [x] ✅ Roadmap détaillée

**Livrables** :
- ✅ Dossier `docs/` complet
- ✅ 5 ADR documentés
- ✅ Diagrammes d'architecture

#### Semaine 2 : Setup Technique (20h)

- [x] ✅ Initialiser Git et `.gitignore`
- [x] ✅ Configurer pnpm workspaces
- [x] ✅ Setup ESLint + Prettier + TypeScript
- [x] ✅ Créer structure Legacy (`apps/legacy-app/`)
- [ ] 🔲 Créer structure Moderne (`apps/moderne/`)
- [ ] 🔲 Setup Supabase (projet + tables de base)
- [ ] 🔲 Configuration CI/CD (GitHub Actions)

**Livrables** :
- [x] ✅ Repository Git initialisé
- [x] ✅ Workspaces fonctionnels
- [x] ✅ Structure Legacy complète
- [ ] 🔲 Supabase configuré
- [ ] 🔲 CI/CD de base

---

### Sprint 1 : Application Legacy (Semaines 3-4) - 40h

**Objectif** : Créer un monolithe fonctionnel avec bugs intentionnels

#### Semaine 3 : Backend Legacy (20h)

**User Stories** :
- [ ] 🔲 **US-L01** : En tant qu'utilisateur, je peux créer un compte (sans validation email)
- [ ] 🔲 **US-L02** : En tant qu'utilisateur, je peux me connecter
- [ ] 🔲 **US-L03** : En tant que visiteur, je peux voir la liste des outils
- [ ] 🔲 **US-L04** : En tant qu'utilisateur, je peux voir les détails d'un outil

**Tâches techniques** :
```yaml
- Setup Express.js + EJS
- Configuration SQLite
- Middleware d'authentification (sessions)
- Routes : /login, /register, /outils, /outils/:id
- Modèle monolithique (tout dans server.js)
- CSS basique (styles.css)
```

**Bugs intentionnels** :
1. ❌ Pas de validation email format
2. ❌ Mot de passe en clair dans DB
3. ❌ Pas de protection CSRF
4. ❌ SQL Injection possible
5. ❌ Pas de gestion d'erreurs

**Livrables** :
- [ ] Application Express fonctionnelle
- [ ] 4 US implémentées
- [ ] 5 bugs documentés

#### Semaine 4 : Frontend Legacy + Réservations (20h)

**User Stories** :
- [ ] 🔲 **US-L05** : En tant qu'utilisateur, je peux créer une réservation
- [ ] 🔲 **US-L06** : En tant qu'utilisateur, je peux voir mes réservations
- [ ] 🔲 **US-L07** : En tant qu'admin, je peux gérer l'inventaire (CRUD outils)

**Tâches techniques** :
```yaml
- Templates EJS : index.ejs, outils.ejs, reservations.ejs, admin.ejs
- Routes : /reservations, /admin/outils
- Logique de réservation (conflits de dates)
- Dashboard admin basique
```

**Bugs intentionnels supplémentaires** :
6. ❌ Pas de vérification disponibilité stock
7. ❌ Double-booking possible
8. ❌ Pas de pagination (performance)
9. ❌ Code dupliqué partout
10. ❌ Pas de tests

**Livrables** :
- [ ] 7 US complètes
- [ ] Application déployable
- [ ] Document "Bugs Legacy" (liste exhaustive)

**Critères d'acceptation** :
- ✅ Application fonctionnelle de bout en bout
- ✅ 10+ bugs identifiés et documentés
- ✅ Score Lighthouse < 60

---

### Sprint 2 : Foundation Moderne (Semaines 5-6) - 40h

**Objectif** : Poser les bases de l'architecture microservices

#### Semaine 5 : Setup Next.js + Microservices Structure (20h)

**Tâches techniques** :
```yaml
- Initialiser Next.js 14 (App Router)
- Configuration TypeScript strict
- Setup Tailwind CSS + shadcn/ui
- Structure microservices :
  - packages/microservices/auth/
  - packages/microservices/catalogue/
  - packages/microservices/reservation/
  - packages/microservices/inventory/
  - packages/microservices/payment/
  - packages/microservices/notification/
- Shared packages :
  - packages/shared/types/
  - packages/shared/ui/ (composants)
  - packages/shared/utils/
  - packages/shared/di/ (Dependency Injection)
  - packages/shared/events/ (Event Bus)
```

**Livrables** :
- [ ] Structure microservices complète
- [ ] Shared packages configurés
- [ ] Next.js fonctionnel

#### Semaine 6 : Auth Service + Supabase (20h)

**User Stories** :
- [ ] 🔲 **US-M01** : En tant qu'utilisateur, je peux créer un compte (avec validation email)
- [ ] 🔲 **US-M02** : En tant qu'utilisateur, je peux me connecter (OAuth Google optionnel)

**Tâches techniques** :
```yaml
- Configuration Supabase Auth
- Row Level Security (RLS) policies
- Auth Service :
  - domain/entities/User.ts
  - application/use-cases/RegisterUser.ts
  - infrastructure/repositories/SupabaseAuthRepository.ts
- Pages Next.js :
  - app/auth/login/page.tsx
  - app/auth/register/page.tsx
- Middleware auth Next.js
- Tests unitaires (Auth Service)
```

**Livrables** :
- [ ] Auth Service complet (Clean Architecture)
- [ ] Authentification fonctionnelle
- [ ] Tests unitaires > 80% coverage

---

### Sprint 3 : Catalogue & Inventory Services (Semaines 7-8) - 50h

**Objectif** : Gestion des outils et stocks

#### Semaine 7 : Catalogue Service (25h)

**User Stories** :
- [ ] 🔲 **US-M03** : En tant que visiteur, je peux rechercher des outils (avec filtres)
- [ ] 🔲 **US-M04** : En tant qu'utilisateur, je peux voir les détails d'un outil (avec images)
- [ ] 🔲 **US-M05** : En tant qu'admin, je peux créer/modifier/supprimer un outil

**Tâches techniques** :
```yaml
Catalogue Service :
  domain/
    - entities/Outil.ts
    - entities/Categorie.ts
    - repositories/IOutilRepository.ts
  application/
    - use-cases/SearchOutils.ts
    - use-cases/GetOutilDetails.ts
    - use-cases/ManageOutil.ts (CRUD)
    - services/CatalogueService.ts
  infrastructure/
    - repositories/SupabaseCatalogueRepository.ts
    - external/SupabaseStorageService.ts (upload images)

API Routes :
  - app/api/outils/route.ts (GET, POST)
  - app/api/outils/[id]/route.ts (GET, PUT, DELETE)
  - app/api/categories/route.ts

Pages :
  - app/outils/page.tsx (liste avec recherche)
  - app/outils/[id]/page.tsx (détails)
  - app/admin/outils/page.tsx (gestion)

Tests :
  - Unit tests (CatalogueService, repositories)
  - Integration tests (API routes)
```

**Patterns appliqués** :
- ✅ Repository Pattern
- ✅ Service Layer
- ✅ Dependency Injection
- ✅ Factory Pattern (OutilFactory)

**Livrables** :
- [ ] Catalogue Service complet
- [ ] 3 US fonctionnelles
- [ ] Tests > 80% coverage

#### Semaine 8 : Inventory Service (25h)

**User Stories** :
- [ ] 🔲 **US-M06** : En tant qu'utilisateur, je vois la disponibilité en temps réel
- [ ] 🔲 **US-M07** : En tant qu'admin, je peux gérer les stocks par entrepôt

**Tâches techniques** :
```yaml
Inventory Service :
  domain/
    - entities/Stock.ts
    - entities/Entrepot.ts
    - repositories/IInventoryRepository.ts
  application/
    - use-cases/CheckAvailability.ts
    - use-cases/ReserveStock.ts
    - use-cases/ReleaseStock.ts
    - services/InventoryService.ts
  infrastructure/
    - repositories/SupabaseInventoryRepository.ts
    - listeners/ReservationListener.ts (Event Bus)

Event Bus Integration :
  - Subscribe to 'reservation.created'
  - Subscribe to 'reservation.cancelled'
  - Publish 'inventory.updated'

Real-time avec Supabase Realtime :
  - Channel 'stock-updates'
  - Broadcast changes to clients

API Routes :
  - app/api/inventory/availability/route.ts
  - app/api/inventory/entrepots/route.ts

Tests :
  - Unit tests (InventoryService)
  - Event Bus tests (mocked)
  - Real-time tests (integration)
```

**Patterns appliqués** :
- ✅ Observer Pattern (Event Bus)
- ✅ Repository Pattern
- ✅ Service Layer

**Livrables** :
- [ ] Inventory Service complet
- [ ] Event Bus fonctionnel
- [ ] Real-time updates opérationnels

---

### Sprint 4 : Reservation & Payment Services (Semaine 9) - 25h

**Objectif** : Boucle complète de réservation avec paiement

#### Semaine 9 : Reservation + Payment Services (25h)

**User Stories** :
- [ ] 🔲 **US-M08** : En tant qu'utilisateur, je peux créer une réservation (avec vérification dispo)
- [ ] 🔲 **US-M09** : En tant qu'utilisateur, je peux payer ma réservation (Stripe)
- [ ] 🔲 **US-M10** : En tant qu'utilisateur, je reçois un email de confirmation

**Tâches techniques** :
```yaml
Reservation Service :
  domain/
    - entities/Reservation.ts
    - repositories/IReservationRepository.ts
    - factories/ReservationFactory.ts (pricing logic)
  application/
    - use-cases/CreateReservation.ts
    - use-cases/CancelReservation.ts
    - use-cases/GetMyReservations.ts
    - services/ReservationService.ts
  infrastructure/
    - repositories/SupabaseReservationRepository.ts
    - events/ReservationEventPublisher.ts

Payment Service :
  domain/
    - entities/Payment.ts
    - repositories/IPaymentRepository.ts
  application/
    - use-cases/ProcessPayment.ts
    - services/PaymentService.ts
  infrastructure/
    - repositories/SupabasePaymentRepository.ts
    - external/StripeService.ts (API Stripe)
    - listeners/ReservationPaymentListener.ts

Notification Service :
  application/
    - services/NotificationService.ts
  infrastructure/
    - external/EmailService.ts (Resend/SendGrid)
    - listeners/ReservationNotificationListener.ts

API Routes :
  - app/api/reservations/route.ts (GET, POST)
  - app/api/reservations/[id]/route.ts (GET, DELETE)
  - app/api/payments/route.ts (POST)
  - app/api/payments/stripe-webhook/route.ts (Stripe webhook)

Pages :
  - app/reservations/page.tsx (mes réservations)
  - app/outils/[id]/reserver/page.tsx (formulaire réservation)
  - app/checkout/[reservationId]/page.tsx (paiement)

Event Flow :
  1. reservation.created → Inventory reserves stock
  2. reservation.created → Notification sends email
  3. payment.succeeded → Reservation status = CONFIRMED
  4. reservation.cancelled → Inventory releases stock
```

**Patterns appliqués** :
- ✅ Factory Pattern (ReservationFactory)
- ✅ Observer Pattern (Event Bus multi-subscribers)
- ✅ Saga Pattern (simple orchestration)

**Livrables** :
- [ ] 3 microservices fonctionnels
- [ ] Flux complet de réservation
- [ ] Paiement Stripe intégré
- [ ] Notifications email

---

### Sprint 5 : Finitions & Comparaison (Semaine 10) - 20h

**Objectif** : Finalisation et documentation de comparaison

#### Semaine 10 : Comparaison, Performance, Présentation (20h)

**Tâches** :
```yaml
Comparaison Legacy vs Moderne :
  - Lighthouse scores (Performance, SEO, Best Practices)
  - Metrics de code (Complexité cyclomatique, duplication)
  - Tests coverage comparison
  - Bundle size analysis

Documentation :
  - Document de comparaison (docs/comparaison.md)
  - Tableau de bord metrics (Markdown)
  - Screenshots avant/après
  - Vidéo démo (5-10 min)

Présentation :
  - Slides (PowerPoint/Keynote/Reveal.js)
  - Structure :
    1. Contexte et problématique
    2. Architecture Legacy (problèmes)
    3. Architecture Moderne (solutions)
    4. Comparaison chiffrée
    5. Patterns appliqués
    6. Démonstration live
    7. Retours d'expérience
  - Durée : 20-30 min

Finitions :
  - Fixes bugs critiques
  - README.md mis à jour
  - CONTRIBUTING.md
  - LICENSE
  - Deploy final (Vercel)
```

**Livrables** :
- [ ] Document de comparaison complet
- [ ] Présentation professionnelle
- [ ] Applications déployées
- [ ] Vidéo démo

---

## 🎯 User Stories Complètes

### Application Legacy (7 US)

| ID | User Story | Sprint | Statut |
|----|-----------|--------|--------|
| US-L01 | En tant qu'utilisateur, je peux créer un compte | Sprint 1 | 🔲 |
| US-L02 | En tant qu'utilisateur, je peux me connecter | Sprint 1 | 🔲 |
| US-L03 | En tant que visiteur, je peux voir la liste des outils | Sprint 1 | 🔲 |
| US-L04 | En tant qu'utilisateur, je peux voir les détails d'un outil | Sprint 1 | 🔲 |
| US-L05 | En tant qu'utilisateur, je peux créer une réservation | Sprint 1 | 🔲 |
| US-L06 | En tant qu'utilisateur, je peux voir mes réservations | Sprint 1 | 🔲 |
| US-L07 | En tant qu'admin, je peux gérer l'inventaire | Sprint 1 | 🔲 |

### Application Moderne (10 US + 2 optionnelles)

| ID | User Story | Sprint | Statut |
|----|-----------|--------|--------|
| US-M01 | En tant qu'utilisateur, je peux créer un compte avec validation | Sprint 2 | 🔲 |
| US-M02 | En tant qu'utilisateur, je peux me connecter (OAuth optionnel) | Sprint 2 | 🔲 |
| US-M03 | En tant que visiteur, je peux rechercher des outils avec filtres | Sprint 3 | 🔲 |
| US-M04 | En tant qu'utilisateur, je peux voir les détails d'un outil avec images | Sprint 3 | 🔲 |
| US-M05 | En tant qu'admin, je peux gérer les outils (CRUD) | Sprint 3 | 🔲 |
| US-M06 | En tant qu'utilisateur, je vois la disponibilité en temps réel | Sprint 3 | 🔲 |
| US-M07 | En tant qu'admin, je peux gérer les stocks par entrepôt | Sprint 3 | 🔲 |
| US-M08 | En tant qu'utilisateur, je peux créer une réservation avec vérification | Sprint 4 | 🔲 |
| US-M09 | En tant qu'utilisateur, je peux payer ma réservation (Stripe) | Sprint 4 | 🔲 |
| US-M10 | En tant qu'utilisateur, je reçois un email de confirmation | Sprint 4 | 🔲 |
| US-M11 (opt) | En tant qu'utilisateur, je peux laisser un avis sur un outil | - | ⏸️ |
| US-M12 (opt) | En tant qu'admin, je vois un dashboard analytics | - | ⏸️ |

---

## 📊 Métriques de Succès

### Métriques Techniques

| Métrique | Legacy | Moderne | Objectif |
|----------|--------|---------|----------|
| **Lighthouse Performance** | < 60 | > 90 | ✅ |
| **Tests Coverage** | 0% | > 80% | ✅ |
| **Bundle Size** | ~500 KB | < 200 KB | ✅ |
| **Time to Interactive (TTI)** | > 5s | < 2s | ✅ |
| **Complexité Cyclomatique** | > 20 | < 10 | ✅ |
| **Code Duplication** | > 30% | < 5% | ✅ |

### Métriques Fonctionnelles

- ✅ **7 US Legacy** implémentées
- ✅ **10 US Moderne** implémentées
- ✅ **10+ bugs Legacy** documentés
- ✅ **0 bug critique Moderne**
- ✅ **100% features comparables**

### Métriques Architecturales

- ✅ **5 ADR** rédigés
- ✅ **3 niveaux C4** diagrammés
- ✅ **5 patterns** appliqués
- ✅ **6 microservices** implémentés
- ✅ **Clean Architecture** respectée

---

## 🚀 Déploiement

### Environnements

| Environnement | URL | Usage |
|---------------|-----|-------|
| **Dev Local** | `localhost:3000` (Legacy) <br> `localhost:3001` (Moderne) | Développement |
| **Staging** | `staging-legacy.vercel.app` <br> `staging-moderne.vercel.app` | Tests |
| **Production** | `bricoloc-legacy.vercel.app` <br> `bricoloc-moderne.vercel.app` | Démo finale |

### CI/CD Pipeline

```yaml
GitHub Actions :
  - on: [push, pull_request]
  - jobs:
    - lint (ESLint + Prettier)
    - type-check (TypeScript)
    - test (Jest + React Testing Library)
    - build (Next.js build)
    - lighthouse (Lighthouse CI)
    - deploy (Vercel)
```

---

## 🎓 Compétences Démontrées

### Architecture Logicielle

- ✅ Décomposition en microservices
- ✅ Clean Architecture (Domain-Driven Design)
- ✅ Event-Driven Architecture
- ✅ API Gateway / BFF Pattern

### Design Patterns

- ✅ Repository Pattern
- ✅ Service Layer Pattern
- ✅ Dependency Injection
- ✅ Factory Pattern
- ✅ Observer Pattern (Event Bus)

### Principes SOLID

- ✅ **S**ingle Responsibility Principle
- ✅ **O**pen/Closed Principle
- ✅ **L**iskov Substitution Principle
- ✅ **I**nterface Segregation Principle
- ✅ **D**ependency Inversion Principle

### Technologies Modernes

- ✅ Next.js 14 (App Router, SSR, ISR)
- ✅ TypeScript (strict mode)
- ✅ Supabase (PostgreSQL, Auth, Realtime, Storage)
- ✅ Tailwind CSS + shadcn/ui
- ✅ Testing (Jest, React Testing Library, Playwright)

---

## 📝 Documentation Livrée

```
docs/
├── specifications/
│   └── cahier-des-charges.md           ✅
├── architecture/
│   ├── ARCHITECTURE.md                 ✅
│   ├── c4-diagrams.md                  ✅
│   └── ADR/
│       ├── 001-mono-repo.md            ✅
│       ├── 002-framework-frontend.md   ✅
│       ├── 003-backend-supabase.md     ✅
│       ├── 004-architecture-microservices.md ✅
│       └── 005-patterns-conception.md  ✅
├── comparaison/
│   ├── comparaison.md                  🔲
│   ├── metrics.md                      🔲
│   └── screenshots/                    🔲
├── guides/
│   ├── setup-wsl.md                    🔲
│   ├── git-workflow.md                 🔲
│   ├── coding-standards.md             🔲
│   └── CONTRIBUTING.md                 🔲
└── presentation/
    ├── slides.md                       🔲
    └── demo-script.md                  🔲
```

---

## ⚠️ Risques & Mitigations

| Risque | Probabilité | Impact | Mitigation |
|--------|-------------|--------|------------|
| **Complexité Event Bus** | Moyenne | Élevé | Simplifier avec Supabase Realtime, tests robustes |
| **Délais Stripe Setup** | Faible | Moyen | Utiliser Stripe Test Mode dès le début |
| **Supabase Quotas** | Faible | Moyen | Plan gratuit suffisant, upgrade si besoin |
| **Scope Creep** | Élevée | Élevé | US optionnelles clairement identifiées (US-M11, US-M12) |
| **Bugs Legacy non maîtrisés** | Moyenne | Faible | Liste documentée, testing manuel |

---

## 🎬 Prochaines Actions Immédiates

### Cette semaine (Semaine 2)

1. [ ] 🔲 Initialiser Git repository
2. [ ] 🔲 Configurer pnpm workspaces
3. [ ] 🔲 Setup ESLint + Prettier + TypeScript
4. [ ] 🔲 Créer structure apps/ et packages/
5. [ ] 🔲 Setup Supabase (créer projet, tables auth)
6. [ ] 🔲 Premier commit "Initial project structure"

### Semaine prochaine (Semaine 3)

1. [ ] 🔲 Commencer Application Legacy (Express.js)
2. [ ] 🔲 Implémenter US-L01 à US-L04
3. [ ] 🔲 Introduire premiers bugs intentionnels

---

**Dernière mise à jour** : Octobre 2025  
**Prochaine révision** : Fin Sprint 1 (Semaine 4)