@elginux/conformicheck-scoring

Algorithme open-source MIT pour matcher un profil TPE/PME francais vers les Plateformes Agreees DGFiP les plus pertinentes.

C'est le moteur de scoring qui anime le comparateur public conformicheck.fr — outil destine aux entreprises francaises pour choisir leur Plateforme Agreee (PA) en vue de la facturation electronique obligatoire (1ᵉʳ septembre 2026 / 1ᵉʳ septembre 2027).

---

Sommaire

• Pourquoi open-source
• Installation
• Usage rapide
• Criteres de scoring
• Methodologie
• Limites
• Hors scope du repository
• Roadmap
• Contribuer
• Licence
• Mainteneur

---

Pourquoi open-source

ConformiCheck est un comparateur independant. Pour que cette independance soit verifiable, l'algorithme qui calcule les recommandations est public, sous licence MIT, et c'est exactement le code execute en production sur conformicheck.fr.

Tu peux donc :

1. Auditer comment chaque PA est scoree.
2. Reproduire les calculs avec ton propre catalogue.
3. Reutiliser le moteur dans tes propres outils, gratuitement, y compris commercialement.

Le scoring est 100 % deterministe : aucune intelligence artificielle n'intervient dans le calcul. A profil identique, resultat identique. C'est aussi ce qui permet a ConformiCheck d'etre conforme a l'EU AI Act (article 50, transparence) en restant en zone "low-risk".

---

Installation

La v0.1.0 est distribuee depuis GitHub (pas encore publiee sur npm — voir Roadmap pour le passage npm).

# Depuis GitHub (recommande pour v0.1.0)
pnpm add github:elginux/conformicheck-scoring
npm install github:elginux/conformicheck-scoring
yarn add github:elginux/conformicheck-scoring

# A partir de v0.2.0 (build dist + publish npm)
# pnpm add @elginux/conformicheck-scoring

Cible : Node.js >= 22 (import attributes JSON natifs), ESM only. Aucune dependance runtime — vitest est en devDependency uniquement pour les tests.

---

Usage rapide

import {
  DEFAULT_QUESTIONS,
  mapOptionsToTags,
  matchPlatforms,
  type PAProfile,
  type QuizAnswers,
} from '@elginux/conformicheck-scoring'

// 1. Catalogue des Plateformes Agreees a evaluer.
const paProfiles: PAProfile[] = [
  {
    id: 'indy',
    name: 'Indy',
    websiteUrl: 'https://www.indy.fr/',
    pricing: { minMonth: 0, maxMonth: 49, hasFreeTier: true },
    supports: {
      statuses: ['micro', 'ei_ir', 'unipersonnelle', 'sci', 'lmnp'],
      sectors: ['b2b_services', 'liberale_autre', 'sante', '*'],
      volumes: ['vol_0', 'vol_micro', 'vol_petit', 'vol_moyen'],
      tva: {
        franchise: true,
        autoliqBtp: false,
        marge: false,
        exonerationSante: true,
        intracom: true,
      },
      support: { phone: false, chat: true, email: true, faq: true },
      integrations: ['qonto', 'stripe'],
    },
    ttmSetupDays: 3,
  },
  // ... ajoute les autres PA de ton catalogue
]

// 2a. Reponses brutes "telles que stockees par l'UI" (option.id par question).
const rawAnswers: QuizAnswers = {
  1: 'micro', // Q1 statut juridique
  2: 'solo', // Q2 effectif
  3: 'b2b_services', // Q3 secteur
  4: 'vol_micro', // Q4 volume mensuel
  5: ['client_b2b_fr'], // Q5 typologie clients (multi)
  6: ['tva_franchise'], // Q6 regimes TVA (multi)
  7: 'budget_gratuit', // Q7 budget mensuel
  8: 'outil_wordexcel', // Q8 outil actuel
  9: 'support_chat', // Q9 canal support prefere
  10: 'echeance_flou', // Q10 urgence de mise en route
}

// 2b. Traduire option.id -> tag canonique (forme attendue par le moteur).
// Cette etape est obligatoire : le moteur compare les reponses aux
// `PAProfile.supports.*` qui sont indexes par tag, pas par option.id.
const answers = mapOptionsToTags(rawAnswers, DEFAULT_QUESTIONS)

// 3. Lancement du scoring.
const results = matchPlatforms(answers, { paProfiles })
// → MatchResult[] : top 5 PA, score 0..100, raisons et avertissements

Convention importante : les reponses passees a matchPlatforms sont des tags canoniques (sas_sarl_tpe, client_b2b_fr, tva_franchise, ...). Si tu construis tes reponses a partir d'un quiz UI qui stocke des option.id (ex sas_sarl), utilise mapOptionsToTags() pour traduire avant l'appel. Si tu construis tes reponses programmatiquement (test ou batch), passe directement les tags. Voir src/types.ts et src/utils.ts.

Pour un exemple complet exécutable : voir examples/basic-usage.ts.

---

Criteres de scoring

Le score d'une PA est la somme ponderee de 10 criteres. Total des poids = 100.

#	Critere	Poids	Question quiz	Compatibilite
Q1	Statut juridique	15	Micro, EI a l'IR, SASU/EURL, SAS/SARL, liberale, SCI, LMNP, asso	exact match → 1, sinon → 0
Q2	Effectif	5	Solo, 2-9, 10-49, 50-249	solo/TPE = 1 ; PME selon PA
Q3	Secteur	10	Services B2B, retail, BTP, industrie, B2C, HCR, sante, liberale, transport	match = 1 ; generaliste = 0.7 ; sinon 0.3
Q4	Volume mensuel	10	0, 1-5, 5-20, 20-50, 50-200, 200+	match = 1, sinon 0.3
Q5	Clients (multi)	10	B2C FR, B2B FR, Chorus Pro, UE, hors UE	moyenne par client (Chorus penalise PA non-pivot)
Q6	Regime TVA (multi)	10	Franchise, autoliq BTP, marge, exo sante, intracom, standard	moyenne par regime
Q7	Budget mensuel	15	0€, 1-15€, 15-50€, 50-100€, 100+€ HT	tolerance asymetrique (free tier compatible budget paye, l'inverse non)
Q8	Outil actuel	10	Word/Excel, free SaaS, banque pro, SaaS PA, ERP, expert-comptable	bonus integration adaptee
Q9	Canal support	10	Telephone, chat, email, FAQ	phone est un dur ; les autres ponderes
Q10	Echeance	5	Urgent < juillet 2026, sept 2026, juin 2027, sept 2027, flou	filtre soft selon ttmSetupDays

Note : Q1 et Q7 portent le poids le plus eleve (15 chacun), car ce sont les criteres les plus discriminants — un statut non supporte ou un budget incompatible disqualifie quasi-mecaniquement la PA.

Pour le detail des fonctions de compatibilite et leurs valeurs exactes, voir src/scoring-criteria.ts ou la page conformicheck.fr/methodologie.

---

Methodologie

Documentation complete et a jour : conformicheck.fr/methodologie.

Ce que la page methodologie couvre :

• Source de donnees PA (DGFiP + verifications manuelles)
• Frequence de mise a jour (cron hebdomadaire + revue humaine)
• Calendrier de re-verification de chaque champ
• Procedure de signalement d'erreur

Conformite reglementaire :

• EU AI Act art. 50 : scoring deterministe, hors champ "high-risk AI"
• Publicite comparative L.122-1 a L.122-7 C.consommation : criteres objectifs et verifiables uniquement
• RGPD : aucune donnee personnelle dans l'algorithme (le quiz collecte des choix non-personnels)

---

Limites

L'algorithme retourne une orientation, pas une recommandation engageante. Concretement :

1. Le score est une agregation de criteres declares. Si l'utilisateur declare mal son profil, le score sera mal calibré.
2. Les criteres sont publics et limites. Des dimensions importantes (qualite UX, pertinence pour un metier de niche, satisfaction support) ne sont pas modelisees.
3. La decision finale appartient toujours a l'humain — utilisateur final, son expert-comptable, son conseil. Le moteur identifie des candidats serieux, il ne remplace pas un essai produit.
4. Le code est sous MIT, "AS IS" : aucune garantie de fitness for purpose.

Si tu construis un produit base sur ce package, prevois un message clair pour ton utilisateur : "ce comparateur t'oriente, il ne te conseille pas".

---

Hors scope du repository

Ce repository ne contient que l'algorithme. Les briques suivantes vivent ailleurs :

Brique	Statut
Dataset officiel des 127+ PA	Maintenu separement, voir conformicheck.fr/methodologie pour modalites d'acces
Quiz user-facing (UI, A/B tests)	Code propre a conformicheck.fr
Generation PDF du rapport personnalise	Specifique au produit user-facing
Enrichissement texte par IA (Claude)	Non publie ici — non deterministe, sort du scope MIT du moteur
Annuaire PA FactureDirectory	Produit distinct (M+3, juillet 2026)

Les fixtures de test (tests/fixtures/pa-dataset-sample.json) contiennent 5 profils didactiques suffisants pour valider l'algorithme. Elles ne reflètent pas l'integralite des donnees ConformiCheck.

---

Roadmap

v0.1.0 — initial release (avril 2026)

• Extraction de l'algorithme depuis la production conformicheck.fr
• 10 questions, ponderation 100, scoring deterministe
• Tests Vitest + 5 personas

v0.2.0 (Q3 2026, indicatif)

• Integration du schema NAF + segments entreprise (micro/TPE/PME/ETI/GE) prevu dans la spec ConformiCheck v0.5
• Breakdown enrichi : segment / sector / budget / features / maturity / ec_compat
• Filtre dur "PA suspendue" en pre-pass

v0.3.0+

• Helpers de generation de rationale en plusieurs langues
• Plug-in d'enrichissement (interface optionnelle pour brancher un LLM tiers, hors MIT)

Les versions 0.x restent pre-1.0 : breaking changes possibles entre mineures, signalees dans le CHANGELOG.md. La version 1.0 sera publiee une fois le schema NAF integre et l'API jugee stable.

---

Contribuer

Voir CONTRIBUTING.md. En resume :

• Issues et PR bienvenues sur l'algorithme.
• PR sur le dataset 127 PA : non, c'est un autre repo.
• Tests obligatoires pour toute modification de scoring.
• Code TypeScript strict, commentaires en francais.

---

Licence

MIT — Copyright (c) 2026 Laurent Jachimiak — Elginux.

Tu peux utiliser ce code dans n'importe quel projet, prive ou commercial, sans demander la permission. La seule condition est de conserver la mention de licence et de copyright.

---

Mainteneur

Laurent Jachimiak — Elginux, studio solo augmente par IA, base dans les Landes (France).

• Site : elginux.fr
• Produit : conformicheck.fr
• LinkedIn : linkedin.com/in/laurent-jachimiak
• Email : laurent@elginux.fr

---

Ce repository n'est pas un produit fini, c'est l'algorithme transparent. Le produit user-facing est sur conformicheck.fr.