Schéma de base de données — vue d'ensemble, tables critiques, FKs, index

La base Kohinos contient environ ~70 tables (100 classes d'entité dans src/Entity/, certaines étant des single table inheritance partageant une même table physique flux, operation_*, account_*). Le moteur cible est MariaDB en prod et SQLite in-memory en test (cf. migrations Doctrine). Cette page n'est pas auto-générée à partir du schéma : elle est tenue à la main pour rester lisible pour un DBA ou un nouveau contributeur, et doit être mise à jour à chaque migration qui touche structurellement un agrégat (table ajoutée, FK ajoutée, index critique modifié). Les identifiants de tables et colonnes sont en anglais ; la documentation, en français.

Vue d'ensemble — agrégats principaux

classDiagram
  class User { +int id +string username +string email +string password +string roles }
  class Adherent { +int id +User user +string firstname +string lastname }
  class Prestataire { +int id +User user +string name +string siret }
  class Comptoir { +int id +string name +Groupe groupe }
  class Groupe { +int id +string name }
  class AccountAdherent { +int id +Adherent owner +decimal balance }
  class AccountPrestataire { +int id +Prestataire owner +decimal balance }
  class AccountComptoir { +int id +Comptoir owner +decimal balance }
  class AccountGroupe { +int id +Groupe owner +decimal balance }
  class AccountSiege { +int id +decimal balance }
  class Flux { +int id +decimal montant +string type +string moyen +datetime createdAt }
  class Operation { +int id +decimal montant +string hash +string currency +bool historical }
  class SepaMandate { +int id +Adherent adherent +string mandateReference +string iban +string status }
  class SolidoumeParameter { +int id +string name +string distributionMode +bool enabled }
  class SolidoumeItem { +int id +Adherent adherent +SolidoumeParameter param +int lastMonthPayed }
  class HelloAsso { +int id +int helloassoId +decimal amount +string state }

  User "1" --> "0..1" Adherent
  User "1" --> "0..1" Prestataire
  Adherent "1" --> "1" AccountAdherent
  Prestataire "1" --> "1" AccountPrestataire
  Comptoir "1" --> "1" AccountComptoir
  Groupe "1" --> "1" AccountGroupe
  Comptoir "0..*" --> "1" Groupe
  Flux "1" --> "1..*" Operation
  Flux "0..*" --> "0..1" SolidoumeParameter
  SepaMandate "0..*" --> "1" Adherent
  SolidoumeItem "0..*" --> "1" Adherent
  SolidoumeItem "0..*" --> "1" SolidoumeParameter
  HelloAsso "0..*" --> "0..1" Adherent
    

Domaines

1. Identité & adhésion

2. Comptes & monnaie eMLc

Chaque entité accountable (Adhérent, Prestataire, Comptoir, Groupe, Siège) possède exactement un compte, créé automatiquement via AccountableObject::postPersist() (cf. invariants financiers). Le solde (balance) est de type NUMERIC(10, 2) et reflète la somme algébrique des opérations associées.

3. Opérations — intégrité par hash

Une opération est l'écriture atomique unitaire au crédit ou au débit d'un compte. Chaque opération est hashée (BLAKE2b via hash), calculé à partir de son contenu. L'invariant somme des opérations = balance du compte est vérifié par bin/ai-workflows/financial/check-invariants.php.

4. Flux — STI (Single Table Inheritance)

Toutes les opérations métier (achat, vente, don, cotisation, transfert, reconversion, change…) sont matérialisées par une ligne dans la table flux avec un discriminator flux_type. Un même flux porte plusieurs opérations (au moins 2 : débiteur et créditeur) pour garantir l'équilibre comptable. Voir bounded contexts pour la cartographie des sous-classes.

Convention de référence (voir CLAUDE.md) : "Solidoume prélèvement {YYYYMM}", "Solidoume {YYYYMM}", "Solidoume cotisation {YYYYMM}", "Achat récurrent {YYYYMM}", "Cotisation MLC {YYYY}". Ces préfixes sont la clé d'identification pour les repos : ne JAMAIS renommer.

5. SEPA — mandats & requêtes récurrentes

6. SSA — Sécurité Sociale de l'Alimentation

Voir documentation SSA dédiée pour les règles métier (taux, redistribution, prestataires éligibles, alertes « ancien participant »).

7. Paiements externes

8. CMS

9. Système, audit & RGPD

Index critiques

Ces index ne sont pas optionnels : ils garantissent l'idempotence ou la performance de processus financiers. Une migration qui les supprime doit être refusée en review.

Champs sensibles chiffrés au repos

Lifecycle & callbacks Doctrine

• AccountableObject::postPersist() — #[ORM\HasLifecycleCallbacks] sur la MappedSuperclass. À la création d'un Adherent / Prestataire / Comptoir / Groupe / Siege, une ligne dans la table account_* correspondante est créée automatiquement avec un solde 0. Casse silencieusement si l'attribut PHP 8 #[ORM\MappedSuperclass] est omis (le callback n'est pas câblé).
• #[Gedmo\Slug(fields: [...])] sur les entités CMS (Page, News, Faq, Rubrique, Prestataire, Comptoir, Groupe…) pour générer un slug à partir du nom. Lifecycle : pré-persist & pré-update. Sans attribut PHP 8, le slug reste NULL.
• #[ORM\PrePersist] / #[ORM\PreUpdate] sur les entités qui dérivent l'updated_at manuellement (SQLite ne supporte pas DEFAULT CURRENT_TIMESTAMP ON UPDATE).
• Pattern double-flush UUID : pour les entités dont une colonne dépend de l'UUID auto-généré (SepaMandate.mandate_reference), on flushe une première fois pour obtenir l'UUID, on dérive la référence, on flushe à nouveau. Cf. CLAUDE.md.

Tables ne devant JAMAIS être éditées en direct

Vues / requêtes utilitaires d'audit

Quelques SELECT à garder sous la main pour vérifier la santé de la base — exécuter en lecture seule, jamais via Sonata. Ces requêtes sont à brancher dans un dashboard self-host (Metabase, Grafana self-host) ou exposées par une commande kohinos:audit:*.

-- Somme algébrique des opérations vs balance affichée (doit être 0)
SELECT a.id, a.balance,
       (SELECT COALESCE(SUM(o.montant), 0) FROM operation_adherent o WHERE o.account_id = a.id) AS sum_ops,
       a.balance - (SELECT COALESCE(SUM(o.montant), 0) FROM operation_adherent o WHERE o.account_id = a.id) AS diff
FROM account_adherent a
HAVING diff != 0;

-- Masse monétaire eMLc totale (tous comptes confondus)
SELECT
  (SELECT COALESCE(SUM(balance), 0) FROM account_adherent)    AS adherents,
  (SELECT COALESCE(SUM(balance), 0) FROM account_prestataire) AS prestataires,
  (SELECT COALESCE(SUM(balance), 0) FROM account_comptoir)    AS comptoirs,
  (SELECT COALESCE(SUM(balance), 0) FROM account_groupe)      AS groupes,
  (SELECT COALESCE(SUM(balance), 0) FROM account_siege)       AS siege;

-- Soldes < 0 (ne devrait jamais arriver — aucun découvert autorisé par construction)
SELECT a.id, u.firstname, u.lastname, a.balance
FROM account_adherent a
JOIN adherent ad ON ad.id = a.adherent_id
JOIN user u ON u.adherent_id = ad.id
WHERE a.balance < 0
ORDER BY a.balance ASC;

-- Mandats SEPA actifs sans aucune requête récurrente associée (mandat orphelin)
SELECT sm.id, sm.mandate_reference, sm.signed_at
FROM sepa_mandate sm
WHERE sm.status = 'active'
  AND NOT EXISTS (SELECT 1 FROM recurring_subscription_request r WHERE r.sepa_mandate_id = sm.id)
  AND NOT EXISTS (SELECT 1 FROM recurring_purchase_request     r WHERE r.sepa_mandate_id = sm.id);

-- Webhooks HelloAsso reçus mais non rattachés (helloasso.adherent_id IS NULL après X heures)
SELECT id, helloassoid, amount, created_at, state
FROM helloasso
WHERE adherent_id IS NULL
  AND created_at < NOW() - INTERVAL 24 HOUR;

-- Détection double prélèvement SSA (devrait toujours être vide grâce à l'index UNIQUE)
SELECT adherent_id, solidoume_parameter_id, last_month_payed, COUNT(*) AS n
FROM solidoume_item
GROUP BY adherent_id, solidoume_parameter_id, last_month_payed
HAVING n > 1;

Maintien de cette doc

Pour aller plus loin