5.2.5 Scan QR et Débit Points - REWAPP Documentation

1

OBJECTIF DU DOCUMENT

Ce document décrit le diagramme de séquence détaillé du processus de scan QR code par un commerçant partenaire et le débit des points du compte client. Ce flux intervient après la génération du QR code par le client (voir document 5.2.4).

CONTEXTE

Le client a généré un QR code depuis son application mobile. Il présente ce QR code au commerçant partenaire pour utiliser ses points comme moyen de paiement.

2

ACTEURS ET COMPOSANTS

2.1 Acteurs Humains

Acteurs du Processus

Acteur	Rôle	Description
Client	Payeur	Utilisateur présentant son QR code pour payer avec ses points
Commerçant	Accepteur	Partenaire scannant le QR code via son dashboard

2.2 Composants Techniques

Architecture du Flux

Composant	Type	Responsabilité
`Dashboard Partenaire`	Frontend PWA	Interface de scan du commerçant
`API Gateway`	Infrastructure	Point d'entrée, authentification, routage
`Service QR Codes`	Microservice	Validation, décodage et traitement des QR codes
`Service Points`	Microservice	Gestion des soldes et débit des points
`Service Transactions`	Microservice	Enregistrement et traçabilité des transactions
`Service Notifications`	Microservice	Envoi des notifications push et email
`Base de Données`	PostgreSQL	Stockage persistant des données
`Cache Redis`	Cache	Stockage temporaire des QR codes actifs

3

PRÉREQUIS

3.1 Prérequis Client

Compte client actif et vérifié
QR code généré et non expiré (< 60 secondes)
Points suffisants et bloqués pour la transaction
Application mobile ouverte avec QR code affiché

3.2 Prérequis Commerçant

Compte partenaire validé par l'administration REWAPP
Abonnement actif (Standard ou Premium)
Dashboard Partenaire accessible (connexion active)
Appareil avec caméra fonctionnelle
Connexion internet stable

3.3 Prérequis Système

QR code présent dans le cache Redis
Signature HMAC-SHA256 valide
Services backend opérationnels
Disponibilité base de données

4

DIAGRAMME DE SÉQUENCE PLANTUML

Diagramme de Séquence - Scan QR et Débit Points

@startuml
skinparam backgroundColor #FFFFFF
skinparam sequenceArrowThickness 2
skinparam roundcorner 10

title Scan QR et Debit Points REWAPP

actor "Commercant" as Partner #Orange
participant "Dashboard" as Dashboard #Yellow
participant "API Gateway" as Gateway #Gold
participant "QR Service" as QRService #Pink
database "Redis" as Redis #Salmon
participant "Points Service" as PointsService #Plum
participant "Transaction Service" as TxService #LightGreen
participant "Notification" as NotifService #Coral
database "PostgreSQL" as DB #LightGray
actor "Client" as Client #LightBlue

== Initiation Scan ==
Partner -> Dashboard : Ouvre scanner QR
Dashboard -> Dashboard : Active camera
Partner -> Dashboard : Scanne QR code
Dashboard -> Dashboard : Decode QR JSON

== Envoi Validation ==
Dashboard -> Gateway : POST /api/v1/qr-codes/scan
Gateway -> Gateway : Auth JWT
Gateway -> QRService : Transmet requete

== Verification QR ==
QRService -> Redis : GET qr_code
Redis --> QRService : Donnees QR status

alt #Pink QR non trouve
    QRService --> Gateway : 404 NOT_FOUND
    Dashboard --> Partner : Erreur invalide
else #Orange QR expire
    QRService --> Gateway : 410 EXPIRED
    Dashboard --> Partner : Erreur expire
else #Yellow QR deja utilise
    QRService --> Gateway : 409 ALREADY_USED
    Dashboard --> Partner : Erreur utilise
else #LightGreen QR valide
    QRService -> QRService : Verifie signature HMAC
    QRService -> QRService : Verifie timestamp
    QRService -> QRService : Verifie partner_id
end

== Debit Points ==
QRService -> PointsService : Demande debit
PointsService -> DB : Verifie solde
DB --> PointsService : Solde confirme

alt #Pink Solde insuffisant
    PointsService --> QRService : INSUFFICIENT
    QRService --> Gateway : 402
    Dashboard --> Partner : Erreur
else #LightGreen Solde OK
    PointsService -> DB : UPDATE status debited
    PointsService -> DB : Applique FIFO
    DB --> PointsService : Debit confirme
    PointsService --> QRService : Reussi
end

== Enregistrement Transaction ==
QRService -> TxService : Creer transaction QR_PAYMENT
TxService -> DB : INSERT transactions
DB --> TxService : Transaction creee tx_id
TxService --> QRService : tx_id confirme

== Invalidation QR ==
QRService -> Redis : SET status used
QRService -> DB : UPDATE used_at NOW

== Reponse Notifications ==
QRService --> Gateway : 200 OK
Gateway --> Dashboard : Succes
Dashboard --> Partner : Confirmation visuelle

QRService ->> NotifService : Notification async
NotifService -> Client : Push Paiement valide

@enduml

5

FLUX NOMINAL - SCAN QR RÉUSSI

5.1 Étapes Détaillées

Séquence Complète

Étape	Action	Acteur	Description
1	Ouverture scanner	Commerçant	Le commerçant ouvre l'interface de scan dans son Dashboard Partenaire
2	Activation caméra	Dashboard	Le système active la caméra de l'appareil pour la lecture QR
3	Scan du QR code	Commerçant	Le commerçant pointe la caméra vers l'écran du client
4	Décodage local	Dashboard	Le QR code est décodé localement (format JSON signé)
5	Envoi au serveur	Dashboard	La requête POST est envoyée à l'API Gateway
6	Authentification	API Gateway	Vérification du token JWT du commerçant
7	Validation QR	Service QR	Vérification existence, expiration, signature, usage unique
8	Débit points	Service Points	Débit des points du compte client (méthode FIFO)
9	Création transaction	Service Transactions	Enregistrement de la transaction avec tous les détails
10	Invalidation QR	Service QR + Redis	Marquage du QR code comme utilisé
11	Confirmation	Dashboard	Affichage visuel + signal sonore pour le commerçant
12	Notification client	Service Notifications	Envoi push notification au client

5.2 Chronologie Typique

Performance du Flux

Moment	Durée	Cumul
Scan et décodage	~500ms	0,5s
Envoi et authentification	~100ms	0,6s
Validation QR code	~50ms	0,65s
Débit des points	~100ms	0,75s
Enregistrement transaction	~80ms	0,83s
Réponse au dashboard	~50ms	0,88s
Notification push client	~200ms	1,08s

PERFORMANCE

Temps total moyen : < 1,1 seconde

5.3 Données Échangées

5.3.1 Contenu du QR Code (Décodé)

JSON

{
  "qr_id": "uuid-unique-qr-code",
  "user_id": "uuid-utilisateur-crypte",
  "points": 200,
  "value_eur": 21.00,
  "generated_at": "2025-11-24T14:30:00.000Z",
  "expires_at": "2025-11-24T14:31:00.000Z",
  "signature": "hmac-sha256-signature-base64"
}

5.3.2 Requête API (Dashboard vers Backend)

POST /api/v1/qr-codes/scan

Headers

Authorization: Bearer {jwt_token_partenaire}
Content-Type: application/json

Body

JSON

{
  "qr_payload": "{contenu_qr_encode_base64}",
  "partner_id": "uuid-partenaire",
  "scanned_at": "2025-11-24T14:30:15.000Z"
}

5.3.3 Réponse Succès

JSON 200 OK

{
  "success": true,
  "transaction_id": "tx-uuid-unique",
  "points_debited": 200,
  "value_eur": 21.00,
  "client_name": "M***e S.",
  "timestamp": "2025-11-24T14:30:15.500Z"
}

6

FLUX ALTERNATIFS

6.1 FA1 - QR Code Expiré (> 60 secondes)

Étape	Comportement
1	Le commerçant scanne un QR code dont le timestamp dépasse 60 secondes
2	Le Service QR Codes détecte l'expiration via le champ `expires_at`
3	Rejet immédiat avec code erreur `QR_CODE_EXPIRED` (HTTP 410)
4	Affichage message : Ce QR code a expiré. Demandez au client d'en générer un nouveau.
5	Les points précédemment bloqués sont automatiquement débloqués côté client

RÈGLE

Validité QR code = 60 secondes (non négociable)

6.2 FA2 - QR Code Déjà Utilisé

Étape	Comportement
1	Le commerçant scanne un QR code qui a déjà été validé
2	Le Service QR Codes vérifie le statut dans Redis et trouve `status = 'used'`
3	Rejet immédiat avec code erreur `QR_CODE_ALREADY_USED` (HTTP 409)
4	Affichage message : Ce QR code a déjà été utilisé.
5	Log de la tentative pour analyse anti-fraude

RÈGLE

Usage UNIQUE - Toute réutilisation est systématiquement rejetée

6.3 FA3 - Signature Invalide

Étape	Comportement
1	Le QR code scanné contient une signature HMAC-SHA256 incorrecte
2	Le Service QR Codes recalcule la signature et détecte l'incohérence
3	Rejet immédiat avec code erreur `INVALID_SIGNATURE` (HTTP 403)
4	Alerte de sécurité générée automatiquement
5	Log complet pour investigation anti-fraude

ALERTE SÉCURITÉ

Ce cas indique une potentielle tentative de fraude ou altération du QR code

6.4 FA4 - Solde Insuffisant

Étape	Comportement
1	Les points ont été débloqués entre la génération et le scan (cas rare)
2	Le Service Points détecte que le solde actuel < montant demandé
3	Rejet avec code erreur `INSUFFICIENT_BALANCE` (HTTP 402)
4	Message : Solde insuffisant. Le client doit générer un nouveau QR code.

NOTE

Ce cas est rare car les points sont normalement bloqués à la génération

6.5 FA5 - Partenaire Non Autorisé

Étape	Comportement
1	Le QR code est scanné par un partenaire différent de celui autorisé
2	Vérification du `partner_id` dans le payload
3	Rejet avec code erreur `UNAUTHORIZED_PARTNER` (HTTP 403)
4	Message : Ce QR code n'est pas utilisable dans votre établissement.

6.6 FA6 - Timeout Réseau

Étape	Comportement
1	La requête n'aboutit pas dans le délai imparti (timeout 10s)
2	Le Dashboard affiche : Erreur de connexion. Veuillez réessayer.
3	Le commerçant peut relancer le scan
4	Si le QR code a expiré entre-temps, le client doit en générer un nouveau

6.7 FA7 - Compte Client Suspendu

Étape	Comportement
1	Le compte client associé au QR code est suspendu
2	Le Service QR Codes vérifie le statut du compte utilisateur
3	Rejet avec code erreur `ACCOUNT_SUSPENDED` (HTTP 403)
4	Message générique : Transaction impossible. Contactez le support.

7

RÈGLES MÉTIER APPLIQUÉES

7.1 Conversion Points vers Euros

RÈGLE DE CONVERSION

10 points = 1,05€ chez le commerçant (+5% bonus)

Formule : Valeur EUR = Points × 0,105

Exemples de Conversion

Points Débités	Valeur Transaction	Calcul
50 points	5,25€	50 × 0,105
100 points	10,50€	100 × 0,105
200 points	21,00€	200 × 0,105
500 points	52,50€	500 × 0,105
1000 points	105,00€	1000 × 0,105

7.2 Méthode FIFO pour le Débit

RÈGLE FIFO

First In, First Out - Les points les plus anciens sont débités en priorité

Exemple de débit de 250 points :

Application de la Méthode FIFO

Lot	Points Avant	Expiration	Points Débités	Points Après
Lot 1	200 pts	10/01/2026	200 pts	0 pts
Lot 2	150 pts	15/02/2026	50 pts	100 pts
Lot 3	300 pts	20/03/2026	0 pts	300 pts
TOTAL	650 pts	-	250 pts	400 pts

7.3 Validité Stricte du QR Code

RÈGLE DE VALIDITÉ

Validité = 60 secondes exactement

Pas de tolérance sur l'expiration
Compteur visible côté client pendant la génération
Synchronisation horloge serveur (NTP)

7.4 Usage Unique Garanti

RÈGLE D'UNICITÉ

Un QR code ne peut être utilisé qu'UNE SEULE FOIS

Marquage immédiat comme "used" après validation
Stockage du statut dans Redis ET PostgreSQL
Rejet systématique de toute tentative de réutilisation

8

MESSAGES ET NOTIFICATIONS

8.1 Messages Commerçant (Dashboard)

Messages d'Interface

Situation	Message Affiché	Visuel
Succès	Paiement validé ! {X} points ({Y}€)	Vert + Icône check + Son
QR expiré	QR code expiré. Demandez un nouveau code au client.	Rouge
QR déjà utilisé	Ce QR code a déjà été utilisé.	Rouge
QR invalide	QR code invalide ou corrompu.	Rouge
Solde insuffisant	Solde insuffisant pour cette transaction.	Orange
Erreur réseau	Erreur de connexion. Veuillez réessayer.	Orange
Erreur serveur	Service temporairement indisponible.	Orange

8.2 Notifications Client (Push)

8.2.1 Notification Succès

Paiement validé ✅

Notification Push

Corps : Vous avez dépensé {X} points ({Y}€) chez {Nom Partenaire}

Action : Ouvre l'historique des transactions

8.2.2 Notification Échec (si QR expiré)

QR code expiré

Notification Push

Corps : Votre QR code a expiré. Vos {X} points ont été débloqués.

Action : Ouvre l'écran de génération QR

8.3 Confirmations Visuelles et Sonores

Succès

Écran vert avec animation checkmark
Son de validation (bip court positif)
Vibration courte (si mobile)
Affichage détails pendant 5 secondes

Échec

Écran rouge avec animation X
Son d'erreur (bip long négatif)
Message d'erreur explicite
Bouton "Réessayer" visible

9

CODES D'ERREUR

Référentiel des Codes d'Erreur

Code HTTP	Code Erreur	Description	Action Suggérée
200	`SUCCESS`	Transaction réussie	Afficher confirmation
400	`INVALID_QR_FORMAT`	Format QR code invalide	Vérifier l'intégrité du QR
402	`INSUFFICIENT_BALANCE`	Solde points insuffisant	Client doit régénérer un QR
403	`INVALID_SIGNATURE`	Signature cryptographique invalide	Alerte fraude potentielle
403	`UNAUTHORIZED_PARTNER`	Partenaire non autorisé	Vérifier la configuration
403	`ACCOUNT_SUSPENDED`	Compte client suspendu	Contacter le support
404	`QR_CODE_NOT_FOUND`	QR code non trouvé en base	QR invalide ou déjà purgé
409	`QR_CODE_ALREADY_USED`	QR code déjà utilisé	Demander nouveau QR au client
410	`QR_CODE_EXPIRED`	QR code expiré (> 60s)	Demander nouveau QR au client
429	`RATE_LIMIT_EXCEEDED`	Trop de tentatives	Attendre avant de réessayer
500	`INTERNAL_ERROR`	Erreur serveur interne	Réessayer ou contacter support
503	`SERVICE_UNAVAILABLE`	Service temporairement indisponible	Réessayer dans quelques instants

10

SÉCURITÉ ET ANTI-FRAUDE

10.1 Mesures de Sécurité

Mesures Implémentées

Mesure	Implémentation	Objectif
Signature HMAC-SHA256	Clé secrète serveur, signature vérifiée à chaque scan	Empêcher la falsification de QR codes
Expiration 60s	Timestamp dans le payload, vérification stricte	Limiter la fenêtre d'exploitation
Usage unique	Flag "used" dans Redis et PostgreSQL	Empêcher la réutilisation
Tokenisation	IDs utilisateur cryptés dans le QR	Protéger les données personnelles
Rate limiting	Max 10 scans/minute par partenaire	Prévenir les attaques brute force
JWT partenaire	Authentification obligatoire	Identifier le commerçant légitime

10.2 Détection de Fraude

Patterns Suspects

Pattern Suspect	Détection	Action
Multiples tentatives QR expiré	> 5 QR expirés en 10 minutes	Alerte équipe sécurité
Tentatives de réutilisation	Même QR scanné plusieurs fois	Log + potentiel blocage temporaire
Volume anormal	> 50 transactions/heure pour un partenaire	Revue manuelle requise
Signatures invalides répétées	> 3 signatures invalides en 1 heure	Blocage temporaire + investigation
Localisations incohérentes	Transactions dans des villes différentes en peu de temps	Alerte au client

10.3 Audit Trail

Chaque tentative de scan est loguée avec :

Timestamp précis (millisecondes)
ID du QR code tenté
ID du partenaire
Résultat (succès/échec + code erreur)
Adresse IP
User-Agent
Géolocalisation (si disponible)

CONSERVATION

Conservation des logs : 24 mois (conformité RGPD)

11

RÉCAPITULATIF

11.1 Synthèse du Flux

< 1,1s Temps de traitement moyen

60s Validité QR code

UNIQUE Usage QR code

1,05€ Valeur de 10 points

FIFO Méthode de débit

HMAC Signature SHA256

11.2 Checklist Validation

QR code non expiré (< 60s)
QR code non utilisé
Signature HMAC-SHA256 valide
Partenaire authentifié et autorisé
Solde client suffisant
Compte client actif
Transaction enregistrée
Notifications envoyées

11.3 Documents Connexes

5.2.4 Génération QR Code - Processus de création du QR
6.6 Sécurité QR Codes - Détail des mesures de sécurité
1.4 Règles Métier de Fidélité - Règles de conversion et validité
7.1 Documentation API Backend - Endpoints détaillés