ansiblenginx/app/bricolociaac/apps/modern-app/docs/ROADMAP_MODERN.md

# 🗺️ Roadmap Application Moderne BricoLoc

**Objectif** : Créer une application moderne avec architecture microservices hybride démontrant les bonnes pratiques architecturales et les patterns de conception avancés.

**Durée** : 5 semaines (Semaines 5-9 du projet global)  
**Effort** : 135 heures  
**Stack technique** : Next.js 14, TypeScript, Supabase, Tailwind CSS, shadcn/ui

---

## 📊 État d'Avancement

**Dernière mise à jour** : 2 Novembre 2025

| Phase | Statut | Progression | Temps estimé |
|-------|--------|-------------|--------------|
| **Semaine 5 - Setup & Structure** | ✅ Terminé | 100% | 20h |
| **Semaine 6 - Auth Service** | 🔲 À démarrer | 0% | 20h |
| **Semaine 7 - Catalogue Service** | 🔲 À démarrer | 0% | 25h |
| **Semaine 8 - Inventory Service** | 🔲 À démarrer | 0% | 25h |
| **Semaine 9 - Reservation/Payment** | 🔲 À démarrer | 0% | 25h |
| **Semaine 10 - Finitions** | 🔲 À démarrer | 0% | 20h |

**Progression globale** : ■■⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜ 17% (1/6 phases)

---

## 🎯 Objectifs Clés

### Démontrer les Bonnes Pratiques

1. ✅ **Architecture Microservices Hybride**
   - Décomposition en services autonomes
   - Communication REST + Event-Driven
   - API Gateway / BFF pattern

2. ✅ **Clean Architecture par Service**
   - Domain Layer (Entities, Business Rules)
   - Application Layer (Use Cases, Services)
   - Infrastructure Layer (Repositories, External APIs)
   - Separation of Concerns stricte

3. ✅ **Design Patterns**
   - Repository Pattern
   - Service Layer Pattern
   - Dependency Injection
   - Factory Pattern
   - Observer Pattern (Event Bus)

4. ✅ **Principes SOLID**
   - Single Responsibility Principle
   - Open/Closed Principle
   - Liskov Substitution Principle
   - Interface Segregation Principle
   - Dependency Inversion Principle

5. ✅ **Tests & Qualité**
   - Tests unitaires (80%+ coverage)
   - Tests d'intégration
   - Tests E2E (Playwright)
   - TypeScript strict mode
   - ESLint + Prettier

6. ✅ **Performance & UX**
   - Server-Side Rendering (SSR)
   - Static Site Generation (SSG)
   - Optimistic UI updates
   - Real-time updates (Supabase Realtime)
   - Lighthouse score > 90

---

## 📋 Livrables Attendus

### Livrables Alignés avec le Cahier des Charges

D'après le document `livrables.md`, nous devons fournir :

#### 1. Schéma de la Couche Applicative du SI ✅
- **Localisation** : `docs/architecture/c4-diagrams.md`
- **Contenu** : Diagrammes C4 montrant les applications et leurs interactions
- **Status** : ✅ Complété (Sprint 0)

#### 2. Démarche de Conception de l'Architecture ✅
- **Localisation** : `apps/modern-app/docs/ARCHITECTURE_DECISION_PROCESS.md`
- **Contenu** : 
  - Analyse des besoins et contraintes
  - Identification des exigences non fonctionnelles
  - Évaluation des styles architecturaux
  - Justification des choix
- **Status** : ✅ Complété (Semaine 5) - Voir ADRs dans `docs/architecture/ADR/`

#### 3. Liste des Exigences Non Fonctionnelles ✅
- **Localisation** : `apps/modern-app/docs/NON_FUNCTIONAL_REQUIREMENTS.md`
- **Contenu** :
  - Performance (temps de réponse, throughput)
  - Scalabilité (horizontal, vertical)
  - Maintenabilité (modularité, testabilité)
  - Sécurité (authentification, autorisation, chiffrement)
  - Disponibilité (uptime, résilience)
  - Utilisabilité (UX, accessibilité)
- **Status** : ✅ Complété (Semaine 5)

#### 4. Schéma d'Architecture Logique ✅
- **Localisation** : `apps/modern-app/docs/LOGICAL_ARCHITECTURE.md`
- **Contenu** :
  - Décomposition en composants métiers
  - Interactions entre composants
  - Dépendances fonctionnelles
  - Sans détails techniques (technos, déploiement)
- **Status** : ✅ Complété (Semaine 5)

#### 5. Comparaison des Styles Architecturaux ✅
- **Localisation** : `apps/modern-app/docs/ARCHITECTURE_STYLES_COMPARISON.md`
- **Contenu** :
  - Monolithe vs Microservices
  - Layered vs Clean Architecture
  - REST vs GraphQL vs gRPC
  - Event-Driven vs Request-Response
  - Justification des choix retenus
- **Status** : ✅ Complété (Semaine 5)

#### 6. Template de Matrice de Choix Technologique ✅
- **Localisation** : `apps/modern-app/docs/TECHNOLOGY_DECISION_MATRIX.md`
- **Contenu** :
  - Critères d'évaluation (pondérés)
  - Système de cotation (1-5 étoiles)
  - Matrices complétées pour :
    - Framework Frontend (Next.js vs Remix vs Nuxt)
    - Backend (Supabase vs Firebase vs AWS Amplify)
    - Base de données (PostgreSQL vs MongoDB vs MySQL)
    - Event Bus (Supabase Realtime vs Redis Pub/Sub vs Kafka)
- **Status** : ✅ Complété (Semaine 5)

#### 7. Points Faibles du SI Actuel 🚧
- **Localisation** : `docs/SI_WEAKNESSES_ANALYSIS.md`
- **Contenu** :
  - Liste des points faibles identifiés
  - Impact sur l'évolution du SI
  - Justifications techniques
  - Propositions d'amélioration
- **Status** : 🔲 À créer (Semaine 5)

#### 8. Bilan sur l'Organisation du Groupe 🚧
- **Localisation** : `docs/TEAM_RETROSPECTIVE.md`
- **Contenu** :
  - Points forts de l'équipe
  - Axes d'amélioration
  - Méthode de travail
  - Communication et collaboration
- **Status** : 🔲 À créer (Semaine 10)

#### 9. Support de Présentation (PowerPoint) 🚧
- **Localisation** : `docs/presentation/BricoLoc_Presentation.pptx`
- **Contenu** : Synthèse de tous les éléments ci-dessus
- **Status** : 🔲 À créer (Semaine 10)

---

## 🏗️ Architecture Technique

### Stack Complète

```yaml
# Frontend
Framework: Next.js 14 (App Router)
Language: TypeScript 5.3 (strict mode)
UI Library: React 18
Styling: Tailwind CSS 3.4
Components: shadcn/ui
State Management: Zustand + React Query
Forms: React Hook Form + Zod

# Backend (BFF + Microservices)
API: Next.js API Routes (BFF pattern)
Microservices: Clean Architecture par service
Communication: REST + Event-Driven

# Database & Backend Services
BaaS: Supabase
Database: PostgreSQL 15
Auth: Supabase Auth (JWT)
Storage: Supabase Storage
Realtime: Supabase Realtime (WebSockets)
Functions: Supabase Edge Functions (optionnel)

# Testing
Unit Tests: Jest + React Testing Library
Integration Tests: Jest + Supertest
E2E Tests: Playwright
Coverage: > 80%

# DevOps
Version Control: Git + GitHub
CI/CD: GitHub Actions
Deployment: Vercel (Next.js) + Supabase (hébergé)
Monitoring: Vercel Analytics + Sentry (optionnel)

# Code Quality
Linting: ESLint (strict)
Formatting: Prettier
Type Checking: TypeScript strict mode
Git Hooks: Husky + lint-staged
```

---

## 📁 Structure du Projet

```
apps/modern-app/
├── src/
│   ├── app/                          # Next.js App Router
│   │   ├── (auth)/                   # Auth routes group
│   │   │   ├── login/
│   │   │   └── register/
│   │   ├── (main)/                   # Main app routes group
│   │   │   ├── outils/
│   │   │   ├── reservations/
│   │   │   └── admin/
│   │   ├── api/                      # API Routes (BFF)
│   │   │   ├── auth/
│   │   │   ├── catalogue/
│   │   │   ├── reservations/
│   │   │   ├── inventory/
│   │   │   ├── payment/
│   │   │   └── notifications/
│   │   ├── layout.tsx
│   │   └── page.tsx
│   │
│   ├── services/                     # Microservices (Business Logic)
│   │   ├── auth/
│   │   │   ├── domain/
│   │   │   │   ├── entities/
│   │   │   │   │   └── user.entity.ts
│   │   │   │   └── repositories/
│   │   │   │       └── auth.repository.interface.ts
│   │   │   ├── application/
│   │   │   │   ├── use-cases/
│   │   │   │   │   ├── register-user.use-case.ts
│   │   │   │   │   └── login-user.use-case.ts
│   │   │   │   └── services/
│   │   │   │       └── auth.service.ts
│   │   │   └── infrastructure/
│   │   │       └── repositories/
│   │   │           └── supabase-auth.repository.ts
│   │   │
│   │   ├── catalogue/
│   │   │   ├── domain/
│   │   │   ├── application/
│   │   │   └── infrastructure/
│   │   │
│   │   ├── reservation/
│   │   │   ├── domain/
│   │   │   ├── application/
│   │   │   └── infrastructure/
│   │   │
│   │   ├── inventory/
│   │   │   ├── domain/
│   │   │   ├── application/
│   │   │   └── infrastructure/
│   │   │
│   │   ├── payment/
│   │   │   ├── domain/
│   │   │   ├── application/
│   │   │   └── infrastructure/
│   │   │
│   │   └── notification/
│   │       ├── domain/
│   │       ├── application/
│   │       └── infrastructure/
│   │
│   ├── shared/                       # Code partagé
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   └── value-objects/
│   │   ├── infrastructure/
│   │   │   ├── di/                   # Dependency Injection
│   │   │   ├── events/               # Event Bus
│   │   │   └── supabase/
│   │   └── utils/
│   │
│   ├── components/                   # UI Components
│   │   ├── ui/                       # shadcn/ui components
│   │   ├── features/                 # Feature-specific components
│   │   └── layouts/
│   │
│   ├── hooks/                        # Custom React Hooks
│   ├── lib/                          # Utility libraries
│   └── types/                        # TypeScript types
│
├── public/
│   ├── images/
│   └── fonts/
│
├── docs/
│   ├── ROADMAP_MODERN.md            # Ce fichier
│   ├── ARCHITECTURE_DECISION_PROCESS.md
│   ├── NON_FUNCTIONAL_REQUIREMENTS.md
│   ├── LOGICAL_ARCHITECTURE.md
│   ├── ARCHITECTURE_STYLES_COMPARISON.md
│   └── TECHNOLOGY_DECISION_MATRIX.md
│
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
│
├── .github/
│   └── workflows/
│       └── ci.yml
│
├── next.config.js
├── tailwind.config.ts
├── tsconfig.json
├── jest.config.js
├── playwright.config.ts
├── .eslintrc.json
├── .prettierrc
└── package.json
```

---

## 📖 Documentation Détaillée par Semaine

Pour éviter un document trop long, la roadmap détaillée est divisée en plusieurs fichiers :

- 📄 [Semaine 5 - Setup & Structure](./WEEK_5_SETUP.md)
- 📄 [Semaine 6 - Auth Service](./WEEK_6_AUTH.md)
- 📄 [Semaine 7 - Catalogue Service](./WEEK_7_CATALOGUE.md)
- 📄 [Semaine 8 - Inventory Service](./WEEK_8_INVENTORY.md)
- 📄 [Semaine 9 - Reservation & Payment](./WEEK_9_RESERVATION_PAYMENT.md)
- 📄 [Semaine 10 - Finitions & Présentation](./WEEK_10_FINITIONS.md)

---

## 🎯 User Stories - Application Moderne

| ID | User Story | Semaine | Priorité | Statut |
|----|-----------|---------|----------|--------|
| **US-M01** | En tant qu'utilisateur, je peux créer un compte avec validation email | 6 | 🔴 Critique | 🔲 |
| **US-M02** | En tant qu'utilisateur, je peux me connecter (+ OAuth Google) | 6 | 🔴 Critique | 🔲 |
| **US-M03** | En tant que visiteur, je peux rechercher des outils avec filtres avancés | 7 | 🔴 Critique | 🔲 |
| **US-M04** | En tant qu'utilisateur, je peux voir les détails d'un outil avec galerie d'images | 7 | 🔴 Critique | 🔲 |
| **US-M05** | En tant qu'admin, je peux gérer les outils (CRUD complet) | 7 | 🟠 Important | 🔲 |
| **US-M06** | En tant qu'utilisateur, je vois la disponibilité en temps réel | 8 | 🔴 Critique | 🔲 |
| **US-M07** | En tant qu'admin, je peux gérer les stocks par entrepôt | 8 | 🟠 Important | 🔲 |
| **US-M08** | En tant qu'utilisateur, je peux créer une réservation avec vérification | 9 | 🔴 Critique | 🔲 |
| **US-M09** | En tant qu'utilisateur, je peux payer ma réservation (Stripe) | 9 | 🔴 Critique | 🔲 |
| **US-M10** | En tant qu'utilisateur, je reçois un email de confirmation | 9 | 🟠 Important | 🔲 |
| **US-M11** | En tant qu'utilisateur, je peux laisser un avis sur un outil | - | 🟢 Optionnel | ⏸️ |
| **US-M12** | En tant qu'admin, je vois un dashboard analytics | - | 🟢 Optionnel | ⏸️ |

---

## 🎨 Principes de Design & UX

### Design System

**Basé sur shadcn/ui** (Radix UI + Tailwind CSS)

```typescript
// Palette de couleurs
const colors = {
  primary: {
    DEFAULT: '#3b82f6', // blue-500
    dark: '#1e40af',    // blue-800
    light: '#93c5fd',   // blue-300
  },
  secondary: {
    DEFAULT: '#64748b', // slate-500
  },
  success: '#22c55e',   // green-500
  warning: '#f59e0b',   // amber-500
  error: '#ef4444',     // red-500
}

// Typography
const typography = {
  fontFamily: {
    sans: ['Inter', 'system-ui', 'sans-serif'],
    mono: ['Fira Code', 'monospace'],
  },
  fontSize: {
    xs: '0.75rem',    // 12px
    sm: '0.875rem',   // 14px
    base: '1rem',     // 16px
    lg: '1.125rem',   // 18px
    xl: '1.25rem',    // 20px
    '2xl': '1.5rem',  // 24px
    '3xl': '1.875rem',// 30px
    '4xl': '2.25rem', // 36px
  }
}
```

### Composants UI Réutilisables

Tous les composants suivent les principes shadcn/ui :
- **Accessibilité** (ARIA, keyboard navigation)
- **Responsive** (mobile-first)
- **Themable** (dark mode support)
- **Type-safe** (TypeScript)

Liste des composants à implémenter :
- ✅ Button, Input, Select, Checkbox, Radio
- ✅ Card, Dialog, Sheet, Popover, Tooltip
- ✅ Table, Pagination, Tabs
- ✅ Form (React Hook Form + Zod)
- ✅ Toast (notifications)
- ✅ Badge, Avatar, Separator
- ✅ Calendar, DatePicker

---

## 🧪 Stratégie de Tests

### Tests Unitaires (Jest)

**Coverage target** : > 80%

```typescript
// Exemple : tests d'un Use Case
describe('CreateReservationUseCase', () => {
  let useCase: CreateReservationUseCase
  let mockReservationRepo: jest.Mocked<IReservationRepository>
  let mockInventoryService: jest.Mocked<InventoryService>

  beforeEach(() => {
    mockReservationRepo = createMockReservationRepository()
    mockInventoryService = createMockInventoryService()
    useCase = new CreateReservationUseCase(
      mockReservationRepo,
      mockInventoryService
    )
  })

  it('should create a reservation when stock is available', async () => {
    // Arrange
    mockInventoryService.checkAvailability.mockResolvedValue(true)
    
    // Act
    const result = await useCase.execute({
      outilId: '123',
      userId: 'user1',
      dateDebut: '2025-11-01',
      dateFin: '2025-11-05'
    })
    
    // Assert
    expect(result.isSuccess).toBe(true)
    expect(mockReservationRepo.create).toHaveBeenCalledTimes(1)
  })

  it('should fail when stock is unavailable', async () => {
    // Arrange
    mockInventoryService.checkAvailability.mockResolvedValue(false)
    
    // Act
    const result = await useCase.execute({...})
    
    // Assert
    expect(result.isFailure).toBe(true)
    expect(result.error).toBe('Stock unavailable')
  })
})
```

### Tests d'Intégration

Tests des API Routes avec base de données réelle (Supabase local)

```typescript
describe('POST /api/reservations', () => {
  beforeAll(async () => {
    await setupTestDatabase()
  })

  afterAll(async () => {
    await cleanupTestDatabase()
  })

  it('should create a reservation with valid data', async () => {
    const response = await fetch('/api/reservations', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${testToken}`
      },
      body: JSON.stringify({
        outilId: 'test-outil-1',
        dateDebut: '2025-11-01',
        dateFin: '2025-11-05'
      })
    })

    expect(response.status).toBe(201)
    const data = await response.json()
    expect(data).toHaveProperty('id')
    expect(data.statut).toBe('en_attente_paiement')
  })
})
```

### Tests E2E (Playwright)

Tests du parcours utilisateur complet

```typescript
test('Parcours complet de réservation', async ({ page }) => {
  // 1. Connexion
  await page.goto('/login')
  await page.fill('[name="email"]', 'test@example.com')
  await page.fill('[name="password"]', 'password123')
  await page.click('button[type="submit"]')
  
  // 2. Recherche d'outil
  await page.goto('/outils')
  await page.fill('[name="search"]', 'Perceuse')
  await page.click('button:has-text("Rechercher")')
  
  // 3. Sélection d'outil
  await page.click('article:has-text("Perceuse Bosch") a')
  
  // 4. Création de réservation
  await page.click('button:has-text("Réserver")')
  await page.fill('[name="dateDebut"]', '2025-11-01')
  await page.fill('[name="dateFin"]', '2025-11-05')
  await page.selectOption('[name="entrepotId"]', 'toulouse')
  await page.click('button:has-text("Confirmer")')
  
  // 5. Vérification
  await expect(page.locator('text=Réservation créée')).toBeVisible()
})
```

---

## 📊 Métriques de Succès

### Métriques Techniques

| Métrique | Objectif | Mesure |
|----------|----------|--------|
| **Lighthouse Performance** | > 90 | Lighthouse CI |
| **Lighthouse Accessibility** | > 95 | Lighthouse CI |
| **Lighthouse Best Practices** | > 95 | Lighthouse CI |
| **Lighthouse SEO** | > 90 | Lighthouse CI |
| **Tests Coverage** | > 80% | Jest Coverage |
| **TypeScript Strict** | 100% | tsc --noEmit |
| **ESLint Errors** | 0 | ESLint |
| **Bundle Size (First Load JS)** | < 200 KB | Next.js Build |
| **Time to Interactive (TTI)** | < 2s | Lighthouse |
| **First Contentful Paint (FCP)** | < 1s | Lighthouse |
| **Largest Contentful Paint (LCP)** | < 2.5s | Lighthouse |
| **Cumulative Layout Shift (CLS)** | < 0.1 | Lighthouse |

### Métriques Fonctionnelles

- ✅ 10 User Stories principales implémentées
- ✅ 0 bug critique en production
- ✅ 100% des features Legacy reproduites (améliorées)
- ✅ Authentification OAuth fonctionnelle
- ✅ Temps réel opérationnel (stocks)
- ✅ Paiement Stripe intégré

### Métriques Architecturales

- ✅ 6 microservices implémentés avec Clean Architecture
- ✅ 5+ design patterns appliqués
- ✅ SOLID respecté (0 violation)
- ✅ Event Bus fonctionnel (3+ événements)
- ✅ API Gateway / BFF implémenté
- ✅ 8+ documents livrables créés

---

## ⚠️ Risques & Mitigations

| Risque | Probabilité | Impact | Mitigation |
|--------|-------------|--------|------------|
| **Complexité de Clean Architecture** | Moyenne | Moyen | Suivre strictement les exemples, documentation détaillée |
| **Supabase Realtime limitations** | Faible | Moyen | Tester tôt, fallback polling si nécessaire |
| **Stripe Test Mode bugs** | Faible | Faible | Utiliser webhooks test, documentation Stripe |
| **Performance Next.js SSR** | Faible | Moyen | ISR + caching, monitoring Vercel |
| **Délais serrés (5 semaines)** | Élevée | Élevé | Priorisation stricte, US optionnelles clairement identifiées |
| **Over-engineering** | Moyenne | Moyen | YAGNI, focus MVP, complexité justifiée |

---

## 🚀 Prochaines Étapes

### Semaine 5 ✅ (Terminée - 2 Novembre 2025)

1. [x] ✅ Créer structure `apps/modern-app/`
2. [x] ✅ Initialiser Next.js 14 avec App Router
3. [x] ✅ Setup TypeScript strict + ESLint + Prettier
4. [x] ✅ Installer Tailwind CSS + shadcn/ui
5. [x] ✅ Créer structure microservices (services/)
6. [x] ✅ Setup Supabase projet + tables de base
7. [x] ✅ Créer les 4 documents livrables principaux
8. [x] ✅ Configuration CI/CD (GitHub Actions + Vercel)
9. [x] ✅ Migrations database appliquées (entrepots, categories, tools)
10. [x] ✅ TypeScript types générés depuis Supabase

**Voir détails** : [Semaine 5 - Setup & Structure](./WEEK_5_SETUP.md)

### Semaine 6 (En cours)

1. [ ] 🔲 Implémenter Auth Service (Clean Architecture)
2. [ ] 🔲 Configurer Supabase Auth (Email + OAuth Google)
3. [ ] 🔲 Créer pages d'authentification (Login/Register)
4. [ ] 🔲 Middleware de protection des routes
5. [ ] 🔲 Tests unitaires Auth Service (> 80% coverage)

**Voir détails** : [Semaine 6 - Auth Service](./WEEK_6_AUTH.md)

---

**Maintenu par** : Équipe Architecture BricoLoc  
**Dernière mise à jour** : 2 Novembre 2025  
**Prochaine révision** : Fin Semaine 6