Annuaire

Périmètre : référentiel d'entreprises clientes/prospects, d'établissements (sites opérationnels), de personnes (contacts), enrichissement KYB via Pappers/INSEE, segmentation commerciale et géocodage.

Vocabulaire & entités

L'ancienne entité Activity (activité org-scoped rattachée à un Establishment) n'existe plus : le référentiel métier est désormais ActivityScope, un arbre porté par une société du groupe (GroupCompany) et administré dans Paramètres → Scopes d'activité. Il ne relève plus de l'annuaire — cf. 3.plateforme/2.modele-de-donnees.md.

Le modèle complet est dans docs/04-data-model.md §4. L'identité légale (SIREN/SIRET/nom/adresse) est toujours lue via Company/Establishment ; les modules CRM et Ventes ne font que référencer ces entités.

Écrans

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

• Company peut exister sans Establishment (prospect étranger ou micro-entreprise), mais un siège ou établissement principal est requis à la première commande/contrat.
• Person est rattaché à 0 ou 1 Company et 0 ou 1 Establishment.
• Suppression d'une Company interdite si Customer/Order/Invoice/LeaseContract actifs — soft delete uniquement.
• Suppression d'un Establishment interdite si des assets y sont en CURRENT_LOCATION actifs.
• Person.optInMarketing conditionne l'inclusion dans les exports Brevo (campagnes marketing).
• Pas de données RGPD-sensitives sur les personnes morales ; RGPD strict sur Person.
• enrichedAt, enrichmentSource (String?), rawEnrichment (JSONB) sur Company.
• Unicité SIREN : index UNIQUE PARTIEL WHERE "deletedAt" IS NULL (migration recyclebin_partial_unique), hors schéma Prisma. Index Prisma déclarés sur Company : (organizationId, name), (organizationId, deletedAt). Même schéma d'unicité partielle pour Establishment (SIRET) et Enseigne/Segment (code/label).

API

Toutes les routes exigent une permission annuaire.* (vérifiée côté API et UI). Les routes sont à plat : aucun préfixe /annuaire/.

Entreprises (companies)

Établissements (establishments)

Personnes (persons)

Segments (segments)

KYB (Pappers / INSEE)

Exemple de référence d'endpoint :

curl -s "$API/api/workspace/kyb/enrich?siren=$SIREN" \
  -H "Cookie: $SESSION"

{
  "company": { "name": "…", "siren": "…", "activityCode": "…" },
  "establishments": [{ "siret": "…", "city": "…" }],
  "dirigeants": [{ "fullName": "…", "role": "…" }]
}

Workflows

Enrichissement KYB

Déclencheur manuel (création d'entreprise avec SIREN)
  │
  ├─→ kyb.service.ts → getKybProvider() (sélection via KYB_PROVIDER, défaut `mock`)
  │      ├─ lookupBySiren(siren)     → KybCompany | null     (route /kyb/lookup)
  │      ├─ enrichBySiren(siren)     → company + …           (route /kyb/enrich)
  │      ├─ listEstablishments(siren)→ établissements[]      (route /kyb/establishments)
  │      └─ getDirigeants(siren)     → dirigeants[]
  │
  └─→ persistance à la création via /companies/with-enrichment
        enrichedAt = now() · enrichmentSource · rawEnrichment = payload

Le fournisseur KYB est abstrait derrière getKybProvider() et sélectionné par KYB_PROVIDER (défaut mock ; pappers en KYB_PROVIDER_MODE=live avec PAPPERS_API_TOKEN). Champs persistés sur Company : enrichedAt, enrichmentSource, rawEnrichment (JSONB), activityCode, etc.

Import multi-établissements

1. Recherche SIREN (autocomplete KYB ou saisie directe).
2. Le fournisseur renvoie la liste des établissements (/kyb/establishments).
3. Wizard de sélection : l'utilisateur coche les établissements à importer.
4. POST /kyb/import-establishment { siren, sirets? } : crée/réutilise la Company puis, par SIRET, findOrCreateEstablishmentBySiret (rapprochement SIRET, idempotent, pas de doublon). Sans sirets, seul le siège est importé.

Géocodage adresse

Establishment porte latitude/longitude (Decimal(10,7), nullables), alimentés lors de la sélection/import KYB.

Détection et merge de doublons

Règles métier

• SIREN unique par organisation via index unique partiel WHERE "deletedAt" IS NULL (les fiches soft-deleted ne bloquent pas une recréation du même SIREN).
• Validation SIREN/SIRET (Luhn) via shared/utils/siret.ts (exemption La Poste). vatNumber est une chaîne libre (≤ 20 car.), sans regex ni vérification VIES.
• Listes paginées (max 100 par page), recherche serveur avec debounce côté UI.
• Suppression : soft delete uniquement si entité référencée (voir contraintes modèle ci-dessus).
• Person.optInMarketing : seuls les contacts opt-in sont exportés vers Brevo.

Intégrations