Fidely

PWA de fidélité pour commerces, 100% offline et sans backend. Deux modes : commerçant (gestion cartes + scan client) et client (QR code personnel).

Stack & environnement

• Nuxt 4.4.2 — structure app/ (Nuxt 4 layer)
• Vue 3 — Composition API + <script setup> exclusivement
• TypeScript 5.9.3
• Nuxt UI 4.5.1 — composants UI (UButton, UCard, UForm, UInput, UModal…)
• Tailwind CSS 4.2.1 — via @import "tailwindcss" dans main.css
• @vite-pwa/nuxt 1.1.1 — PWA offline-first, auto-update
• qrcode 1.5.4 — génération QR côté client uniquement
• html5-qrcode 2.3.8 — scan QR via caméra, import dynamique dans onMounted
• Icônes : Lucide (i-lucide-*) + Simple Icons (i-simple-icons-*)
• Gestionnaire de paquets : pnpm 10.32.1
• Stockage : IndexedDB (object stores cards + clients), localStorage pour client_id et mode
• State management : composables uniquement, pas de Pinia
• Tests : Vitest 4.1 + @nuxt/test-utils 4.0 + fake-indexeddb 6.2 + happy-dom 20.8

Commandes essentielles

pnpm dev          # Serveur de développement
pnpm build        # Build production (génère le service worker PWA)
pnpm preview      # Preview du build (tester PWA offline)
pnpm lint         # ESLint
pnpm typecheck    # Vérification TypeScript via nuxt typecheck
pnpm postinstall  # nuxt prepare (auto après install)
pnpm vitest run   # Lancer tous les tests unitaires

Le service worker et le comportement offline/installable ne sont actifs qu'après pnpm build && pnpm preview.

Architecture du projet

app/
├── app.vue              # Racine : <UApp><NuxtPage /></UApp> + useHead/useSeoMeta
├── app.config.ts        # Thème Nuxt UI : primary=green, neutral=slate
├── assets/css/main.css  # @import tailwindcss + @nuxt/ui + palette verte custom
├── components/
│   ├── CardItem.vue         # Carte fidélité avec actions points
│   ├── QRCodeDisplay.vue    # Rendu QR code (canvas, ClientOnly)
│   └── Scanner.vue          # Scan QR via caméra (html5-qrcode, dynamic import)
├── composables/
│   ├── useDB.ts         # Toutes les opérations IndexedDB
│   └── useClient.ts     # Gestion UUID client (localStorage)
├── pages/
│   ├── index.vue        # Sélection mode + redirect localStorage
│   ├── merchant.vue     # Dashboard commerçant
│   ├── scan.vue         # Scanner QR client
│   ├── me.vue           # QR code client plein écran
│   └── client/[id].vue  # Gestion points d'un client
└── utils/
    └── uuid.ts          # generateUUID() via crypto.randomUUID()
public/
├── pwa-192x192.png      # Icône PWA
└── pwa-512x512.png      # Icône PWA
nuxt.config.ts           # Modules, ESLint stylistic, PWA manifest + workbox

Conventions obligatoires

Ces conventions DOIVENT être respectées sur tout code écrit ou modifié, sans exception.

Règles tests non négociables :

• Toute nouvelle feature (composable, composant, règle métier) doit être accompagnée de tests
• 0 test en échec avant de marquer une tâche ✅

Tests automatisés

Framework configuré : Vitest + @nuxt/test-utils + fake-indexeddb + happy-dom

Règle absolue — toujours lancer les tests

Après toute modification de composable, composant ou utilitaire :

pnpm vitest run

• 0 test en échec avant de marquer une tâche comme ✅
• Si un test échoue suite à un changement intentionnel : mettre à jour le test en même temps que le code
• Ne jamais commiter du code qui casse des tests existants

Ce que Claude ne doit PAS faire

• Ne pas modifier nuxt.config.ts sans confirmation explicite
• Ne pas modifier app/app.config.ts (thème de couleurs) sans confirmation
• Ne pas changer la structure des dossiers dans app/ sans validation
• Ne pas installer de nouvelles dépendances sans confirmation
• Ne pas écrire de code sans types TypeScript explicites (pas de any)
• Ne pas utiliser d'autres composants UI que ceux de @nuxt/ui (pas de shadcn, Vuetify, etc.)
• Ne pas ajouter de store Pinia sans discussion préalable (architecture composables en place)
• Ne pas prérenderer les pages (routeRules prerender) — l'app dépend de localStorage/IndexedDB au montage
• Ne pas importer html5-qrcode en import statique (crash SSR)
• Ne pas utiliser localStorage / indexedDB en dehors de onMounted ou avec guard process.server

📝 Mise à jour README.md

Mettre à jour README.md pour toute nouvelle feature visible, commande ou dépendance. Ne pas dupliquer avec CLAUDE.md ni TASKS.md.

🛠️ Skills disponibles

🤖 Agents disponibles

Règles

• Ne jamais supprimer une section existante sans raison — enrichir plutôt que remplacer
• Rester concis : le README est lu par quelqu'un qui découvre le projet, pas par quelqu'un qui le maintient
• Pas de duplication avec CLAUDE.md (instructions Claude) ni PLANNING.md (specs) ni TASKS.md (avancement)

📋 Synchronisation PLANNING.md → TASKS.md

À chaque fois que PLANNING.md est modifié, analyse et mets immédiatement à jour TASKS.md en conséquence.

Procédure obligatoire après toute modification de PLANNING.md

1. Lire TASKS.md dans son état actuel
2. Identifier ce qui a changé dans PLANNING.md :
   • Nouvelle feature ajoutée → ajouter en 📋 À faire
   • Feature supprimée → déplacer en 🚫 Hors scope avec date et raison
   • Règle métier modifiée → vérifier si une tâche ✅ Fait doit repasser en ⚠️ À revoir
   • Décision technique changée → vérifier les tâches impactées
   • Hors scope étendu → vérifier si des tâches 📋 À faire doivent être archivées
3. Mettre à jour le compteur d'avancement global en haut de TASKS.md
4. Mettre à jour _Dernière mise à jour_ dans TASKS.md
5. Informer l'utilisateur avec ce format exact :

🔄 TASKS.md mis à jour suite à une modification de PLANNING.md

• ➕ Ajouté en "À faire" : [liste ou "aucun"]
• 🔁 Déplacé : [liste ou "aucun"]
• ⚠️ Repassé en "À revoir" : [liste ou "aucun"]
• 🚫 Archivé en "Hors scope" : [liste ou "aucun"]

Règles absolues

• Ne jamais modifier TASKS.md sans avoir lu PLANNING.md en entier
• Ne jamais supprimer une tâche — toujours déplacer ou archiver
• Ne jamais modifier TASKS.md sans en informer l'utilisateur
• En cas de doute sur l'impact d'un changement → demander confirmation avant toute modification