ansiblenginx/app/bricolociaac/docs/architecture/ADR/005-patterns-conception.md

# ADR-005 : Patterns de Conception Appliqués

**Statut** : ✅ Accepté  
**Date** : Octobre 2025  
**Décideurs** : Équipe Architecture  
**Tags** : `patterns`, `design-patterns`, `clean-code`

---

## Contexte

Pour garantir la **maintenabilité**, la **testabilité**, et le **découplage** du système, nous devons appliquer des **Design Patterns** éprouvés.

L'objectif est de démontrer la maîtrise de patterns architecturaux modernes (au-delà de la simple implémentation fonctionnelle).

### Besoins identifiés
- **Découplage** : Indépendance entre couches
- **Testabilité** : Code facilement testable unitairement
- **Réutilisabilité** : Éviter duplication
- **Maintenabilité** : Code compréhensible et évolutif

---

## Décision

✅ **Nous appliquons 5 patterns principaux** :

1. **Repository Pattern** (Accès aux données)
2. **Service Layer Pattern** (Logique métier)
3. **Dependency Injection (DI)** (Découplage)
4. **Factory Pattern** (Création d'objets)
5. **Observer Pattern via Event Bus** (Communication asynchrone)

---

## Patterns Détaillés

### 1️⃣ Repository Pattern

**Objectif** : Abstraire l'accès aux données, découpler le domaine de l'infrastructure.

#### Principe

```
Domain Layer → Interface Repository
Infrastructure Layer → Implementation (Supabase)
```

**Le domaine ne connaît PAS Supabase** ✅

#### Exemple : Reservation Service

**Interface (Domain Layer)**
```typescript
// packages/microservices/reservation/src/domain/repositories/IReservationRepository.ts

export interface IReservationRepository {
  findById(id: string): Promise<Reservation | null>
  findByUserId(userId: string): Promise<Reservation[]>
  findByOutilId(outilId: string): Promise<Reservation[]>
  create(data: CreateReservationDTO): Promise<Reservation>
  update(id: string, data: UpdateReservationDTO): Promise<Reservation>
  delete(id: string): Promise<void>
  findOverlapping(params: OverlapParams): Promise<Reservation[]>
}
```

**Implémentation (Infrastructure Layer)**
```typescript
// packages/microservices/reservation/src/infrastructure/repositories/SupabaseReservationRepository.ts

import { SupabaseClient } from '@supabase/supabase-js'
import { IReservationRepository } from '@/domain/repositories/IReservationRepository'

export class SupabaseReservationRepository implements IReservationRepository {
  constructor(private supabase: SupabaseClient) {}

  async findById(id: string): Promise<Reservation | null> {
    const { data, error } = await this.supabase
      .from('reservations')
      .select('*')
      .eq('id', id)
      .single()
    
    if (error) throw new RepositoryError(error.message)
    return data ? ReservationMapper.toDomain(data) : null
  }

  // ... autres méthodes
}
```

#### Avantages

✅ **Testabilité** : Mock facile du repository
```typescript
// Test
const mockRepo: IReservationRepository = {
  findById: jest.fn().mockResolvedValue(mockReservation),
  // ...
}
```

✅ **Changement de DB** : Remplacer Supabase par Prisma/MongoDB sans toucher au domaine

✅ **Séparation des responsabilités** : Le domaine ne gère pas les requêtes SQL

---

### 2️⃣ Service Layer Pattern

**Objectif** : Centraliser la logique métier, orchestrer les use cases.

#### Principe

```
API Routes → Services → Repositories
```

Les **services** contiennent la logique métier complexe et orchestrent les appels.

#### Exemple : Reservation Service

**Service Métier**
```typescript
// packages/microservices/reservation/src/application/services/ReservationService.ts

export class ReservationService {
  constructor(
    private reservationRepo: IReservationRepository,
    private inventoryService: InventoryService, // Dépendance autre microservice
    private notificationService: NotificationService,
    private eventBus: EventBus
  ) {}

  async createReservation(
    userId: string,
    data: CreateReservationDTO
  ): Promise<Reservation> {
    // 1. Valider les données
    this.validateReservationDates(data)

    // 2. Vérifier disponibilité (appel Inventory Service)
    const isAvailable = await this.inventoryService.checkAvailability({
      outilId: data.outilId,
      entrepotId: data.entrepotId,
      dateDebut: data.dateDebut,
      dateFin: data.dateFin
    })

    if (!isAvailable) {
      throw new BusinessError('OUTIL_NON_DISPONIBLE')
    }

    // 3. Créer la réservation
    const reservation = await this.reservationRepo.create({
      ...data,
      userId,
      status: 'PENDING'
    })

    // 4. Émettre un event (asynchrone)
    await this.eventBus.publish('reservation.created', {
      reservationId: reservation.id,
      outilId: data.outilId,
      entrepotId: data.entrepotId,
      userId
    })

    // 5. Envoyer notification
    await this.notificationService.sendReservationConfirmation(userId, reservation)

    return reservation
  }

  private validateReservationDates(data: CreateReservationDTO): void {
    if (data.dateDebut >= data.dateFin) {
      throw new ValidationError('Date de fin doit être après date de début')
    }
    if (data.dateDebut < new Date()) {
      throw new ValidationError('Date de début ne peut pas être dans le passé')
    }
  }
}
```

#### Avantages

✅ **Logique métier centralisée** : Pas dispersée dans les API routes

✅ **Réutilisabilité** : Le service peut être appelé depuis n'importe où

✅ **Testabilité** : Tester la logique sans API HTTP

✅ **Orchestration** : Coordonne plusieurs repositories et services

---

### 3️⃣ Dependency Injection (DI)

**Objectif** : Inverser les dépendances, faciliter les tests et le découplage.

#### Principe (IoC - Inversion of Control)

**Avant (Bad) ❌**
```typescript
class ReservationService {
  private repo = new SupabaseReservationRepository() // Hard-coded !
}
```

**Après (Good) ✅**
```typescript
class ReservationService {
  constructor(private repo: IReservationRepository) {} // Interface !
}
```

#### Implémentation avec Container

**Container DI**
```typescript
// packages/shared/di/src/container.ts

import { Container } from 'inversify'

const container = new Container()

// Repositories
container.bind<IReservationRepository>('IReservationRepository')
  .to(SupabaseReservationRepository)
  .inSingletonScope()

// Services
container.bind<ReservationService>('ReservationService')
  .to(ReservationService)
  .inSingletonScope()

export { container }
```

**Injection dans API Route**
```typescript
// apps/moderne/app/api/reservations/route.ts

import { container } from '@bricoloc/shared-di'
import { ReservationService } from '@bricoloc/reservation-service'

export async function POST(req: Request) {
  const service = container.get<ReservationService>('ReservationService')
  const data = await req.json()
  
  const reservation = await service.createReservation(userId, data)
  return Response.json(reservation)
}
```

#### Avantages

✅ **Testabilité** : Injecter des mocks facilement
```typescript
// Test
container.bind<IReservationRepository>('IReservationRepository')
  .toConstantValue(mockRepository)
```

✅ **Découplage** : Le service ne connaît que l'interface

✅ **Configuration centralisée** : Toutes les bindings au même endroit

✅ **Lifetime management** : Singleton, Transient, Scoped

---

### 4️⃣ Factory Pattern

**Objectif** : Centraliser la création d'objets complexes.

#### Exemple : Entity Factory

**Use Case** : Créer une entité Reservation avec validation et business rules

**Factory**
```typescript
// packages/microservices/reservation/src/domain/factories/ReservationFactory.ts

export class ReservationFactory {
  static create(data: CreateReservationDTO, userId: string): Reservation {
    // 1. Validation
    this.validateData(data)

    // 2. Calculer le prix
    const prix = this.calculatePrice(data.outilId, data.dateDebut, data.dateFin)

    // 3. Déterminer le status initial
    const status = this.determineInitialStatus(data)

    // 4. Créer l'entité
    return new Reservation({
      id: generateId(),
      userId,
      outilId: data.outilId,
      entrepotId: data.entrepotId,
      dateDebut: data.dateDebut,
      dateFin: data.dateFin,
      prix,
      status,
      createdAt: new Date()
    })
  }

  private static validateData(data: CreateReservationDTO): void {
    if (!data.outilId) throw new ValidationError('outilId requis')
    if (!data.dateDebut) throw new ValidationError('dateDebut requis')
    // ...
  }

  private static calculatePrice(
    outilId: string,
    dateDebut: Date,
    dateFin: Date
  ): number {
    // Logique de pricing
    const days = differenceInDays(dateFin, dateDebut)
    const dailyRate = 15 // €/jour
    return days * dailyRate
  }

  private static determineInitialStatus(data: CreateReservationDTO): string {
    // Si réservation immédiate → PENDING
    // Si réservation future → SCHEDULED
    return data.dateDebut <= new Date() ? 'PENDING' : 'SCHEDULED'
  }
}
```

**Usage dans Service**
```typescript
async createReservation(userId: string, data: CreateReservationDTO) {
  // Factory s'occupe de toute la complexité
  const reservation = ReservationFactory.create(data, userId)
  
  return await this.reservationRepo.create(reservation)
}
```

#### Avantages

✅ **Encapsulation** : Logique de création centralisée

✅ **Validation** : Garantit que l'objet est valide

✅ **Business Rules** : Applique les règles métier (pricing, status)

✅ **Testabilité** : Tester la création isolément

---

### 5️⃣ Observer Pattern via Event Bus

**Objectif** : Communication asynchrone entre microservices.

#### Principe

```
Service A → Émet Event → Event Bus → Service B écoute
```

**Découplage** : Service A ne connaît PAS Service B ✅

#### Implémentation avec Supabase Realtime

**Event Bus Abstraction**
```typescript
// packages/shared/events/src/EventBus.ts

export interface IEventBus {
  publish(eventName: string, data: any): Promise<void>
  subscribe(eventName: string, handler: EventHandler): void
  unsubscribe(eventName: string, handler: EventHandler): void
}

export class SupabaseEventBus implements IEventBus {
  constructor(private supabase: SupabaseClient) {}

  async publish(eventName: string, data: any): Promise<void> {
    const channel = this.supabase.channel('events')
    await channel.send({
      type: 'broadcast',
      event: eventName,
      payload: data
    })
  }

  subscribe(eventName: string, handler: EventHandler): void {
    const channel = this.supabase.channel('events')
    channel.on('broadcast', { event: eventName }, handler)
    channel.subscribe()
  }

  // ...
}
```

**Publisher (Reservation Service)**
```typescript
async createReservation(...) {
  const reservation = await this.reservationRepo.create(data)

  // Émet un event
  await this.eventBus.publish('reservation.confirmed', {
    reservationId: reservation.id,
    outilId: data.outilId,
    entrepotId: data.entrepotId,
    dateDebut: data.dateDebut,
    dateFin: data.dateFin
  })

  return reservation
}
```

**Subscriber (Inventory Service)**
```typescript
// packages/microservices/inventory/src/application/listeners/ReservationListener.ts

export class ReservationListener {
  constructor(
    private inventoryService: InventoryService,
    private eventBus: IEventBus
  ) {
    this.setupListeners()
  }

  private setupListeners(): void {
    this.eventBus.subscribe('reservation.confirmed', this.handleReservationConfirmed.bind(this))
    this.eventBus.subscribe('reservation.cancelled', this.handleReservationCancelled.bind(this))
  }

  private async handleReservationConfirmed(event: ReservationConfirmedEvent): Promise<void> {
    // Mettre à jour le stock
    await this.inventoryService.reserveStock({
      outilId: event.outilId,
      entrepotId: event.entrepotId,
      quantity: 1,
      reservationId: event.reservationId
    })
  }

  private async handleReservationCancelled(event: ReservationCancelledEvent): Promise<void> {
    // Libérer le stock
    await this.inventoryService.releaseStock({
      reservationId: event.reservationId
    })
  }
}
```

#### Avantages

✅ **Découplage** : Services ne se connaissent pas directement

✅ **Asynchrone** : Pas de blocage (fire-and-forget)

✅ **Scalabilité** : Plusieurs subscribers possibles

✅ **Résilience** : Si un subscriber échoue, les autres continuent

✅ **Audit Trail** : Tous les events sont tracés

---

## Récapitulatif des Patterns

| Pattern | Objectif | Couche | Exemple |
|---------|----------|--------|---------|
| **Repository** | Abstraction accès données | Infrastructure | `SupabaseReservationRepository` |
| **Service Layer** | Logique métier | Application | `ReservationService` |
| **Dependency Injection** | Découplage | Tous | Container IoC (inversify) |
| **Factory** | Création objets complexes | Domain | `ReservationFactory` |
| **Observer (Event Bus)** | Communication async | Infrastructure | Supabase Realtime Channels |

---

## Architecture Complète avec Patterns

```
┌─────────────────────────────────────────────────┐
│          API Routes (Next.js API)               │
│              (Thin Controllers)                 │
└──────────────────┬──────────────────────────────┘
                   │ Injection DI
        ┌──────────▼──────────┐
        │   Service Layer     │ ← Logique métier
        │ (ReservationService)│
        └──────────┬──────────┘
                   │
        ┌──────────▼──────────┐
        │  Repository Pattern │ ← Abstraction
        │ (IReservationRepo)  │
        └──────────┬──────────┘
                   │
        ┌──────────▼──────────┐
        │  Infrastructure     │ ← Implémentation
        │ (SupabaseRepo)      │
        └─────────────────────┘

        ┌─────────────────────┐
        │   Factory Pattern   │ ← Création entités
        └─────────────────────┘

        ┌─────────────────────┐
        │  Observer Pattern   │ ← Events async
        │   (Event Bus)       │
        └─────────────────────┘
```

---

## Conséquences

### ✅ Avantages

1. **Testabilité maximale** : Chaque composant testable isolément
2. **Maintenabilité** : Code organisé et découplé
3. **Évolutivité** : Facile d'ajouter features sans casser existant
4. **Réutilisabilité** : Services et repositories réutilisables
5. **Démonstration** : Montre maîtrise des patterns modernes

### ⚠️ Complexités

1. **Boilerplate** : Plus de code (interfaces, implémentations)
2. **Courbe d'apprentissage** : Patterns à comprendre
3. **Over-engineering** : Risque si mal appliqué

### 🛠️ Mitigations

- **Documentation** : Bien expliquer chaque pattern
- **Exemples** : Fournir des templates pour chaque pattern
- **Progressif** : Appliquer patterns seulement où c'est utile

---

## Alternatives Rejetées

### ❌ Pas de Patterns (Code procédural)

**Raisons du rejet** :
- Pas de découplage
- Difficile à tester
- Logique métier dispersée
- Maintenance cauchemar

### ❌ Patterns complexes (CQRS, Event Sourcing, DDD complet)

**Raisons du rejet** :
- Trop complexe pour projet académique
- Overhead important
- Courbe d'apprentissage élevée
- Pas nécessaire pour cette échelle

---

## Références

- [Repository Pattern](https://martinfowler.com/eaaCatalog/repository.html)
- [Service Layer Pattern](https://martinfowler.com/eaaCatalog/serviceLayer.html)
- [Dependency Injection](https://martinfowler.com/articles/injection.html)
- [Factory Pattern](https://refactoring.guru/design-patterns/factory-method)
- [Observer Pattern](https://refactoring.guru/design-patterns/observer)
- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)

---

## Validations

- [x] Repository interfaces définies
- [x] Service Layer implémenté
- [x] DI Container configuré (inversify)
- [x] Factory patterns identifiés
- [x] Event Bus testé avec Supabase Realtime
- [x] Tests unitaires avec mocks validés

---

**Prochaine révision** : Après 1 sprint de développement (feedback sur complexité)