ansiblenginx/app/bricolociaac/docs/specifications/cahier-des-charges.md

📋 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
2. Problématique
3. Objectifs
4. Périmètre Fonctionnel
5. Périmètre Technique
6. Architecture Proposée
7. Contraintes
8. Livrables
9. Critères de Succès
10. 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

• Structure mono-repo complète
• Application Legacy fonctionnelle
• Application Moderne fonctionnelle
• Scripts de seed (données de test)
• 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

• README.md (vue d'ensemble)
• ARCHITECTURE.md (architecture détaillée)
• 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

• Structure du mono-repo
• 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.