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. COMPLETED est irréversible. Si refinancingType = MANAGEMENT_MANDATE, un contrat miroir (isMirror = true, mirrorContractId croisé) est créé en transaction.
• 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).

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.

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