piilot-pack-compta-esms 0.2.0

Piilot plugin — verticale comptabilité ESMS (cabinets-EC : production EPRD/ERRD/DM/RIA/ERCP/EPCP, M22 bis, ventilation H/D/S, contrôles annexes DGCS).

piilot-pack-compta-esms

Plugin Piilot dédié à la production complète des documents budgétaires obligatoires des ESSMS (Établissements et Services Sociaux et Médico-Sociaux) — EPRD, ERRD, DM, RIA, ERCP, EPCP — conformes aux cadres normalisés DGCS.

Table des matières

• En une phrase
• Pour qui ?
• Surface fonctionnelle v0.2
• Architecture
• Installation
• Activation per-company
• Quickstart 5 minutes
• 8 module views
• Agent IA & assistant template
• Référentiels & dépendances
• Tests & couverture
• Documentation détaillée
• Decision log clé
• Compatibilité SDK & versioning
• Hors scope v0.2 & roadmap
• Contribuer
• Licence & crédits

---

En une phrase

Permettre à un cabinet d'expertise comptable gérant des dossiers ESSMS (EHPAD, FAM, MAS, IME, ITEP, CMPP, SAD-SPASAD, etc.) de produire en moins d'une journée un EPRD ou un ERRD conforme DGCS à partir d'une balance comptable client (Pennylane / Sage / EBP / Cegid), sans saisir une seule ligne de M22 bis manuellement.

Pour qui ?

• Cabinets-EC spécialisés ESSMS qui produisent les documents budgétaires obligatoires de leurs clients (associations gestionnaires, EPS, ESSMS du secteur public).
• Directeurs financiers des organismes gestionnaires (OG) qui veulent une plateforme self-hostable plutôt qu'un SaaS DGCS-dépendant.
• Auditeurs / commissaires aux comptes qui ont besoin d'un format normalisé pour leur revue annuelle.

Surface fonctionnelle v0.2

piilot-pack-compta-esms produit l'ensemble des documents budgétaires obligatoires des ESSMS à partir des données saisies dans la plateforme Piilot :

Document	Annexe DGCS	Statut v0.2
EPRD (État Prévisionnel)	Annexe 1	✅ workflow complet + double validation ARS/CD
ERRD (État Réalisé)	Annexe 8	✅ workflow complet + affectation résultats
DM (Décision Modificative)	Annexe 1bis	✅ héritage périmètre + economy_bouleversee soft
RIA (Rapport Infra-Annuel)	Annexe 7a	✅ Synthèse résultats (D-065)
ERCP / EPCP	Annexes 11/12 (M21)	✅ secteur sanitaire + cadres SA
TPER / TER (effectifs)	Annexes 6 / 9H-J	✅ unifié type_tableau + 4 type_etablissement
Annexe 3 Bilans	PC / PNL	✅ 3 variantes coexistantes (financier + comptable PC/PNL)
Annexe 4 Activité GIR	—	✅ 6 GIR × N-4→N + :compute-theorique
Annexe 5 Financière	5A / 5C / 5D	✅ tarification ternaire / forfait soins / SAD-SPASAD
PGFP Plan financement	—	✅ 148 lignes × 8 exercices N-1 → N+6
Affectations résultats	—	✅ 4 variantes Privé_I/II × Public_I/II (D-082)
Suivi affectations	—	✅ snapshot solde_début/mouvements/solde_fin par ETS+compte
Tableau de financement	Annexe 7	✅ TF 4 colonnes ERRD / TFP 8 colonnes EPRD
Provisions	—	✅ 4 catégories c/14, c/15, c/29-59, c/13
Emprunts/Dettes	—	✅ 9 types_dette (bancaire, bail, préfinancement, etc.)
RCC Reversement Charges	—	✅ validation Σ%=100 par ligne

Contrôles intégrés : 117 contrôles (3 bloquants C-001/2/3 + 13 TER computables C-101→C-113 + 101 squelettes NA pour future extension).

Exports : XLSX format DGCS (13 onglets prioritaires) + DOCX rapport budgétaire (3 parties + 7 tableaux).

Recueil consentement RGPD : 17 fédérations canoniques + 3 lignes libres custom + durée 1_an / 5_ans / jusqu_revocation.

Assistant mapping balance D-108 : transforme une balance Pennylane / Sage / EBP / Cegid en plan comptable M22 bis avec suggestions LLM scorées (gpt-4o-mini + cache cross-tenant TTL 90j).

Architecture

Plugin Piilot composé de 2 packages dans un seul mono-repo Git :

Package	Registry	Tag	Description
piilot-pack-compta-esms	PyPI	v<version>	Backend Python — 95 endpoints, 17 migrations, 117 contrôles, 23 ratios, 13 exports XLSX, 3 parties DOCX, 9 agent tools
piilot-pack-compta-esms-ui	npm	ui-v<version>	Frontend TypeScript/React — 8 module views, 23 services, 22 hooks, ~520 clés i18n FR/EN

Les deux paquets shippent indépendamment : un hotfix frontend ne force pas un rebuild backend, et vice-versa.

Pile technique

Backend :

• Python 3.12+ · FastAPI · Pydantic v2 (extra='forbid' + Literal)
• piilot-sdk ≥ 0.7 (KB v2 PG natif, register_kb_template, bind_session)
• PostgreSQL 18 · openpyxl / python-docx pour exports
• langchain_core (StructuredTool pour agent tools) · psycopg2-binary · slowapi (rate limiting)

Frontend :

• React 19 · Vite 7 · TypeScript strict
• Pattern stack léger : useAsyncResource natif (pas React Query), useState/useReducer, apiFetch host
• Tailwind utility classes pures (pas de shadcn/ui dans cette release — v0.3)
• react-i18next FR/EN ~520 clés

Schémas DB :

• compta_esms.* (27 tables company-scoped RLS FORCE) avec triggers updated_at
• KBs plugin-owned matérialisées sous kbs.compta_esms__balance__<uuid8> via SDK create_kb
• KBs référentielles core consommées sous kbs_reference.* (PCG, M22 bis + M21, CASF, CNSA fonctions, valeur point GIR)

Flux logique Routes → Services → Repositories

HTTP request
   │
   ▼
routes/<domain>.py   ─── auth + slowapi + Pydantic validation
   │
   ▼
services/<domain>_service.py   ─── logique métier + guards (freeze, dm_perimeter, eps_scope)
   │                              ─── validations transverses (D-075 pipe char, R.314-222)
   ▼
repositories/<domain>_repo.py   ─── SQL paramétré + cursor() context manager
   │                               ─── column allowlists explicites (_COLUMNS / _INSERTABLE / _UPDATABLE)
   ▼
PostgreSQL 18 (kbs.* + kbs_reference.* + compta_esms.* + public.*)

Tous les services backend passent par piilot.sdk.db.run_in_thread pour préserver le contexte RLS thread-local entre coroutines.

Référentiels & bindings KB

Le plugin ne redéfinit jamais un plan comptable, une typologie ou un articulaire CASF (D-101). Il consomme :

kbs_reference.com_piilot_core_plan-comptable-esms__<uuid>   ─── M22 bis 2024-25 + M21 (PLT-M21)
kbs_reference.com_piilot_core_typologies-essms__<uuid>      ─── 39 typologies ESSMS (PLT-T1)
kbs_reference.com_piilot_core_cnsa-fonctions-esms__<uuid>   ─── CNSA fonctions × catégorie (PLT-44)
kbs_reference.com_piilot_core_audit-controls-esms__<uuid>   ─── 117 contrôles (PLT-43)
kbs_reference.com_piilot_core_valeur-point-gir-departemental__<uuid>  ─── PLT-VG
kbs_reference.com_piilot_core_conventions-collectives-esms__<uuid>    ─── 12 CCN

Côté company : le cabinet binde ses propres KBs (balance Pennylane materialized, journal paie SILAE, etc.) aux features du plugin via l'écran "Sources de données" (D-103). Chaque binding lie 1 feature à 1 KB + un column_mapping explicite.

Installation

Piilot SaaS (Cloud)

Ajouter la dépendance au requirements.txt du core AICockpit :

piilot-pack-compta-esms==0.2.0

Et au frontend/package.json :

"piilot-pack-compta-esms-ui": "^0.2.0"

Coolify rebuild les images. Activer le plugin pour un workspace via :

curl -X PUT \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "X-Company-Id: $COMPANY_ID" \
  https://api.piilot.ai/admin/plugins/compta_esms/activations/$COMPANY_ID

Self-hosted (docker-compose.selfhost.yml)

pip install piilot-pack-compta-esms
docker compose restart backend

L'image frontend du host bundle automatiquement le package npm si présent dans son package.json.

Dev local (mono-repo Mutagen)

# 1. Clone du mono-repo plugin dans plugins-dev/ (gitignored par AICockpit)
cd $AICOCKPIT_ROOT/workspaces/<branche>/plugins-dev
gh repo clone Kinetics-Consulting-V2/piilot-pack-compta-esms

# 2. Installer en mode éditable côté backend
cd piilot-pack-compta-esms
pip install -e ".[dev]"

# 3. Frontend : symlink déjà géré par `vite.config.ts` du host avec
# 3-tier fallback (plugins-dev/ → node_modules/ → noop shim).

Activation per-company

L'admin platform active le plugin via l'API admin (cf. ci-dessus) ou l'écran Settings → Plugins du workspace. Une fois activé :

1. Les 8 module views apparaissent dans la sidebar
2. Les routes /plugins/compta_esms/* deviennent accessibles
3. Les KBs référentielles core deviennent lisibles par les agents IA
4. La migration plugin crée les 27 tables compta_esms.* au premier boot (idempotent, RLS FORCE)
5. Les 16 features du catalog (D-103) sont seedées
6. L'agent template compta-esms-assistant-eprd-errd est upserté (UUID stable)

Quickstart 5 minutes

Pour un guide pas-à-pas complet : voir docs/USER_GUIDE.md.

# 1. Créer un Organisme Gestionnaire (OG = association loi 1901, FINESS juridique)
curl -X POST /plugins/compta_esms/orgs \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Company-Id: $COMPANY" \
  -d '{
    "raison_sociale": "Association ESMS Pilote",
    "finess_juridique": "750000000",
    "statut_juridique": "essms_prive_non_lucratif",
    "plan_comptable": "PNL"
  }'

# 2. Créer un Établissement sous l'OG
curl -X POST /plugins/compta_esms/orgs/$OG_ID/etablissements -d '{
  "raison_sociale": "EHPAD Les Ormes",
  "finess_ets": "750000001",
  "typologie": "ehpad",
  "capacite_installee": 80,
  "capacite_hp": 70,
  "capacite_uhr": 10,
  "tarification_ternaire": true
}'

# 3. Créer un exercice 2025 sous l'OG
curl -X POST /plugins/compta_esms/orgs/$OG_ID/exercices -d '{
  "annee": 2025, "millesime_m22bis": "2024-2025"
}'

# 4. Créer un ERRD 2025 brouillon (auto-CRPP D-073)
curl -X POST /plugins/compta_esms/documents -d '{
  "exercice_id": "'$EXERCICE_ID'",
  "type_document": "errd",
  "cadre_version": "#ERRDHA-2025-01#"
}'
# → renvoie {id, statut="brouillon", cr_principal_id, ...}

# 5. Exporter en XLSX format DGCS
curl -X POST /plugins/compta_esms/documents/$DOC_ID/exports/xlsx
# → renvoie {export_id, download_url, file_size}

Pour la saisie complète (binding KB → CRP lignes → contrôles → transmit → affectation), suivre le scénario complet dans docs/USER_GUIDE.md.

8 module views

Module view	Rôle	Sous-écrans clés
Documents	CRUD documents budgétaires + workflow	List + Create + Editor (Overview / CR / Contrôles / Exports)
Sources	Binding KB → feature (D-103) + assistant mapping D-108	Binding page + Wizard 4 étapes (Upload / Detect / Mapping / Materialize)
Établissements	CRUD OG + ETS avec capacités décomposées	List OG → List ETS par OG + Formulaire création
Effectifs	TPER (prévisionnel) + TER (réalisé)	Sélecteur doc + ETS + Type → Table éditable bulk-upsert
Activité	Annexe 4 GIR + :compute-theorique D-051	Sélecteur doc + ETS → Table 6 GIR × N-4→N
Annexes financières	Hub 4 tabs : Annexe5 / Bilan / PGFP / Affectations	Mini-tables read-only + équilibre check + 8 colonnes N-1→N+6
Dashboard	KPI cards + Recueil RGPD	Overview (4 KPI + 7 statuts + 5 docs récents) + RGPD
EPS sanitaire	Documents ERCP/EPCP + Plan M21	Filtre type + class_num 1-7 + recherche text

Agent IA & assistant template

Documentation détaillée : docs/AGENT_GUIDE.md.

9 tools métier propriétaires exposés au builder UI du host (StructuredTool langchain_core + bind_session) :

Tool ID	Rôle
compta_esms_compute_indicateurs	CAF, FRNG, BFR, Trésorerie pour 1 document
compta_esms_compute_ratios	15 ratios ERRD + 8 PGFP prévisionnels
compta_esms_list_controles	Liste tous les contrôles d'un document avec statut
compta_esms_explain_controle	Explication détaillée d'un contrôle (formule + seuil + valeurs observées)
compta_esms_detect_anomalies	Détection d'atypies sur ETPR, rémunérations, ratios
compta_esms_analyse_affectation_resultat	Analyse de la cohérence d'une affectation D-082
compta_esms_compare_eprd_errd	Comparaison EPRD/ERRD même exercice (écarts par section)
compta_esms_synthese_ria	Synthèse RIA (résultat N-1 + projection actualisée N)
compta_esms_suggest_workflow_transition	Suggestion next-step workflow (transmit ? affecter ? exporter ?)

Agent template compta-esms-assistant-eprd-errd (UUID stable, upsert idempotent) :

• Model : gpt-4o-mini
• Temperature : 0.2
• Scope : company
• Tools auto-injectés : les 9 ci-dessus + les 4 tools analytics core (top_n / aggregate / groupby / query_knowledge) si une KB numeric est accessible

Exemple de conversation :

User : "Compare mon ERRD 2025 et l'EPRD 2024 sur les charges d'exploitation."

Assistant : appelle compta_esms_compare_eprd_errd(exercice_id, eprd_id, errd_id), retourne un tableau d'écarts par section avec commentaire FR

Référentiels & dépendances

Type	Nom	Version
Core Piilot	piilot-sdk	>=0.7.0,<1.0.0
KB référentielle core	com.piilot.core.plan-comptable-esms	M22 bis 2024-25 + M21 (PLT-M21)
KB référentielle core	com.piilot.core.typologies-essms	39 typologies + 12 CCN (PLT-T1)
KB référentielle core	com.piilot.core.cnsa-fonctions-esms	catégories × fonctions (PLT-44)
KB référentielle core	com.piilot.core.audit-controls-esms	117 contrôles (PLT-43)
KB référentielle core	com.piilot.core.valeur-point-gir-departemental	PLT-VG
Backend deps	fastapi>=0.115, langchain-core>=0.3, psycopg2-binary>=2.9, slowapi>=0.1.9, openpyxl>=3.1, python-docx>=1.1, python-multipart>=0.0.9	—
Frontend peer	react>=19, react-dom>=19, react-i18next>=16, react-router-dom>=7	—

Tests & couverture

Métrique	Valeur
Tests backend	1645/1645 ✓
Tests frontend	175/175 ✓ (Vitest + RTL + jsdom)
Coverage backend	95.66% sources+tests (gate --cov-fail-under=80)
Coverage frontend	71.06% lines / 80.64% branches / 62.69% functions (gate thresholds.lines=70)
Repositories à 100%	28/28
Controls evaluators à 100%	8/8 (engagement L5b §7)
Migrations	17 (001→017) idempotentes
CI quality gates	ruff ✓ · black ✓ · pytest --cov-fail-under=80 ✓ · vitest --coverage ≥70% ✓

Lancer les tests :

# Backend
pip install -e ".[dev]"
pytest --cov --cov-report=term-missing --cov-fail-under=80 --ignore=tests/test_migrations_integration.py

# Frontend
cd frontend
npm ci
npx vitest run --coverage

Documentation détaillée

• CHANGELOG.md — historique des versions Keep-a-Changelog
• CLAUDE.md — guide Claude Code pour itérer dans ce repo
• docs/USER_GUIDE.md — guide utilisateur cabinet (quickstart + scénario complet ERRD)
• docs/AGENT_GUIDE.md — documentation des 9 agent tools + assistant template

Spec source (côté repo Kinetics-Consulting-V2/AICockpit, branche feature/ESMS-63) :

• docs/docs_dev/dev-package-compta-esms-v0.2/L1-schema-db.sql — schéma 24 tables
• docs/docs_dev/dev-package-compta-esms-v0.2/L2-routes-api.md — 84 endpoints REST
• docs/docs_dev/dev-package-compta-esms-v0.2/L3-mockups-ecrans.md — 15 wireframes
• docs/docs_dev/dev-package-compta-esms-v0.2/L4-composants-frontend.md — ~80 composants
• docs/docs_dev/dev-package-compta-esms-v0.2/L5b-plan-tests.md — pyramide tests
• docs/docs_dev/dev-package-compta-esms-v0.2/L5c-spec-export-xlsx.md — 32 onglets DGCS
• docs/docs_dev/dev-package-compta-esms-v0.2/L5d-spec-export-docx.md — rapport budgétaire
• docs/docs_dev/dev-package-compta-esms-v0.2/knowledge-base/11-decisions.md — 109 décisions D-001 → D-109
• docs/docs_dev/dev-package-compta-esms-v0.2/knowledge-base/15-annexe8-errd-structure.md — ERRD complet

Decision log clé

Le plan-dev compte 109 décisions actées (D-001 → D-109). Les plus structurantes pour comprendre le plugin :

Décision	Impact
D-018	Multi-établissement (1 OG → N ESMS), FINESS juridique vs géographique
D-023	Workflow ERRD brouillon → transmis → affectation_definie (pas d'APPROUVE)
D-024	Workflow EPRD : double validation ARS+CD parallèle, rejet par 1 → rejet global
D-034	Validation R.314-222 5 conditions à transition transmit (3 bloquants C-001/2/3)
D-048	Capacités triples autorisée/financée/installée + décomposition EHPAD HP/UHR/PASA/HT/AJ
D-055	Règles dures imputation : compte 65 → 100% Hébergement, compte 66 → 100% Soins
D-063	DM hérite immuablement du périmètre EPRD parent
D-066	Bilan comptable (Annexe 3) distinct du Bilan financier (Annexe 8) — 3 variantes coexistantes
D-075	Caractère | interdit dans tous les champs de saisie (validator transverse 10 models)
D-082	4 variantes Affectation : Privé_I/II / Public_I/II selon CPOM × statut juridique
D-083	Ventilation simple vs ternaire H/D/S (EHPAD)
D-085	Forfait global unique SEA (expérimentation 2026) — 4ème section "Soins et entretien autonomie"
D-086	PC vs PNL — 2 plans comptables Bilan
D-090	Recueil consentement RGPD 17 fédérations — HORS CHAMP RÉGLEMENTAIRE (option)
D-091	15 ratios financiers ERRD calculés à la volée
D-098	Format colonnes temporelles différencié Annexe 4 (N-4 → N) vs Annexe 9 (N-3 → N)
D-101	KBs core M22 bis / PCG / CASF — plugin ne redéfinit jamais
D-102	Référentiels en core, données client en company-scoped RLS
D-103	Binding KB → feature (écran "Sources de données" préalable à la production)
D-104	Sélecteur année N-1/N/N+1 contextuel
D-107	Plugin compta-ESMS structurellement autonome
D-108	Assistant mapping balance interne au plugin (KB pcg_to_m22bis + presets + LLM)
D-109	Granularité mapping = N:1 + 1:N coefficients, ventilation H/D/S découplée

Détail complet : docs/docs_dev/dev-package-compta-esms-v0.2/knowledge-base/11-decisions.md côté Kinetics-Consulting-V2/AICockpit.

Compatibilité SDK & versioning

SDK pin : piilot-sdk>=0.7.0,<1.0.0. Toute rupture SDK (major bump) requiert un nouveau major release de ce plugin. Surveiller le SDK changelog upstream.

Versioning : Semantic Versioning. Tags séparés backend (v<version>) et frontend (ui-v<version>) publiés via OIDC Trusted Publisher (PyPI + npm).

Composant	Tag git	Registry
Backend Python	v0.2.0	pypi.org/project/piilot-pack-compta-esms
Frontend TS	ui-v0.2.0	npmjs.com/package/piilot-pack-compta-esms-ui

Convention identique aux autres plugins Piilot first-party (pennylane, microsoft-365, supabase, fropendata, compta).

Hors scope v0.2 & roadmap

Item	Version cible	Raison
Annexe 5B intermédiaire	bloqué amont	Spec DGCS S10 silencieuse — plugin suit DDL = 3 valeurs (5A/5C/5D)
TPER/TER granularité salarié	v0.3	5 tables prévues plan-dev:1264-1273 vs 1 table agrégée v0.2
type_poste prefill	v0.3	Pas dans contrat features tper_effectifs/ter_effectifs
Catalogue 352 contrôles complet	v0.4	v0.2 ship 117 contrôles (KB PLT-43), reste 235 squelettes NA
Endpoints :compute forfait/GMP/valeur_point_gir	v0.3	Biblio §I disponible, à exposer en routes (~400 LOC)
Guards R.314-222 strict full wiring	v0.3	v0.2 = 3 contrôles bloquants C-001/2/3
DM economy_bouleversee enforce strict	v0.5	v0.2 = squelette soft, validate endpoint en place
Tests E2E Playwright	post-v0.2	5 scénarios spec L5b §4 — feature/ESMS-63 §AK
shadcn/ui adoption	v0.3	v0.2 = Tailwind utility classes pures

Contribuer

Voir CONTRIBUTING.md du repo (à créer). PRs bienvenues via le workflow standard Piilot :

1. Fork ou branche feature/<nom>
2. Tests verts en local : pytest --cov-fail-under=80 + cd frontend && npx vitest run --coverage
3. Lint : ruff check . && black --check . && cd frontend && npx tsc --noEmit
4. PR + review + merge squash
5. Bump version + tag via les workflows OIDC release

Pour itérer avec Claude Code : voir CLAUDE.md à la racine du repo.

Licence & crédits

Licence : Apache-2.0. Voir LICENSE.

Développé par : Kinetics Consulting V2 (SMKC59 + Bigperss) en collaboration avec les cabinets EC ESMS pilotes.

Stack open-source : remerciements aux mainteneurs de FastAPI, Pydantic, openpyxl, python-docx, React 19, Vite 7, Vitest, react-i18next, langchain-core, psycopg2.

Spec DGCS : merci aux équipes DGCS / CNSA / ARS pour la mise à disposition publique des cadres normalisés (Annexes 1 / 1bis / 3 / 4 / 5 / 5D / 6 / 7 / 7a / 8 / 9H-J / 11 / 12 sous R.314-211 / R.314-219 / R.314-223 / R.314-224 / R.314-232 / R.314-233 / R.314-242 / R.314-222 / R.314-229 / R.314-175 CASF).