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

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 ("pappers" | "insee" | null), rawEnrichment (JSONB) sur Company.
• Index PostgreSQL : FTS gin(search), (organizationId, name), (organizationId, siren), (organizationId, postalCode).

API

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

Exemple de référence d'endpoint :

curl -s -X POST "$API/api/workspace/annuaire/companies/$ID/enrich" \
  -H "Cookie: $SESSION"

{ "id": "cmp_…", "enrichmentSource": "pappers", "enrichedAt": "2026-06-16T10:00:00.000Z" }

Workflows

Enrichissement KYB Pappers

Déclencheur (manuel / création avec SIREN / job hebdomadaire)
  │
  ├─→ pappers.service.ts → GET /entreprise?siren=...
  │      │  200 OK  → mapping Company + Establishment[] + Person[] (dirigeants)
  │      │  404 / timeout → fallback INSEE Sirene V3
  │      └─ tout échoue → enrichmentSource=null, données existantes inchangées
  │
  └─→ enrichedAt = now() · rawEnrichment = payload · audit log company.enriched

Mapping Pappers → Company : name, legalName, legalForm, activityCode, registrationDate, capitalAmount, websiteUrl, status. Établissements : créer/mettre à jour via rapprochement SIRET. Dirigeants : créer/mettre à jour Person via rapprochement nom complet.

Cache : si un appel Pappers pour ce SIREN date de moins de 7 jours → payload caché renvoyé (sauf force-refresh).

Import multi-établissements

1. Recherche SIREN (autocomplete Pappers ou saisie directe).
2. Pappers renvoie la liste des etablissements[].
3. Wizard de sélection : l'utilisateur coche les établissements à importer.
4. Pour chaque SIRET sélectionné : upsert Establishment (rapprochement SIRET, pas de doublon).
5. Géocodage asynchrone (job geocode-establishment) si lat/lng absents.

Géocodage adresse

À la création/modification d'un Establishment avec adresse complète et sans coordonnées → job geocode-establishment via MapTiler (priorité, couverture FR) ou Nominatim (fallback gratuit, throttling 1 req/s). Si échec : geocodeFailed = true, correction manuelle possible.

Détection et merge de doublons

• À la création : SIREN existant → erreur 409 avec CTA « Voir fiche existante » ; nom + ville > 80 % similarité → warning « Doublon possible ».
• Job nocturne detect-duplicates via trigrammes pg_trgm → page /workspace/annuaire/duplicates.
• Merge : choix du master, sélection champ par champ, redirection de toutes les FK, slaves marqués deletedAt + commentaire « Mergé dans X », audit log company.merged.

Règles métier

• SIREN unique par organisation (unique(organizationId, siren)).
• Validation Zod : SirenSchema (9 chiffres + Luhn), SiretSchema (14 chiffres + Luhn), VatNumberSchema (/^[A-Z]{2}\d{2,12}$/). TVA intra-UE vérifiable via VIES (async, optionnel).
• Recherche full-text PostgreSQL (tsvector GENERATED, index GIN) sur Company, Establishment, Person. Requête via websearch_to_tsquery('french', :q).
• Listes paginées (max 100 par page), search avec debounce 300 ms 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