Laverie/backend
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e569c84c9d144db1be1a7ae7c621f461529ce6d3
backend/documentation/CDC_API_Backend.md
T
bastien 293f49adfa Ajout documentation
2026-07-04 22:47:55 +02:00

23 KiB
Raw Blame History

Cahier des Charges — API & Base de Données

Projet : Laverie Connectée — Backend

Version : 1.0
Date : 2026-06-27
Stack principale : Laravel 11, MySQL 8, Redis, Docker

1. Contexte & Objectifs

1.1 Contexte

Développement d'une API REST centrale servant :

  • Une application mobile multi-plateforme (Flutter : Android / iOS / Web)
  • Un back-office d'administration (Vue.js)
  • Des automates de laverie connectés via passerelle LLDP

L'API est le seul point d'entrée pour toute la logique métier. Aucun client ne communique directement avec la base de données.

1.2 Objectifs

  • Exposer des endpoints REST sécurisés (JWT) pour tous les clients
  • Gérer les utilisateurs, l'authentification, les porte-monnaie et les paiements
  • Orchestrer les communications avec les automates (commandes machines)
  • Automatiser les notifications (cron, push, événementiel)
  • Garantir la conformité RGPD sur toutes les données personnelles

2. Stack Technique

Composant Technologie Version Justification
Framework Laravel 11.x Robustesse, écosystème, ORM Eloquent
Base de données principale MySQL 8.0 Transactions ACID, maturité
Cache & Queues Redis 7.x Queues asynchrones, cache sessions
Auth Laravel Sanctum 4.x JWT stateless multi-guard
ORM Eloquent (Laravel) Relations, scopes, casting
Queues Laravel Horizon 5.x Monitoring des workers Redis
Scheduler Laravel Scheduler (Laravel) Cron jobs natifs
Notifications Push Firebase FCM HTTP v1 Android + Web
Notifications Push APNs (Apple) HTTP/2 iOS
Paiement Abstraction PaymentProvider — Multi-partenaire
Tests PHPUnit + Pest — TDD sur logique métier critique
Documentation API Scramble (L5-Swagger) — OpenAPI 3.0 auto-générée
Conteneurisation Docker + Docker Compose — Dev/staging/prod reproductibles
CI/CD GitHub Actions — Tests + déploiement automatisé

3. Architecture

3.1 Structure du projet Laravel

app/
├── Http/
│   ├── Controllers/
│   │   ├── Auth/
│   │   │   ├── UserAuthController.php
│   │   │   └── SupervisorAuthController.php
│   │   ├── User/
│   │   │   ├── WalletController.php
│   │   │   ├── BookingController.php
│   │   │   └── WashController.php
│   │   ├── Supervisor/
│   │   │   ├── DashboardController.php
│   │   │   ├── MachineController.php
│   │   │   └── PricingController.php
│   │   └── Webhook/
│   │       └── PaymentWebhookController.php
│   ├── Middleware/
│   │   ├── EnsureEmailVerified.php
│   │   ├── CheckWalletBalance.php
│   │   └── RateLimitPayment.php
│   └── Requests/          # Form Requests (validation)
├── Models/
│   ├── User.php
│   ├── Supervisor.php
│   ├── Establishment.php
│   ├── Machine.php
│   ├── Booking.php
│   ├── Wash.php
│   ├── WalletTransaction.php
│   ├── PricingRule.php
│   ├── Promotion.php
│   ├── Notification.php
│   └── GdprConsent.php
├── Services/
│   ├── WalletService.php           # Logique porte-monnaie (atomique)
│   ├── BookingService.php          # Réservation + débit auto no-show
│   ├── MachineCommandService.php   # Abstraction commandes LLDP
│   ├── NotificationService.php     # FCM + APNs
│   ├── Payment/
│   │   ├── PaymentProviderInterface.php
│   │   ├── StripeProvider.php
│   │   └── LydiProvider.php        # Exemple partenaire alternatif
│   └── PricingService.php          # Calcul tarif dynamique
├── Jobs/
│   ├── SendPushNotificationJob.php
│   ├── DebitNoShowBookingJob.php
│   └── SyncMachineStatusJob.php
├── Events/ & Listeners/
├── Policies/                       # Autorisation par modèle
└── Console/Commands/               # Artisan custom

3.2 Guards d'authentification

sanctum guards :
├── user      → token scope [user]    → app mobile
├── supervisor → token scope [supervisor] → back-office
└── machine   → token scope [machine] → automates (optionnel)

3.3 Flux de données principal

App Flutter → HTTPS → API Laravel → MySQL
                              ↓
                        Redis Queue → Job Workers
                              ↓
                    FCM / APNs / LLDP Gateway

4. Base de Données — Schéma Complet

4.1 Table users

CREATE TABLE users (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    uuid            CHAR(36) UNIQUE NOT NULL,              -- Identifiant public exposé dans l'API
    first_name      VARCHAR(100) NOT NULL,
    last_name       VARCHAR(100) NOT NULL,
    email           VARCHAR(255) UNIQUE NOT NULL,
    phone           VARCHAR(20) UNIQUE,
    birthdate       DATE,
    email_verified_at TIMESTAMP NULL,
    password        VARCHAR(255) NOT NULL,
    wallet_balance  DECIMAL(10,2) NOT NULL DEFAULT 0.00,
    referral_code   VARCHAR(20) UNIQUE,
    referred_by     BIGINT UNSIGNED NULL REFERENCES users(id),
    loyalty_points  INT UNSIGNED NOT NULL DEFAULT 0,
    fcm_token       VARCHAR(255) NULL,                     -- Token push Android/Web
    apns_token      VARCHAR(255) NULL,                     -- Token push iOS
    locale          VARCHAR(10) DEFAULT 'fr',
    is_active       BOOLEAN DEFAULT TRUE,
    anonymized_at   TIMESTAMP NULL,                        -- RGPD : suppression logique
    created_at      TIMESTAMP,
    updated_at      TIMESTAMP,
    deleted_at      TIMESTAMP NULL                         -- Soft delete
);

4.2 Table gdpr_consents

CREATE TABLE gdpr_consents (
    id          BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    user_id     BIGINT UNSIGNED NOT NULL REFERENCES users(id),
    type        ENUM('data_processing','marketing','analytics') NOT NULL,
    accepted    BOOLEAN NOT NULL,
    ip_address  VARCHAR(45),
    user_agent  TEXT,
    accepted_at TIMESTAMP NOT NULL,
    revoked_at  TIMESTAMP NULL
);

4.3 Table supervisors

CREATE TABLE supervisors (
    id                BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    establishment_id  BIGINT UNSIGNED NOT NULL REFERENCES establishments(id),
    name              VARCHAR(200) NOT NULL,
    email             VARCHAR(255) UNIQUE NOT NULL,
    password          VARCHAR(255) NOT NULL,
    role              ENUM('admin','manager','viewer') DEFAULT 'manager',
    is_active         BOOLEAN DEFAULT TRUE,
    created_at        TIMESTAMP,
    updated_at        TIMESTAMP
);

4.4 Table establishments

CREATE TABLE establishments (
    id          BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    uuid        CHAR(36) UNIQUE NOT NULL,
    name        VARCHAR(200) NOT NULL,
    address     TEXT NOT NULL,
    city        VARCHAR(100),
    zip_code    VARCHAR(10),
    latitude    DECIMAL(10,8),
    longitude   DECIMAL(11,8),
    timezone    VARCHAR(50) DEFAULT 'Europe/Paris',
    is_active   BOOLEAN DEFAULT TRUE,
    created_at  TIMESTAMP,
    updated_at  TIMESTAMP
);

4.5 Table machines

CREATE TABLE machines (
    id                BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    uuid              CHAR(36) UNIQUE NOT NULL,
    establishment_id  BIGINT UNSIGNED NOT NULL REFERENCES establishments(id),
    name              VARCHAR(100) NOT NULL,
    type              ENUM('washer_small','washer_large','dryer_small','dryer_large') NOT NULL,
    qr_code           VARCHAR(255) UNIQUE NOT NULL,
    lldp_device_id    VARCHAR(100),                        -- Identifiant côté passerelle LLDP
    status            ENUM('available','running','reserved','maintenance','offline') DEFAULT 'available',
    current_user_id   BIGINT UNSIGNED NULL REFERENCES users(id),
    cycle_started_at  TIMESTAMP NULL,
    cycle_ends_at     TIMESTAMP NULL,
    last_heartbeat    TIMESTAMP NULL,                      -- Dernier ping de l'automate
    created_at        TIMESTAMP,
    updated_at        TIMESTAMP
);

4.6 Table pricing_rules

CREATE TABLE pricing_rules (
    id            BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    machine_id    BIGINT UNSIGNED NOT NULL REFERENCES machines(id),
    day_type      ENUM('weekday','weekend','holiday','all') DEFAULT 'all',
    slot_start    TIME NOT NULL,
    slot_end      TIME NOT NULL,
    price         DECIMAL(6,2) NOT NULL,
    label         VARCHAR(100),                            -- Ex: "Heure creuse", "Heure pleine"
    requires_app  BOOLEAN DEFAULT FALSE,                   -- Tarif exclusif app
    created_at    TIMESTAMP,
    updated_at    TIMESTAMP
);

4.7 Table promotions

CREATE TABLE promotions (
    id                BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    establishment_id  BIGINT UNSIGNED NOT NULL REFERENCES establishments(id),
    machine_type      ENUM('washer_small','washer_large','dryer_small','dryer_large','all') DEFAULT 'all',
    discount_type     ENUM('percent','fixed') NOT NULL,
    discount_value    DECIMAL(6,2) NOT NULL,
    starts_at         TIMESTAMP NOT NULL,
    ends_at           TIMESTAMP NOT NULL,
    description       TEXT,
    is_active         BOOLEAN DEFAULT TRUE,
    created_at        TIMESTAMP,
    updated_at        TIMESTAMP
);

4.8 Table bookings

CREATE TABLE bookings (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    uuid            CHAR(36) UNIQUE NOT NULL,
    user_id         BIGINT UNSIGNED NOT NULL REFERENCES users(id),
    machine_id      BIGINT UNSIGNED NOT NULL REFERENCES machines(id),
    slot_start      TIMESTAMP NOT NULL,
    slot_end        TIMESTAMP NOT NULL,
    amount_reserved DECIMAL(6,2) NOT NULL,                 -- Montant débité au moment de la réservation
    amount_penalty  DECIMAL(6,2) DEFAULT 0.00,             -- Pénalité no-show
    status          ENUM('pending','confirmed','active','completed','cancelled','no_show') DEFAULT 'pending',
    cancelled_at    TIMESTAMP NULL,
    penalty_applied_at TIMESTAMP NULL,
    created_at      TIMESTAMP,
    updated_at      TIMESTAMP
);

4.9 Table washes

CREATE TABLE washes (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    uuid            CHAR(36) UNIQUE NOT NULL,
    user_id         BIGINT UNSIGNED NOT NULL REFERENCES users(id),
    machine_id      BIGINT UNSIGNED NOT NULL REFERENCES machines(id),
    booking_id      BIGINT UNSIGNED NULL REFERENCES bookings(id),
    trigger_method  ENUM('qr_code','booking','terminal') NOT NULL,
    started_at      TIMESTAMP NOT NULL,
    ended_at        TIMESTAMP NULL,
    duration_minutes INT UNSIGNED,
    cost            DECIMAL(6,2) NOT NULL,
    pricing_rule_id BIGINT UNSIGNED NULL REFERENCES pricing_rules(id),
    created_at      TIMESTAMP,
    updated_at      TIMESTAMP
);

4.10 Table wallet_transactions

CREATE TABLE wallet_transactions (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    uuid            CHAR(36) UNIQUE NOT NULL,
    user_id         BIGINT UNSIGNED NOT NULL REFERENCES users(id),
    type            ENUM('credit','debit') NOT NULL,
    amount          DECIMAL(10,2) NOT NULL,
    balance_after   DECIMAL(10,2) NOT NULL,
    source          ENUM('top_up','wash','booking','penalty','refund','referral_bonus') NOT NULL,
    reference_id    BIGINT UNSIGNED NULL,                  -- ID du wash ou booking associé
    reference_type  VARCHAR(100) NULL,                     -- Morph polymorphique
    payment_provider VARCHAR(50) NULL,
    payment_ref     VARCHAR(255) NULL,                     -- Référence transaction externe
    created_at      TIMESTAMP
);

4.11 Table push_notifications

CREATE TABLE push_notifications (
    id          BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    user_id     BIGINT UNSIGNED NULL REFERENCES users(id),   -- NULL = broadcast
    type        VARCHAR(100) NOT NULL,
    title       VARCHAR(255) NOT NULL,
    body        TEXT NOT NULL,
    data        JSON NULL,
    channel     ENUM('fcm','apns','both') DEFAULT 'both',
    status      ENUM('pending','sent','failed') DEFAULT 'pending',
    sent_at     TIMESTAMP NULL,
    created_at  TIMESTAMP
);

5. Endpoints API — Spécification Complète

5.1 Authentification utilisateur

Méthode Endpoint Description Auth
POST /api/v1/auth/register Inscription + collecte consentements RGPD Public
POST /api/v1/auth/login Connexion, retourne access_token + refresh_token Public
POST /api/v1/auth/refresh Renouvelle le token Public
POST /api/v1/auth/logout Révoque le token User
POST /api/v1/auth/forgot-password Envoi email reset Public
POST /api/v1/auth/reset-password Réinitialisation Public
GET /api/v1/auth/verify-email/{token} Vérification email Public

Payload register :

{
  "first_name": "Jean",
  "last_name": "Dupont",
  "email": "jean@example.com",
  "phone": "+33612345678",
  "password": "••••••••",
  "birthdate": "1990-01-15",
  "referral_code": "ABC123",
  "consents": {
    "data_processing": true,
    "marketing": false,
    "analytics": true
  }
}

Réponse login :

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200...",
  "user": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jean",
    "wallet_balance": "12.50"
  }
}

5.2 Porte-monnaie

Méthode Endpoint Description Auth
GET /api/v1/wallet Solde actuel User
GET /api/v1/wallet/transactions Historique paginé User
POST /api/v1/wallet/top-up/initiate Initier rechargement User
POST /api/v1/wallet/top-up/confirm Confirmer après paiement User
GET /api/v1/wallet/top-up/providers Liste partenaires paiement disponibles User

Payload top-up initiate :

{
  "amount": 20.00,
  "provider": "stripe",
  "return_url": "laverie://wallet/topup-result"
}

Réponse :

{
  "payment_intent_id": "pi_xxx",
  "redirect_url": "https://checkout.stripe.com/...",
  "expires_at": "2026-06-27T15:30:00Z"
}

5.3 Établissements & Machines

Méthode Endpoint Description Auth
GET /api/v1/establishments Liste avec coordonnées GPS User
GET /api/v1/establishments/{uuid} Détail + machines + disponibilités User
GET /api/v1/machines/{uuid} Détail machine + tarif actuel User
GET /api/v1/machines/{uuid}/availability Créneaux disponibles sur N jours User
GET /api/v1/machines/{uuid}/pricing Grille tarifaire active User
POST /api/v1/machines/{uuid}/heartbeat Ping de l'automate (machine scope) Machine

5.4 Réservations

Méthode Endpoint Description Auth
POST /api/v1/bookings Créer une réservation User
GET /api/v1/bookings Mes réservations User
GET /api/v1/bookings/{uuid} Détail réservation User
PATCH /api/v1/bookings/{uuid}/cancel Annuler User
PATCH /api/v1/bookings/{uuid}/move Déplacer le créneau User

Payload POST /bookings :

{
  "machine_uuid": "550e8400-...",
  "slot_start": "2026-06-28T09:00:00Z",
  "slot_end": "2026-06-28T10:00:00Z"
}

Règles métier :

  • Vérification atomique du solde (mutex Redis sur wallet:user:{id})
  • Débit immédiat du montant + supplément réservation (1€)
  • Si annulation > 2h avant : remboursement intégral
  • Si annulation < 2h ou no-show : pénalité définie par machine.no_show_penalty
  • Cron toutes les 5 minutes : détection no-show → DebitNoShowBookingJob

5.5 Lavages

Méthode Endpoint Description Auth
POST /api/v1/washes/start Démarrer via QR code User
GET /api/v1/washes/{uuid} Statut en cours User
GET /api/v1/washes Historique User

Payload POST /washes/start :

{
  "qr_code": "MACHINE_QR_ABC123",
  "program": "60C_standard"
}

Flux :

  1. Valider le QR → identifier la machine
  2. Vérifier statut machine (available)
  3. Vérifier solde suffisant
  4. Calculer prix (tarif actuel + promo éventuelle)
  5. Débit atomique du porte-monnaie
  6. Envoyer commande à la passerelle LLDP via MachineCommandService
  7. Mettre à jour le statut machine (running)
  8. Retourner confirmation + durée estimée

5.6 Authentification superviseur

Méthode Endpoint Description Auth
POST /api/v1/supervisor/auth/login Connexion superviseur Public
POST /api/v1/supervisor/auth/logout Déconnexion Supervisor
GET /api/v1/supervisor/dashboard Statistiques + alertes Supervisor
GET /api/v1/supervisor/machines Parc machines de l'établissement Supervisor
PATCH /api/v1/supervisor/machines/{uuid} Mise à jour machine Supervisor
GET /api/v1/supervisor/pricing Grille tarifaire Supervisor
POST /api/v1/supervisor/pricing Créer règle tarifaire Supervisor
PUT /api/v1/supervisor/pricing/{id} Modifier règle Supervisor
DELETE /api/v1/supervisor/pricing/{id} Supprimer règle Supervisor
GET /api/v1/supervisor/promotions Promotions actives Supervisor
POST /api/v1/supervisor/promotions Créer promotion Supervisor

6. Services Métier Critiques

6.1 WalletService — Opérations atomiques

Toute opération sur le porte-monnaie passe par ce service. Les débits/crédits sont encapsulés dans des transactions MySQL + verrou Redis pour éviter les race conditions.

WalletService::credit(user, amount, source, referenceId)
WalletService::debit(user, amount, source, referenceId)  ← lance WalletInsufficientFundsException si insuffisant
WalletService::reserve(user, amount, bookingId)          ← débit préventif réservation
WalletService::refund(user, walletTransactionId)

Règle absolue : Aucun controller ne doit modifier users.wallet_balance directement. Tout passe par WalletService.

6.2 PricingService — Tarif dynamique

PricingService::getCurrentPrice(machine, datetime)
  → Cherche la PricingRule active pour (machine_id, day_type, heure)
  → Applique Promotion active si existante
  → Retourne { base_price, discount, final_price, label, requires_app }

Priorité des règles : Règle spécifique machine > Règle par type machine > Tarif défaut établissement.

6.3 MachineCommandService — Abstraction LLDP

MachineCommandService::startWash(machine, program)
MachineCommandService::stopWash(machine)
MachineCommandService::getStatus(machine)

L'implémentation concrète (LldpGatewayAdapter) communique avec la passerelle LLDP via HTTP interne. En cas d'indisponibilité de la passerelle, la commande est mise en queue Redis et retentée 3 fois (backoff exponentiel).

6.4 PaymentProviderInterface

interface PaymentProviderInterface {
    public function initiateTopUp(User $user, float $amount, string $returnUrl): TopUpIntent;
    public function confirmTopUp(string $paymentRef): TopUpConfirmation;
    public function handleWebhook(Request $request): void;
}

Implémentations : StripeProvider, LydiProvider, SumUpProvider (extensible).

7. Tâches Planifiées (Cron)

Fréquence Job Description
Toutes les 5 min CheckNoShowBookings Détecter et débiter les no-shows
Toutes les 5 min SyncMachineStatuses Interroger la passerelle LLDP
Toutes les heures SendScheduledNotifications Notifications planifiées en attente
Chaque jour 02:00 GenerateDailyStats Agrégation statistiques pour dashboard
Chaque jour 03:00 CleanExpiredTokens Purge tokens révoqués
Chaque semaine AnonymizeInactiveUsers RGPD : users inactifs > 3 ans

8. Notifications — Architecture

8.1 Déclencheurs

Événement Canal Timing
Rechargement confirmé Push Immédiat
Réservation confirmée Push Immédiat
Rappel créneau Push 30 min avant
Lavage terminé Push Immédiat
Solde faible (< 5€) Push À chaque débit
Promotion disponible Push Planifié par superviseur
No-show détecté Push À la détection

8.2 Implémentation

  • Les notifications sont toujours créées en base (push_notifications) avant envoi
  • L'envoi passe par un Job Redis (SendPushNotificationJob) → résilience
  • FCM HTTP v1 pour Android/Web, APNs HTTP/2 pour iOS
  • En cas d'échec, 3 retries avec backoff (1min, 5min, 15min)

9. Sécurité

9.1 Authentification

  • Tokens JWT via Laravel Sanctum (stateless)
  • Refresh token rotation (invalidation à chaque renouvellement)
  • Rate limiting : 5 tentatives de login / 10 minutes / IP
  • Rate limiting paiements : 3 initiations / minute / user

9.2 Données

  • Mots de passe hashés : bcrypt (cost 12)
  • Données sensibles (IBAN, tokens paiement) : chiffrées AES-256-CBC en base
  • HTTPS obligatoire (TLS 1.3 minimum)
  • UUID exposés dans l'API (jamais les auto-increment IDs)
  • Soft deletes sur users — anonymisation RGPD séparée

9.3 API

  • Validation stricte de tous les inputs (FormRequest)
  • Politique CORS restrictive (origines whitelist)
  • Headers sécurité : Strict-Transport-Security, X-Frame-Options, Content-Security-Policy

10. Tests

Type Outil Couverture cible
Tests unitaires Pest WalletService, PricingService, BookingService
Tests d'intégration Pest + SQLite in-memory Tous les endpoints API
Tests de contrats — Webhooks paiement
Tests de charge k6 Endpoints critiques (start wash, top-up)

Cas critiques à tester :

  • Race condition débit simultané du porte-monnaie
  • Timeout passerelle LLDP → comportement de la queue
  • Webhook paiement reçu en doublon (idempotence)
  • No-show avec annulation simultanée

11. Variables d'environnement requises

APP_ENV=production
APP_KEY=base64:...

DB_HOST=
DB_DATABASE=laverie
DB_USERNAME=
DB_PASSWORD=

REDIS_HOST=
REDIS_PASSWORD=

# Paiement
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=

# Notifications
FIREBASE_PROJECT_ID=
FIREBASE_PRIVATE_KEY=
FIREBASE_CLIENT_EMAIL=
APNS_KEY_ID=
APNS_TEAM_ID=
APNS_PRIVATE_KEY_PATH=

# LLDP Gateway
LLDP_GATEWAY_URL=
LLDP_GATEWAY_TOKEN=

# URLs
FRONTEND_URL=
APP_URL=

12. Livrables attendus

  • Code source Laravel complet (GitHub)
  • Migrations SQL versionnées
  • Seeders (données de démo)
  • Documentation OpenAPI 3.0 auto-générée (/api/documentation)
  • Collection Postman exportée
  • docker-compose.yml pour dev local
  • .env.example documenté
  • README avec instructions d'installation
  • Suite de tests (couverture > 80% sur les services critiques)
Reference in New Issue View Git Blame Copy Permalink