La Cafête — Plateforme de Gestion Multi-Tenant

La Cafête est une plateforme de gestion de buvette et cantine scolaire/entreprise avec système de carte prépayée QR. Elle permet de gérer les rechargements de carte, les ventes de produits, les réservations de repas, les scan de QR code, les cartes liées parent-enfant, la gestion de stock, et dispose d'un système complet de détection d'anomalies et de notifications multi-canal.

Version

Cette documentation couvre la v1.0 de l'API La Cafête.

---

Architecture

Vue d'ensemble

┌─────────────────────────────────────────────────────────────────┐
│                        Frontend (React + Vite)                   │
│   Dashboard Admin  │  App Détenteur (Flutter)  │  PWA La Cafête  │
└───────────────────────────────┬─────────────────────────────────┘
                                │ HTTPS / REST
┌───────────────────────────────▼─────────────────────────────────┐
│                     Backend (Rust + Axum)                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │   API    │  │   Auth   │  │ Persist. │  │  Worker  │       │
│  │ (Axum)   │  │  (JWT)   │  │  (SQLx)  │  │ (Apalis) │       │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ Storage  │  │  Notif.  │  │  Events  │  │  Domain  │       │
│  │(Local/S3)│  │(Multi)   │  │ (Outbox) │  │  (Pure)  │       │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
└────────────┬──────────────────────┬──────────────────────────────┘
             │                      │
┌────────────▼────────┐  ┌──────────▼──────────┐
│     PostgreSQL       │  │  Redis + MinIO S3   │
│ (Schema Multi-Tenant)│  │   (Jobs + Assets)    │
└─────────────────────┘  └─────────────────────┘

Isolation Multi-Tenant

La Cafête utilise le modèle schema-per-tenant de PostgreSQL :

Niveau	Description	Schema	Tables clés
Système	Plateforme, organisations, utilisateurs admin	public	organizations, platform_users, roles, permissions
Organisation	Sites, utilisateurs, cartes, transactions	org_{slug}	sites, tenant_users, cards, card_transactions, products

Chaque organisation possède son propre schéma PostgreSQL (org_{slug}). Le schéma public stocke les données globales du système.

Principes clés

Principe	Description
Ledger immuable	Toutes les transactions financières sont enregistrées dans card_transactions (source de vérité). Aucun update ou delete n'est autorisé.
RBAC dynamique	Permissions composables assignées via des rôles. Aucune permission codée en dur.
Idempotence	Toute mutation financière requiert un Idempotency-Key pour garantir l'atomicité.
Atomicité DB	Le solde d'une carte n'est JAMAIS modifié directement — passe par la fonction fn_apply_card_transaction().
Transactional Outbox	Les événements sont d'abord écrits en DB puis consommés de manière asynchrone (garantie at-least-once).
Signature QR Ed25519	Les cartes sont identifiées par QR code signé. Le système supporte la rotation des clés sans interruption.
Scan QR code	Détenteurs et caissiers peuvent scanner les QR codes depuis l'application mobile ou le dashboard.
Cartes liées parent-enfant	Les porteurs peuvent lier des cartes enfants pour gérer les budgets familiaux.
Gestion de stock	Suivi des entrées/sorties, détection des produits périmés, seuils d'alerte.
Multi-langue	L'interface est disponible en Français et en Anglais.

---

Niveaux d'accès

Système vs Organisation

La Cafête définit deux niveaux d'accès complètement séparés :

Niveau	Utilisateurs	Permissions	Routes
Système (Platform)	Administrateurs N2	Gérer les organisations, utilisateurs platform, rôles système	/admin/system/*
Organisation (Tenant)	Admin N1, Superviseur, Caissier, Vendeur, Porteur	Opérer dans l'organisation	/admin/org/*, /cards/*, /transactions/*

Schéma des autorisations

Platform (N2) ──────────────────────────────────────
  │  └── super_admin     : toutes les permissions
  │  └── org_viewer      : consultation orgs + stats globales
  │  └── support_agent   : support limité
  │
  └── Contexte JWT ──► Organisation (org_id) ────────
                          │  └── admin_n1      : gestion complète org
                             └── supervisor : supervision + correction
                             └── cashier   : encaissement
                             └── seller    : vente produits
                             └── card_holder : porteur (mobile)

---

Démarrage rapide

# 1. Cloner et démarrer l'infrastructure
git clone https://github.com/lescale-africaine/caffette
cd caffette
docker compose up -d

# 2. Configurer l'environnement
cp .env.example .env
# Éditer .env avec vos secrets (JWT keys, credentials SMTP, etc.)

# 3. Compiler et lancer l'API
cargo build --workspace
cargo run -p caffette-api

# 4. Lancer le worker (dans un autre terminal)
cargo run -p caffette-worker

# 5. Lancer le dashboard frontend
cd apps/dashboard && npm install && npm run dev

Vérification

curl http://localhost:3500/healthz
# {"status":"ok","service":"caffette-api","version":"0.1.0"}

---

Organisation de la documentation

Section	Contenu
Guide	Concepts, authentification, permissions, notifications, erreurs
API — Auth	Authentification et gestion de sessions
API — Me	Profil et préférences de l'utilisateur connecté
API — Cards	Gestion des cartes, rechargement, transactions
API — Products	Catalogue produits, catégories, stocks
API — Réservations	Réservation de repas et plannings
API — Transactions	Historique et recherche de transactions
API — Paiements	Sessions de paiement et validation
API — Statistiques	Tableaux de bord et rapports
API — Sites	Points de vente et configuration
API — Notifications	Templates, canaux, envois
API — Paramètres	Configuration organisation, seuils d'anomalie
API — Système	Administration plateforme, organisations, rôles
Flows métier	Diagrammes et descriptions des parcours UC-01 à UC-11
Opérations	Guides pour l'exploitation : rôles, provisioning, jobs, monitoring

---

Support

• GitHub : lescale-africaine/caffette
• Issues : Ouvrir un ticket