Ma Caisse

Caisse enregistreuse et gestion de commerce — SPA React 19 + Vite + TypeScript, pensée pour les commerces de détail en FCFA.

L'application est un SaaS multi-organisation : un même utilisateur peut appartenir à plusieurs commerces, avec un rôle différent par commerce (propriétaire, gérant, caissier). Elle fonctionne seule en mode démo (données simulées persistées localement) et se branche sur un backend REST sans modifier une ligne d'interface.

État : frontend complet, aucune dépendance backend dans ce dépôt. bun run lint ✔ · bun run test → 23 fichiers / 175 tests ✔ · bun run build ✔

---

Sommaire

• Fonctionnalités
• Stack technique
• Démarrage rapide
• Comptes de démonstration
• Scripts
• Variables d'environnement
• Mode démo ou backend REST
• Rôles et permissions
• Architecture
• Structure du projet
• Tests et qualité
• Déploiement
• Documentation

---

Fonctionnalités

Domaine	Contenu
Caisse (POS)	Panier, recherche produit, 5 moyens de paiement (Espèces, Wave, Orange Money, Carte, Crédit partiel), reçu écran + PDF, ventes récentes, clôture de journée
Stock	Création/édition d'articles, catégories, réapprovisionnement rapide, alertes de rupture, prix d'achat et marge (réservés aux rôles autorisés)
Crédits	Créances clients, encaissements partiels, filtres, historiques par client
Dépenses	Saisie et suivi des charges du commerce
Bilan	Chiffre d'affaires, marge, trésorerie, répartition par canal de paiement, objectif journalier
Accueil	Tableau de bord (tendance des ventes, alertes stock, dernières ventes, clôture)
Équipe	Invitation de membres, changement de rôle, retrait — avec hiérarchie des rôles
Multi-organisation	Appartenance à plusieurs commerces, changement d'espace, données cloisonnées par organisation
Abonnement	Plans Starter et Pro Commerçant
Export	Export CSV et PDF comptable (respecte les permissions)
UI/UX	Responsive (sidebar ≥ lg, barre inférieure < lg), toasts, modales accessibles (Échap, focus, scroll verrouillé), thème maison

---

Stack technique

Brique	Version	Usage
React	19.3	Interface
TypeScript	5.8 (strict)	Typage
Vite	6.4	Dev server + build (chunks react / charts / pdf)
Tailwind CSS	4.1	Design system (@theme dans src/index.css)
Zustand	5	État persistant (localStorage), mutations optimistes
Recharts	3	Graphiques (bilan, accueil)
jsPDF + autotable	4	Reçus et exports PDF
Vitest + Testing Library	5	Tests unitaires, stores, services, smoke
ESLint 10 + Prettier	—	Lint et formatage
Bun	≥ 1.4	Runtime, gestionnaire de paquets et scripts

bun.lock est en lockfileVersion: 2 : Bun 1.4 ou plus récent est requis. Le package-lock.json a été retiré volontairement (ignoré par .gitignore).

---

Démarrage rapide

# prérequis : Bun ≥ 1.4
bun install --frozen-lockfile
bun run dev            # http://localhost:3000

Aucune configuration n'est nécessaire : sans variable d'environnement, l'application démarre en mode démo avec des données de test réalistes.

---

Comptes de démonstration

Mot de passe commun : demo1234 (mode démo uniquement).

Utilisateur	Email	Rôle
Mamadou Konaté	[email protected]	propriétaire de Boutique Étoile + gérant de Supérette Le Baobab
Awa Ndiaye	[email protected]	caissière de Boutique Étoile
Koffi Mensah	[email protected]	propriétaire de Supérette Le Baobab
Fatou Diop	[email protected]	gérante de Supérette Le Baobab

Mamadou appartient à deux organisations : utilisez le sélecteur d'espace (sidebar ou profil) pour observer le cloisonnement des données et les différences de permissions.

---

Scripts

Commande	Effet
bun run dev	Serveur de développement sur le port 3000 (--host 0.0.0.0)
bun run build	Build de production dans dist/
bun run preview	Prévisualisation du build
bun run lint	tsc --noEmit + eslint src --max-warnings 0 (zéro tolérance)
bun run test	Tests Vitest (une passe)
bun run test:coverage	Tests + couverture (seuils bloquants)
bun run test:watch	Tests en mode watch
bun run format	Prettier sur src/**/*.{ts,tsx,css}
bun run clean	Supprime dist/ et server.js

---

Variables d'environnement

Toutes les variables client sont préfixées VITE_ et lues uniquement dans src/config/env.ts.

Variable	Défaut	Rôle
VITE_API_MODE	mock	mock = données locales ; http = backend REST réel
VITE_API_BASE_URL	/api	URL de base du backend (ex. https://api.macaisse.app/v1)
VITE_API_MOCK_LATENCY_MS	250 (0 en test)	Latence simulée de l'adaptateur démo
VITE_API_TIMEOUT_MS	15000	Délai maximal avant abandon d'une requête
VITE_AUTH_PHONE	off	on réaffiche la connexion par téléphone (OTP WhatsApp, D2). Masquée tant que les crédits WhatsApp/SMS ne sont pas provisionnés : l'écran d'accès ne montre que e-mail + Google
DISABLE_HMR	—	true coupe le HMR et le watch (utilisé par l'environnement AI Studio)
GEMINI_API_KEY	—	Optionnel ; utilisé par src/lib/ai/client.ts (client IA expérimental, non branché à l'UI)

Exemple .env.local pour brancher un backend :

This is the beginning of the README. Read the rest at the original. Read the full README ↗