Initial local backup snapshot

docs/compliance/association-directory-official-enrichment.md

@@ -0,0 +1,197 @@
+# Enrichissement officiel du bordereau d'associations
+
+## Objectif
+
+Le bordereau interne reste la source de verite.
+
+Les API externes servent uniquement a :
+
+- rechercher des mises a jour probables ;
+- comparer les informations officielles a la fiche existante ;
+- proposer des enrichissements a validation humaine.
+
+Le systeme ne doit jamais creer automatiquement une nouvelle association depuis une API externe.
+
+## Regles fonctionnelles
+
+### 1. Aucune creation automatique
+
+- une API ne peut pas inserer une nouvelle fiche dans le bordereau ;
+- seules les fiches deja presentes dans le referentiel peuvent etre enrichies ;
+- si aucune correspondance fiable n'est trouvee, aucune mise a jour n'est appliquee.
+
+### 2. Validation manuelle obligatoire
+
+- aucune donnee officielle n'est ecrite directement dans la fiche ;
+- l'admin doit toujours voir une proposition avant application ;
+- l'admin peut :
+  - valider et appliquer ;
+  - ignorer ;
+  - relancer une recherche plus tard.
+
+### 3. Bordereau = source de verite
+
+- l'annuaire public n'affiche que les donnees validees ;
+- les donnees brutes API ne sont jamais publiees directement ;
+- toute proposition doit rester tracable.
+
+## Sources actuellement exploitables
+
+### Recherche Entreprises / Sirene public
+
+Source :
+
+- `https://recherche-entreprises.api.gouv.fr/search`
+
+Usage :
+
+- recherche par nom ;
+- verification SIREN/SIRET ;
+- adresse du siege ;
+- commune ;
+- etat administratif ;
+- identifiant association si disponible.
+
+Cette source fonctionne sans workflow d'email ou validation manuelle externe.
+
+### DJEPVA / Entreprise API
+
+Source :
+
+- `https://entreprise.api.gouv.fr`
+
+Usage :
+
+- RNA ;
+- SIRET siege ;
+- statut actif/inactif ;
+- date de creation ;
+- objet ;
+- adresse ;
+- forme juridique.
+
+Condition :
+
+- necessite `ENTREPRISE_API_TOKEN`.
+
+Si le token est absent, le systeme continue de fonctionner avec la recherche publique.
+
+### HelloAsso
+
+Usage :
+
+- logo ;
+- description publique ;
+- signaux de presence publique.
+
+Regle :
+
+- aucune creation automatique ;
+- enrichissement ou proposition uniquement apres rapprochement.
+
+## Workflow admin attendu
+
+### Bouton de travail
+
+Dans l'admin, le bouton principal est :
+
+- `Rechercher des mises a jour`
+
+Il peut etre utilise :
+
+- sur une fiche du bordereau ;
+- sur une vue filtree du referentiel.
+
+### Resultat
+
+Le systeme :
+
+1. charge la fiche existante du bordereau ;
+2. interroge les sources accessibles ;
+3. compare les champs ;
+4. construit une proposition d'enrichissement ;
+5. stocke cette proposition en statut `pending`.
+
+### Validation humaine
+
+L'admin voit ensuite :
+
+- le resume de la proposition ;
+- la source ;
+- la liste des differences `Actuel / Propose`.
+
+Puis il choisit :
+
+- `Valider et appliquer`
+- `Ignorer`
+
+## Champs actuellement compares
+
+Les propositions couvrent en priorite :
+
+- RNA ;
+- SIRET ;
+- statut de l'association ;
+- date de creation ;
+- adresse ;
+- code postal ;
+- ville ;
+- statut juridique ;
+- objet de l'association.
+
+## Architecture
+
+### Table de propositions
+
+Une table dediee stocke les enrichissements proposes :
+
+- `associationDirectoryUpdateProposals`
+
+Statuts :
+
+- `pending`
+- `applied`
+- `dismissed`
+
+### Rendu admin
+
+Le module admin :
+
+- ne pousse plus directement les donnees officielles dans la fiche ;
+- affiche une carte de proposition explicite ;
+- conserve un workflow de validation metier.
+
+## Ce qui est automatique aujourd'hui
+
+- recherche des sources officielles ;
+- calcul des differences ;
+- creation ou mise a jour d'une proposition en attente ;
+- scan par fiche ;
+- scan par vue filtree.
+
+## Ce qui reste volontairement manuel
+
+- application finale sur la fiche ;
+- refus d'une proposition ;
+- arbitrage en cas de doute ;
+- futur enrichissement avec API protegees par compte, mail ou autorisation supplementaire.
+
+## Etapes suivantes recommandees
+
+### Phase 2
+
+- brancher les logos HelloAsso dans le meme schema de proposition ;
+- ajouter un filtre admin `Propositions officielles en attente` ;
+- afficher des compteurs par statut.
+
+### Phase 3
+
+- ajouter RNA / DINUM / DJEPVA complets selon les acces reels ;
+- enrichir le score de confiance ;
+- proposer des rapprochements plus fins sur dirigeants, email et telephone.
+
+### Phase 4
+
+- historiser visuellement les enrichissements acceptes ;
+- permettre une revue periodique du referentiel ;
+- produire des rapports de mise a jour pour le pilotage.