docker-figli-compta/CLAUDE.md

figli_compta

Outil métier interne pour la SAS Figures Libres (collectif de 6 graphistes freelance, agissant comme proxy de facturation entre clients et graphistes). Remplace progressivement les tableurs .ods historiques (suivi manuel des entrées/sorties par personne).

Ce projet est séparé du dossier d'analyse comptable d'origine (/mnt/Data/bach/Documents/SAS Figures Libres/DEV_COMPTA, qui contient les fichiers .ods sources et les scripts Python d'audit). Ici, on ne travaille que sur l'outil (Drupal + Docker).

sources-compta/ (à la racine de ce dossier) est un lien symbolique local vers ce dossier DEV_COMPTA — pas versionné (chemin absolu propre à cette machine, voir .gitignore). Utile pour les futures migrations (2021-2025 pas encore faites) :

• sources-compta/compta_figli/suivi_compta_SASFigli20XX.ods : fichiers sources par année.
• sources-compta/compat_bach/ : fichiers personnels de Bachir (pour recoupement).
• sources-compta/scripts/ : scripts Python d'audit/extraction (build_bachir_full.py contient la logique d'unification des noms de clients, réutilisable/à généraliser pour la migration multi-année).
• sources-compta/tableaux/ : exports xlsx déjà produits (soldes corrigés, anomalies, etc.) — utile pour vérifier une migration après coup.

Si ce lien n'existe pas (nouvelle machine), le recréer : ln -s "/mnt/Data/bach/Documents/SAS Figures Libres/DEV_COMPTA" sources-compta.

Stack

• Drupal 11 en decoupled progressif : Drupal sert la page (nav, auth, permissions, formulaires de saisie natifs), un dashboard Vue 3 interroge JSON:API et fait tous les calculs/pivots côté client.
• Docker : mysql (mariadb), php-8.4-fpm, nginx, phpmyadmin. Structure calquée sur le projet leshed (même dossier Developer/Docker/).
• src/ est un sous-module git séparé (bachir/drupal-figli-compta.git), le dossier parent (bachir/docker-figli-compta.git) ne contient que le Docker.

Démarrer

make build && make up

• Site : http://localhost:8990 (admin/admin — à changer avant tout usage réel)
• phpMyAdmin : http://localhost:8991
• make exec_php pour un shell dans le container, vendor/bin/drush ... pour drush

Modèle de données

• Compte (taxonomie, 8 termes) : Sandrine, Maud, Ouidade, Chloé, Bachir, Valentin, EXT., EXT.WEB. (⚠️ "Provision EPAU" existait dans les tableurs historiques mais a été volontairement retiré — ne pas le réintroduire.)
• Client (taxonomie) : liste unifiée (ex. "EPAU / POPSU" et "COLLECTIF RIVAGE / OU ATTERRIR" fusionnent des noms historiquement inconsistants).
• Ligne comptable (content type) : date, type, client, montant HT/TTC, notes.
  • field_type_ligne (list_string) : entree, charge, versement, achat, hebergement (= toute sortie qui touche EXT.WEB), autre, ouverture.
• Répartition (Paragraph, multivalué sur field_repartition) : compte + montant. La somme des répartitions doit être égale au montant HT — contrôle automatique (figli_compta_ledger_node_presave + un #validate de formulaire pour un message propre) qui bloque la saisie de nouvelles lignes incohérentes.

Le flag figli_compta_ledger.skip_validation

Les données historiques migrées (2026) contiennent de vrais écarts de répartition (hérités des tableurs, préservés tels quels — on ne corrige jamais les données historiques, on les affiche). Pour importer/réassigner ce genre de ligne sans que le contrôle bloque, entourer l'opération de :

\Drupal::state()->set('figli_compta_ledger.skip_validation', TRUE);
// ... $node->save() ...
\Drupal::state()->delete('figli_compta_ledger.skip_validation');

Ce contournement ne doit jamais s'appliquer à la saisie via le formulaire normal (uniquement aux scripts d'import/migration/réassignation en masse).

Pages

• /lignes (= page d'accueil du site, configurée via system.site.page.front) : vue "tableur" de toutes les lignes comptables. Filtres (compte, client, type, année), regroupement (mois/année), colonne par compte comme dans les tableurs d'origine, colonne Écart, ligne de totaux (soldes créditeur/débiteur par compte) en pied de tableau. Les lignes en écart ont un fin liseré rouge (pas de fond plein). "+ Ajouter une ligne" ouvre le vrai formulaire Drupal dans une modale AJAX (core/drupal.dialog.ajax), pas de formulaire dupliqué en JS.
• /dashboard : vue agrégée simple (solde par compte / solde par client), page secondaire.

Les deux sont dans le module custom web/modules/custom/figli_compta_ledger/.

Pièges déjà rencontrés (pour ne pas les refaire)

1. Mode sombre Gin actif par défaut (html.gin--dark-mode). Ne jamais compter sur les CSS custom properties de Gin (--gin-bg-layer2 etc.) avec juste un fallback clair — elles ne se résolvent pas de façon fiable sur ces routes custom. Définir des couleurs explicites en local (--figli-*) + un bloc html.gin--dark-mode #figli-xxx { ... }.
2. Pagination JSON:API instable : trier uniquement par un champ non-unique (field_date_ligne) fait dupliquer/sauter des lignes entre les pages offset. Toujours ajouter drupal_internal__nid comme clé de tri secondaire, + dédupliquer par id côté client en filet de sécurité (fetchAllLignes() dans home.js/dashboard.js).
3. Bouton "Save" dans une modale jQuery UI + formulaire Paragraphs : plusieurs boutons input[type=submit] existent dans le DOM (dragdrop-mode, collapse, remove, duplicate, le vrai submit). Cibler précisément input[name="op"][value="Save"], pas le premier input[type=submit] trouvé.
4. hook_form_alter sur les formulaires de node : le base_form_id d'un node est générique (node_form), pas node_{bundle}_form. Utiliser hook_form_alter() et comparer $form_id explicitement à node_ligne_comptable_form / node_ligne_comptable_edit_form.
5. _wrapper_format pour une modale vaut drupal_modal (pas drupal_ajax) quand ouverte via data-dialog-type="modal" / Drupal.ajax({dialogType: 'modal', ...}).
6. Twig vs Vue : les deux utilisent {{ }}. Toujours envelopper le template Vue dans {% verbatim %}...{% endverbatim %} dans les fichiers .html.twig.

Migration des données historiques

suivi_compta_SASFigli2026_v2.ods (2026) a été entièrement migré (207 lignes + ouvertures depuis REPORT CLOTURE 2025), vérifié au centime près contre les totaux du fichier source. Les années 2021-2025 ne sont pas encore migrées. Les scripts Python d'extraction/unification de clients (réutilisables) sont dans DEV_COMPTA/scripts/ (autre dossier — voir build_bachir_full.py pour la logique d'unification des noms de clients, transposable).

Remotes git

• gitea-figureslibres.io:bachir/docker-figli-compta.git (parent, SSH)
• .gitmodules référence src/ en HTTPS (https://figureslibres.io/gitea/bachir/drupal-figli-compta.git) — c'est volontaire, ne pas le changer en SSH même si le remote local gitea de src/ est en SSH.