Diagramme de Séquence
Génération QR Code

1.1 Objectif du Document

Ce document décrit le diagramme de séquence pour la fonctionnalité de génération de QR code dans l'application mobile REWAPP. Cette fonctionnalité permet aux utilisateurs de convertir leurs points en un QR code scannable par un commerçant partenaire pour obtenir une réduction immédiate sur leurs achats.

1.2 Contexte Fonctionnel

La génération de QR code est au cœur du système de cashback commerçant REWAPP. Elle permet aux utilisateurs de :

• Convertir leurs points accumulés en valeur dépensable
• Bénéficier d'un ratio avantageux (+5% vs cashback bancaire)
• Utiliser leurs points instantanément chez un partenaire

1.3 Règles Fondamentales

2.1 Acteurs Principaux

2.2 Composants Backend

3.1 Diagramme Complet

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

title Generation QR Code - REWAPP

actor "Client" as client #LightBlue
participant "App Mobile" as app #LightGreen
participant "API Gateway" as gateway #Orange
participant "QR Service" as qr_service #Yellow
participant "Points Service" as points_service #Cyan
database "Redis" as redis #Pink
database "PostgreSQL" as db #LightGray

== Initialisation ==
client -> app : Ouvre ecran Utiliser points
app -> gateway : GET /api/v1/points/balance
gateway -> points_service : getBalance userId
points_service -> db : SELECT balance
db --> points_service : balance 850
points_service --> gateway : balance 850
gateway --> app : 200 OK solde
app --> client : Affiche solde 850 pts

== Saisie Montant ==
client -> app : Saisit 200 points
app -> app : Validation locale
app --> client : Apercu 200 pts = 21 EUR

== Generation QR Code ==
client -> app : Clic Generer QR Code
app -> gateway : POST /api/v1/qrcode/generate
gateway -> gateway : Validation JWT
gateway -> qr_service : generateQRCode

qr_service -> points_service : lockPoints 200
points_service -> db : BEGIN TRANSACTION
points_service -> db : UPDATE user_points locked
points_service -> db : INSERT point_locks
db --> points_service : OK
points_service -> db : COMMIT
points_service --> qr_service : lockId

qr_service -> qr_service : Genere UUID unique
qr_service -> qr_service : Calcule expiration 60s
qr_service -> qr_service : Signature HMAC-SHA256
qr_service -> redis : SET qr EXPIRE 70s
redis --> qr_service : OK
qr_service -> db : INSERT qr_codes
db --> qr_service : OK

qr_service --> gateway : qrCode expiresAt
gateway --> app : 201 Created QR data
app --> client : QR Code affiche Compteur 60s

== Expiration si non scanne ==
alt #Pink QR non scanne apres 60s
    app --> client : QR Code expire
    app -> gateway : POST expire qrId
    gateway -> qr_service : expireQRCode
    qr_service -> redis : DEL qr
    qr_service -> points_service : unlockPoints
    points_service -> db : UPDATE locked
    qr_service -> db : UPDATE status EXPIRED
    gateway --> app : Points debloques
    app --> client : Points restaures
end

@enduml

4.1 Phase 1 : Consultation du Solde

4.2 Phase 2 : Saisie du Montant

4.3 Phase 3 : Génération du QR Code

4.4 Phase 4 : Affichage et Compteur

5.1 Scénario A : Solde Insuffisant

5.2 Scénario B : Régénération Immédiate

5.3 Scénario C : Perte de Connexion

5.4 Scénario D : Application en Arrière-plan

6.1 Erreurs Côté Client

6.2 Erreurs Côté Serveur

6.3 Exceptions Métier

7.1 Ratio de Conversion

7.2 Validité du QR Code

7.3 Usage Unique

7.4 Blocage des Points (FIFO)

8.1 Signature HMAC-SHA256

Le QR code contient une signature cryptographique garantissant son authenticité :

{
  "data": {
    "qrId": "qr_abc123def456",
    "userId": "usr_789xyz",
    "points": 200,
    "valueEur": 21.00,
    "createdAt": 1732456800,
    "expiresAt": 1732456860
  },
  "signature": "a3b8c9d4e5f6..."
}

signature = HMAC-SHA256(JSON.stringify(data), SERVER_SECRET_KEY)

8.2 Protections Anti-Fraude

8.3 Protection du Secret

• Clé HMAC stockée dans Variables d'environnement CapRover
• Rotation automatique tous les 90 jours
• Accès restreint aux services autorisés uniquement
• Logs d'accès audités

9.1 Endpoint API

Authorization: Bearer {jwt_token}
Content-Type: application/json
X-Device-Id: {device_uuid}
X-App-Version: {version}

{
  "points": 200,
  "merchantId": "optional_merchant_uuid"
}

{
  "success": true,
  "data": {
    "qrId": "qr_abc123def456",
    "qrCode": "data:image/png;base64,iVBORw0...",
    "points": 200,
    "valueEur": 21.00,
    "createdAt": "2025-11-24T10:00:00Z",
    "expiresAt": "2025-11-24T10:01:00Z",
    "ttlSeconds": 60
  }
}

9.2 Structure de Données Redis

Clé : qr:{qrId}
TTL : 70 secondes
Valeur :
{
  "qrId": "qr_abc123",
  "userId": "usr_456",
  "points": 200,
  "valueEur": 21.00,
  "lockId": "lock_xyz123",
  "status": "ACTIVE",
  "createdAt": 1732456800,
  "expiresAt": 1732456860,
  "signature": "..."
}

9.3 Table PostgreSQL

10.1 Points Clés du Flux

• Consultation du solde disponible en temps réel
• Validation du montant (min 10 points, max solde)
• Blocage immédiat des points à la génération
• Signature cryptographique HMAC-SHA256
• Validité stricte de 60 secondes
• Compteur visuel avec code couleur progressif
• Expiration automatique et déblocage des points
• Usage unique garanti côté serveur

10.2 Métriques de Performance

10.3 Checklist Implémentation

• Endpoint POST /api/v1/qrcode/generate implémenté
• Service de blocage/déblocage des points fonctionnel
• Signature HMAC-SHA256 avec clé sécurisée
• Stockage Redis avec TTL configuré
• Persistance PostgreSQL avec index optimisés
• Compteur visuel côté mobile avec animations
• Gestion expiration automatique (client + serveur)
• Rate limiting configuré (5/heure)
• Monitoring et alerting activés
• Tests unitaires et d'intégration validés