Djelimeet

Authentification par numéro de téléphone + OTP, sans mot de passe

• Contexte : la cible (bureaux d'associations, tontines de quartier à Abidjan) est équipée en smartphones mais peu habituée aux mots de passe forts ; le numéro de téléphone est déjà l'identifiant universel du mobile money local (Wave, Orange Money). Un mot de passe oublié est le premier motif d'abandon d'une app grand public en Afrique de l'Ouest francophone, et sa récupération par email est peu fiable (adresses email secondaires, mal retenues).

• Options envisagées :

  1. Email + mot de passe classique — familier pour un public technique, mais quasi inexistant comme identifiant stable chez la cible réelle (une association de quartier n'a pas d'email collectif) ; ajoute un flux de récupération de mot de passe à sécuriser et à maintenir.
  2. Numéro de téléphone + OTP (WhatsApp puis SMS), sans mot de passe — alignement total avec l'identifiant déjà utilisé pour le mobile money ; supprime toute la surface d'attaque liée aux mots de passe (réutilisation, fuite de base, phishing de mot de passe). Coût : dépendance à la délivrabilité WhatsApp/SMS (latence, coût d'envoi, zones mal couvertes), et un numéro perdu/volé devient le point unique de récupération de compte.
  3. OTP + mot de passe optionnel en secours — compromis qui réintroduit la complexité qu'on voulait éviter (deux chemins de login à sécuriser et à tester) pour un bénéfice marginal, la cible n'en demande pas.
• Décision : option 2. OTP à 6 chiffres (WhatsApp d'abord, repli SMS à 20 s), haché en base, TTL 5 min, anti-abus (3 envois/numéro/h, 10/IP/h, 5 tentatives puis blocage 15 min). Un code PIN à 4 chiffres, distinct de l'OTP, protège en plus chaque opération financière — pas l'ouverture de l'app — pour qu'un téléphone déverrouillé ne vide pas une caisse à lui seul.

• Conséquences :

  • Bénéfices : zéro mot de passe à stocker, zéro flux de récupération à sécuriser, parcours d'inscription aligné sur les habitudes mobile money déjà acquises par la cible ; le PIN ajoute une seconde barrière spécifiquement sur l'argent, sans alourdir l'usage quotidien non financier.
  • Coûts et risques acceptés : dépendance à un prestataire WhatsApp Business/SMS et à sa délivrabilité (coût direct par envoi, latence en zone mal couverte) ; un changement de numéro devient une opération sensible nécessitant OTP sur l'ancien ET le nouveau numéro, blocage des retraits 48 h et notification à tous les chefs de tous les groupes de l'utilisateur ; la sécurité du compte dépend in fine de la sécurité de la carte SIM (SIM swap), risque partagé avec tout système OTP-first.
  • Conditions de révision : si le coût d'envoi SMS/WhatsApp devient significatif à l'échelle, évaluer un second facteur alternatif (passkey, TOTP applicatif) en complément — jamais en remplacement du numéro comme identifiant, qui reste la promesse produit vis-à-vis de la cible.

SQL brut paramétré (db.rawQuery) plutôt que Lucid ORM comme couche d'accès aux données

• Contexte : Djelimeet est construit sur AdonisJS 6, qui fournit Lucid comme ORM par défaut. Le cœur du produit (grand livre en partie double, immuabilité des écritures, unicité d'un vote de retrait, contraintes de classes de membres) repose sur des invariants qui doivent être garantis au niveau base — triggers (deny_ledger_mutation, assert_transaction_balanced, deny_audit_mutation), contraintes d'unicité composées, index partiels. Un ORM à mapping objet modéliserait ces invariants de façon imparfaite ou les laisserait entièrement à la charge du code applicatif, plus fragile.

• Options envisagées :

  1. Lucid ORM pour tout le CRUD, SQL brut seulement pour les requêtes complexes — productivité élevée sur les domaines simples (group_settings, profils), mais introduit deux styles d'accès aux données dans la même base de code : incohérence qui rend plus difficile de savoir, pour un nouveau domaine, quelle convention suivre. Risque réel qu'un développeur presse par les délais utilise Lucid même sur une table financière, contournant un trigger sans le savoir.
  2. SQL brut paramétré partout (db.rawQuery / trx.rawQuery), Lucid réservé aux migrations (BaseSchema) — cohérence totale du style d'accès, les contraintes fortes vivent explicitement en SQL visible dans le code de service, aucune abstraction ne masque un verrou de ligne ou une transaction explicite. Coût : plus de code répétitif (mapping manuel ligne → objet), courbe d'apprentissage pour un développeur venu d'un monde Lucid/ActiveRecord.
  3. Un ORM distinct type Drizzle ou Prisma, plus proche du SQL — compromis entre les deux, mais change radicalement la stack déjà choisie (AdonisJS + Lucid pour les migrations) et n'était pas disponible au moment du choix initial du module financier déjà livré.
• Décision : option 2. Le module financier déjà codé (app/finance/) sert de modèle de convention : tout accès aux données passe par db.rawQuery/trx.rawQuery avec requêtes paramétrées, y compris pour les domaines qui n'ont pas de contrainte forte (ex. CRUD de group_settings) — un compromis documenté en commentaire de tête de fichier plutôt qu'un choix silencieux, mais la cohérence prime sur l'optimisation locale.

• Conséquences :

  • Bénéfices : les invariants les plus critiques (équilibre d'une transaction, immuabilité du grand livre, unicité d'un vote) sont visibles et vérifiables directement dans les migrations SQL, indépendamment du code applicatif — un audit de sécurité peut les relire sans comprendre Lucid. Un seul style de requête à auditer pour la revue pre-commit automatisée.
  • Coûts et risques acceptés : plus de code de mapping manuel à écrire et maintenir par service ; onboarding plus long pour un développeur habitué à un ORM classique ; risque d'injection SQL si la discipline de paramétrage n'est pas respectée scrupuleusement (mitigé par la revue automatique pre-commit qui cherche spécifiquement le SQL brut non paramétré).
  • Conditions de révision : si un domaine purement CRUD sans contrainte d'intégrité (ex. paramètres d'affichage utilisateur) s'avère disproportionnellement coûteux à écrire en SQL brut, documenter l'exception en tête de fichier plutôt que de généraliser Lucid silencieusement.

Isolation multi-tenant par RLS PostgreSQL, en plus du middleware applicatif

• Contexte : le tenant est le groupe. Une fuite d'un groupe vers un autre (un membre qui verrait la caisse ou le fil d'un groupe auquel il n'appartient pas) est qualifiée dans le cahier des règles métier comme « la classe de bug la plus coûteuse du projet » — un seul oubli de filtre WHERE group_id = ? dans une requête, sur une centaine de routes, suffit à l'exposer. Un schéma PostgreSQL séparé par tenant a été écarté dès le cahier d'architecture (ADR-01) : ingérable dès 500 groupes (migrations × N).

• Options envisagées :

  1. Un schéma partagé, isolation uniquement par filtre applicatif (WHERE group_id = ? dans chaque requête) — le plus simple à écrire au départ, mais entièrement dépendant de la discipline humaine : un seul service ou une seule requête ad hoc qui oublie le filtre expose tout. Aucune deuxième barrière si la première échoue.
  2. Un schéma par tenant — isolation maximale nativement, mais migrations × N groupes et connexions dispersées ; écarté comme ingérable à l'échelle visée (ADR-01).
  3. Schéma partagé + trois barrières indépendantes : middleware de résolution du tenant (lit group_id dans l'URL, jamais dans le corps), scope obligatoire côté accès aux données, et Row-Level Security PostgreSQL sur les tables financières (et étendue à group_settings, posts, meetings, minutes, events, etc.) — la RLS agit comme filet de sécurité au niveau moteur de base, indépendant du code applicatif : même une requête qui oublierait le filtre applicatif ne verrait que les lignes du tenant courant, posé via SELECT set_current_group('<uuid>') en SET LOCAL.
• Décision : option 3. group_id sur toute table portée par un groupe, RLS créée dès les migrations mais activée table par table une fois le middleware de tenant posé et testé (choix explicite de séquencement, pas un oubli) ; certaines tables enfants sans group_id propre (post_media, comments, attendances, tickets...) restent protégées par les deux premières barrières seulement, leur accès ne passant jamais que par leur parent déjà couvert par la RLS.

• Conséquences :

  • Bénéfices : une fuite entre groupes nécessiterait l'échec simultané de trois mécanismes indépendants plutôt que d'un seul oubli de WHERE ; la RLS protège aussi contre un accès direct à la base (script de debug, outil d'administration) qui contournerait la couche applicative ; le modèle reste un schéma unique, donc les migrations restent linéaires quel que soit le nombre de groupes.
  • Coûts et risques acceptés : le rôle applicatif PostgreSQL ne doit jamais être SUPERUSER ni BYPASSRLS, ce qui impose une discipline d'exploitation (séparation des rôles base de données) à maintenir dans le temps ; chaque transaction doit explicitement poser le groupe courant en SET LOCAL, un oubli désactive silencieusement la troisième barrière pour cette transaction (bien que les deux premières restent actives) ; les tables enfants sans group_id dénormalisé restent un angle mort documenté — accepté tant qu'aucune requête ne les interroge directement hors de leur parent ; un accès back-office légitime multi-groupes (modérateur système) nécessite un rôle PostgreSQL séparé ou une politique additionnelle, point explicitement laissé ouvert avant l'activation de la RLS en production.
  • Conditions de révision : activer ENABLE ROW LEVEL SECURITY table par table seulement après avoir testé le middleware de tenant sur cette table ; trancher le rôle back-office multi-groupes (rôle BYPASSRLS séparé vs politique dédiée) avant la mise en production, pas après.

Retrait de caisse validé par au moins 80 % des chefs actifs, collège figé à l'ouverture

• Contexte : la promesse centrale du produit est « personne ne peut vider la caisse seul ». Une banque règle ce problème depuis un siècle avec la double signature ; le mobile money, en rendant le transfert instantané et individuel, a rouvert le problème pour les groupes communautaires. Le mécanisme doit rester praticable pour un petit groupe (parfois un seul chef au démarrage) tout en étant réellement collégial pour un groupe structuré.

• Options envisagées :

  1. Unanimité systématique de tous les chefs — maximise la sécurité mais bloque tout retrait dès qu'un seul chef est injoignable (voyage, téléphone perdu) ; inadapté à un collège de 6+ chefs où l'unanimité devient statistiquement rare dans la fenêtre utile.
  2. Seuil fixe (ex. 2 signatures) indépendant de la taille du collège — simple, mais dilue la protection à mesure que le collège grandit (2 voix sur 10 chefs n'est plus une décision collégiale) et ne reflète pas l'intention réelle des bureaux.
  3. Seuil proportionnel ceil(0.8 × N), N = chefs actifs hors demandeur, figé à l'ouverture de la demande — s'adapte à la taille réelle du collège, équivaut à l'unanimité sous 4 chefs (où 80 % n'a pas de sens fractionnaire autre que « tous »), et le fait de figer N à l'ouverture empêche qu'une nomination de chef en cours de vote ne déplace discrètement le seuil requis.
• Décision : option 3 (ADR-06 du cahier d'architecture). Table de référence : N=1→1, N=2→2, N=3→3, N=4→4, N=5→4, N=6→5. L'écran annonce toujours le seuil en fraction (« 3 approbations sur 3 »), jamais en pourcentage, pour rester lisible sous 4 chefs. Un chef qui est aussi le demandeur ne vote pas et ne compte pas dans N (séparation des pouvoirs) ; un chef ne peut pas se retirer du collège pendant un vote en cours ; modifier la demande après un premier vote invalide tous les votes émis.

• Conséquences :

  • Bénéfices : le mécanisme reste praticable pour une tontine naissante (1 chef) tout en devenant réellement collégial à mesure que le groupe se structure ; figer le collège à l'ouverture élimine une classe entière de manipulation (nommer un chef favorable juste avant la décision finale) ; le non-quorum sous 72 h restitue intégralement les fonds, donc aucune caisse ne reste bloquée indéfiniment par l'indécision.
  • Coûts et risques acceptés : un groupe avec un seul chef (cas de démarrage encouragé mais réel) n'a aucune protection collégiale réelle — le produit l'annonce explicitement à l'écran plutôt que de le masquer, mais le risque existe tant que le bureau ne nomme pas d'autres chefs ; le calcul du seuil doit être recalculé et vérifié à chaque nouvelle demande, ce qui ajoute une étape de lecture (compter les chefs actifs) avant toute ouverture de retrait ; une attaque sociale visant à faire nommer puis retirer rapidement des chefs entre deux demandes reste un vecteur théorique, non totalement neutralisé par le seul figeage à l'ouverture.
  • Conditions de révision : le seuil et son mécanisme de double validation ne doivent jamais être changés sans demande explicite (règle écrite dans CLAUDE.md) ; au niveau plateforme, un changement de ce paramètre suit lui-même le même schéma à deux signatures distinctes que pour un groupe (platform_setting_change_requests/...approvals), pour qu'aucune modification de cet invariant ne dépende d'une seule personne côté exploitant non plus.

Grand livre en partie double avec immuabilité stricte des écritures

• Contexte : Djelimeet affiche des soldes réels en francs CFA pour des groupes qui n'ont ni comptable ni DAF. Le risque fatal identifié (pitch produit, partie 08) est « un incident financier public : un retrait exécuté deux fois, un solde faux » — ce type d'incident détruirait la réputation du produit dans un marché où « tout se sait ». Un simple champ balance incrémenté par chaque mouvement ne permet ni de prouver un historique ni de détecter un bug de double-crédit après coup.

• Options envisagées :

  1. Solde en champ mutable, historique de transactions en table de log séparée (best-effort) — plus simple et rapide à implémenter, mais le solde affiché devient la source de vérité : un bug applicatif qui l'incrémente mal corrompt silencieusement l'état, sans moyen de rejouer ou d'auditer un recalcul fiable depuis zéro.
  2. Grand livre en partie double (ledger_entries), solde = cache recalculable, écritures non modifiables/supprimables par trigger — chaque mouvement est une écriture équilibrée (débit = crédit), une erreur se corrige par contre-passation visible, jamais par réécriture. Coût : complexité de modélisation et de requête plus élevée (toute lecture de solde est une agrégation, pas un SELECT direct), discipline transactionnelle stricte requise dans chaque service qui écrit au journal.
  3. Partie double mais sans triggers d'immuabilité (confiance dans la discipline applicative seule) — même modèle de données que l'option 2 mais sans garde-fou en base ; un bug ou un accès direct à la base (migration manuelle, script de hotfix) pourrait modifier une écriture sans qu'aucune couche ne s'y oppose.
• Décision : option 2. Le solde affiché est un cache recalculable à partir de ledger_entries, jamais la source de vérité. Les triggers PostgreSQL deny_ledger_mutation() et assert_transaction_balanced() interdisent l'UPDATE/DELETE sur les écritures et refusent toute transaction déséquilibrée, y compris pour un compte applicatif disposant de tous les droits — la garantie vit en base, pas seulement dans le code.

• Conséquences :

  • Bénéfices : un audit externe (régulateur, investisseur, bureau d'association méfiant) peut vérifier l'intégralité de l'historique sans faire confiance au code applicatif ; une erreur ne disparaît jamais, elle se corrige visiblement ; la réconciliation quotidienne avec le relevé de l'opérateur devient un simple contrôle d'écart entre deux sources indépendantes plutôt qu'une tentative de recoller un solde opaque.
  • Coûts et risques acceptés : chaque lecture de solde (wallet, caisse) nécessite une agrégation sur ledger_entries, qu'il faut indexer et éventuellement mettre en cache (lecture peu volatile, invalidation explicite à l'écriture — jamais de TTL seul) ; tout nouveau domaine financier doit passer par le point d'écriture unique (LedgerService.post()), ce qui impose une discipline de revue systématique sur ce fichier, qui devient un goulot d'étranglement organisationnel volontaire.
  • Conditions de révision : aucune prévue — c'est un invariant « socle » du cahier d'architecture (ADR-03) ; toute évolution qui toucherait au sens des débits/crédits ou à l'immuabilité doit être explicitement demandée et documentée, jamais glissée dans un autre changement (règle écrite dans CLAUDE.md du dépôt).

Identité et RBAC

RG-01 — Numéro de téléphone, identifiant unique

• L'inscription et la connexion se font exclusivement par numéro de téléphone normalisé E.164 ⇒ aucun email, aucun mot de passe n'est jamais demandé. Sinon : toute tentative de créer un compte par email est rejetée dès la validation d'entrée.
• Portée : users.msisdn (unique) · POST /auth/otp/request · écrans Bienvenue/Numéro.

RG-02 — OTP anti-abus

• Une demande de code ⇒ envoi WhatsApp, repli SMS si non délivré en 20 s, code à 6 chiffres haché en base, TTL 5 min. Au-delà de 3 envois/numéro/h ou 10 envois/IP/h ⇒ 429 RateLimited. Après 5 tentatives de vérification erronées ⇒ invalidation du code et blocage de 15 min.
• Portée : table OTP (Redis) · POST /auth/otp/request, POST /auth/otp/verify.

RG-03 — PIN distinct de l'OTP, jamais lisible par l'admin

• Un PIN à 4 chiffres protège chaque opération financière (pas l'ouverture de l'app) ⇒ requis sur retrait, vote, paiement par wallet. L'API ne renvoie et ne journalise jamais le PIN en clair ; aucun endpoint back-office ne l'expose, sous aucune forme.
• Portée : users.pin_hash · PUT /me/pin · toutes les routes financières sensibles.

RG-04 — Session à rotation

• Un refresh token est opaque, lié à l'appareil, valide 30 j, et tourne à chaque usage ⇒ la réutilisation d'un refresh déjà tourné révoque toute la famille de tokens (401, reconnexion complète requise).
• Portée : auth_sessions, devices · POST /auth/refresh.

RG-05 — Changement de numéro sous contrôle

• Un changement de numéro exige un OTP validé sur l'ancien ET le nouveau numéro ⇒ retraits bloqués 48 h après confirmation, notification automatique à tous les chefs de tous les groupes de l'utilisateur. Sinon : POST /me/phone-change/confirm échoue si l'un des deux codes est manquant ou expiré.
• Portée : users · POST /me/phone-change/request, POST /me/phone-change/confirm.

RG-06 — Cloisonnement strict entre groupes

• L'identité (profil, wallet) est globale ; tout le reste (fil, caisse, membres, réunions) est cloisonné par group_id ⇒ rejoindre un groupe n'expose au bureau que nom et numéro du nouveau membre, jamais ses autres groupes ni son solde personnel. Sinon : 403 sur toute tentative de lecture croisée.
• Portée : toutes les tables group_id · middleware de résolution de tenant.

RG-07 — RBAC cumulatif, rôle « membre » permanent

• Les rôles d'une adhésion se cumulent (ex. secrétaire + chef) ⇒ la permission effective est l'union des rôles ; le rôle « membre » ne peut jamais être retiré. Sinon : toute tentative de désactiver le rôle « membre » est rejetée en 422.
• Portée : memberships, membership_roles · POST /groups/{groupId}/members/{membershipId}/roles.

RG-08 — Séparation des pouvoirs sur le vote de retrait

• Un chef qui est aussi l'auteur (ou trésorier demandeur) d'une demande de retrait ne vote pas sur sa propre demande et ne compte pas dans le quorum requis ⇒ 403 en cas de tentative. Un chef ne peut pas se retirer lui-même du collège pendant un vote en cours ⇒ 409.
• Portée : withdrawal_requests, withdrawal_approvals · POST /groups/{groupId}/withdrawal-requests/{withdrawalId}/approvals.

Groupes

RG-09 — Création de groupe et premier chef

• Le créateur d'un groupe en devient automatiquement le premier chef, avec pouvoir de nommer trésorier, secrétaire et autres chefs ⇒ tant qu'il reste seul chef, un retrait ne nécessite que sa seule voix (N=1 ⇒ seuil=1), avec avertissement explicite à l'écran.
• Portée : groups, memberships · POST /groups.

RG-10 — Visibilité et annuaire

• Un groupe private n'apparaît dans aucune recherche ni annuaire ; on y entre uniquement sur invitation nominative. Le repassage en privé purge le cache public et désindexe la fiche. Sinon : GET /groups/directory ne retourne jamais un groupe privé.
• Portée : groups.visibility · GET /groups/directory, GET /groups/{groupId}/public.

RG-11 — Invitation et demande d'adhésion

• Une invitation entre toujours avec le rôle « membre », expire après 14 jours, et peut être renvoyée ⇒ l'invité voit avant d'accepter exactement ce que le groupe verra de lui (nom, numéro). Une demande via l'annuaire public passe obligatoirement par une validation du bureau — jamais d'entrée immédiate. Sinon : 410 sur une invitation expirée.
• Portée : invitations, join_requests · POST /groups/{groupId}/invitations, POST /groups/{groupId}/join-requests/{joinRequestId}/decide.

RG-12 — Avis des bureaux, anonymisés

• Un avis par groupe et par personne (contrainte d'unicité), rédigé par un chef, modifiable, et seulement après 30 jours d'adhésion. La lecture inter-groupes d'un profil ne renvoie jamais group_id ni l'auteur — seulement note, commentaire, date.
• Portée : member_reviews · GET /groups/{groupId}/join-requests/{joinRequestId}/applicant, POST /groups/{groupId}/members/{membershipId}/review.

Finance et grand livre

RG-13 — Montants entiers, jamais de décimale

• Tous les montants sont des entiers (bigint) en francs CFA ⇒ aucun champ de type float ou numeric flottant n'est toléré dans le schéma financier. Sinon : rejet de validation à l'écriture.
• Portée : tous les champs *Xof · plan de comptes (accounts).

RG-14 — Écritures en partie double, immuables

• Toute variation de solde est une écriture équilibrée dans ledger_entries ⇒ aucun solde n'est un champ qu'on incrémente directement ; une erreur se corrige par une contre-passation référençant l'écriture d'origine, jamais par une modification. Sinon : le trigger deny_ledger_mutation() bloque l'UPDATE/DELETE au niveau PostgreSQL, y compris pour l'administration système.
• Portée : ledger_entries, transactions · GET /groups/{groupId}/journal.

RG-15 — Wallet et caisse créés automatiquement

• Le wallet d'un membre se crée à l'inscription ; la caisse et le compte de fonds gelés d'un groupe se créent à la création du groupe. Sinon : aucune route financière de groupe n'est accessible avant la création effective de ces comptes.
• Portée : accounts (kind member_wallet, group_treasury, group_frozen_funds).

RG-16 — Frais de rechargement à la charge du membre

• Un rechargement applique les frais opérateur à la charge du membre, affichés avant confirmation (« vous rechargez 10 000 F, total à payer 10 100 F »). Sinon : l'intention de paiement n'est créée qu'après acceptation explicite du montant total affiché.
• Portée : payment_intents · POST /me/wallet/topups.

RG-17 — Webhook jamais autorité sur le montant

• Le montant annoncé par l'opérateur est toujours comparé à celui de l'intention enregistrée en base ⇒ en cas d'écart, la transaction part en litige, jamais d'ajustement silencieux. Rejouer un webhook ou un appel réseau ne crédite jamais deux fois (idempotence par clé unique topup:<intentId>).
• Portée : payment_intents, provider_events · webhook waveCheckoutCompleted.

RG-18 — Cotisation : wallet gratuit, opérateur avec frais

• Une cotisation payée depuis le wallet interne est gratuite (changement de propriétaire au journal, sans mouvement chez l'opérateur, PIN requis) ; payée directement via l'opérateur, elle porte les frais de rechargement. En cas d'échec de paiement : rien n'est prélevé, la cotisation reste due sans pénalité.
• Portée : contributions, contribution_payments · POST /groups/{groupId}/contributions/{contributionId}/payments.

RG-19 — Abonnement impayé : dégradation, jamais de blocage

• Un abonnement Djelimeet impayé dégrade le service (publication suspendue, plus de nouvelles cotisations ni d'événements) mais ne bloque jamais la lecture du journal ni le retrait des fonds d'un groupe. Règle non négociable, écrite dans le code, pas seulement dans les CGU.
• Portée : subscriptions.status = unpaid · toutes les routes de lecture financière.

Retraits à double validation (seuil 80 %)

RG-20 — Calcul du seuil, collège figé à l'ouverture

• À l'ouverture d'une demande, N = chefs actifs hors demandeur, requiredApprovals = ceil(0.8 × N) est figé immédiatement (table : N=1→1, N=2→2, N=3→3, N=4→4, N=5→4, N=6→5). Sous 4 chefs, 80 % veut dire l'unanimité — toujours annoncée en fraction (« 3 approbations sur 3 »), jamais en pourcentage.
• Portée : withdrawal_requests.required_approvals · POST /groups/{groupId}/withdrawal-requests.

RG-21 — Un chef, une voix

• Contrainte d'unicité (withdrawal_id, approver_membership_id) ⇒ rejouer l'appel d'approbation ne double jamais le vote. Modifier la demande (montant, bénéficiaire, motif) après un premier vote invalide tous les votes déjà émis, qui doivent être reproposés.
• Portée : withdrawal_approvals · PATCH /groups/{groupId}/withdrawal-requests/{withdrawalId}.

RG-22 — Le vote porte sur le total sortant, frais compris

• Le montant mis au vote est toujours amountXof + feeEstimateXof (total qui sort de la caisse), jamais le seul montant net au bénéficiaire. L'écart entre frais estimés et frais réels est écrit séparément (operator_fees), jamais fondu dans le montant du retrait.
• Portée : withdrawal_requests.fee_estimate_xof / fee_actual_xof.

RG-23 — Bénéficiaire contraint à un membre actif

• Le bénéficiaire d'un retrait est obligatoirement un membre actif du groupe, référencé par clé étrangère ⇒ jamais un numéro de téléphone libre saisi à la main. Sinon : 422 à la création de la demande.
• Portée : withdrawal_requests.beneficiary_membership_id.

RG-24 — Liquidité insuffisante : jamais d'échec silencieux

• Avant exécution, le float du compte marchand doit couvrir montant + frais et respecter le plafond journalier de l'opérateur ⇒ sinon la demande passe en awaiting_liquidity : les fonds restent gelés, personne n'est débité, l'exploitation est alertée.
• Portée : withdrawal_requests.status = awaiting_liquidity.

RG-25 — Expiration à 72 h sans quorum

• Une demande sans quorum atteint sous 72 h expire automatiquement ⇒ fonds intégralement restitués en caisse, notification collective. Pas d'exclusion automatique du collège pour un chef silencieux ; la demande est reproposable.
• Portée : withdrawal_requests.status = expired, expires_at · job planifié.

RG-26 — Reddition de comptes séparée du grand livre

• Un décaissement n'est terminé que « soldé » : lignes de justification (libellé, montant, date, justificatif facultatif) saisies par le bénéficiaire, visibles par tout le groupe. Ces lignes ne touchent jamais le grand livre ni l'équation de bilan — un témoignage, pas une écriture. Un reliquat se reverse en caisse par un rechargement ordinaire référencé au décaissement d'origine.
• Portée : disbursement_lines · POST /groups/{groupId}/withdrawal-requests/{withdrawalId}/disbursement-lines, .../return-remainder.

Réunions et PV

RG-27 — QR de présence tournant, double scan sans effet

• Le QR de présence est un jeton HMAC régénéré toutes les 60 s ; le scanner valide hors ligne avec une dérive tolérée de ±2 fenêtres. La contrainte d'unicité (meeting_id, membership_id) rend le double pointage (QR puis manuel) sans effet, par construction.
• Portée : attendances · POST /groups/{groupId}/meetings/{meetingId}/attendances/scan.

RG-28 — PV publié immuable

• Un PV publié n'est plus modifiable ; toute correction crée une nouvelle version visible de tous (même mécanisme d'immuabilité que le journal financier). La liste de présence d'un PV est reprise automatiquement du pointage électronique, jamais ressaisie.
• Portée : minutes, minute_versions · POST /groups/{groupId}/meetings/{meetingId}/minutes/publish.

Billetterie et événements

RG-29 — Quota décrémenté par écriture atomique

• Un quota de billets se décrémente par écriture conditionnelle (jamais lecture puis écriture) ; la jauge globale et celle de chaque formule sont contraignantes, la plus stricte gagne. Une place sélectionnée est tenue 10 minutes le temps du paiement, libérée automatiquement et sans frais si le délai expire.
• Portée : ticket_tiers, orders.status = held · POST /events/{eventId}/orders.

RG-30 — Billet à usage unique, recettes vers la caisse du groupe

• Le contrôle d'entrée fait une écriture conditionnelle (« déjà utilisé, entré à 20h14 » plutôt qu'un refus muet) ; fonctionne hors ligne. Les recettes de billetterie vont toujours à la caisse du groupe, jamais à un portefeuille personnel, y compris celui de l'organisateur.
• Portée : tickets, ticket_scans · POST /events/{eventId}/scan.

Abonnement

RG-31 — Palier mesuré à l'échéance, jamais en cours de cycle

• Le palier d'abonnement se mesure uniquement à la date d'échéance ⇒ recruter 20 membres en janvier ne facture rien avant l'échéance de février. « Membre actif » = adhésion active à la date d'échéance (un membre suspendu ou parti ne compte pas).
• Portée : subscriptions.members_at_renewal · job generateRecurringInvoices().

RG-32 — Prélèvement d'abonnement toujours autorisé explicitement

• Le prélèvement se fait sur la caisse du groupe, autorisé explicitement par un chef à la souscription (ou alternativement depuis le wallet personnel d'un chef) ⇒ jamais de prélèvement silencieux. Un échec documente sa cause : insufficient_funds (caisse vide) ou not_authorized (aucun chef actif n'a autorisé).
• Portée : subscriptions.charge_source, invoices.failure_reason.

Social et modération

RG-33 — Publication publique explicite uniquement

• Un post n'apparaît sur le site public que si is_public = true est explicitement posé ⇒ jamais par défaut. Toute action de modération masque le contenu à l'affichage (deleted_at) mais le conserve en base — jamais de suppression physique.
• Portée : posts.is_public, moderation_actions · GET /me/feed (public).

RG-34 — Un signalement ouvert par signaleur et par contenu

• Un même utilisateur n'a qu'un signalement ouvert par contenu (index partiel WHERE status = 'open') ⇒ un double envoi hors ligne n'ajoute rien au compteur de la file de modération. Le motif est un code fermé (defamation, off_topic, scam, harassment, spam, inappropriate, other), la précision libre va dans details.
• Portée : reports.reason, reports_open_once_uniq · POST /reports.

Notifications et administration

RG-35 — Catégories financières non désactivables, double validation du seuil plateforme

• Les catégories de notification contribution, withdrawal et subscription ne peuvent jamais être désactivées (contrainte notification_preferences_financial_locked en base) ⇒ 422 sur toute tentative. Un changement du seuil des 80 % au niveau plateforme suit le même schéma qu'un retrait de groupe : une demande, des approbations distinctes, appliquée seulement à deux signatures.
• Portée : notification_preferences, platform_setting_change_requests + platform_setting_change_approvals · PUT /me/notification-preferences, POST /admin/platform-settings/change-requests/{changeRequestId}/approve.

1. Contexte et problème

En Côte d'Ivoire, l'argent des associations, tontines et groupes communautaires circule déjà par mobile money, mais la décision collective qui l'entoure reste orale et invérifiable : un trésorier tient un cahier, personne ne peut lui donner tort ni raison, et ce climat de soupçon — plus que la fraude elle-même — use les groupes jusqu'à leur extinction. Les outils existants (compte mobile money personnel, groupe WhatsApp, cahier/tableur, compte bancaire associatif) ne couvrent chacun qu'un morceau du problème : aucun ne porte la gouvernance (qui décide, à combien de voix, avec quelle trace). Djelimeet numérise cette règle de gouvernance — pas l'argent, qui reste chez l'opérateur mobile money agréé.

2. Objectifs mesurables

• Réduire à zéro les sorties de caisse non collégiales : 100 % des retraits de groupe passent par un vote à seuil (≥ 80 % des chefs actifs), sans exception technique possible (contrainte en base, pas seulement en écran).
• Fiabilité du grand livre : 0 écriture modifiable ou supprimable après coup, vérifié par triggers PostgreSQL (deny_ledger_mutation, assert_transaction_balanced) sur 100 % des tables financières.
• Idempotence : un rejeu de webhook ou d'appel réseau ne crédite jamais deux fois un wallet ou une caisse (0 double-crédit toléré en production).
• Délai de traitement d'une demande de retrait sans quorum : expiration automatique sous 72 h, restitution à 100 % des fonds gelés.
• Couverture du contrat d'API : 147 opérations OpenAPI 3.1 documentées sur 13 domaines, chaque route livrée correspond exactement à une opération du contrat (0 route hors spec).
• Pilote commercial (horizon 90 jours post-lancement) : 3 groupes pilotes signés, mesure du taux de couverture opérateur chez les membres (seuil cible ≥ 80 % pour que le module financier soit viable) et du délai d'obtention du contrat marchand.

3. Parties prenantes

4. Glossaire

5. Périmètre

Inclus (v1) : identité par numéro de téléphone (OTP, PIN), groupes multi-tenant avec RBAC cumulatif, grand livre en partie double, wallet et rechargement (Wave), cotisations (montant fixe ou cagnotte libre, tarifs par classe de membre), retraits à 80 % avec reddition de comptes, réunions avec présence QR et PV, billetterie d'événements (formules, contrôle d'entrée), fil social modéré, sondages, notifications, abonnement par groupe/palier, back-office système (facturation, réconciliation, litiges, modération).

Exclus (hors v1) : catégories comptables et budgets prévisionnels, deuxième opérateur mobile money branché (architecture prête, intégration non faite), commission sur les flux comme source de revenu, versionnement de rupture de l'API (/v2), notifications financières désactivables sous quelque forme que ce soit, module tontine dédié (praticable aujourd'hui via cotisation + retrait, sans schéma spécifique).

6. Exigences fonctionnelles

7. Exigences non fonctionnelles

8. Contraintes

• Réglementaire : aucune détention de fonds, aucune commission sur les flux — positionnement éditeur de logiciel, pas émetteur de monnaie électronique au sens UEMOA/BCEAO ; position à faire confirmer par un juriste ivoirien avant le premier franc réel.
• Technique : SQL brut paramétré sur PostgreSQL comme couche d'accès (pas de Lucid ORM) pour les domaines financiers — cohérence de style imposée par CLAUDE.md du dépôt backend ; AdonisJS 6 / TypeScript ESM ; Redis pour OTP et verrous courts ; BullMQ pour les jobs asynchrones.
• Opérateur : un seul opérateur mobile money en production au lancement (Wave) ; l'interface PaymentProvider doit rester multi-opérateur dès le premier jour sans que l'ajout d'un deuxième opérateur soit une refonte.
• Budgétaire : modèle économique fondé exclusivement sur l'abonnement par groupe/palier ; le palier gratuit (≤ 15 membres) est un moteur d'acquisition volontairement non rentable.
• Marché : cible initiale Abidjan, langue française, montants exclusivement en francs CFA (XOF).

9. Risques majeurs

10. Règles de gestion

Voir l'artefact dédié regles_gestion (RG-01 à RG-35), regroupées par domaine : identité/RBAC, groupes, finance/grand livre, retraits à double validation, abonnements, billetterie/événements, réunions/PV, social, notifications, admin. Chaque exigence fonctionnelle ci-dessus référence les RG qui la justifient.

Suite de tests tests/functional/retraits.spec.ts instable — 2026-09 — Sévérité : bloquante (CI)

• Impact : le hook pre-commit (.husky/pre-commit, scripts/pre_commit_review.mjs) exécute pnpm test avant toute revue automatisée. Tant que ce défaut n'est pas corrigé, tous les commits sur le dépôt djelimeet-api sont bloqués à l'étape test — pas seulement ceux qui touchent au module de retrait. Aucune donnée de production affectée (le défaut est contenu à l'environnement de test).

• Timeline :

  • Détection : lors de la mise en place du hook pre-commit, la suite de tests fonctionnels a révélé des échecs préexistants et instables sur tests/functional/retraits.spec.ts, avec le message « aucun OTP en attente ».
  • Diagnostic : le comportement n'est pas reproductible de façon déterministe — le symptôme apparaît ou non selon l'état laissé par une exécution précédente, signe d'un défaut d'isolation entre cas de test plutôt que d'un bug du mécanisme de retrait lui-même.
  • Mitigation : documentation explicite du défaut dans CLAUDE.md du dépôt, avec la décision assumée de laisser le hook bloquer en échec sûr (« fail safe ») plutôt que de l'ignorer silencieusement.
  • Résolution : non résolu à la date de rédaction de ce cas d'étude — corriger cette suite de tests est un préalable à tout commit normal sur le dépôt, pas une tâche différable.

• Cause racine :

  • Technique : l'OTP est stocké dans Redis avec une clé vraisemblablement partagée ou insuffisamment isolée entre cas de test (ex. même numéro de téléphone réutilisé sans nettoyage entre tests, ou TTL qui chevauche l'exécution suivante). Le test suivant lit un état OTP laissé par le test précédent (ou l'absence d'un état qu'il attendait), d'où « aucun OTP en attente ».
  • Organisationnelle : le hook pre-commit a été introduit après l'écriture du module financier, révélant une dette de test déjà présente plutôt que créée par le hook — signe qu'aucune exécution systématique de la suite complète n'avait eu lieu en continu avant cette mise en place.
• Ce qui a bien marché : le choix d'échec sûr (bloquer tous les commits plutôt que de laisser passer une suite de tests non fiable) a rendu le défaut immédiatement visible et documenté, au lieu de laisser une suite « flaky » être silencieusement ignorée ou relancée en boucle jusqu'à passer par hasard — un piège classique qui aurait masqué un vrai risque sur le mécanisme de retrait.
• Ce qui a mal marché : l'absence d'isolation des tests n'a été détectée qu'au moment de l'automatisation du hook, pas au moment de l'écriture des tests eux-mêmes — un signal que la suite de tests du module financier n'avait pas encore de garde-fou d'isolation (reset Redis entre tests, numéros de téléphone générés uniques par cas) dès sa conception.

• Actions :

  • Isoler chaque cas de test sur une clé Redis/numéro de téléphone généré dynamiquement (ex. UUID par test) plutôt que des valeurs fixes réutilisées → garde-fou : assertion explicite en fin de test que l'état OTP est nettoyé → Responsable : équipe backend → Échéance : avant la prochaine session de développement sur le module Retraits.
  • Ajouter un hook afterEach qui purge systématiquement les clés OTP Redis créées pendant le test → garde-fou : test de régression qui exécute la suite deux fois de suite et vérifie l'absence d'interférence → Responsable : équipe backend → Échéance : même lot que l'action précédente.
  • Documenter dans app/finance/README.md la convention d'isolation adoptée, pour que tout nouveau test financier la suive dès l'écriture plutôt que de la découvrir après coup → Responsable : auteur du correctif → Échéance : avec la correction elle-même.

1. Prérequis (versions exactes)

• Node.js 20 LTS (ESM natif, requis par AdonisJS 6)
• pnpm 9+ (workspace pnpm-workspace.yaml utilisé dans les deux dépôts)
• PostgreSQL 16
• Redis 7
• Docker + Docker Compose (pour l'infra locale fournie — docker-compose.yml à la racine du dépôt API)

2. Variables d'environnement

3. Installation pas-à-pas

# 1. Backend
cd djelimeet-api
pnpm install
docker compose up -d          # PostgreSQL + Redis locaux
cp .env.example .env           # puis renseigner les variables ci-dessus
node ace generate:key          # colle le résultat dans APP_KEY
node ace migration:run         # applique les 29 migrations dans l'ordre des horodatages
node ace serve --watch         # démarre l'API sur http://localhost:3333

Résultat attendu : node ace migration:run affiche 29 migrations appliquées sans erreur ; node ace serve affiche Server started on http://localhost:3333.

# 2. Frontend
cd ../djelimeet-web
pnpm install
pnpm dev                       # démarre Nuxt sur http://localhost:3000

Résultat attendu : page d'accueil Djelimeet accessible, requêtes vers NUXT_PUBLIC_API_BASE visibles dans les logs réseau du navigateur.

4. Vérification

• curl -X POST http://localhost:3333/v1/auth/otp/request -H "Content-Type: application/json" -d '{"msisdn":"+2250700000000"}' → 202 avec un champ devCode en environnement development.
• node ace test (Japa) depuis djelimeet-api → suite fonctionnelle exécutée (voir limitation connue ci-dessous).
• Ouvrir http://localhost:3000/auth → le parcours OTP complet doit aboutir à une session.

5. Problèmes fréquents

0.5.0 — 2026-09-25

Added

• Classes de membres et tarifs de cotisation par classe (member_classes, contribution_class_rates) — RG-18.
• Réunions récurrentes (meeting_series) : une occurrence n'est générée qu'une fois par série (RG-28, migration 1757000026).
• Formule de billet réservée à une classe de membre (eligibility_mode = class) — migration 1757000027.
• 147 opérations documentées dans api/openapi.yaml (contrat initial à 89, croissance par lots additifs documentée dans database/README.md).

0.4.0 — 2026-09-20

Added

• Avis des bureaux sur un demandeur d'adhésion, anonymisés (member_reviews) — RG-12.
• Description de profil utilisateur (users.bio, bornée à 500 caractères).

Changed

• Facturation back-office : prix négocié et palier figé par administration (subscriptions.plan_locked), cause d'impayé distinguée (insufficient_funds / not_authorized) — RG-32.

0.3.0 — 2026-09-12

Added

• File de signalements structurée : motif fermé (reports.reason), un signalement ouvert par signaleur et par contenu (RG-34).
• Sondages du fil et des réunions (polls, poll_options, poll_votes) — un bulletin par membre sur un choix unique.
• Rechargement en espèces (cash_recharge_requests) unifié avec le rechargement Wave sous une seule route (recharge_providers.requires_proof).

0.2.0 — 2026-08-30

Added

• Grand livre en partie double complet (accounts, transactions, ledger_entries), triggers d'immuabilité (deny_ledger_mutation, assert_transaction_balanced).
• Retraits à double validation (seuil 80 %) : withdrawal_requests, withdrawal_approvals, disbursement_lines — RG-20 à RG-26.
• Row-Level Security PostgreSQL créée (désactivée par défaut) sur les tables financières.

Breaking

• Aucune route financière antérieure à ce lot n'existait — pas de migration de rupture.

0.1.0 — 2026-08-15

Added

• Identité par OTP (WhatsApp/SMS), PIN distinct, sessions à rotation (users, devices, auth_sessions) — RG-01 à RG-04.
• Groupes, adhésions et rôles cumulables (groups, memberships, membership_roles) — RG-06, RG-07.
• Squelette AdonisJS 6 bootstrap, convention SQL brut paramétré établie par app/finance/ (voir ADR dédié).

Notes de version

• Le backend/API est déclaré complet et validé par son propre contrat (api/README.md) à la date du changelog le plus récent ci-dessus.
• Le frontend Nuxt/Ionic (djelimeet-web) suit son propre rythme de livraison, non repris dans ce changelog backend — plus de 80 écrans déjà présents au moment de la rédaction de ce cas d'étude (auth, dashboard groupe, financier, réunions, événements, back-office admin).

US-01 — Rejoindre la plateforme sans mot de passe

• En tant que membre potentiel d'une association, je veux m'inscrire avec mon seul numéro de téléphone, afin de ne jamais avoir à retenir un mot de passe supplémentaire.
• Exigence liée : EXF-01 · Priorité : MUST

Critères d'acceptation

• Given un numéro ivoirien valide non encore inscrit When je demande un code OTP Then je reçois un code à 6 chiffres par WhatsApp, repli SMS si non délivré en 20 s.
• Given un code OTP valide saisi dans les 5 minutes When je le soumets Then une session s'ouvre (access 15 min + refresh 30 j).

Cas d'erreur couverts

• Code expiré ou faux 5 fois → blocage 15 min, message explicite.

US-02 — Créer un groupe et devenir chef

• En tant que fondateur d'une tontine, je veux créer un groupe et en devenir automatiquement le premier chef, afin de démarrer la gestion de la caisse immédiatement.
• Exigence liée : EXF-03 · Priorité : MUST

Critères d'acceptation

• Given un compte vérifié When je crée un groupe Then je deviens chef unique, la caisse et le compte de fonds gelés sont créés, et un avertissement m'indique qu'un retrait ne nécessitera que ma seule voix tant que je reste seul chef.
• Given un groupe créé When je consulte mes groupes Then mon rôle y est affiché par groupe, jamais globalement.

US-03 — Demander un retrait de caisse

• En tant que trésorier, je veux ouvrir une demande de retrait avec un motif et un devis chiffré, afin de financer une dépense du groupe de façon traçable.
• Exigence liée : EXF-05 · Priorité : MUST

Critères d'acceptation

• Given une caisse avec un solde suffisant When j'ouvre une demande de 150 000 F avec des lignes de devis Then les fonds (montant + frais estimés) sont gelés immédiatement et le seuil requis est calculé et figé.
• Given une demande déjà votée une fois When je modifie le montant Then tous les votes déjà émis sont invalidés et doivent être repris.

US-04 — Approuver un retrait en tant que chef

• En tant que chef de groupe, je veux approuver ou rejeter une demande de retrait après ré-authentification, afin de garantir qu'aucune sortie de caisse ne se fait sans accord collégial.
• Exigence liée : EXF-06 · Priorité : MUST

Critères d'acceptation

• Given une demande en attente où je suis chef actif et non demandeur When j'approuve avec mon PIN et un code OTP Then mon vote est enregistré une seule fois, même si l'appel est rejoué (idempotence).
• Given je suis le trésorier demandeur et aussi chef When je tente de voter sur ma propre demande Then je reçois une erreur 403, je ne compte pas dans le quorum.

Cas d'erreur couverts

• Demande déjà décidée ou expirée (72 h) → 410.

US-05 — Justifier un décaissement

• En tant que bénéficiaire d'un retrait exécuté, je veux déclarer mes dépenses ligne par ligne, afin de rendre compte de l'usage des fonds devant le groupe.
• Exigence liée : EXF-08 · Priorité : MUST

Critères d'acceptation

• Given un retrait payé non soldé When j'ajoute des lignes de justification Then elles sont visibles de tout le groupe et le statut de justification se met à jour (partial/settled), sans jamais toucher le grand livre.
• Given un reliquat après dépenses When je le reverse en caisse Then c'est journalisé comme un rechargement ordinaire référencé au retrait d'origine.

US-06 — Pointer sa présence à une réunion

• En tant que membre, je veux scanner un QR affiché en salle pour signaler ma présence, afin de figurer sur la liste officielle sans ressaisie manuelle.
• Exigence liée : EXF-11 · Priorité : MUST

Critères d'acceptation

• Given une réunion en cours When je scanne le QR tourné depuis moins de 60 s Then ma présence est enregistrée, même hors ligne, et un second scan reste sans effet.
• Given mon téléphone est déchargé When le secrétaire me pointe manuellement Then le pointage est tracé avec l'identité du secrétaire.

US-07 — Publier un PV immuable

• En tant que secrétaire, je veux publier le procès-verbal d'une réunion, afin de fixer définitivement la trace des décisions prises.
• Exigence liée : EXF-11 · Priorité : MUST

Critères d'acceptation

• Given un PV en brouillon When je le publie Then son statut passe à publié et il devient immuable.
• Given un PV déjà publié When je corrige une erreur Then une nouvelle version est créée, l'ancienne reste visible.

US-08 — Acheter un billet d'événement

• En tant que membre, je veux réserver et payer un billet pour un événement du groupe, afin de garantir ma place sans risque de double-vente.
• Exigence liée : EXF-12 · Priorité : MUST

Critères d'acceptation

• Given une formule disponible When je réserve 2 billets Then ils sont tenus 10 minutes, décomptés de la jauge de façon atomique.
• Given le paiement effectué dans le délai When je consulte mes billets Then chacun porte un QR à usage unique et un numéro de série.

Cas d'erreur couverts

• Paiement non effectué après 10 min → réservation annulée automatiquement, sans frais.

US-09 — Refuser de désactiver les alertes financières

• En tant que membre, je veux que mes notifications de cotisation/retrait/abonnement restent toujours actives, afin de ne jamais manquer une information qui engage l'argent du groupe.
• Exigence liée : EXF-16 · Priorité : MUST

Critères d'acceptation

• Given mes préférences de notification When je tente de désactiver la catégorie « withdrawal » Then la requête est rejetée en 422, la catégorie reste active.
• Given une alerte « fil » ou « réunion » When je la désactive Then la préférence est bien enregistrée (ces catégories restent coupables).

US-10 — Changer le seuil des 80 % en double validation

• **En tant qu'**administrateur système, je veux proposer et faire approuver par un second administrateur un changement du seuil de quorum, afin de garantir qu'aucun paramètre critique ne dépend d'une seule personne.
• Exigence liée : EXF-17 · Priorité : MUST

Critères d'acceptation

• Given une proposition de changement avec une première signature When un second administrateur distinct approuve Then le changement est appliqué.
• Given le même administrateur qui a proposé When il tente d'approuver aussi Then la demande reste en attente (deux signatures distinctes requises).

Palette, typographie et composants extraits tels qu'implémentés dans djelimeet-web/app/assets/css/main.css et app/app.config.ts (Nuxt UI 4) — pas une proposition, l'état réel du code. Chaque couleur de la palette existe déjà en 11 nuances dans le dépôt ; aucune valeur n'est inventée pour cet artefact.

1. Tokens

Couleurs

Palette brand (primaire) — ancrée sur #17614C (nuance 600, couleur de marque Djelimeet), hover sur #0F4638 (700) :

Palette paper (neutre — fonds, bordures, texte) :

Palette sand (avertissement — vote de retrait en attente) : texte #8F6314 (600) sur fond #F3EAD7 (100). Échelle complète 50→950 de #FBF6EC à #2A1C06, utilisée pour tout badge « en attente d'approbation » ou « cotisation en retard ».

Palette clay (erreur — écart de réconciliation, échec de paiement) : texte #8E2F22 (600) sur fond #F4E2DD (100). Échelle 50→950 de #FBF0ED à #290C09, réservée aux états d'échec réel (jamais pour un simple avertissement — voir sand).

Couleurs dédiées back-office : --color-admin-bar: #1B1A16 (fond du bandeau), --color-admin-bar-text: #FFFEFA, --color-admin-bar-accent: #8FCFB8 — seule touche sombre délibérée de toute l'interface, pour qu'un agent du back-office sache en permanence qu'il est hors du contexte d'un groupe.

Mapping sémantique Nuxt UI (app.config.ts) : primary → brand, secondary → paper, success → brand, warning → sand, error → clay, info → brand, neutral → paper. Le succès partage la teinte de marque plutôt qu'un vert générique — cohérence avec le propos financier du produit (confirmer une opération dans la couleur même de la confiance qu'on vend).

Typographie

Espacements, rayons et forme

• Rayon global : 0px. --ui-radius: 0px est posé explicitement au niveau :root : aucune carte, bouton ou champ arrondi dans toute l'interface — identité visuelle délibérément « administrative, nette », cohérente avec le propos de traçabilité. Seule exception documentée : input reçoit rounded-[2px], jamais plus.
• Cartes (UCard) : rounded-none, ring-1 ring-default — contour net plutôt qu'ombre, corps sans padding par défaut (p-0 sm:p-0) pour laisser le contenu (souvent un tableau financier) occuper tout l'espace.
• Modales et slideovers (« feuilles glissantes ») : rounded-none, ring-1 ring-default — patron unique documenté dans le code (canvas.json, annotation sheets-note) : poignée, titre, champs, puis toujours Annuler à gauche / action à droite. Quand la feuille touche à l'argent (devis, dépense), elle affiche le nouveau total avant validation, jamais après.

Icônes

• Bibliothèques Iconify embarquées : @iconify-json/lucide (usage général) et @iconify-json/simple-icons (logos d'opérateurs/réseaux sociaux).
• Règle d'usage : icône toujours accompagnée d'un libellé visible sauf pour une action universellement reconnue (fermer, retour).

Tableaux (UTable) — journal financier, listes admin

• En-têtes : classe utilitaire lbl sur fond bg-muted (paper-200).
• Cellules : taille de texte fixe text-[13.5px] — densité volontairement élevée pour un journal financier lu en colonnes, pas de zébrage arrondi (cohérent avec le rayon 0).

2. Composants

3. Règles transverses

• Mode sombre : colorMode: false dans nuxt.config.ts — l'interface est volontairement mono-thème clair (scheme-light posé sur body), cohérent avec un public qui lit des montants et où un mauvais contraste sur un chiffre n'est pas tolérable. Le bandeau admin reste la seule zone sombre, par choix fonctionnel (distinction de contexte), pas par thème.
• Accessibilité : contrastes vérifiés AA minimum pour le texte sur paper-100/paper-50 (texte en paper-900) et pour brand-600 comme couleur d'action sur fond clair ; cible tactile minimale conservée malgré l'absence d'arrondi (le rayon 0 ne réduit pas la zone cliquable).
• Animations : non documentées comme un système à part — l'identité visuelle « nette et administrative » (rayon 0, pas de dégradé) va de pair avec des transitions discrètes ; respecter prefers-reduced-motion sur toute transition ajoutée.
• Conventions de nommage : classes utilitaires Tailwind 4 (@theme static pour les tokens), pas de BEM ; interdiction explicite documentée dans le CSS source de réintroduire un arrondi, un dégradé ou une couleur hors palette (« voir CLAUDE.md §1-§2 ») — toute couleur hors brand/paper/sand/clay/admin-* est un défaut, pas une variante.
• i18n : @nuxtjs/i18n chargé — tout composant doit prévoir la variation de longueur de texte français/anglais sans casser la mise en page en colonnes du journal financier.

1. Diagramme (ASCII)

                      ┌────────────────────────┐        ┌───────────────────────┐
                      │  Nuxt 4 + Ionic (hybride)│        │  Nuxt 4 — back-office   │
                      │  app membre / bureau     │        │  système (admin)       │
                      │  Nuxt UI 4 · Pinia       │        │  Nuxt UI 4             │
                      └───────────┬──────────────┘        └───────────┬───────────┘
                                  │ HTTPS · JSON · JWT access 15min   │ HTTPS · JSON
                                  │ + refresh 30j (rotation)          │ x-system-role
                                  ▼                                  ▼
                      ┌────────────────────────────────────────────────────────┐
                      │            api.commuapp.ci / admin.commuapp.ci          │
                      │         API AdonisJS 6 — REST versionné /v1             │
                      │  routes → controllers (parse+valide) → services        │
                      │  (logique métier, SQL brut paramétré) → PostgreSQL     │
                      │  middlewares : resolve_group (groupId URL uniquement),  │
                      │  authentification OTP, Bouncer (x-permission/role)      │
                      └───┬───────────────┬───────────────┬────────────────┬───┘
                          │ SQL paramétré │ SET LOCAL      │ BullMQ enqueue │ cache/lock
                          ▼               │ set_current_   ▼                ▼
              ┌───────────────────────┐   │ group()  ┌─────────────┐  ┌───────────┐
              │   PostgreSQL 16        │◄──┘          │ Workers      │  │ Redis 7    │
              │  schéma partagé        │              │ BullMQ       │  │ OTP · cache│
              │  group_id + RLS sur    │              │ (process     │  │ verrous    │
              │  tables financières    │              │ séparé)      │  │ courts     │
              │  triggers : deny_ledger│              │ webhooks Wave│  └───────────┘
              │  _mutation, assert_    │              │ rappels      │
              │  transaction_balanced  │              │ réconciliat. │
              └───────────────────────┘              └──────┬───────┘
                                                              │ HTTPS webhook signé
                                                              ▼
                                                     ┌─────────────────────┐
                                                     │ Wave (compte marchand│
                                                     │ opérateur agréé)     │
                                                     │ float unique au      │
                                                     │ lancement — ADR-04   │
                                                     └─────────────────────┘

   Canaux sortants (via workers) :  WhatsApp/SMS (OTP, relances)  ·  Push FCM (Android/iOS)

2. Inventaire des composants

3. Flux critiques pas-à-pas

Flux A — Rechargement de wallet (Wave)

1. App → POST /me/wallet/topups (providerCode=wave) → API crée une intention en base avant tout appel sortant (payment_intents, statut pending).
2. API → Wave POST /v1/checkout/sessions → réponse wave_launch_url, renvoyée à l'app.
3. Utilisateur paie côté Wave (hors app) → Wave → webhook checkout.session.completed signé sur corps brut → capture_raw_body_middleware → événement brut stocké → 200 renvoyé en < 5 s.
4. Worker BullMQ consomme l'événement sous verrou Redis keyed sur topup:<intentId> → TopupService.settle() → écriture équilibrée au grand livre (crédit wallet membre, débit float Wave).
5. Filet de sécurité : si le webhook n'arrive jamais, sweepPendingIntents() (toutes les 5 min) relit l'état chez Wave et appelle le même settle() — idempotence par clé garantit un seul crédit, quel que soit le chemin.

Flux B — Retrait validé à 80 %

1. Trésorier → POST /groups/{groupId}/withdrawal-requests → service gèle les fonds (caisse → compte group_frozen_funds), photographie N = chefs actifs hors demandeur, fige requiredApprovals = ceil(0.8×N).
2. Chaque chef → OTP de re-authentification + PIN → POST .../approvals (idempotent, UNIQUE(withdrawal_id, approver_membership_id)).
3. Dès approvalsCount ≥ requiredApprovals → statut approved → vérification du float (plafond journalier opérateur) → executing → payout Wave → paid ; si liquidité insuffisante → awaiting_liquidity (fonds restent gelés, alerte exploitation).
4. Sans quorum sous 72 h → job planifié → expired, restitution intégrale en caisse, notification collective.
5. Bénéficiaire → lignes de justification (disbursement_lines, hors grand livre) jusqu'à solde ; reliquat → return-remainder (rechargement ordinaire référencé).

Flux C — Présence à une réunion, hors ligne

1. Secrétaire ouvre la réunion le jour J → app génère un QR HMAC tournant (60 s) affiché en salle.
2. Chaque membre scanne (ou le secrétaire scanne son badge) → validation locale hors ligne (tolérance ±2 fenêtres) → mise en file de mutation côté app si pas de réseau, avec clé d'idempotence.
3. Synchronisation différée → API → contrainte (meeting_id, membership_id) rend un double scan sans effet.
4. Secrétaire publie le PV (liste de présence reprise automatiquement) → minutes verrouillé, minute_versions pour toute correction ultérieure.

4. Stockage

• PostgreSQL 16 : schéma unique, ~30 tables sur 12 domaines (identité, groupes, financier, abonnement, réunions, billetterie, social, notifications, opérateurs). Sauvegarde continue (PITR) ; RLS activée table par table sur les tables porteuses de group_id financières et sensibles, scope applicatif partout ailleurs.
• Redis 7 : OTP (TTL 5 min), verrous courts (TTL de l'ordre de la seconde, libération par jeton), cache de lecture invalidé explicitement — jamais de donnée financière durable.
• Stockage objet (S3-compatible) : médias du fil, justificatifs de dépense, PV exportés en PDF — upload direct par URL pré-signée, l'API ne sert jamais d'intermédiaire pour les octets.
• File BullMQ (sur Redis) : jobs webhooks, relances, génération de factures, réconciliation — persistants jusqu'à traitement, avec reprise sur échec.

5. Décisions structurelles → ADR liés

• SQL brut paramétré plutôt que Lucid ORM comme couche d'accès → ADR « SQL brut paramétré ».
• Authentification OTP sans mot de passe → ADR « Authentification par OTP sans mot de passe ».
• Grand livre en partie double et immuabilité → ADR « Grand livre en partie double, écritures immuables ».
• Seuil des 80 % et collège figé → ADR « Retraits à double validation, seuil 80 % ».
• RLS PostgreSQL pour l'isolation multi-tenant → ADR « Isolation multi-tenant par RLS PostgreSQL ».
• Un seul opérateur en production (Wave), interface multi-opérateur prête → cahier d'architecture ADR-04/ADR-11 (float modélisé comme compte, pas solde caché).
• SSE (@adonisjs/transmit) plutôt que WebSocket pour les mises à jour temps réel (compteur de présence, avancement d'un vote) → cahier d'architecture ADR-08.

6. Limites connues

• Un seul opérateur mobile money branché en production : la bascule multi-opérateur réelle (routage, float consolidé) reste à implémenter, seule l'interface PaymentProvider existe.
• RLS créée mais pas activée sur toutes les tables : l'activation table par table dépend de la validation préalable du middleware de tenant sur chacune — un chantier d'exploitation encore ouvert, pas un oubli.
• Pas de rôle back-office BYPASSRLS dédié encore tranché : un modérateur système multi-groupes dépend d'une décision à prendre avant la mise en production.
• Pas de catégories comptables ni de budgets prévisionnels (hors périmètre v1, cahier d'architecture §8).
• Pas de versionnement de rupture d'API (/v2) ni de stratégie de dépréciation formalisée — non nécessaire tant qu'aucune rupture de contrat n'est requise.
• Rate limiting documenté en texte sur certaines routes (OTP) mais pas encore déclaré via un mécanisme standard (en-têtes X-RateLimit-*).