Points et compteurs

Les compteurs portent tous les soldes du programme de fidélité. Remizo les tient à jour en temps réel, ticket par ticket.

Types de compteurs

Type	Usage	Unité
Points	Programme à points classique	pts
Cashback	Cagnotte en euros	centimes
Visites	Nombre de passages, cartes à tampons	visites
Technique	Compteurs internes à une mécanique (paliers, jeux)	libre

Chaque type a un code (POINTS, CASHBACK, VISITS), une règle d’expiration par défaut et indique s’il peut devenir négatif.

Le registre des mouvements

Chaque variation est un mouvement : gain (earn), utilisation (burn), réservation, libération, ajustement manuel, expiration, remise à zéro. Le registre n’efface jamais rien : une annulation de ticket crée des mouvements de compensation. Le solde est la somme des mouvements ; il est matérialisé pour être lu instantanément et peut toujours être recalculé.

Trois valeurs sont exposées :

• total : tout ce qui a été crédité et non consommé ;
• en attente : crédité mais pas encore actif (délai d’activation, par exemple 14 jours pour couvrir les retours) ;
• disponible : total − réservé, ce que le client peut utiliser maintenant.

Expiration

Chaque crédit forme un lot avec sa date d’expiration (jamais, au bout de N jours, fin de mois, fin d’année, date fixe). Les utilisations consomment les lots dans l’ordre d’échéance (les points qui expirent le plus tôt partent en premier). La tâche points.expire crée les mouvements d’expiration ; points.expiry_warnings prévient les clients avant l’échéance.

Gagner des points

Par les actions d’offre : points fixes, points par tranche d’euros (sur le brut, l’éligible, ou le montant après remises), multiplicateur sur les points des niveaux inférieurs. Les points sont projetés à l’évaluation et postés au commit.

Payer en points

Le paiement en points se fait en deux temps, pour ne jamais débiter un client dont le ticket est abandonné :

1. Réserver : POST /v1/points/reserve avec le client, le compteur, le montant et une durée de vie. Si le solde disponible est insuffisant, la réponse est 409 insufficient-balance. Le montant réservé n’est plus disponible.
2. Confirmer : POST /v1/points/reservations/{id}/confirm, éventuellement pour un montant inférieur ; le reste est libéré. L’opération est idempotente.
3. ou Annuler : POST /v1/points/reservations/{id}/cancel. Les réservations non résolues expirent automatiquement (tâche points.reservations.expire).

Variante intégrée : la caisse indique la réservation dans le ticket (options.pointsBurn.reservationId, ou un paiement method: points dont la référence est l’identifiant de réservation) ; la confirmation se fait alors atomiquement au commit.

Gestes commerciaux

Depuis la fiche client du studio, un utilisateur autorisé peut ajouter ou retirer des points. Le motif est obligatoire (code et texte libre) et l’opération est tracée dans le journal d’audit. Ces ajustements passent par les mêmes fonctions que le moteur : aucune arithmétique de solde n’existe ailleurs.

Exemples : points fixes, multiplicateur, compteur de visites.