adb-contracts
Rôle
Service de gestion du cycle de vie des contrats liés à un bien : bail (rental contract), bail délégué (rental delegate), assurance, garantie, mandat SEPA, prélèvement automatique. Très riche fonctionnellement, il combine :
- des machines d'états Spring Statemachine pour piloter les transitions (DRAFT → ACTIVE → TERMINATED, etc.),
- la génération de documents (PDF via FreeMarker + html2pdf),
- la gestion du dunning (relances impayés),
- la création de mandats SEPA ISO20022 (PAIN.008),
- des événements vers
adb-accountingpour déclencher la création de factures (call-for-rent).
Stack
| Élément | Valeur |
|---|---|
| Spring Boot | 3.1.3 |
| Java | 18 |
| Port | 8084 |
| Database | MongoDB Atlas — base adb-contracts |
| Auth | Keycloak (resource server) |
| Stack réactive | Spring WebFlux + Reactive MongoDB |
| State machines | Spring Statemachine 2.2.3 |
| html2pdf 4.0.2 + iTextPDF | |
| Templating | FreeMarker |
| Stockage | AWS S3 (templates), AWS SQS/SNS (events) |
| Version | 0.48.0-SNAPSHOT |
| Main class | fr.lifeconnect.adb.contract.AdbContractApplication |
Architecture interne
flowchart TB
subgraph Controllers["15 Controllers"]
CC[ContractController]
BCC[BankContractController]
ICC[InsuranceContractController]
GCC[GuaranteeContractController]
RACC[RentalAllowanceContractController]
SMCC[SepaMandateContractController]
DDC[DirectDebitController]
DC[DocumentController]
DnC[DunningController]
CEC[ContractEventsController]
CACC[ContractAccountingController]
CPC[ContractPersonsController]
CPaC[ContractPartsController]
TVC[TemplateValuesController]
end
subgraph StateMachines
RCSM[RentalContractStateMachine]
RDSM[RentalDelegateStateMachine]
SMM[StateMachineManager]
end
subgraph Listeners["SQS Listeners"]
L1[PartFunction → onPartModified]
L2[PersonFunction → onPersonModified]
L3[FileFunction → onFileMetaDataModified]
L4[IndexFunction → onIndexPublished]
L5[ContractFunction]
L6[AccountingFunction]
L7[DunningFunction]
end
Mongo[(adb-contracts)]
S3[(S3 templates)]
SNS[SNS topics]
Controllers --> StateMachines
Controllers --> Mongo
DC --> S3
Listeners --> Mongo
StateMachines -.publish.-> SNS
Endpoints (15 controllers)
| Controller | Path | Rôle |
|---|---|---|
ContractController | /contracts | CRUD contrats génériques |
BankContractController | /contracts/banks | Comptes bancaires liés aux contrats |
InsuranceContractController | /contracts/insurances | Contrats d'assurance |
GuaranteeContractController | /contracts/guarantee | Contrats de garantie |
RentalAllowanceContractController | /contracts/rental-allowances | Allocations logement |
SepaMandateContractController | /contracts/sepa-mandates | Mandats SEPA |
DirectDebitController | /contracts/direct-debit | Prélèvements automatiques |
DocumentController | /contracts/documents | Documents (PDF) liés aux contrats |
DunningController | /contracts/dunnings | Relances impayés |
ContractEventsController | /contracts | Événements de contrat (call-for-rent…) |
ContractAccountingController | /contracts | Vue comptable d'un contrat |
ContractPersonsController | /contracts | Personnes liées au contrat |
ContractPartsController | /contracts/parts | Parts liées au contrat |
TemplateValuesController | – | Valeurs injectées dans les templates |
ErrorDebugController | /contracts/errors | Debug |
Modèle de données
erDiagram
ContractEntity ||--o{ ContractPartEntry : "couvre"
ContractEntity ||--|| DirectDebitEntity : "prélèvement"
ContractEntity ||--o{ TemplateValuesEntity : "génère"
ContractEntity ||--o{ ProposeContractEntity : "draft de"
ContractEntity {
string _id
string type "rental / insurance / guarantee / sepa"
string state "DRAFT / ACTIVE / TERMINATED"
date startDate
date endDate
array partIds
array personIds
}
DirectDebitEntity {
string _id
string contractId
string mandateId
number amount
}
TemplateValuesEntity {
string _id
string contractId
object values
}
ProposeContractEntity {
string _id
string contractId
object proposal
}
Collections : contracts, propose_contracts, direct_debits, template_values.
Machines d'états
Deux machines principales :
- RentalContractStateMachine — pilote le cycle de vie d'un bail standard.
- RentalDelegateContractStateMachine — bail délégué (gestion locative).
Pool size : 1000 (config state-machine.pool.size).
États typiques : DRAFT, PROPOSED, SIGNED, ACTIVE, TERMINATED, CANCELLED. Événements : UPDATE, SIGN, CANCEL, TERMINATE, RENEW.
Événements
Émis (SNS)
onContractModifiedonContractUpdatedonDirectDebitProcesseddunningNoticeSent
Consommés (SQS Listeners)
onPartModified(depuisadb-parts)onPersonModified(depuisadb-persons)onFileMetaDataModified(depuisadb-files)onIndexPublished(depuisadb-utilities) → ré-indexation des loyersonAccountingEventModified(depuisadb-accounting)dunningNoticeSent(auto-listening pour orchestration)ContractsAuxiliaryAccountBalanceUpdated
Dépendances inter-services
flowchart LR
contracts[adb-contracts]
persons[adb-persons]
parts[adb-parts]
files[adb-files]
accounting[adb-accounting]
utilities[adb-utilities]
contracts -->|GET /persons| persons
contracts -->|GET /parts| parts
contracts -->|GET /files,<br/>POST /files| files
contracts -->|GET /accounting/balances,<br/>POST /accounting/entries| accounting
contracts -->|GET /utilities/i18n| utilities
parts2[adb-parts] -->|GET /contracts/sellPart| contracts
accounting2[adb-accounting] -->|GET /contracts| contracts
aggregates[adb-aggregates] -->|GET /contracts| contracts
views[adb-views] -->|GET /contracts| contracts
reports[adb-reports] -.via aggregates.-> contracts
Intégrations externes
- AWS S3 (
BUCKET_TEMPLATES) : stockage des templates FreeMarker pour les PDF. - AWS SQS/SNS : nombreuses queues
${CONTRACTS_*_QUEUE}(régioneu-west-1). - Twilio SendGrid : envoi d'emails (mandats SEPA, dunning) —
TWILIO_SENDGRID_API_KEY. - JAXB + ISO20022 : sérialisation XML des fichiers PAIN.008 pour les banques.
- html2pdf : conversion HTML → PDF pour les contrats signés.
Configuration & déploiement
Variables d'environnement clés
| Variable | Rôle |
|---|---|
MONGO_DB_URI | Connection string MongoDB |
SECURITY_ISSUER_URI / SECURITY_TOKEN_URI | Keycloak |
CLIENT_ID / CLIENT_SECRET | OAuth2 |
AWS_REGION / AWS_ACCESS_KEY / AWS_SECRET_KEY | AWS |
BUCKET_TEMPLATES | Bucket S3 des templates |
CONTRACTS_*_QUEUE | URLs des queues SQS consommées |
TWILIO_SENDGRID_API_KEY | Envoi d'emails |
Chart Helm
adb-charts/charts/services/templates/adb-contracts.yaml. Image : lifeconnect/adb-contracts.
Liens
- Code :
adb-contracts/ - State machine config :
adb-contracts/src/main/java/fr/lifeconnect/adb/contract/ - Doc fonctionnelle :
technical-epics/contracts/