Location (LLD/LCD)

Périmètre : cycle de vie complet du dossier de location longue durée (LLD) et courte durée (LCD) — qualification, équipements, devis fournisseurs, financement, propositions, agréments bailleurs, signature, mise en service, loyers, assurance, maintenance, suivi des prélèvements bailleur, engagements bancaires, cession de contrat à bailleur, restitution. C'est le cœur du métier Pulse.

Vocabulaire & entités

Le modèle complet est dans docs/04-data-model.md §9.

Écrans

Modèle de données (points clés)

• LeaseContract.number : séquence CLLD-YY-MM-NNN générée sous advisory lock PostgreSQL — immuable à la création.
• LeaseRentSchedule : tableau d'amortissement figé après SIGNED (sauf via avenant). La régénération est refusée si un échéancier existe déjà.
• LeaseFinancing : stocke capital, taux, PMT, VR, frais de dossier et la décomposition de marge (brute/nette/commissions partenaire/Pulse).
• LeaseRentSchedule.isIntercalary : ligne intercalaire distincte dans la 1ère facture (PMT × jours / 30).
• Cession : machine à états PROPOSED → ACCEPTED → COMPLETED, avec sorties REFUSED/CANCELED (PROPOSED peut aller vers ACCEPTED/REFUSED/CANCELED ; ACCEPTED vers COMPLETED/CANCELED). COMPLETED est irréversible. Si refinancingType = MANAGEMENT_MANDATE, un contrat miroir (isMirror = true, mirrorContractId croisé) est créé en transaction et le contrat d'origine passe CEDED.
• LeaseInsuranceSchedule / LeaseMaintenanceSchedule : une ligne par exercice civil, prorata via prorataTemporis() (FIRST/INTERMEDIATE/LAST). Une ligne SENT ou SETTLED est immuable.
• LeaseBankCommitment.outstandingHt : recalculé chaque 1er du mois (periodicAmount × remainingRentCount) par le job lease:bank-commitment-refresh.
• LeaseContract.legacyExternalRef : référence Sat&Lease conservée pour les contrats repris. replacedByContractId trace la chaîne de remplacement.
• LenderApprovalRequest soumise (SUBMITTED) ne peut pas être supprimée (audit).

API

Toutes les routes exigent une permission lease.* (vérifiée côté API et UI). Les ressources « affaire » / « contrat » sont des collections REST à tiret (lease-affairs, lease-contracts) ; les vues agrégées et le simulateur restent sous lease/.

Exemple de référence d'endpoint :

curl -s -X POST "$API/api/workspace/lease-contracts/$ID/unlock" \
  -H "Content-Type: application/json" -H "Cookie: $SESSION" \
  -d '{"reason":"Erreur de saisie du taux bailleur validée par direction"}'

{ "id": "ctr_…", "isLocked": false, "unlockedAt": "2026-06-16T10:00:00Z" }

Workflows

Cycle de vie d'une affaire LLD

QUALIFICATION
   │  (proposition financière prête)
   ▼
PROPOSAL
   │  (accord client sur principes)
   ▼
NEGOTIATION
   │  (lancement demande agrément bailleur)
   ▼
LENDER_REVIEW  ←──(refus → retour NEGOTIATION ou autre bailleur)
   │  (accord bailleur)
   ▼
CONTRACT_DRAFT
   │  (signature client + bailleur)
   ▼
SIGNED
   │  (mise en service)
   ▼
IN_USE
   ├──→ TERMINATED  (fin contrat normale ou anticipée + restitution)
   └──→ CEDED       (cédé à un bailleur)

Transitions contrôlées par la state machine lease.workflow.ts. Une affaire IN_USE ne peut plus être annulée, seulement résiliée.

Facturation des loyers

Job Nitro lease:billing (30 2 * * *) : pour chaque contrat ACTIVE ou CEDED (mandat de gestion inclus), génère 1 Invoice par LeaseRentSchedule dont dueDate ≤ today + 15j et status = PLANNED. Idempotent (invoiceId non-null → skip). 1ère facture = loyer intercalaire + frais de dossier + 1er loyer ordinaire.

Unlock & re-lock contrat

Réservé ADMIN. Raison obligatoire (≥ 20 chars) + confirmation 2-step + audit log renforcé + email automatique à la direction Pulse + re-verrouillage auto après 24 h. Task Nitro lease:contract-auto-relock schedulée 15 * * * *.

Avenant

Création avenant numéroté → PDF → signature (identique au contrat initial) → recalcul tableau d'amortissement si durée ou taux modifiés (nouveaux loyers à partir de la date effective). C'est le seul mécanisme permettant de modifier l'échéancier après SIGNED.

Cession à un bailleur

Proposition → acceptation bailleur (ACCEPTED) → émission facture de cession → création éventuelle contrat miroir → date effective → COMPLETED. Si MANAGEMENT_MANDATE : Pulse reste émetteur des facturations et responsable du suivi des prélèvements (LenderPaymentSchedule).

Facturation assurance & maintenance

Jobs lease-insurance-billing (0 3 * * *) et lease-maintenance-billing (0 4 * * *) : itèrent sur les échéances PLANNED dues → génèrent les factures → passent SENT puis SETTLED. Prorata temporis 1ère/dernière année géré par computeYearlySlices dans server/lib/finance.ts.

Pointage bancaire (3-voies)

PATCH /lender-payments/[id]/reconcile : transition ACTIVE → SETTLED ou REJECTED. En cas de rejet : statut REJECTED + notification gestionnaire. Job lease:bank-commitment-refresh (0 5 1 * *) : recalcule outstandingHt sur tous les engagements.

Signature électronique

Provider abstrait (FIXTURES / YOUSIGN / DOCUSEAL). Webhook HMAC Yousign → handleSignatureWebhook → transitions PENDING_CUSTOMER_SIGNATURE → PENDING_LENDER_SIGNATURE → ACTIVE. PDF signé + certificat eIDAS archivés dans bucket SIGNATURES_EVIDENCE (Object Lock COMPLIANCE 10 ans). Cron de rattrapage signature:archival-reconcile (45 * * * *) ré-essaie les enveloppes COMPLETED sans signedFileId.

Jalons d'affaire (AffairCheckpoint)

Les jalons matérialisent les étapes de validation d'une affaire (CE1, signature, etc.). Le mécanisme est partagé entre la Location et le CRM : un jalon (AffairCheckpoint) est polymorphe et pointe via affairModel sur une LeaseAffair ou une Opportunity (service server/services/commercial/affair-checkpoint.service.ts).

Modèle

• AffairCheckpointTemplate : étape standard configurable par organisation (code unique par org, label, position, isActive). Ciblage double : affairTypes (SALE / LEASE_LLD / LEASE_LCD / SERVICE) et natureCodes (codes OpportunityNature). Vide = template « commun » posé sur toute affaire.
• AffairCheckpoint : instance posée sur une affaire (@@unique([affairModel, affairId, templateId])), portant un status, doneAt / doneById, notes et resultRef (référence vers l'entité produite — Invoice.id, File.id…).

AffairCheckpointStatus : PENDING · IN_PROGRESS · DONE · NA · BLOCKED.

Logique

• Bootstrap incrémental & idempotent : bootstrapCheckpoints ne pose que les templates isActive applicables au périmètre résolu de l'affaire (type d'affaire + natures), sans dupliquer ni écraser les jalons déjà posés. Le périmètre d'une LeaseAffair est dérivé de son LeaseType (LLD/LCD) via le mapping server/lib/commercial/affair-type-mapping.ts ; celui d'une Opportunity de l'union des natures portées par ses lignes.
• Validation : markDone est le seul chemin vers DONE (horodate et trace le validateur) ; il refuse un jalon déjà DONE (409).
• Réaffectation : setCheckpointStatus n'autorise que PENDING / NA / BLOCKED (DONE exclu) ; quitter DONE efface doneAt / doneById pour la cohérence des compteurs.
• Toutes les mutations sont auditées (commercial.checkpoints.bootstrap, commercial.checkpoint.done, commercial.checkpoint.status).

API

Règles métier

• Un contrat ne peut être cédé qu'une seule fois (mirrorContractId anti-double cession).
• Demande d'agrément SUBMITTED non supprimable (audit trail).
• Une échéance d'assurance ou maintenance SENT/SETTLED est immuable.
• Affaire IN_USE : annulation interdite (résiliation uniquement).
• Statut affaire et statut contrat sont distincts : une affaire peut être SIGNED (workflow) pendant que le contrat est ACTIVE (lifecycle technique).
• Mandat de gestion : Pulse reste émetteur des facturations tant que ce type de refinancement est actif.
• Contrats repris de Sat&Lease : legacyExternalRef conservé, chaîne de remplacement tracée via replacedByContractId.

KPIs

Nb affaires par statut · cycle moyen Qualification → Signature · taux d'aboutissement · taux d'accord par bailleur · délai moyen agrément · exposition (capital restant dû) par bailleur · encours engagements bancaires par bailleur et BU · ratio cession / auto-portage · marge brute/nette/cession par contrat · loyers attendus M+1/M+3/M+6 · taux attestations assurance reçues · taux de rejet des prélèvements.

Notifications