Ajout documentation
This commit is contained in:
bastien
@@ -0,0 +1,396 @@
|
||||
# Cahier des Charges — Back-Office Exploitant
|
||||
## Projet : Laverie Connectée — Interface d'Administration
|
||||
**Version :** 2.0
|
||||
**Stack principale :** Laravel 11 + Vue.js 3 + Inertia.js
|
||||
**Positionnement :** V1 simple, cloisonnée par exploitant, démontrable rapidement
|
||||
|
||||
---
|
||||
|
||||
## 1. Contexte & Objectifs
|
||||
|
||||
### 1.1 Objectif
|
||||
Le back-office permet à un exploitant de piloter ses laveries sans exposer les données des autres exploitants présents sur la plateforme.
|
||||
|
||||
### 1.2 Objectifs V1
|
||||
- authentifier les exploitants,
|
||||
- afficher les machines et leur état,
|
||||
- afficher les indicateurs métier de base,
|
||||
- consulter réservations et lavages,
|
||||
- gérer les tarifs,
|
||||
- consulter les alertes techniques simples,
|
||||
- garantir un cloisonnement strict par exploitant.
|
||||
|
||||
### 1.3 Principes
|
||||
- une organisation ne voit que ses établissements,
|
||||
- un manager peut être restreint à un établissement,
|
||||
- la V1 privilégie la lisibilité et la fiabilité plutôt que la richesse fonctionnelle,
|
||||
- le temps réel peut être simulé ou remplacé par du polling si nécessaire.
|
||||
|
||||
---
|
||||
|
||||
## 2. Périmètre fonctionnel
|
||||
|
||||
### 2.1 MVP V1
|
||||
- connexion superviseur,
|
||||
- tableau de bord simple,
|
||||
- liste des machines,
|
||||
- détail machine,
|
||||
- liste des réservations,
|
||||
- liste des lavages,
|
||||
- gestion simple des tarifs,
|
||||
- consultation simple des promotions si activées en V1,
|
||||
- affichage des alertes de base,
|
||||
- audit minimal des actions sensibles.
|
||||
|
||||
### 2.2 V2 prévue
|
||||
- campagnes de notifications,
|
||||
- exports avancés,
|
||||
- analytics détaillées,
|
||||
- gestion multi-utilisateurs plus riche,
|
||||
- segmentation marketing,
|
||||
- vue consolidée plus poussée pour groupes de laveries.
|
||||
|
||||
### 2.3 Hors périmètre V1
|
||||
- CRM,
|
||||
- marketing automation,
|
||||
- édition de rapports complexes,
|
||||
- configuration technique profonde des intégrations machines.
|
||||
|
||||
---
|
||||
|
||||
## 3. Utilisateurs et droits
|
||||
|
||||
| Rôle | Portée | Droits |
|
||||
|------|--------|--------|
|
||||
| `platform_admin` | plateforme complète | vision globale, administration complète |
|
||||
| `owner` | organization complète | accès complet à ses laveries |
|
||||
| `manager` | organization ou établissement | gestion opérationnelle |
|
||||
| `viewer` | organization ou établissement | lecture seule |
|
||||
|
||||
### 3.1 Règle de cloisonnement
|
||||
Toute donnée visible dans le back-office doit être filtrée au minimum par `organization_id`. Si le superviseur est attaché à un établissement précis, la visibilité est encore plus restreinte.
|
||||
|
||||
---
|
||||
|
||||
## 4. Stack Technique
|
||||
|
||||
| Composant | Technologie | Version | Commentaire |
|
||||
|-----------|-------------|---------|-------------|
|
||||
| Backend | Laravel 11 | — | Backend partagé avec l'API |
|
||||
| Rendu SPA | Inertia.js | 2.x | Intégration Laravel / Vue |
|
||||
| UI | Vue.js | 3.x | Composition API |
|
||||
| UI kit | PrimeVue | 4.x | Rapide pour dashboard / tables |
|
||||
| Styles | Tailwind CSS | 3.x | Mise en forme rapide |
|
||||
| State | Pinia | 2.x | Si besoin de stores front |
|
||||
| Graphiques | Chart.js | 4.x | KPIs simples |
|
||||
| Tests front | Vitest + Vue Test Utils | — | Composants critiques |
|
||||
| Tests E2E | Playwright | — | Flux exploitant |
|
||||
|
||||
### 4.1 Temps réel
|
||||
Le temps réel n'est pas un prérequis absolu de la V1. Deux stratégies possibles :
|
||||
- **V1 rapide** : polling 15 à 30 secondes,
|
||||
- **V1 enrichie** : Laravel Echo / Soketi ou Pusher.
|
||||
|
||||
Si le délai est serré, le polling est acceptable.
|
||||
|
||||
---
|
||||
|
||||
## 5. Architecture recommandée
|
||||
|
||||
```
|
||||
resources/js/
|
||||
├── Components/
|
||||
│ ├── Layout/
|
||||
│ ├── Dashboard/
|
||||
│ ├── Machines/
|
||||
│ ├── Pricing/
|
||||
│ ├── Bookings/
|
||||
│ ├── Washes/
|
||||
│ └── UI/
|
||||
├── Pages/
|
||||
│ ├── Auth/
|
||||
│ ├── Dashboard/
|
||||
│ ├── Machines/
|
||||
│ ├── Pricing/
|
||||
│ ├── Bookings/
|
||||
│ ├── Washes/
|
||||
│ └── Settings/
|
||||
└── app.js
|
||||
```
|
||||
|
||||
### 5.1 Principe de navigation
|
||||
- menu latéral simple,
|
||||
- accès rapide au dashboard,
|
||||
- pages data-centric,
|
||||
- peu de modales complexes en V1.
|
||||
|
||||
---
|
||||
|
||||
## 6. Écrans V1
|
||||
|
||||
## 6.1 Connexion
|
||||
|
||||
### Fonctionnalités
|
||||
- email,
|
||||
- mot de passe,
|
||||
- message d'erreur clair,
|
||||
- redirection vers dashboard si session active.
|
||||
|
||||
### Sécurité
|
||||
- session cookie,
|
||||
- CSRF,
|
||||
- rate limiting.
|
||||
|
||||
---
|
||||
|
||||
## 6.2 Tableau de bord
|
||||
|
||||
### Objectif
|
||||
Donner à l'exploitant une vue immédiate de l'état de ses laveries.
|
||||
|
||||
### KPIs V1
|
||||
- chiffre d'affaires du jour,
|
||||
- nombre de lavages du jour,
|
||||
- réservations du jour,
|
||||
- taux d'occupation courant,
|
||||
- nombre de machines offline / en erreur.
|
||||
|
||||
### Sections recommandées
|
||||
- bandeau KPI,
|
||||
- liste des alertes,
|
||||
- aperçu du parc machines,
|
||||
- graphique simple de CA ou occupation.
|
||||
|
||||
### Données affichées
|
||||
Toujours filtrées sur le périmètre du superviseur connecté.
|
||||
|
||||
---
|
||||
|
||||
## 6.3 Liste des machines
|
||||
|
||||
### Colonnes minimales
|
||||
- nom,
|
||||
- établissement,
|
||||
- type,
|
||||
- statut,
|
||||
- dernier heartbeat,
|
||||
- utilisateur courant anonymisé si pertinent,
|
||||
- actions.
|
||||
|
||||
### Filtres
|
||||
- établissement,
|
||||
- statut,
|
||||
- type.
|
||||
|
||||
### Actions V1
|
||||
- voir détail,
|
||||
- basculer maintenance si autorisé,
|
||||
- forcer disponibilité seulement si besoin réel et journalisé.
|
||||
|
||||
---
|
||||
|
||||
## 6.4 Détail machine
|
||||
|
||||
### Contenu
|
||||
- informations générales,
|
||||
- statut actuel,
|
||||
- historique récent des cycles,
|
||||
- historique récent des événements machines,
|
||||
- tarification appliquée,
|
||||
- alertes récentes,
|
||||
- uptime simple si disponible.
|
||||
|
||||
Cette page est très utile pour la démo car elle montre la profondeur du produit sans nécessiter trop d'écrans.
|
||||
|
||||
---
|
||||
|
||||
## 6.5 Réservations
|
||||
|
||||
### Vue liste
|
||||
- utilisateur anonymisé,
|
||||
- machine,
|
||||
- établissement,
|
||||
- créneau,
|
||||
- statut,
|
||||
- montant réservé,
|
||||
- pénalité éventuelle.
|
||||
|
||||
### Filtres
|
||||
- période,
|
||||
- établissement,
|
||||
- machine,
|
||||
- statut.
|
||||
|
||||
---
|
||||
|
||||
## 6.6 Lavages
|
||||
|
||||
### Vue liste
|
||||
- utilisateur anonymisé,
|
||||
- machine,
|
||||
- établissement,
|
||||
- heure de démarrage,
|
||||
- heure de fin,
|
||||
- coût,
|
||||
- statut.
|
||||
|
||||
### Intérêt
|
||||
Permet à l'exploitant de relier l'activité terrain au chiffre d'affaires.
|
||||
|
||||
---
|
||||
|
||||
## 6.7 Tarification
|
||||
|
||||
### Vue liste
|
||||
- établissement,
|
||||
- machine ou type de machine,
|
||||
- plage horaire,
|
||||
- prix,
|
||||
- libellé,
|
||||
- actif / inactif.
|
||||
|
||||
### Formulaire V1
|
||||
- machine ou type,
|
||||
- jours applicables,
|
||||
- heure début / fin,
|
||||
- prix,
|
||||
- libellé,
|
||||
- tarif exclusif app si retenu.
|
||||
|
||||
### Validations
|
||||
- pas de plage inversée,
|
||||
- pas de conflit de règles non géré,
|
||||
- audit de toute modification.
|
||||
|
||||
---
|
||||
|
||||
## 6.8 Promotions
|
||||
|
||||
Si activé en V1, les promotions restent simples :
|
||||
- portée établissement,
|
||||
- type de machine,
|
||||
- réduction fixe ou pourcentage,
|
||||
- date début / fin.
|
||||
|
||||
Si le timing est trop serré, cette page peut être préparée mais non activée en démonstration.
|
||||
|
||||
---
|
||||
|
||||
## 6.9 Paramètres
|
||||
|
||||
### Contenu minimal
|
||||
- profil superviseur,
|
||||
- établissement ou organisation associés,
|
||||
- informations de session,
|
||||
- éventuellement préférences simples.
|
||||
|
||||
---
|
||||
|
||||
## 7. Cloisonnement des données
|
||||
|
||||
### Règles obligatoires
|
||||
- `platform_admin` : accès global,
|
||||
- `owner` : toutes les laveries de son organization,
|
||||
- `manager` : selon son scope,
|
||||
- `viewer` : lecture seule.
|
||||
|
||||
### Implémentation
|
||||
- policies Laravel,
|
||||
- query scopes,
|
||||
- tests dédiés au cloisonnement.
|
||||
|
||||
### Interdiction
|
||||
Aucune page ne doit faire remonter des agrégats globaux non filtrés à un exploitant local.
|
||||
|
||||
---
|
||||
|
||||
## 8. Audit
|
||||
|
||||
### Actions à journaliser
|
||||
- connexion superviseur,
|
||||
- modification de tarif,
|
||||
- création / modification de promotion,
|
||||
- changement manuel de statut machine,
|
||||
- toute action d'administration sensible.
|
||||
|
||||
### Utilité
|
||||
- sécurité,
|
||||
- compréhension métier,
|
||||
- support,
|
||||
- preuve en cas de litige.
|
||||
|
||||
---
|
||||
|
||||
## 9. Temps réel / polling
|
||||
|
||||
### Option 1 - Polling V1 recommandé si délai serré
|
||||
- refresh du dashboard toutes les 30 secondes,
|
||||
- refresh détail machine toutes les 15 à 30 secondes.
|
||||
|
||||
### Option 2 - Temps réel enrichi
|
||||
- Echo,
|
||||
- Soketi ou Pusher,
|
||||
- mise à jour machine / alertes / KPIs.
|
||||
|
||||
### Recommandation
|
||||
Pour la démo de fin de mois, le polling propre est souvent suffisant.
|
||||
|
||||
---
|
||||
|
||||
## 10. Sécurité
|
||||
|
||||
### 10.1 Authentification
|
||||
- session cookie sécurisée,
|
||||
- CSRF,
|
||||
- timeout de session,
|
||||
- rate limiting login.
|
||||
|
||||
### 10.2 Autorisation
|
||||
- policies explicites par rôle,
|
||||
- filtre systématique des établissements.
|
||||
|
||||
### 10.3 Données utilisateur
|
||||
- anonymisation des noms dans les écrans exploitants si non nécessaire,
|
||||
- pas d'affichage d'email complet côté exploitation terrain.
|
||||
|
||||
---
|
||||
|
||||
## 11. Dashboard de démo
|
||||
|
||||
Le dashboard de démo doit montrer visuellement :
|
||||
- plusieurs laveries sur la plateforme,
|
||||
- un exploitant qui ne voit que les siennes,
|
||||
- des machines dans plusieurs états,
|
||||
- un lavage qui démarre puis se termine,
|
||||
- un KPI qui évolue,
|
||||
- une tarification modifiable.
|
||||
|
||||
C'est le meilleur compromis entre crédibilité et temps de développement.
|
||||
|
||||
---
|
||||
|
||||
## 12. Tests
|
||||
|
||||
| Type | Outil | Portée |
|
||||
|------|-------|--------|
|
||||
| Controllers | Pest | Accès dashboard, pricing, machines |
|
||||
| Components | Vitest | KPIs, listes, formulaires |
|
||||
| E2E | Playwright | Connexion, dashboard, tarif, machine |
|
||||
|
||||
### Cas critiques
|
||||
1. un exploitant A ne voit pas les données de B,
|
||||
2. un viewer ne peut pas modifier un tarif,
|
||||
3. un manager voit les bons KPI,
|
||||
4. une machine passe de disponible à en cours,
|
||||
5. une modification de tarif est auditée.
|
||||
|
||||
---
|
||||
|
||||
## 13. Livrables attendus
|
||||
|
||||
- code source back-office,
|
||||
- pages Inertia principales,
|
||||
- dataset de démonstration multi-exploitants,
|
||||
- audit minimal,
|
||||
- tests critiques,
|
||||
- guide court de démonstration.
|
||||
Reference in New Issue
Block a user