CLAUDE.md — App Fidélité (tablette magasin)

Guide pour travailler sur ce projet. À lire avant toute modification.

Vue d'ensemble

Application Flutter de programme de fidélité pour un magasin, sur tablette Android en portrait (caisse). Chaque client a une carte = un QR code ; le staff scanne, ajoute des factures (montant € → points), et le client échange ses points contre des récompenses.

Fait partie d'un écosystème de deux apps partageant le même backend :

app_fideliter (CE repo) : app tablette / staff.
app_fideliter_client (repo séparé) : app client (compte, points, QR).

App sœur gestion_prix_produit (autre projet) : même stack et mêmes conventions, reprises ici. Thème identique mais accent vert émeraude (au lieu du bleu) pour distinguer les apps sur une même tablette.

Stack technique

Flutter (Material 3), Dart. Cible : Android tablette, portrait verrouillé.
PocketBase comme backend (auto-hébergé sur un Raspberry Pi) : auth + base SQLite + API REST + temps réel (SSE).
Packages clés :
- pocketbase — client backend (auth, CRUD, réaltime)
- shared_preferences — persistance de la session (rester connecté)
- mobile_scanner — scan du QR client (caméra ; scanette externe à venir)
- qr_flutter — affichage/génération du QR d'un client
- intl — formatage € et dates (locale fr_FR)
Icône via flutter_launcher_icons (source : assets/icon/).

Backend PocketBase

URL serveur : https://db.tailb756e1.ts.net (définie dans lib/pocketbase_config.dart). Le Raspberry est exposé publiquement en HTTPS via Tailscale Funnel (gratuit) → accessible de partout (4G, autre WiFi…), pas seulement sur le LAN. En local, le serveur reste aussi joignable en http://192.168.1.32:8090. Tailscale est installé sur le Pi uniquement ; les clients n'installent que l'app. Le Pi doit rester allumé
- connecté à Internet.
Compte staff : mathew.simon2004@gmail.com (mot de passe défini au setup). Un compte est « staff » si son champ is_staff = true dans la collection users.
Superuser (admin PocketBase) : géré via l'UI http://192.168.1.32:8090/_/.

Collections

Collection	Type	Champs principaux	Accès (règles)
`users`	auth	`is_staff` (bool) + email/password	chacun voit son compte ; `is_staff` non modifiable par l'utilisateur
`clients`	base	`user` (relation, option.), `code` (unique), `nom`, `prenom`, `telephone`, `points`	staff = tout ; client = sa fiche uniquement
`mouvements`	base	`client` (relation), `type` (facture/recompense/ajustement), `montant_euros`, `points`, `libelle`, `created`	staff écrit ; client lit les siens (anti-triche)
`recompenses`	base	`nom`, `cout_points`, `actif`	tout connecté lit ; staff modifie
`reglages`	base	`euros_par_point`, `nom_magasin` (1 seule ligne)	tout connecté lit ; staff modifie

Points de vigilance backend

Pas de trigger PocketBase : le solde clients.points est maintenu par l'app (ClientRepository._ecrireSolde), qui crée le mouvement PUIS met à jour le solde. Comme seul le staff écrit, pas de souci de concurrence.
Code client (FID-XXXXXX) généré côté app (ClientRepository._genererCode), unicité garantie par un index unique + réessais.
Créer/modifier des collections : voir l'admin UI, ou l'API superuser (POST /api/collections/_superusers/auth-with-password puis /api/collections).

Architecture de l'app

Singletons .instance pour les services/repositories.
Repositories ChangeNotifier = source de vérité, écoutés via AnimatedBuilder.
Temps réel : chaque repository s'abonne (pb.collection(...).subscribe) et met à jour sa liste en mémoire → l'UI se synchronise entre tous les appareils.
Auth : AuthGate écoute pb.authStore.onChange. Session persistée via AsyncAuthStore (SharedPreferences) → on reste connecté.

Structure

lib/
├── main.dart                     # init (locale fr, PocketBase) + thème
├── config.dart                   # constantes (ratio défaut, préfixe code)
├── pocketbase_config.dart        # URL serveur, client `pb`, helper `estStaff`
├── theme.dart                    # thème noir & blanc + accent vert émeraude
├── models/                       # client, mouvement, recompense (fromMap PocketBase)
├── services/
│   ├── reglages.dart             # ratio €/point + nom magasin (+ temps réel)
│   ├── client_repository.dart    # clients + factures + récompenses + points (+ temps réel)
│   └── recompense_repository.dart# catalogue (+ temps réel)
├── screens/
│   ├── auth_gate.dart            # login staff ↔ app selon la session
│   ├── staff_login_screen.dart
│   ├── home_shell.dart           # 4 onglets
│   ├── clients_screen.dart       # liste + recherche + création
│   ├── client_edit_screen.dart   # Nom / Prénom / Téléphone
│   ├── client_detail_screen.dart # solde, facture, récompense, historique (édit/suppr, temps réel)
│   ├── scan_screen.dart          # scan QR → fiche client (_ouvrirParCode)
│   ├── recompenses_screen.dart
│   └── reglages_screen.dart      # ratio, nom magasin, état serveur, déconnexion
├── widgets/                      # pastille_points, qr_client
└── utils/format.dart            # euro(), points(), dateHeure() (fr_FR)

Règles métier

Points gagnés = montant facture ÷ euros_par_point (fractionnaires, ex. 12 € à 10 €/pt = 1,2 pt).
Changer le ratio n'affecte que les nouvelles factures (pas de recalcul rétroactif — volontaire).
Éditer une facture recalcule ses points au ratio courant et réajuste le solde.
Récompenses : gagner et dépenser des points (débit à l'utilisation).

Conventions de code

Tout en français : noms de variables, méthodes, commentaires, libellés UI.
Reprendre le style existant (singletons, ChangeNotifier, copyWith, fromMap).
Modèles : fromMap(record.toJson()) où record est un RecordModel PocketBase. Les relations sont des id (string) ; created est une date ISO (string).

Commandes

flutter pub get
flutter analyze                     # doit rester à 0 problème
flutter test
flutter build apk --release
# Installer en gardant les données (session conservée) :
adb -s <DEVICE_ID> install -r build/app/outputs/flutter-apk/app-release.apk
adb devices                         # lister les appareils branchés

Icône : dart run flutter_launcher_icons après modif de assets/icon/.

Roadmap / à faire

Scanette USB externe : se comporte comme un clavier → brancher un champ caché qui appelle scan_screen.dart → _ouvrirParCode (déjà factorisé).
Accès externe au serveur (hors LAN) : IP/domaine public + HTTPS (puis retirer usesCleartextTraffic).
Impression du QR (carte physique), bonus de bienvenue / paliers, statistiques.
App client (app_fideliter_client) : à aligner sur ce backend PocketBase.

7.2 KiB Raw Permalink Blame History