romain
/
ansiblenginx
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
main
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '51fd44da17'
${ noResults }
ansiblenginx/app/bricolociaac/docs/specifications/cahier-des-charges.md

752 lines
22 KiB
Markdown
Raw Normal View History Unescape Escape

Ajouter l'app Bricoloc au repo pour synchronize
2 months ago
# 📋 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.*