SEKOUH — Wiki Sprint 4 — Gestion

Financière
Module Finance : Frais · Paiements · Reçus · Suivi
Mars–Avril 2026 | Confidentiel & Interne

🔧 Stack BDD 📦 Livraison

Spring Boot + [Link] PostgreSQL + Keycloak 14 jours / 5 US

Table des matières

1. Description du Module
2. Stack Technique
3. Acteurs & Use Cases
4. Contraintes
5. Modèle de Données
6. Flows Fonctionnels
7. Workflow Backend (Spring Boot)
8. Frontend [Link]
9. Stratégie QA
10. Plan d'Action & Workflow Équipes
11. Aperçu User Stories — Futures Évolutions

Révision v1.1 — Ajout des tranches de paiement (scolarité) configurables par

l'Admin · Suppression du téléchargement de reçu PDF côté Parent

1. Description du Module
Ce module gère l'ensemble du cycle financier de SEKOUH. Il couvre :

● La configuration des frais de scolarité par niveau

● La configuration des tranches de paiement de scolarité par l'Admin (montant, date
de début, date de fin)
● L'enregistrement des paiements (complets ou partiels, par tranche)
● La génération automatique de reçus PDF officiels
● La consultation de l'historique financier par les comptables et administrateurs
● La vue dédiée aux parents pour suivre l'état des paiements de leurs enfants

Ce module s'appuie sur :

● Années scolaires (Sprint 1)

 ● Classes/Niveaux (Sprint 2)
● Inscriptions élèves (Sprint 3)
● Utilisateurs/Rôles via Keycloak

2. Stack Technique
Backend

● Spring Boot 3.x (Java 17)

● Spring Data JPA + Spring Security
● Keycloak (OIDC/OAuth2) — gestion des rôles et identités
● Modulith — événements domain
● PostgreSQL
● OpenPDF / iText — génération des reçus PDF

Frontend

● [Link] 16+ (App Router) avec React Server Components

● Tailwind CSS / Shadcn UI
● TanStack Query — data fetching
● JWT via Keycloak

Outils & Infra

● Docker · Git · CI/CD (GitLab)

● Génération PDF : OpenPDF / iText
● Devise : Franc CFA (XAF) par défaut
● Logs : SLF4J + ELK

3. Acteurs & Use Cases

Rôle Fonctionnalités principales

👑 Admin Configuration frais, configuration des tranches de paiement,

consultation historique paiements, export, accès complet.

💰 Enregistrer paiements, générer reçus PDF, consulter historique, configurer

Comptable frais.

📝 Secrétaire Consultation de l'état de paiement d'un élève. Accès lecture seule.

Parent Consultation de l'état financier de ses enfants et des tranches de paiement

en cours. Aucun accès aux reçus PDF.
 Enseignant Aucun accès au module Finance.

🎓 Élève Aucun accès direct au module Finance.

4. Contraintes
Fonctionnelles

● Les frais sont configurés par niveau, pas par classe individuelle.
● Les frais de type SCOLARITE peuvent être découpés en tranches configurées par
l'Admin (montant par tranche, date de début, date de fin).
● La somme des montants de toutes les tranches d'un niveau doit être égale au montant
total de scolarité configuré dans fee_configs.
● Un paiement peut être partiel — le solde est mis à jour en temps réel.
● Le statut d'un paiement évolue : En attente → Partiel → Soldé.
● Devise par défaut : Franc CFA (XAF). Aucune conversion de devise.
● Un reçu PDF est généré automatiquement à chaque paiement enregistré.
● Un paiement enregistré ne peut pas être supprimé — uniquement modifié (avec motif
journalisé).
● Les reçus PDF sont archivés sur le serveur avec un nom normalisé.
● Les reçus PDF ne sont accessibles qu'aux rôles Admin et Comptable — les
parents n'ont pas accès au téléchargement des reçus.

Non Fonctionnelles

● Sécurité : RBAC via Keycloak — le parent ne voit que ses propres enfants.
● Performance : historique paginé, cache TanStack Query côté frontend.
● Audit : created_at, updated_at, recorded_by (Spring Data
AuditorAware).
● Numéro de reçu unique : format REC-ANNEE-XXXXX, séquence par année.
● Génération PDF < 2 secondes par reçu.
● Internationalisation : montants formatés XAF, dates ISO, langue française.

5. Modèle de Données
Enum : StatutPaiement
Valeur Description

EN_ATTEN Paiement déclaré mais non encore encaissé

TE
PARTIEL Montant partiel reçu — solde restant > 0

SOLDE Montant total atteint — inscription soldée

Table : fee_configs

Configuration des frais par niveau et par type, rattachée à l'année scolaire active.

Champ Type Requi Exemple Description / Règle métier

s

id UUID Oui auto Identifiant unique auto-généré

level_id UUID (FK) Oui — Référence → [Link]

academic_yea UUID (FK) Oui — Référence →

r_id annee_scolaire.id
(ACTIVE)

fee_type Enum Oui INSCRIPTI INSCRIPTION |

ON SCOLARITE | AUTRE

label String Oui Frais de Libellé descriptif du frais

scolarité

amount Decimal(10, Oui 150000.00 Montant en XAF — doit être

2) >0

due_date Date Oui 2026-04-30 Échéance de paiement

created_at DateTime Oui — Audit automatique

updated_at DateTime Oui — Audit automatique

Table : payment_tranches

Découpage des frais de scolarité en tranches de paiement, configuré par l'Admin

par niveau et par année scolaire.

Champ Type Requi Exemple Description / Règle métier

s

id UUID Oui auto Identifiant unique auto-généré

fee_confi UUID (FK) Oui — Référence → fee_configs.id

g_id (doit être de type SCOLARITE)
label String Oui Tranche Libellé de la tranche (ex : « 1ère
1 tranche », « Tranche de janvier »)

amount Decimal(10, Oui 50000.00 Montant de la tranche en XAF — doit

2) être > 0

start_dat Date Oui 2026-09- Date d'ouverture de la tranche (début

e 01 de la période de paiement)

end_date Date Oui 2026-10- Date de clôture de la tranche

31 (échéance limite de paiement)

tranche_o Integer Oui 1 Ordre d'affichage et de traitement des

rder tranches (1, 2, 3…)

created_a DateTime Oui — Audit automatique

t

updated_a DateTime Oui — Audit automatique

t

Règles métier :

● Une tranche est liée exclusivement à un fee_config de type SCOLARITE.

● La somme des amount de toutes les tranches d'un fee_config doit être égale à
fee_configs.amount.
● Les plages de dates (start_date / end_date) ne doivent pas se chevaucher pour
un même fee_config.
● end_date doit être strictement postérieure à start_date.
● Un enregistrement de paiement peut référencer une tranche via tranche_id dans la
table payments.

Table : payments (mise à jour)

Enregistrement de chaque versement financier. Supporte les paiements partiels et

multiples.

Champ Type Requi Exemple Description / Règle

s métier

id UUID Oui — Identifiant unique auto-

généré

receipt_numb String Oui REC-2026- Auto-généré, format

er 00088 REC-ANNEE-XXXXX
student_id UUID (FK) Oui — Référence →
[Link]

fee_config_i UUID (FK) Non — Référence →

d fee_configs.id
(optionnel)

tranche_id UUID (FK) Non — Référence →

payment_tranches.
id — renseigné si le
paiement couvre une
tranche de scolarité

academic_yea UUID (FK) Oui — Référence →

r_id annee_scolaire.id

amount_paid Decimal(10, Oui 75000.00 Montant encaissé en XAF

2)

total_amount Decimal(10, Oui 150000.00 Frais total dû pour ce type

2)

remaining_ba Decimal(10, Oui 75000.00 Calculé : total_amount

lance 2) − Σ versements

payment_meth Enum Oui MOBILE_MONE ESPECES |

od Y MOBILE_MONEY |
VIREMENT

transaction_ String Non MPESA- Référence pour Mobile

ref XY1234 Money / Virement

status Enum Oui PARTIEL EN_ATTENTE |

PARTIEL | SOLDE |
ANNULE

payment_date DateTime Oui 2026-04-01 Date/heure du versement

recorded_by UUID (FK) Oui — Comptable ayant

enregistré — [Link]

receipt_pdf_ String Non /docs/REC- URL du reçu PDF archivé

url ….pdf
notes Text Non Versement 1/2 Commentaire libre

created_at DateTime Oui — Audit automatique

updated_at DateTime Oui — Audit automatique

Relations entre tables

● students 1 → * payments (historique complet des versements)

● levels 1 → * fee_configs (un niveau peut avoir plusieurs types de frais)
● fee_configs (type SCOLARITE) 1 → * payment_tranches (découpage en
tranches)
● payment_tranches 1 → * payments via tranche_id (paiements rattachés à
une tranche)
● academic_year_id obligatoire sur fee_configs et payments, vérifié
ACTIVE
● users (rôle COMPTABLE) 1 → * payments via recorded_by

6. Flows Fonctionnels
Flow 0 — Configurer les tranches de paiement de scolarité (US-16b)

Acteur : Admin uniquement

Étape Description

1 L'admin accède à « Finances → Configuration des frais → Tranches de scolarité

».

2 Il sélectionne le niveau et l'année scolaire active. Le système affiche le barème de

scolarité (SCOLARITE) déjà configuré pour ce niveau.

3 Il clique sur « Gérer les tranches » pour ce barème.

4 Il ajoute une ou plusieurs tranches en renseignant pour chacune : le libellé, le

montant, la date de début et la date de fin.

5 Il clique sur « Enregistrer ». Le système valide : somme des tranches = montant

total du barème, pas de chevauchement de dates, end_date > start_date.

6 Confirmation affichée. Les tranches sont visibles par les comptables lors de
l'enregistrement d'un paiement.

Cas d'erreur :
 ● Somme des montants des tranches ≠ montant total du barème :
blocage avec message « La somme des tranches (X XAF) ne
correspond pas au montant total de scolarité (Y XAF) ».
● Chevauchement de dates entre deux tranches : message « Les périodes de deux
tranches ne peuvent pas se chevaucher ».
● end_date ≤ start_date : validation bloquante.
● Modification des tranches après paiements existants sur une tranche : avertissement «
Des paiements sont déjà enregistrés sur cette tranche. La modification n'affectera pas
les paiements existants ».

Flow 1 — Configurer les frais d'un niveau (US-17)

Acteurs : Admin / Comptable

Étape Description

1 L'admin/comptable accède à « Finances → Configuration des frais ».

2 Il sélectionne le niveau dans la liste déroulante (seuls les niveaux de l'année active
sont affichés).

3 Il ajoute un ou plusieurs types de frais (INSCRIPTION, SCOLARITE) avec les

montants correspondants.

4 Il définit une date d'échéance par type de frais.

5 Il clique sur « Enregistrer ». Le système valide : montant > 0, niveau actif, pas de
doublon (level + type + année).

6 Confirmation affichée. Les frais sont immédiatement applicables à tous les élèves
du niveau.

Cas d'erreur :

● Montant nul ou négatif : validation bloquante avec message d'erreur.

● Doublon (même niveau + même type + même année) : message « Ce type de frais est
déjà configuré pour ce niveau ».
● Modification après paiements existants : avertissement « La modification n'affectera
pas les paiements déjà enregistrés ».

Flow 2 — Enregistrer un paiement (US-18)

Acteur : Comptable

Étape Description
1 Le comptable accède à « Finances → Nouveau paiement ».

2 Il recherche l'élève par matricule ou nom, clique sur l'élève puis sur « Ajouter un
paiement ». Le système affiche la fiche financière : montant total dû, montant déjà
payé, solde restant.

3 Il sélectionne le type de frais concerné (si plusieurs types configurés pour le

niveau).

4 Si le type sélectionné est SCOLARITE et que des tranches sont configurées, le

système affiche la liste des tranches disponibles avec leur statut (ouverte / échue /
soldée). Le comptable sélectionne la tranche concernée.

5 Il saisit le montant versé, le mode de paiement (Espèces / Mobile Money /

Virement) et la date.

6 Pour Mobile Money / Virement : saisie obligatoire de la référence de transaction.

7 Il clique sur « Valider ». Le système vérifie : montant > 0, élève actif, frais
configurés pour son niveau.

8 Le paiement est enregistré. Le solde restant est recalculé automatiquement. Le

statut passe à PARTIEL ou SOLDE.

9 Un reçu PDF est généré automatiquement et proposé au téléchargement.

L'événement PaymentRecordedEvent est publié.

Cas d'erreur :

● Élève introuvable : message « Aucun élève correspondant à cette recherche ».

● Frais non configurés pour le niveau : blocage avec message « Veuillez d'abord
configurer les frais du niveau de cet élève ».
● Montant supérieur au solde restant : avertissement bloquant « Le montant dépasse le
solde restant. »
● Référence de transaction manquante (Mobile Money) : validation bloquante.

Flow 3 — Générer un reçu PDF (US-19)

Acteurs : Système (auto) / Comptable (manuel)

Étape Description

1 Déclenchement automatique immédiatement après l'enregistrement d'un paiement

(Flow 2, étape 9).

2 Le moteur PDF injecte les données : logo établissement, infos élève, montant payé,
 solde restant, date, mode de paiement, numéro de reçu unique (REC-ANNEE-
XXXXX), tranche concernée (si applicable).

3 Le fichier est nommé : RECU-PAY-{receipt_number}-{date}.pdf et

archivé sur le serveur.

4 L'URL du reçu est enregistrée dans le champ receipt_pdf_url de la table

payments.

5 Le comptable peut télécharger ou imprimer le reçu depuis la fiche paiement.

6 L'accès au reçu PDF est réservé aux rôles Admin et Comptable. Le parent ne
peut pas télécharger les reçus.

Contenu du reçu PDF :

Zone Contenu

En-tête Logo + nom établissement, année scolaire, numéro de reçu unique

Élève Nom, prénom, matricule, classe, niveau

Paiement Montant payé (XAF), montant total dû, solde restant, date, mode de
paiement

Transaction Référence Mobile Money / Virement (si applicable)

Signature Nom et identifiant du comptable ayant enregistré, cachet numérique

Pied de page Date de génération, mention « Document officiel — ne pas modifier »

Cas d'erreur : Erreur de génération → le paiement reste enregistré. Bouton « Regénérer

le reçu » disponible manuellement sur la fiche paiement.

Flow 4 — Consulter l'historique des paiements (US-20)

Acteurs : Admin / Comptable

Étape Description

1 Le comptable/admin accède à « Finances → Historique des paiements ».

2 Il applique les filtres souhaités : période (date début/fin), classe, niveau, statut
(SOLDE / PARTIEL / EN_ATTENTE), mode de paiement.
 3 La liste paginée s'affiche avec : matricule élève, nom, montant payé, solde restant,
statut, date, comptable.

4 Le total des montants encaissés sur la période filtrée est affiché en bas de page.

5 Il peut cliquer sur un paiement pour voir la fiche détail et accéder au reçu PDF.

6 Export Excel ou PDF disponible pour la liste filtrée.

Cas d'erreur : Aucun résultat pour les critères → message « Aucun paiement trouvé pour
ces critères ».

Flow 5 — Consulter l'état de paiement (Vue élève) (US-21)

Acteur : Parent authentifié

Étape Description

1 Le parent se connecte à son espace via Keycloak.

2 Il accède à « Finances ».

3 Finances s'affiche : montant total dû, montant déjà payé, solde restant, statut global
(badge coloré), pourcentage réglé (barre de progression).

4 Les tranches de scolarité configurées sont affichées avec leur statut (ouverte /
échue / soldée) et les montants associés.

5 La liste chronologique des versements s'affiche en dessous : date, montant, mode,

statut, tranche concernée.

6 Aucun bouton de téléchargement de reçu PDF n'est disponible pour le parent.

7. Workflow Backend (Spring Boot)

Classes & Architecture

● Entités JPA : FeeConfig, PaymentTranche, Payment

● DTOs : FeeConfigCreateDTO, FeeConfigUpdateDTO,
PaymentTrancheCreateDTO, PaymentTrancheUpdateDTO,
PaymentCreateDTO, PaymentSummaryDTO
● Services : FeeConfigService, PaymentTrancheService,
PaymentService, ReceiptPdfService
 ● Validation : @Valid + validators custom (ActiveYearCheck,
PositiveAmountValidator, TrancheSumValidator,
TrancheDateOverlapValidator)
● Événements publiés : FeeConfigCreatedEvent,
TrancheConfiguredEvent, PaymentRecordedEvent,
PaymentStatusUpdatedEvent

Endpoints REST API

Méthod Endpoint Rôle(s) Description
e

POST /api/fee-configs Comptabl Créer/configurer les

e / Admin frais d'un niveau →
FeeConfigCreated
Event

PUT /api/fee-configs/{id} Comptabl Modifier un barème

e / Admin (avec avertissement si
paiements existants)

GET /api/fee-configs Comptabl Lister tous les barèmes

e / Admin (filtre : niveau, année)

POST /api/fee-configs/{id}/ Admin Créer les tranches de

tranches scolarité pour un
barème →
TrancheConfigure
dEvent

PUT /api/fee-configs/{id}/ Admin Modifier une tranche

tranches/{trancheId} (avertissement si
paiements existants sur
cette tranche)

DELET /api/fee-configs/{id}/ Admin Supprimer une tranche

E tranches/{trancheId} (bloqué si des
paiements y sont
rattachés)

GET /api/fee-configs/{id}/ Comptabl Lister les tranches d'un

tranches e / Admin barème de scolarité

POST /api/payments Comptabl Enregistrer un paiement

e (avec tranche_id
 optionnel) →
déclenche génération
PDF +
PaymentRecordedE
vent

GET /api/payments Comptabl Historique paginé avec

e / Admin filtres (période, classe,
statut, mode)

GET /api/payments/{id} Comptabl Détail d'un paiement +

e / Admin URL du reçu PDF

POST /api/payments/{id}/ Comptabl Regénération manuelle

regenerate-pdf e / Admin du reçu PDF

GET /api/students/{id}/payment- Tous Solde financier d'un

summary rôles élève : total dû, payé,
autorisés restant, statut, tranches

GET /api/parents/me/children/ Parent Vue parent : état

{id}/payments financier d'un enfant,
liste des versements et
tranches — sans accès
aux reçus PDF

Événements Domaine publiés

● FeeConfigCreatedEvent — à la création d'un barème de frais

● TrancheConfiguredEvent — à la création ou modification d'un découpage en
tranches (Admin)
● PaymentRecordedEvent — à chaque nouveau paiement enregistré (consommé
par le module PDF)
● PaymentStatusUpdatedEvent — quand le statut passe à SOLDE

Publiés via ApplicationEventPublisher pour consommation par les

autres modules.

8. Frontend [Link]
Pages Principales
Route Rôle(s) Description
/dashboard/finances/frais Admin / Configuration des barèmes de
Comptable frais par niveau. Formulaire
ajout/édition par type de frais
+ échéance.

/dashboard/finances/frais/ Admin Gestion des tranches de

[id]/tranches scolarité pour un barème :
ajout, édition, suppression.
Validation en temps réel de la
somme et des dates.

/dashboard/finances/ Comptable Formulaire enregistrement

paiements/nouveau paiement. Recherche élève,
affichage solde, sélection
tranche (si SCOLARITE),
saisie
montant/mode/référence,
validation.

/dashboard/finances/paiements Admin / Historique paginé avec filtres

Comptable (période, classe, niveau,
statut, mode). Totaux en bas
+ export Excel/PDF.

/dashboard/finances/ Admin / Détail d'un paiement +

paiements/[id] Comptable bouton téléchargement reçu +
bouton regénérer PDF.

/dashboard/eleves/[id]/ Admin / Vue financière d'un élève :

finances Secrétaire / récapitulatif solde + tranches
Comptable + liste versements + accès
reçus.

/parent/enfants/[id]/finances Parent Vue parent : tableau de bord

financier enfant, barre de
progression, tranches, liste
versements. Aucun bouton
de téléchargement de reçu.

Interfaces UX — Détail pour le Designer

Interface Éléments UX requis

Tableau de bord Indicateurs synthèse : total encaissé du jour / mois, nombre de

financier paiements partiels en attente, accès rapide « Nouveau paiement ».
(Comptable)
Gestion des Liste des tranches existantes pour le barème sélectionné, formulaire
tranches (Admin) ajout/édition inline (libellé, montant, date début, date fin), indicateur
en temps réel de la somme restante à affecter, validation bloquante si
chevauchement ou solde non atteint.

Formulaire Champ recherche élève (autocomplete), fiche solde élève (read-only),

nouveau paiement sélecteur type de frais, sélecteur tranche (conditionnel si
SCOLARITE avec tranches configurées), saisie montant, toggle
mode paiement, champ référence (conditionnel Mobile
Money/Virement), date picker, bouton « Valider et générer reçu ».

Fiche financière Barre de progression du paiement (0–100%), badges statut colorés

élève (EN_ATTENTE=gris, PARTIEL=orange, SOLDE=vert), tableau des
tranches avec statut par tranche, tableau des versements avec icône
téléchargement par ligne.

Configuration des Liste des niveaux, pour chaque niveau : tableau des types de frais
frais avec champs montant et échéance éditables en ligne, bouton «
Ajouter un type », lien « Gérer les tranches » si type = SCOLARITE,
sauvegarde par niveau.

Vue parent Dashboard épuré : carte récapitulative (montant total / payé / restant),
(Finances) barre de progression, tableau des tranches en lecture seule (libellé,
montant, dates, statut), liste des versements en lecture seule. Aucun
bouton de téléchargement de reçu PDF.

Historique Filtres en barre latérale ou en ligne (période, classe, niveau, statut,

paiements mode), tableau paginé (20 lignes/page), ligne total collée en bas,
bouton export.

Flux UX

● Auth Keycloak → menu adapté au rôle (Comptable voit Finance, Parent voit ses
enfants uniquement)
● Comptable : bouton flottant « + Paiement » accessible depuis n'importe quelle page
Finance
● Parent / Élève : vues read-only filtrées sur leurs propres données
● Mutations via Server Actions [Link], fetches via useQuery TanStack Query
● Notifications toast (succès / erreur) après chaque action critique

9. Stratégie QA
Outils
 ● Postman / Newman — tests API
● Squash / Cypress — E2E frontend

Couverture cible

● ≥ 80% de couverture backend

● Happy paths + scénarios d'erreur : 401, 403, 422
● Tests unitaires : entités / validators / calcul solde / TrancheSumValidator /
TrancheDateOverlapValidator
● Tests d'intégration : endpoints paiement + génération PDF + endpoints tranches
● E2E flows : configuration des tranches, enregistrement paiement complet + partiel
avec tranche, génération reçu, vue parent (sans reçu)
● Scénarios edge : montant dépassant le solde, frais non configurés,
année inactive, paiement ANNULE, somme des tranches ≠ montant
total, chevauchement de dates de tranches, tentative d'accès au
reçu PDF par un parent (doit retourner 403)

10. Plan d'Action & Workflow Équipes

Jours Phase Activités

J1 – J2 📋 Review & Review wiki + refinement User Stories (PO + Devs)

Planning

J3 – J5 ⚙️Backend Impl. entités FeeConfig + Payment, services, endpoints,

génération PDF, événements — équipe backend

J6 – J9 Frontend Pages configuration frais + paiements + vue parent — équipe

frontend

J10 – 🔗 Intégration & Tests E2E + tests manuels + corrections

J12 QA

J13 – 🚀 Démo & Fix Démo sprint + correction des bugs identifiés
J14

Rituels quotidiens :

● Daily standup à 8h45 chaque matin

● GitLab MR review sous 24h
● Wiki mis à jour en continu sur GitLab

11. Aperçu User Stories — Futures Évolutions

User Stories planifiées après le core Sprint 4 :
 ● US13 — Tableau de bord financier global (revenus du mois, taux de recouvrement
par niveau)
● US14 — Relances automatiques parents (email/SMS) pour soldes impayés avant
échéance
● US15 — Annulation de paiement avec motif obligatoire et journalisation
● US16 — Rapport financier exportable par période / classe / niveau
● US17 — Support multi-devises (pour établissements internationaux)

SEKOUH — Wiki Sprint 4 — Confidentiel & Interne