# 📋 Cahier des Charges - BricoLoc 2.0
## Projet de Refonte Architecturale

**Version** : 1.0  
**Date** : Octobre 2025  
**Statut** : Validé  
**Type** : Projet Académique - Architecture Logicielle

---

## 📑 Table des Matières

1. [Contexte du Projet](#contexte-du-projet)
2. [Problématique](#problématique)
3. [Objectifs](#objectifs)
4. [Périmètre Fonctionnel](#périmètre-fonctionnel)
5. [Périmètre Technique](#périmètre-technique)
6. [Architecture Proposée](#architecture-proposée)
7. [Contraintes](#contraintes)
8. [Livrables](#livrables)
9. [Critères de Succès](#critères-de-succès)
10. [Planning & Phases](#planning--phases)

---

## 🏢 Contexte du Projet

### Entreprise

**BricoLoc** est une entreprise de location d'outils en ligne (B2C) basée à Toulouse, avec **10 entrepôts** en France :
- Toulouse (siège), Paris, Nancy, Strasbourg
- Rennes, Nantes, Bordeaux, Montpellier, Avignon, Ajaccio

**Effectifs** : ~30 employés (Direction, Commercial, Logistique, DSI)

### Application Actuelle (Legacy)

**Mise en service** : 2013  
**Technologies** :
- Frontend : Spring Framework 5 (Java) + Apache Tomcat
- Backend : Java EE 6 + WebLogic Server
- BDD : Oracle 11g R2 (2 serveurs)
- Reverse Proxy : Apache HTTP Server

**Évolution** : Architecture peu évolutive depuis 12 ans

---

## ❌ Problématique

### Problèmes Critiques Identifiés

#### 1. **Architecture Monolithique Rigide**
- Couplage fort entre toutes les couches
- Logique métier éparpillée (frontend, backend, PL/SQL)
- Impossible à faire évoluer sans tout casser
- Single point of failure

#### 2. **Performance Dégradée**
- Temps de réponse > 3 secondes
- Base de données surchargée (tables > 150 colonnes)
- Pas de cache efficace
- Requêtes SQL non optimisées

#### 3. **Incohérence des Stocks** ⚠️ (Problème Majeur)
- Synchronisation quotidienne par batch CSV
- Décalage de **24h** entre ERP et application
- Réservations sur stock inexistant
- Perte de clients et insatisfaction

#### 4. **Maintenance Cauchemardesque**
- 80% du temps en maintenance corrective
- Régressions fréquentes (effets de bord)
- Code spaghetti accumulé sur 12 ans
- Documentation obsolète
- Aucun test automatisé

#### 5. **Expérience Utilisateur Obsolète**
- Design années 2010
- Pas responsive (mobile cassé)
- Navigation lente (rechargement complet)
- Bugs fréquents (filtres, pagination, paiement)

#### 6. **Scalabilité Limitée**
- Scaling vertical uniquement (coûts exponentiels)
- Impossibilité de scaler par fonction
- Expansion européenne bloquée

#### 7. **Solution Marque Blanche Non Viable**
- Déploiement complexe chez les partenaires
- Configuration difficile
- Peu de succès commercial

---

## 🎯 Objectifs

### Objectifs Principaux

#### 1. **Démontrer la Maîtrise de l'Architecture Logicielle** 🏛️
- Appliquer les **principes SOLID**
- Implémenter **Clean Architecture**
- Utiliser des **Design Patterns** reconnus
- Concevoir une **architecture microservices hybride**

#### 2. **Résoudre les Problèmes Critiques**
- ✅ Stocks en **temps réel** (fin des incohérences)
- ✅ Performance optimale (< 500ms)
- ✅ Zéro régression (tests automatisés)
- ✅ UX moderne (responsive, fluide)
- ✅ Scalabilité horizontale

#### 3. **Créer une Comparaison Concrète**
- Application Legacy simulée (avec bugs volontaires)
- Application Moderne fonctionnelle
- Métriques quantifiables (performance, qualité, maintenabilité)

#### 4. **Préparer l'Expansion Européenne** 🌍
- Architecture scalable
- Support multi-langues (prêt)
- Multi-devises (prêt)
- Déploiement facilité (cloud-ready)

---

## 📦 Périmètre Fonctionnel

### Fonctionnalités Implémentées (MVP)

#### ✅ Application Client (B2C)

##### EF-01 : Catalogue d'Outils
- Parcourir le catalogue par catégories
- Filtrer (catégorie, prix, disponibilité)
- Recherche intelligente
- Tri dynamique

##### EF-03 : Fiche Outil Détaillée
- Informations complètes (prix, description, specs)
- Galerie d'images
- Disponibilité par entrepôt
- Documentation technique

##### EF-04 : Calendrier des Disponibilités
- Vue calendrier interactive
- Disponibilité en temps réel ⚡
- Sélection de dates

##### EF-02 : Comparateur de Prix (simplifié)
- Prix comparatifs (données mockées)
- Affichage dans fiche produit

---

#### ✅ Authentification & Utilisateurs

##### EF-05 : Inscription
- Formulaire complet
- Type client (particulier/professionnel)
- Validation Zod

##### EF-06 : Authentification
- Connexion sécurisée (Supabase Auth)
- Gestion JWT
- Row Level Security (RLS)

##### EF-07 : Espace Personnel
- Dashboard utilisateur
- Historique des réservations
- Profil éditable

---

#### ✅ Réservation & Paiement

##### EF-08 : Réservation
- Formulaire multi-étapes
- Sélection dates + entrepôt
- Calcul prix en temps réel
- Vérification disponibilité

##### EF-09 : Paiement
- Interface Stripe (simulée)
- Confirmation sécurisée
- Génération facture (mock)

##### EF-10 : Modes de Livraison
- Récupération sur place
- Livraison à domicile (si outil < 50kg)

---

#### ✅ Gestion des Stocks

##### EF-11 : Stocks Temps Réel ⚡ (Amélioration Majeure)
- Disponibilité en temps réel (Supabase Realtime)
- Stocks par entrepôt (10 entrepôts)
- Réservation automatique lors de la confirmation
- Synchronisation immédiate (vs 24h avant)

---

### 🚫 Fonctionnalités Hors Périmètre (Phase 1)

Les fonctionnalités suivantes seront documentées mais **non implémentées** dans la version de démonstration :

- ❌ **EF-12 à EF-16** : Gestion administrative (relation client, achats, transporteurs)
- ❌ **EF-17 à EF-18** : Facturation et synchronisation ERP SAP
- ❌ **EF-19** : Business Intelligence / PowerBI
- ❌ **EF-20** : Interface Admin complète
- ❌ **EF-21** : Solution Marque Blanche
- ❌ **EF-22 à EF-23** : Expansion géographique et B2B grands comptes
- ❌ **Location P2P** (particuliers entre eux)

**Justification** : Focus sur la démonstration architecturale (qualité > quantité)

---

## 🏗️ Périmètre Technique

### Architecture

#### Style Architectural : **Microservices Hybride**

Décomposition en **6 microservices** :

| Service | Responsabilité | Technologies |
|---------|----------------|--------------|
| **Auth Service** | Authentification, JWT, RBAC | Supabase Auth |
| **Catalogue Service** | CRUD outils, recherche, filtres | Next.js API + Supabase |
| **Reservation Service** | Réservations, disponibilités | Next.js API + Supabase |
| **Inventory Service** | Stocks temps réel, entrepôts | Next.js API + Supabase Realtime |
| **Payment Service** | Paiement, transactions | Next.js API + Stripe Mock |
| **Notification Service** | Emails, notifications | Next.js API + Resend |

#### Communication
- **Synchrone** : REST API (HTTP)
- **Asynchrone** : Event Bus (Supabase Realtime Channels)

#### API Gateway / BFF
- Next.js agit comme Backend For Frontend
- Agrégation des appels microservices
- Orchestration de la logique métier

#### Architecture Interne (Clean Architecture)
Chaque microservice implémente :
```
├── domain/         # Entities, business rules
├── application/    # Use cases, services
└── infrastructure/ # Repositories, DB access
```

---

### Stack Technique

#### 🕰️ **Application Legacy**

| Couche | Technologie |
|--------|-------------|
| Frontend | HTML5, CSS3, JavaScript Vanilla, jQuery |
| Backend | Node.js + Express + EJS |
| Base de données | SQLite (fichier local) |
| Auth | Sessions côté serveur, hash MD5 |
| Design | Années 2010 (volontairement daté) |

**Bugs volontaires** :
- Incohérence stocks (synchro quotidienne simulée)
- Erreurs aléatoires (paiement : 20% échec)
- Performance dégradée (délais artificiels)
- Navigation cassée, filtres qui se réinitialisent

---

#### ⚡ **Application Moderne**

| Couche | Technologie | Version |
|--------|-------------|---------|
| **Framework** | Next.js (App Router) | 14+ |
| **Langage** | TypeScript | 5+ |
| **UI Library** | React | 18+ |
| **Styling** | Tailwind CSS | 3+ |
| **Components** | shadcn/ui | Latest |
| **Backend** | Next.js API Routes | - |
| **BDD** | Supabase (PostgreSQL) | Latest |
| **Auth** | Supabase Auth | Latest |
| **Realtime** | Supabase Realtime | Latest |
| **ORM** | Prisma (local dev) | 5+ |
| **Validation** | Zod | 3+ |
| **Forms** | React Hook Form | 7+ |
| **State** | React Query + Zustand | Latest |
| **Animations** | Framer Motion | Latest |
| **Paiement** | Stripe (mock) | - |
| **Emails** | Resend (mock) | - |

---

### Infrastructure

| Service | Technologie | Usage |
|---------|-------------|-------|
| **Hosting Frontend** | Vercel | Next.js moderne |
| **Hosting Legacy** | Render / Heroku | Node.js legacy |
| **Base de données** | Supabase Cloud | PostgreSQL + Realtime |
| **Storage** | Supabase Storage | Images outils |
| **CI/CD** | GitHub Actions | Tests + Deploy |
| **Monitoring** | Vercel Analytics | Performance |

---

### Environnement de Développement

- **OS** : WSL (Ubuntu)
- **Node.js** : 20+ LTS
- **Package Manager** : pnpm (mono-repo)
- **IDE** : VS Code
- **Git** : Workflow feature branches
- **Linting** : ESLint + Prettier
- **Testing** : Jest + React Testing Library

---

## 🏛️ Architecture Proposée

### Vue d'Ensemble Microservices

```
┌─────────────────────────────────────────────┐
│         Client (Next.js SSR/CSR)            │
└────────────────┬────────────────────────────┘
                 │
┌────────────────▼────────────────────────────┐
│      API Gateway / BFF (Next.js API)        │
└─┬──────┬──────┬──────┬──────┬──────┬───────┘
  │      │      │      │      │      │
  ▼      ▼      ▼      ▼      ▼      ▼
┌─────┐┌─────┐┌─────┐┌─────┐┌─────┐┌─────┐
│Auth ││Cata-││Reser││Inven││Pay- ││Noti-│
│Svc  ││logue││vation││tory ││ment ││fica-│
│     ││Svc  ││Svc  ││Svc  ││Svc  ││tion │
└──┬──┘└──┬──┘└──┬──┘└──┬──┘└──┬──┘└──┬──┘
   │      │      │      │      │      │
   └──────┴──────┴──────┴──────┴──────┘
                 │
          ┌──────▼──────┐
          │  Event Bus  │ (Supabase Realtime)
          └──────┬──────┘
                 │
          ┌──────▼──────┐
          │  Supabase   │ (PostgreSQL + Auth + Storage)
          └─────────────┘
```

### Principes Architecturaux Appliqués

#### SOLID
- ✅ Single Responsibility (services focalisés)
- ✅ Open/Closed (extension via interfaces)
- ✅ Liskov Substitution (implémentations interchangeables)
- ✅ Interface Segregation (interfaces spécifiques)
- ✅ Dependency Inversion (dépendances vers abstractions)

#### Clean Architecture
- ✅ Couches découplées (domain → application → infrastructure)
- ✅ Indépendance des frameworks
- ✅ Testabilité maximale
- ✅ Indépendance de la BDD

#### Patterns
- ✅ Repository Pattern (abstraction data)
- ✅ Service Layer (logique métier)
- ✅ Dependency Injection
- ✅ Factory Pattern
- ✅ Observer Pattern (events)
- ✅ API Gateway / BFF

---

## ⚠️ Contraintes

### Contraintes Techniques

| Contrainte | Description |
|------------|-------------|
| **Mono-repo** | Structure unique pour les 2 apps |
| **WSL** | Développement sous Linux (WSL) |
| **Supabase** | Backend obligatoire (MCP disponible) |
| **TypeScript** | Moderne app uniquement |
| **Next.js 14** | App Router (pas Pages Router) |
| **pnpm** | Package manager pour workspace |

### Contraintes Fonctionnelles

| Contrainte | Description |
|------------|-------------|
| **2 applications** | Legacy ET Moderne (fonctionnelles) |
| **Mêmes fonctionnalités** | Catalogue, réservation, paiement, etc. |
| **Vraies BDD** | SQLite (legacy) + Supabase (moderne) |
| **Authentification réelle** | Inscription/connexion fonctionnelles |
| **Données de test** | ~50 outils, 10 entrepôts |

### Contraintes Organisationnelles

| Contrainte | Description |
|------------|-------------|
| **Équipe** | 1-2 personnes (solo + 1 possible) |
| **Durée** | 6-7 semaines |
| **Contexte** | Projet académique (pas production) |
| **Ressources** | Tier gratuit Supabase/Vercel |

---

## 📦 Livrables

### 1. Code Source ✅

#### Repository Git
- [x] Structure mono-repo complète
- [x] Application Legacy fonctionnelle
- [x] Application Moderne fonctionnelle
- [x] Scripts de seed (données de test)
- [x] Configuration complète (ESLint, Prettier, TypeScript)

#### Qualité du Code
- [ ] Tests unitaires (coverage > 70%)
- [ ] Tests d'intégration
- [ ] CI/CD fonctionnel (GitHub Actions)
- [ ] Linting sans erreurs
- [ ] TypeScript strict mode

---

### 2. Documentation Architecture 📚

#### Documents Principaux
- [x] **README.md** (vue d'ensemble)
- [x] **ARCHITECTURE.md** (architecture détaillée)
- [x] **Cahier des Charges** (ce document)
- [ ] **ADR** (Architecture Decision Records)
  - ADR-001 : Mono-repo
  - ADR-002 : Next.js vs alternatives
  - ADR-003 : Supabase backend
  - ADR-004 : Architecture microservices
  - ADR-005 : Patterns (Repository, Service Layer)

#### Diagrammes
- [ ] **Diagrammes C4** (Mermaid)
  - Level 1 : Context
  - Level 2 : Container
  - Level 3 : Component (Reservation Service)
  - Level 4 : Code (optionnel)
- [ ] **Diagrammes de séquence** (flux utilisateur)
- [ ] **Schéma base de données** (ERD)

#### Guides
- [ ] **Development Setup** (WSL, installation)
- [ ] **Coding Standards** (conventions)
- [ ] **Git Workflow** (branching strategy)
- [ ] **CONTRIBUTING.md** (guide de contribution)

---

### 3. Documentation Comparative 📊

- [ ] **Tableau comparatif** (architecture, performance, qualité)
- [ ] **Métriques Lighthouse** (legacy vs moderne)
- [ ] **Analyse de complexité** (code, couplage, cohésion)
- [ ] **Screenshots côte à côte**

---

### 4. Applications Déployées 🚀

- [ ] **Legacy App** : URL publique (Render/Heroku)
- [ ] **Modern App** : URL publique (Vercel)
- [ ] **Accessibles 24/7** pour démonstration

---

### 5. Présentation Académique 🎓

- [ ] **Slides** (20-30 slides)
  - Contexte et problématique
  - Architecture Legacy (problèmes)
  - Architecture Moderne (solutions)
  - Démonstration des patterns
  - Métriques et résultats
  - Retour d'expérience
- [ ] **Live Demo** (15 min)
- [ ] **Vidéo de démonstration** (5-10 min, backup)

---

## ✅ Critères de Succès

### Critères Techniques

| Critère | Objectif | Mesure |
|---------|----------|--------|
| **Performance** | Moderne < 500ms | Lighthouse Performance > 90 |
| **Accessibilité** | WCAG 2.1 AA | Lighthouse Accessibility = 100 |
| **SEO** | Optimisé | Lighthouse SEO = 100 |
| **Tests** | Coverage élevé | > 70% |
| **TypeScript** | Zéro erreur | `tsc --noEmit` = 0 errors |
| **Linting** | Code propre | ESLint = 0 errors |

### Critères Fonctionnels

| Critère | Description |
|---------|-------------|
| ✅ **2 apps fonctionnelles** | Legacy ET Moderne déployées |
| ✅ **Auth complète** | Inscription, connexion, profil |
| ✅ **Catalogue** | 50 outils, recherche, filtres |
| ✅ **Réservation** | Formulaire, calcul prix, confirmation |
| ✅ **Paiement simulé** | Interface Stripe mock fonctionnelle |
| ✅ **Stocks temps réel** | Supabase Realtime actif |
| ✅ **Responsive** | Mobile, tablet, desktop |

### Critères Architecturaux (Prioritaire 🏛️)

| Critère | Description |
|---------|-------------|
| ✅ **Microservices** | 6 services identifiés et implémentés |
| ✅ **Clean Architecture** | Couches respectées par service |
| ✅ **SOLID** | Principes appliqués et démontrables |
| ✅ **Patterns** | Repository, Service Layer, DI, Factory |
| ✅ **Event-Driven** | Communication asynchrone fonctionnelle |
| ✅ **API Gateway** | BFF avec orchestration |
| ✅ **Documentation** | ADR complets, diagrammes C4 |

### Critères de Comparaison

| Métrique | Legacy | Moderne | Objectif |
|----------|--------|---------|----------|
| Lighthouse Score | < 60 | > 95 | +58% minimum |
| Temps chargement | > 3s | < 0.5s | -83% minimum |
| Bugs | 5+ volontaires | 0 | -100% |
| Maintenabilité | Faible | Élevée | Démontrable |
| Tests | 0% | > 70% | +70% |

---

## 📅 Planning & Phases

### Phase 1 : Fondations (Semaine 1-2) ✅ ACTUEL
**Durée** : 2 semaines

#### Objectifs
- [x] Structure du mono-repo
- [x] Documentation architecture (README, ARCHITECTURE.md, Cahier des Charges)
- [ ] ADR initiaux (5 premiers)
- [ ] Diagrammes C4
- [ ] Roadmap détaillée
- [ ] Configuration pnpm workspace
- [ ] Git initialized

#### Livrables
- Documentation complète
- Structure projet propre
- Premier commit Git

---

### Phase 2 : Application Legacy (Semaine 3-4)
**Durée** : 2 semaines

#### Objectifs
- [ ] Setup Express + SQLite
- [ ] Authentification (sessions, MD5)
- [ ] Catalogue d'outils (EJS templates)
- [ ] Réservation + Paiement (formulaires basiques)
- [ ] Espace personnel
- [ ] Bugs volontaires intégrés
- [ ] Design années 2010
- [ ] Déploiement Render/Heroku

#### Livrables
- Application Legacy fonctionnelle et déployée

---

### Phase 3 : Setup Moderne (Semaine 5)
**Durée** : 1 semaine

#### Objectifs
- [ ] Setup Next.js 14 + TypeScript
- [ ] Configuration Supabase
- [ ] Setup shadcn/ui + Tailwind
- [ ] Structure microservices (dossiers)
- [ ] Configuration Prisma (optionnel)
- [ ] Authentification Supabase Auth

#### Livrables
- Squelette application moderne
- Authentification fonctionnelle

---

### Phase 4 : Microservices Métier (Semaine 6-7)
**Durée** : 2 semaines

#### Objectifs
- [ ] **Catalogue Service** : CRUD, recherche, filtres
- [ ] **Reservation Service** : Création, vérification, calcul prix
- [ ] **Inventory Service** : Stocks temps réel (Realtime)
- [ ] **Payment Service** : Mock Stripe
- [ ] **Notification Service** : Emails simulés
- [ ] Event Bus : Communication asynchrone
- [ ] Tests unitaires par service

#### Livrables
- 5 microservices fonctionnels
- Communication inter-services

---

### Phase 5 : Frontend & Intégration (Semaine 8)
**Durée** : 1 semaine

#### Objectifs
- [ ] Pages Next.js (catalogue, détail, réservation)
- [ ] Composants shadcn/ui
- [ ] Intégration avec microservices (API calls)
- [ ] Formulaire multi-étapes (réservation)
- [ ] Espace personnel (dashboard)
- [ ] Responsive design
- [ ] Animations Framer Motion

#### Livrables
- Frontend complet et responsive
- Application moderne déployée (Vercel)

---

### Phase 6 : Tests & Qualité (Semaine 9)
**Durée** : 1 semaine

#### Objectifs
- [ ] Tests unitaires (services, use cases)
- [ ] Tests d'intégration (API)
- [ ] Tests E2E (optionnel)
- [ ] Lighthouse audit
- [ ] Correction bugs
- [ ] Optimisations performance
- [ ] CI/CD GitHub Actions

#### Livrables
- Tests coverage > 70%
- Lighthouse scores > 90
- CI/CD fonctionnel

---

### Phase 7 : Documentation & Démo (Semaine 10)
**Durée** : 1 semaine

#### Objectifs
- [ ] Finaliser ADR
- [ ] Compléter diagrammes C4
- [ ] Documentation comparative (métriques)
- [ ] Screenshots legacy vs moderne
- [ ] Vidéo de démonstration (10 min)
- [ ] Slides de présentation (30 slides)
- [ ] Répétition de la démo

#### Livrables
- Documentation complète
- Présentation prête
- Vidéo de backup

---

## 📈 Estimation de Charge

| Phase | Durée | Charge (heures) |
|-------|-------|-----------------|
| Phase 1 : Fondations | 2 sem | 30h |
| Phase 2 : Legacy App | 2 sem | 40h |
| Phase 3 : Setup Moderne | 1 sem | 20h |
| Phase 4 : Microservices | 2 sem | 50h |
| Phase 5 : Frontend | 1 sem | 30h |
| Phase 6 : Tests | 1 sem | 25h |
| Phase 7 : Documentation | 1 sem | 20h |
| **TOTAL** | **10 sem** | **215h** |

**Charge hebdomadaire** : ~20-25h (mi-temps)

---

## 🎯 Indicateurs de Réussite

### Réussite Minimale ⭐
- 2 applications fonctionnelles (même simples)
- Documentation architecture claire
- Démonstration de quelques patterns
- Comparaison basique

### Réussite Attendue ⭐⭐⭐
- 2 applications complètes et déployées
- Architecture microservices démontrée
- Patterns SOLID + Clean Architecture appliqués
- Documentation exhaustive (ADR, C4)
- Métriques quantifiables
- Présentation convaincante

### Réussite Exceptionnelle ⭐⭐⭐⭐⭐
- Tout ci-dessus +
- Tests coverage > 80%
- CI/CD complet
- Observabilité (logs, metrics)
- Feature additionnelle (P2P, Admin, etc.)
- Contribution open-source (article, talk)

---

## 📝 Notes & Annexes

### Risques Identifiés

| Risque | Probabilité | Impact | Mitigation |
|--------|-------------|--------|------------|
| Sous-estimation temps | Moyenne | Élevé | Buffer de 1 semaine |
| Complexité microservices | Faible | Moyen | Simplification si besoin |
| Problème Supabase | Faible | Élevé | Plan B : Firebase/PocketBase |
| Camarade ne rejoint pas | Élevée | Faible | Projet solo viable |

### Ressources Externes

- **Supabase MCP** : Disponible et configuré ✅
- **Documentation Supabase** : https://supabase.com/docs
- **Documentation Next.js** : https://nextjs.org/docs
- **shadcn/ui** : https://ui.shadcn.com
- **Clean Architecture** : Blog Uncle Bob

---

## ✍️ Signatures & Validation

**Porteur du projet** : [Nom]  
**Encadrant académique** : [Nom]  
**Date de validation** : Octobre 2025

---

**Version** : 1.0  
**Statut** : ✅ Validé  
**Prochaine révision** : À la fin de chaque phase

---

*Ce cahier des charges est un document vivant, mis à jour selon l'avancement du projet.*