CRM

Périmètre : pipeline commercial (« PAC » — Plan d'Action Commerciale), prospection (KYB), opportunités, actions commerciales (appels Aircall, emails, RDV, démos, visites), classeurs, reporting & KPI, cotation client (cf. domaine Rating). La référence d'affaire est le point d'entrée du suivi.

Vocabulaire & entités

Le modèle complet est dans docs/04-data-model.md §7. Le prospect ne porte que des données de prospection ; l'identité (SIREN/SIRET/nom/adresse) se lit via la relation establishment.

Écrans

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

• Opportunity.amountHt est dérivé : somme des OpportunityLine (× quantité, net de remise), recalculé à chaque mutation de ligne. Jamais saisi à la main.
• weightedAmountHt = amountHt × probability / 100 (recalculé aux transitions).
• EstablishmentProspect.establishmentId est NOT NULL : un prospect existe toujours via un établissement de l'annuaire (un seul prospect actif par établissement — dédup service, 409 PROSPECT_ALREADY_EXISTS).
• ProspectAction : multi-assignés (ProspectActionAssignee), multi-contacts (ProspectActionContact), rattachée à une ligne d'opportunité (opportunityLineId), statut ActionStatus, origine ActionOrigin.

API

Toutes les routes exigent une permission crm.* (vérifiée côté API et UI).

Exemple de référence d'endpoint :

curl -s -X POST "$API/api/workspace/crm/opportunities/$ID/change-stage" \
  -H "Content-Type: application/json" -H "Cookie: $SESSION" \
  -d '{"stageId":"qualification","memoSummary":"Budget confirmé"}'

{ "id": "opp_…", "stage": "QUALIFICATION", "probability": 40, "weightedAmountHt": 12000 }

Workflows

Pipeline commercial standard

PROSPECT → QUALIFICATION → PROPOSAL → NEGOTIATION
   ├──→ CLOSED_WON  → conversion LeaseAffair ou contrat direct
   └──→ CLOSED_LOST → motif de perte obligatoire (liste fermée)

À chaque transition : recalcul probability + weightedAmountHt, mise à jour caMaturity, audit log, notification owner si réaffectation.

Autres workflows

• Conversion opportunité → affaire LLD : wizard depuis la fiche (un seul LeaseAffair par Opportunity, FK unique anti double conversion).
• Sync Aircall : webhook HMAC call.* → CallLog, matching contact E.164, action « à rappeler » sur appel manqué entrant.
• Enrichissement Google Places (hors budget IA) : job crm:prospect-place-enrich remplit phone/website/openingHours vides — jamais d'écrasement.
• Détection d'opportunités stagnantes : cron crm:stagnance (0 7 * * *) — alerte owner > 30j, manager > 60j sans activité.

Règles métier

• Opportunity.number : séquence par organisation, immuable, posée à la création.
• Mémo de synthèse obligatoire avant tout changement d'étape.
• CLOSED_LOST → lossReasonId requis (motif de la liste fermée).
• Conversion en LeaseAffair : un seul par opportunité.
• Suppression interdite si LeaseAffair ou Quote liés (soft delete uniquement).

KPIs

Taux de conversion par étape · cycle moyen Qualification → clôture · taux Won · pipeline coverage · CA par source · top raisons de perte. Détail des états dans le module Reporting CRM et la doc utilisateur.