Architecture et conventions

La SIM Database est une instance PostgreSQL 18.4 unique (Alpine) dont le schéma est versionné par Flyway et testé avec pgTAP. Cette page décrit l’architecture, l’organisation des schémas et les conventions qui maintiennent le projet maintenable.

Architecture de haut niveau

┌──────────────────────────────────────────────────────────────┐
│                         Host                                  │
│   Makefile  ──►  docker compose  ──►  sim-postgres:local      │
│                         │                                     │
│   Flyway one-shot       │                                     │
│   container ────────────┤                                     │
│                         ▼                                     │
│                PostgreSQL 18.4 + pgTAP                        │
│   migrations/  seeds/  tests/  scripts/  (mounted)            │
└──────────────────────────────────────────────────────────────┘

Composants principaux

Composant	Technologie	Responsabilité
Moteur de base	PostgreSQL 18.4 Alpine	Stocke toutes les données, exécute les tests pgTAP dans le conteneur
Migrations	Flyway 13.2 (conteneur one-shot)	Évolution et validation du schéma
Tests	pgTAP 1.3.4	Tests de régression au niveau SQL
Orchestration locale	Docker Compose	Conteneur de dev sim-postgres:local
Orchestration production	Docker Compose	Conteneur dédié sim-postgres:prod + pgAdmin optionnel
Wrapper de commandes	GNU Make	Cibles multi-plateforme pour Windows cmd/Git Bash/POSIX
Outillage de seed	Node + bcryptjs	Génère/vérifie les hachages bcrypt commités

Carte des schémas

La base est créée dans migrations/common/001_bootstrap_schemas.sql. public est volontairement réservé ; chaque table métier vit dans le schéma de son module.

Schéma PostgreSQL	Module	Créé par	Rôle
core	M0 — Transverse	001_bootstrap_schemas.sql	Paramètres globaux
client	M0 — Client	001_bootstrap_schemas.sql	Référentiel client unique
residence	M2 — Résidence	001_bootstrap_schemas.sql	Logement et locations
market	M3 — Market	001_bootstrap_schemas.sql	Super-Marché
pressing	M4 — Pressing	001_bootstrap_schemas.sql	Pressing
restaurant	M5 — Restaurant	001_bootstrap_schemas.sql	Restauration
salle_fete	M6 — Salle de fête	001_bootstrap_schemas.sql	Salle de réception
facturation	M7 — Facturation	001_bootstrap_schemas.sql	Facturation
finances	M8 — Finances	001_bootstrap_schemas.sql	Paiements et consolidation
rh	M9 — RH	001_bootstrap_schemas.sql	Ressources humaines
admin	M11 — Admin	001_bootstrap_schemas.sql	Utilisateurs, rôles, permissions
audit	R15 — Audit	001_bootstrap_schemas.sql	Journal en ajout seul
abonnement	Catalogue d’abonnements	046_common_abonnement_schema.sql	Catégories d’abonnement

Conventions de migration

Nommage des fichiers

Chaque migration est un fichier unique nommé avec un numéro globalement unique, complété de zéros :

<numéro>_<module>_<description>.sql

Exemples :

migrations/common/001_bootstrap_schemas.sql
migrations/residence/021_residence_batiments.sql
migrations/finances/procedures/025_finances_routines.sql

Règles :

• Les numéros sont globaux à tout le projet, pas par dossier.
• Tables et routines/vues ne sont pas mélangées dans un même fichier ; les routines vont dans un sous-dossier procedures/.
• Les migrations appliquées sont immuables. Flyway validateOnMigrate=true rejette toute modification d’une migration déjà appliquée.
• Les nouveaux changements sont ajoutés sous forme de nouveaux fichiers de migration (les back-fills utilisent FLYWAY_OUT_OF_ORDER=true).

Nommage des objets

Objet	Patron de nommage	Exemple
Tables	lowercase_snake_case (domaine français)	contrat_location, mouvement_stock
Colonnes	lowercase_snake_case	id_client, montant_loyer
Clés primaires	pk_<table>	pk_facture
Clés étrangères	fk_<table>_<colonne>	fk_facture_client
Contraintes uniques	uq_<table>_<colonne>	uq_role_code
Contraintes check	chk_<table>_<domaine>	chk_logement_type
Index	idx_<table>_<colonne>	idx_client_nom
Index uniques	ux_<table>_<colonne>	ux_utilisateur_email
Fonctions	qualifiées par le schéma, verbe d’abord	residence.generer_echeances
Triggers	trg_<table>_<événement>	trg_mouvement_stock_solde

Règles du modèle de données

1. Pas d’usage du schéma public — public reste vide pour la compatibilité d’infrastructure.
2. Référentiel client unique — client.client est la seule table client ; tous les modules la référencent.
3. Préférer ON DELETE RESTRICT — les suppressions en cascade sont évitées sur les données de référence et métier.
4. Énumérations de statut et type — implémentées en contraintes CHECK sur des colonnes VARCHAR plutôt qu’en enums PostgreSQL natifs, pour permettre une extension facile via de nouvelles migrations.
5. Audit par défaut — chaque table des 11 schémas métier reçoit un trigger AFTER INSERT OR UPDATE OR DELETE qui journalise dans audit.journal_audit.

Migrations vs seeds

Zone	Rôle	Contenu
migrations/	DDL et DML structurel	Création/modification de tables, fonctions, triggers, contraintes
seeds/reference/	Données de référence requises	Activités, moyens de paiement, rôles, permissions, catégories
seeds/dev/	Fixtures de développement jetables	Clients, contrats, produits, employés de test
seeds/generated/	Artefacts générés	Hachages bcrypt (10_auth_passwords.sql)

Flux de migration

Flyway applique les migrations dans l’ordre numérique. FLYWAY_OUT_OF_ORDER=true permet aux migrations de back-fill (ex. 032 insérée après que 033 a déjà été déployée) de s’exécuter sur des bases plus anciennes. Comme les migrations sont purement additives, c’est sûr.

Sur une base neuve :

001 → 002 → 003 → ... → 073

Sur une base déjà en 073, un back-fill 032_* est un no-op pour les objets existants et n’ajoute que le changement manquant.