Modules métier

Le backend est organisé en tranches métier verticales. Chaque tranche a un module Nest, un contrôleur, un service, un repository, un fichier DTO et généralement une tranche e2e.ts sur base réelle.

Core / Client / Abonnement

Core (src/core)

Paramètres globaux clé/valeur dans core.parametre.

Route	Permission
GET /api/v1/core/parametres	CORE.VOIR
POST /api/v1/core/parametres	CORE.CREER
PUT /api/v1/core/parametres/:cle	CORE.MODIFIER

Client (src/client)

Référentiel client unique. Les DTO gèrent les pièces d’identité (piece_identite) et les contacts d’urgence (contact_urgence).

Route	Permission
GET /api/v1/client/clients	CLIENT.VOIR
POST /api/v1/client/clients	CLIENT.CREER
PATCH /api/v1/client/clients/:id	CLIENT.MODIFIER
POST /api/v1/client/clients/:id/pieces-identite	CLIENT.MODIFIER

ClientRepository.nextClientCode produit GSG-CL-NNN en castant le suffixe numérique, évitant le basculement lexicographique au-delà de 999.

Abonnement (src/abonnement)

Catégories d’abonnement uniquement (abonnement.categorie_abonnement).

Route	Permission
GET /api/v1/abonnement/categories	ABONNEMENT.VOIR
POST /api/v1/abonnement/categories	ABONNEMENT.CREER
PATCH /api/v1/abonnement/categories/:id	ABONNEMENT.MODIFIER
DELETE /api/v1/abonnement/categories/:id	ABONNEMENT.SUPPRIMER

Residence

Le ResidenceModule (src/residence/) est l’implémentation de référence de l’architecture du projet : bâtiments, logements, contrats de bail, échéances de loyer, charges refacturées, courts séjours, abonnements, photos d’inventaire et portail résident.

Sous-modules

Sous-module	Fichiers	Périmètre
Bâtiments	batiments.*	Référentiel multi-bâtiments
Logements	logements.*	Inventaire locatif, numérotation
Contrats / loyers	residence.*	Contrats de bail, échéances, dépôts, PDF
Charges	charges.*	Charges refacturées
Courts séjours	sejours.*	Nuitées/siestes
Abonnements	abonnements.*	Services récurrents
Portail	portail.*	Espace résident en lecture seule
Inventaire	etat-lieux.*	Photos d’entrée/sortie

Routes clés

Route	Permission	Rôle
POST /api/v1/residence/contrats	RESIDENCE.CREER	Créer un contrat
POST /api/v1/residence/contrats/:id/activer	RESIDENCE.MODIFIER	EN_ATTENTE → ACTIF
POST /api/v1/residence/contrats/:id/resilier	RESIDENCE.MODIFIER	ACTIF → RESILIE
POST /api/v1/residence/echeances/:id/encaisser	FINANCES.CREER	Encaissement d’une échéance
POST /api/v1/residence/contrats/:id/encaisser-loyer-lot	FINANCES.CREER	Encaissement en lot
GET /api/v1/residence/suivi	RESIDENCE.VOIR	Vue de suivi des loyers
GET /api/v1/residence/impayes	RESIDENCE.VOIR	Vue des retards/partiels
GET /api/v1/residence/occupation	RESIDENCE.VOIR	Occupation par bâtiment

Machines à états

Entité	États
contrat_location	EN_ATTENTE, ACTIF, RESILIE, TERMINE
logement	DISPONIBLE, RESERVE, OCCUPE, EN_NETTOYAGE, EN_MAINTENANCE, INDISPONIBLE
charge_facturee	IMPAYEE, PARTIELLE, PAYEE
sejour_court	EN_COURS, TERMINE, ANNULE
abonnement	ACTIF, SUSPENDU, RESILIE, EXPIRE

Portail résident

GET /api/v1/residence/portail/* est protégé par RESIDENT.VOIR. Toutes les requêtes sont limitées à AuthUser.idClient. Les routes incluent :

• resume
• echeances et echeances/:id/recu/pdf
• etat-des-lieux et etat-des-lieux/:id/photo
• paiements et paiements/:id/recu/pdf
• caution

Modules commerciaux

Tous les modules commerciaux utilisent SettlementService de FacturationModule pour créer ou solder des lignes facturation.facture.

Market (src/market)

Affiché « Super-Marché » dans le frontend (routes /supermarche/*, feature src/features/supermarche) ; permissions MARCHANDISE.*.

Domaine	Tables
Catalogue	categorie_produit, fournisseur, produit
Stock	mouvement_stock (le trigger possède quantite_stock)
Ventes	vente, ligne_vente

quantite_stock n’est jamais écrit directement ; il est calculé par trg_mouvement_stock_solde. Les mouvements manuels sont ENTREE, SORTIE, AJUSTEMENT.

Pressing (src/pressing)

Cycle de vie des commandes : DEPOSE → EN_TRAITEMENT → PRET → RETIRE / ANNULEE.

• Le dépôt peut inclure une avance (acompte) qui crée une facture COMMANDE_PRESSING PARTIELLE.
• Le retrait (retirer) solde le reste sur la même facture.
• L’annulation n’est possible qu’avant toute facture.

Restaurant (src/restaurant)

Cycle de vie des commandes :

EN_COURS → EN_PREPARATION → SERVIE → PAYEE / ANNULEE

Les commandes sont entièrement payées à la création. Les transitions de statut sont garanties par TRANSITIONS_COMMANDE_STATUT.

Salle de fête (src/salle_fete)

Cycle de vie des réservations : RESERVEE → CONFIRMEE → REALISEE / ANNULEE.

• confirmer encaisse une avance et crée une facture RESERVATION_FETE PARTIELLE.
• realiser encaisse le solde sur la même facture.
• disponibilites retourne les créneaux occupés pour une date donnée.

Facturation et Finances

Facturation (src/facturation)

• Prestations (prestations)
• Factures (factures, factures/:id/pdf, factures/:id/ticket)
• SettlementService exporté pour tous les modules commerciaux
• FacturationRepository.prochainNumeroFacture produit GSG-FAC-YYYY-NNN

SettlementService.settle résout une activité, crée/lit une facture, applique un paiement et retourne montant_total, montant_paye, reste, statut recalculés par le trigger.

Finances (src/finances)

Domaine	Tables principales
Paiements	paiement, application_paiement
Dépenses	depense, categorie_depense
Tiroirs-caisses	caisse, periode_caisse, tirage
Moyens de paiement	moyen_paiement
Consolidation	vues ca_par_activite, tableau_de_bord

Règles des tiroirs-caisses :

• creerPaiement / creerDepense exigent une periode_caisse ouverte pour la caisse choisie.
• creerTirage calcule montant_attendu depuis encaissements − décaissements − dépenses et émet une notification HIGH si ecart !== 0.

RH et Dashboard

RH (src/rh)

Entité	Routes
Services	services
Employés	employes
Présences	pointages, pointages/:id/depart
Paie	paies, paies/:id/elements, paies/:id/recalculer, paies/:id/valider, paies/:id/payer

• heure_arrivee et duree_travaillee sont possédées par les triggers.
• Les totaux de paie sont recalculés par trg_element_salaire_paie.
• BulletinPdfService génère les bulletins de paie en PDF.

Dashboard (src/dashboard)

Tuiles agrégées pour le tableau de bord dirigeant et les tableaux par activité. Réutilise RapportsModule et DashboardRepository. Formats de sortie : json, pdf, xlsx.

Audit, Rapports, Uploads, Jobs

Audit (src/audit)

Accès en lecture seule à audit.journal_audit. Gère les rapports JSON, PDF et XLSX. POST /api/v1/audit/masquer masque les champs sensibles comme mot_de_passe avant affichage.

Rapports (src/rapports)

Endpoints d’agrégation en lecture seule :

• /api/v1/rapports/synthese-globale
• /api/v1/rapports/financier
• /api/v1/rapports/activites/:code
• /api/v1/rapports/rh
• /api/v1/rapports/series

La sérialisation CSV / Excel utilise le délimiteur ; et aplatit récursivement le JSON imbriqué.

Uploads (src/uploads)

• POST /api/v1/uploads — upload multipart de file + categorie
• GET /api/v1/uploads?key=... — télécharge les octets de l’objet

Catégories : client-photo, piece-identite, plat-photo, etat-lieux, produit-photo.

Jobs (src/jobs)

Jointure cron / BullMQ. Exemples de planifications cron :

Job	Cron	Rôle
generer-echeances	12 2 * * *	Générer les échéances de loyer
recalculer-paie	41 4 1 * *	Recalculer la paie
reesolde-stock	23 3 * * *	Recalculer le stock market
transition-contrats-expires	30 2 * * *	Expirer les contrats terminés
sauvegarde-auto	* * * * *	Déclencher les sauvegardes planifiées

Les routes de déclenchement manuel sont sous POST /api/v1/jobs/*.