ronan.quintin/Keryloo
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions

Gestion des échéances / quittances #4

New issue
Closed
opened 2025-11-03 21:28:11 +01:00 by ronan.quintin · 0 comments
ronan.quintin commented 2025-11-03 21:28:11 +01:00
Owner
Copy link

📘 Spécification fonctionnelle – Gestion des échéances, paiements et charges (Keryloo)

🎯 Objectif

Mettre en place la gestion complète des échéances de loyers, des paiements locataires, et des charges locatives, incluant :

  • la génération automatique des échéances mensuelles,
  • la gestion des paiements et du compte locataire,
  • le suivi des provisions sur charges,
  • l’enregistrement des charges réelles payées par le bailleur,
  • la régularisation annuelle des charges.

🧱 1. Modèle de données

1.1. Lease (Bail)

Représente le contrat entre un bailleur et un locataire.

Champ Type Description
id Long Identifiant unique
lessor Owner Bailleur
tenant Tenant Locataire
startDate LocalDate Date de début du bail
endDate LocalDate (nullable) Date de fin du bail
rentAmount BigDecimal Montant mensuel du loyer
chargesAmount BigDecimal Montant mensuel des charges (provision)
paymentDueDay Integer Jour du mois où le paiement est attendu (ex : 5)
status Enum (ACTIVE, TERMINATED) État du bail

1.2. RentDue (Échéance)

Représente une échéance mensuelle à payer par le locataire.

Champ Type Description
id Long Identifiant
lease Lease Référence du bail
dueDate LocalDate Date d’échéance (ex : 05/08/2024)
rentAmount BigDecimal Montant du loyer
chargesAmount BigDecimal Montant des provisions sur charges
totalAmount BigDecimal Total dû (loyer + charges)
status Enum (TO_PAY, PARTIALLY_PAID, PAID, LATE) Statut du paiement
createdAt LocalDateTime Date de création

1.3. Payment

Représente un paiement effectué par le locataire.

Champ Type Description
id Long Identifiant
lease Lease Référence du bail
paymentDate LocalDate Date du paiement
amount BigDecimal Montant payé
method String Moyen de paiement (VIREMENT, CHEQUE, ESPECES...)
comment String Commentaire libre
createdAt LocalDateTime Date d’enregistrement

1.4. PaymentAllocation

Table d’affectation facultative entre un paiement et une ou plusieurs échéances.

Champ Type Description
id Long Identifiant
payment Payment Paiement associé
rentDue RentDue Échéance associée
allocatedAmount BigDecimal Montant affecté à cette échéance

💡 Permet de savoir quelles échéances ont été payées avec quel paiement, sans imposer un lien strict.

1.5. AccountingEntry (MouvementComptable)

Représente un mouvement financier dans le compte du locataire.

Champ Type Description
id Long Identifiant
lease Lease Référence du bail
operationDate LocalDate Date de l’opération
type Enum (RENT, CHARGES_PROVISION, PAYMENT, DEPOSIT, DISCOUNT, EXPENSE, REGULARIZATION, REFUND) Type d’opération
amount BigDecimal Montant du mouvement
credit Boolean true si c’est en faveur du locataire, false sinon
comment String Commentaire descriptif
relatedPayment Payment (nullable) Paiement lié (si applicable)
relatedRentDue RentDue (nullable) Échéance liée (si applicable)

💡 Le solde du compte locataire est calculé comme la somme des mouvements (+ pour débits, − pour crédits).

1.6. RealCharge (ChargeReelle)

Représente une dépense réelle payée par le bailleur pour le logement.

Champ Type Description
id Long Identifiant
lease Lease Référence du bail
expenseDate LocalDate Date de la dépense
category String Catégorie (Eau, Électricité, Copropriété...)
amount BigDecimal Montant de la dépense
periodicity Enum (MONTHLY, QUARTERLY, ANNUAL, OCCASIONAL) Périodicité
comment String Détail ou référence facture

1.7. ChargesRegularization

Représente le bilan annuel des provisions sur charges et des dépenses réelles.

Champ Type Description
id Long Identifiant
lease Lease Référence du bail
year Integer Année concernée
totalProvisions BigDecimal Somme des provisions (charges payées via échéances)
totalRealCharges BigDecimal Somme des charges réelles du bailleur
balance BigDecimal Différence (totalProvisions - totalRealCharges)
refundToTenant Boolean true si le bailleur doit rembourser le locataire
createdAt LocalDateTime Date du calcul

⚙️ 2. Logique applicative

2.1. Génération automatique des échéances

  • Un batch planifié (Spring @Scheduled) s’exécute chaque jour.
  • Pour chaque bail actif :
    • Génère les échéances manquantes depuis la date de début jusqu’à la date courante.
    • Calcule les montants rentAmount et chargesAmount.
    • Crée une entrée RentDue avec statut TO_PAY.

2.2. Enregistrement des paiements

  • L’utilisateur saisit un paiement via l’interface.
  • Une entité Payment est créée.
  • Un mouvement comptable (AccountingEntry de type PAYMENT) est ajouté.
  • Optionnellement, le paiement est affecté à une ou plusieurs échéances (PaymentAllocation).

2.3. Gestion du compte locataire

  • Le solde est calculé à partir des AccountingEntry :

Solde = Σ(debits) - Σ(credits)

  • Un relevé de compte peut être généré par période.
  • Quand une échéance est totalement payée, son statut passe à PAID.
  • Une quittance PDF peut alors être générée et envoyée par e-mail.

2.4. Gestion des charges réelles

  • Le bailleur saisit les charges qu’il paye (eau, ordures, entretien...).
  • Chaque dépense crée une entité RealCharge.
  • Ces données sont historisées et consultables par catégorie et période.

2.5. Régularisation annuelle des charges

  • À la fin d’une année civile :
  1. Calculer la somme des provisions sur charges payées (via RentDue).
  2. Calculer la somme des charges réelles (RealCharge) sur la même période.
  3. Créer une entité ChargesRegularization :
    • Si provisions > charges réelles → remboursement au locataire.
    • Si provisions < charges réelles → complément à facturer.
  4. Générer un AccountingEntry de type REGULARIZATION.

🧮 3. Exemple fonctionnel

Date Type Description Montant Sens Solde
01/08/2024 RENT Loyer août +300 Débit +300
01/08/2024 CHARGES_PROVISION Provision charges août +100 Débit +400
05/08/2024 PAYMENT Paiement locataire −400 Crédit 0
01/09/2024 RENT Loyer septembre +300 Débit +300
01/09/2024 CHARGES_PROVISION Provision charges septembre +100 Débit +400
10/09/2024 PAYMENT Paiement locataire −400 Crédit 0
31/12/2024 REGULARIZATION Régularisation charges +50 Débit +50

→ Le locataire doit encore 50 € au bailleur à la suite de la régularisation annuelle.

🧰 4. Implémentation technique

4.1. Côté back-end (Spring Boot)

  • Création des entités JPA ci-dessus.
  • Toutes les entités sont auditées avec :
@CreatedBy
@CreatedDate
@LastModifiedBy
@LastModifiedDate
# 📘 Spécification fonctionnelle – Gestion des échéances, paiements et charges (Keryloo) ## 🎯 Objectif Mettre en place la gestion complète des **échéances de loyers**, des **paiements locataires**, et des **charges locatives**, incluant : - la génération automatique des échéances mensuelles, - la gestion des paiements et du compte locataire, - le suivi des provisions sur charges, - l’enregistrement des charges réelles payées par le bailleur, - la régularisation annuelle des charges. --- ## 🧱 1. Modèle de données ### 1.1. `Lease` (Bail) Représente le contrat entre un bailleur et un locataire. | Champ | Type | Description | |-------|------|-------------| | `id` | Long | Identifiant unique | | `lessor` | `Owner` | Bailleur | | `tenant` | `Tenant` | Locataire | | `startDate` | LocalDate | Date de début du bail | | `endDate` | LocalDate (nullable) | Date de fin du bail | | `rentAmount` | BigDecimal | Montant mensuel du loyer | | `chargesAmount` | BigDecimal | Montant mensuel des charges (provision) | | `paymentDueDay` | Integer | Jour du mois où le paiement est attendu (ex : 5) | | `status` | Enum (ACTIVE, TERMINATED) | État du bail | --- ### 1.2. `RentDue` (Échéance) Représente une échéance mensuelle à payer par le locataire. | Champ | Type | Description | |-------|------|-------------| | `id` | Long | Identifiant | | `lease` | `Lease` | Référence du bail | | `dueDate` | LocalDate | Date d’échéance (ex : 05/08/2024) | | `rentAmount` | BigDecimal | Montant du loyer | | `chargesAmount` | BigDecimal | Montant des provisions sur charges | | `totalAmount` | BigDecimal | Total dû (loyer + charges) | | `status` | Enum (TO_PAY, PARTIALLY_PAID, PAID, LATE) | Statut du paiement | | `createdAt` | LocalDateTime | Date de création | --- ### 1.3. `Payment` Représente un paiement effectué par le locataire. | Champ | Type | Description | |-------|------|-------------| | `id` | Long | Identifiant | | `lease` | `Lease` | Référence du bail | | `paymentDate` | LocalDate | Date du paiement | | `amount` | BigDecimal | Montant payé | | `method` | String | Moyen de paiement (VIREMENT, CHEQUE, ESPECES...) | | `comment` | String | Commentaire libre | | `createdAt` | LocalDateTime | Date d’enregistrement | --- ### 1.4. `PaymentAllocation` Table d’affectation facultative entre un paiement et une ou plusieurs échéances. | Champ | Type | Description | |-------|------|-------------| | `id` | Long | Identifiant | | `payment` | `Payment` | Paiement associé | | `rentDue` | `RentDue` | Échéance associée | | `allocatedAmount` | BigDecimal | Montant affecté à cette échéance | > 💡 Permet de savoir quelles échéances ont été payées avec quel paiement, sans imposer un lien strict. --- ### 1.5. `AccountingEntry` (MouvementComptable) Représente un mouvement financier dans le compte du locataire. | Champ | Type | Description | |-------|------|-------------| | `id` | Long | Identifiant | | `lease` | `Lease` | Référence du bail | | `operationDate` | LocalDate | Date de l’opération | | `type` | Enum (`RENT`, `CHARGES_PROVISION`, `PAYMENT`, `DEPOSIT`, `DISCOUNT`, `EXPENSE`, `REGULARIZATION`, `REFUND`) | Type d’opération | | `amount` | BigDecimal | Montant du mouvement | | `credit` | Boolean | `true` si c’est en faveur du locataire, `false` sinon | | `comment` | String | Commentaire descriptif | | `relatedPayment` | `Payment` (nullable) | Paiement lié (si applicable) | | `relatedRentDue` | `RentDue` (nullable) | Échéance liée (si applicable) | > 💡 Le solde du compte locataire est calculé comme la somme des mouvements (`+` pour débits, `−` pour crédits). --- ### 1.6. `RealCharge` (ChargeReelle) Représente une dépense réelle payée par le bailleur pour le logement. | Champ | Type | Description | |-------|------|-------------| | `id` | Long | Identifiant | | `lease` | `Lease` | Référence du bail | | `expenseDate` | LocalDate | Date de la dépense | | `category` | String | Catégorie (Eau, Électricité, Copropriété...) | | `amount` | BigDecimal | Montant de la dépense | | `periodicity` | Enum (MONTHLY, QUARTERLY, ANNUAL, OCCASIONAL) | Périodicité | | `comment` | String | Détail ou référence facture | --- ### 1.7. `ChargesRegularization` Représente le bilan annuel des provisions sur charges et des dépenses réelles. | Champ | Type | Description | |-------|------|-------------| | `id` | Long | Identifiant | | `lease` | `Lease` | Référence du bail | | `year` | Integer | Année concernée | | `totalProvisions` | BigDecimal | Somme des provisions (charges payées via échéances) | | `totalRealCharges` | BigDecimal | Somme des charges réelles du bailleur | | `balance` | BigDecimal | Différence (`totalProvisions - totalRealCharges`) | | `refundToTenant` | Boolean | `true` si le bailleur doit rembourser le locataire | | `createdAt` | LocalDateTime | Date du calcul | --- ## ⚙️ 2. Logique applicative ### 2.1. Génération automatique des échéances - Un batch planifié (Spring `@Scheduled`) s’exécute chaque jour. - Pour chaque bail actif : - Génère les échéances manquantes depuis la date de début jusqu’à la date courante. - Calcule les montants `rentAmount` et `chargesAmount`. - Crée une entrée `RentDue` avec statut `TO_PAY`. --- ### 2.2. Enregistrement des paiements - L’utilisateur saisit un paiement via l’interface. - Une entité `Payment` est créée. - Un mouvement comptable (`AccountingEntry` de type `PAYMENT`) est ajouté. - Optionnellement, le paiement est affecté à une ou plusieurs échéances (`PaymentAllocation`). --- ### 2.3. Gestion du compte locataire - Le **solde** est calculé à partir des `AccountingEntry` : Solde = Σ(debits) - Σ(credits) - Un **relevé de compte** peut être généré par période. - Quand une échéance est totalement payée, son statut passe à `PAID`. - Une **quittance PDF** peut alors être générée et envoyée par e-mail. --- ### 2.4. Gestion des charges réelles - Le bailleur saisit les charges qu’il paye (eau, ordures, entretien...). - Chaque dépense crée une entité `RealCharge`. - Ces données sont historisées et consultables par catégorie et période. --- ### 2.5. Régularisation annuelle des charges - À la fin d’une année civile : 1. Calculer la somme des **provisions sur charges** payées (via `RentDue`). 2. Calculer la somme des **charges réelles** (`RealCharge`) sur la même période. 3. Créer une entité `ChargesRegularization` : - Si `provisions > charges réelles` → remboursement au locataire. - Si `provisions < charges réelles` → complément à facturer. 4. Générer un `AccountingEntry` de type `REGULARIZATION`. --- ## 🧮 3. Exemple fonctionnel | Date | Type | Description | Montant | Sens | Solde | |------|------|--------------|----------|-------|--------| | 01/08/2024 | RENT | Loyer août | +300 | Débit | +300 | | 01/08/2024 | CHARGES_PROVISION | Provision charges août | +100 | Débit | +400 | | 05/08/2024 | PAYMENT | Paiement locataire | −400 | Crédit | 0 | | 01/09/2024 | RENT | Loyer septembre | +300 | Débit | +300 | | 01/09/2024 | CHARGES_PROVISION | Provision charges septembre | +100 | Débit | +400 | | 10/09/2024 | PAYMENT | Paiement locataire | −400 | Crédit | 0 | | 31/12/2024 | REGULARIZATION | Régularisation charges | +50 | Débit | +50 | > → Le locataire doit encore 50 € au bailleur à la suite de la régularisation annuelle. --- ## 🧰 4. Implémentation technique ### 4.1. Côté back-end (Spring Boot) - Création des entités JPA ci-dessus. - Toutes les entités sont **auditées** avec : ```java @CreatedBy @CreatedDate @LastModifiedBy @LastModifiedDate
ronan.quintin referenced this issue from a commit 2025-12-14 15:08:08 +01:00
#4 passage sur WSL
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: ronan.quintin/Keryloo#4
No description provided.
Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?