# ZepClicExtractor

ZepClicExtractor est l'application indépendante de production des dictionnaires CSV S9C consommés par ZepClic3.

## Frontières

- L'interface, le serveur local et le lanceur restent distincts de ZepClic3.
- Le format produit est défini par `contracts/s9c-extract-v1.json`, aussi bien dans les sources que dans la distribution sous `ZepClic3_Application/Application_ZepClicExtractor/`.
- ZepClic3 conserve la lecture des organisations CSV historiques, mais cette compatibilité est uniquement entrante.
- ZepClicExtractor produit toujours le format courant complet de 18 colonnes, y compris lorsque certaines valeurs sont vides.
- Aucun `node_modules`, fichier `.runtime`, PDF métier ou configuration propre à un poste ne doit être versionné.
- Les moteurs PDF/OCR sont des adaptateurs ; les règles d'extraction ne doivent pas en dépendre directement.

## Migration initiale

Les sources historiques se trouvent actuellement dans `Bureau/S9C Extractor`. Leur import doit exclure :

- `.runtime/` et `__pycache__/` ;
- `node_modules/` ;
- `config.json`, qui contient un chemin absolu ;
- les JAR PDFBox en double.

La configuration distribuée sera reconstruite depuis `config.example.json` avec des chemins relatifs.

## Lancement

ZepClicExtractor ne démarre aucun serveur distinct. `ZepClic3_Application/ZepClicExtractor.bat` démarre ou réutilise le serveur de ZepClic3 puis ouvre `/zepclic-extractor.html` sur le port commun. Le runtime Node commun et Java sont vérifiés par l'infrastructure distribuée.

## Distribution commune

Définir `PDFBOX_JAR` vers le JAR à distribuer puis exécuter :

```powershell
npm.cmd run package:release
```

Toute distribution place à la racine opérateur le raccourci `ZepClic 3.lnk` et le script `Créer raccourci Bureau ZepClic.bat`. Le vrai lanceur `ZepClic.bat` et le lanceur avancé `ZepClicExtractor.bat` sont placés dans `ZepClic3_Application/`. Les dépendances distribuées sont centralisées sous `ZepClic3_Application/dependances/`, y compris les modules Node et les données linguistiques utilisés par l'OCR. ZepClicExtractor est installé sous `ZepClic3_Application/Application_ZepClicExtractor/`, contrats compris : l'application forme un tout autonome, ce qui permet d'en remettre le code source indépendamment du reste de ZepClic.

## Contrôle OCR des groupements

Les groupements sans décomposition textuelle et les groupes d'une ou deux fiches non-groupement intercalées entre des groupements font l'objet d'un OCR ciblé. Une décomposition reconnue reste une proposition : l'utilisateur voit un extrait de l'image avec marge, peut corriger la liste, puis doit accepter ou ignorer la proposition. Un refus ou un OCR illisible conserve une alerte de contrôle manuel.

Une décomposition OCR peut occuper plusieurs lignes. Lorsque la fiche présente `nom du groupement = décomposition`, tout ce qui précède le premier signe `=` est ignoré. Une décomposition ne peut jamais contenir un autre groupement : seuls les identifiants de ZEP ou de ZE sont admis.

Les rapprochements tolèrent les différences de ponctuation, de séparateurs et quelques lettres. Toutes les séquences numériques doivent en revanche être strictement identiques et dans le même ordre. Une référence absente peut être déclarée comme appartenant à une consigne pas encore extraite ; elle suit alors le circuit de confirmation ou de forçage du suffixe externe.

Avant l'export, les décompositions sont également contrôlées pour repérer les composants répétés, les décompositions à un seul élément, les auto-références et les cycles entre groupements. Ces anomalies restent visibles sur les lignes concernées.

Le rapport de décisions téléchargeable est distinct du CSV métier. Il recense les décisions OCR, les rapprochements, les exclusions AC/Poste, les remplacements ou conservations de CSV, les suffixes externes, les références forcées et les anomalies de décomposition acceptées.

## Traitement par lot

L'interface accepte jusqu'à vingt PDF dans un même lot logique. La concurrence est choisie manuellement de un à quatre traitements, avec deux par défaut. Un lot dont la taille, la charge mémoire estimée ou l'occupation du stockage est importante déclenche un avertissement ; l'utilisateur peut le réduire ou poursuivre explicitement.

L'affectation collective des AC précède les décisions propres à chaque document. Les validations individuelles sont ensuite présentées fichier par fichier. Chaque source conserve ses propres lignes, son rapport et son CSV : aucun CSV consolidé ni aucune archive de lot ne sont produits.

Après les validations individuelles, un contrôle croisé recherche les identifiants présents dans plusieurs PDF, les composants de décomposition résolus dans un autre document, les suffixes probablement attribués au mauvais fichier, les rapprochements de noms à chiffres identiques et les groupements employés comme composants. La recherche des décompositions utilise un index par signature afin de rester bornée sur les gros lots. Après une correction manuelle, le contrôle croisé peut être relancé sans réextraire les PDF.

Un échec reste attaché au seul fichier concerné. Les autres fichiers poursuivent leur traitement et restent exportables. Le brouillon du dernier espace de travail est conservé sans date limite jusqu'à une réinitialisation explicite. Les PDF sont enregistrés séparément de l'état des décisions afin de ne pas être réécrits à chaque sauvegarde. Un avertissement apparaît lorsque l'occupation locale atteint 1 Go.

## Réouverture d'un dictionnaire

Un `.dictionnaireZepclic` déjà produit peut être rouvert pour être corrigé à la main. Choisir une archive sans aucun PDF l'ouvre aussitôt, sans passer par « Traiter les fichiers » : son catalogue devient directement le tableau de travail, la vue se porte dessus, et le PDF embarqué est recopié dans la session pour la visionneuse et le réenregistrement. Un lot mixte reste explicite et attend le bouton, puisque l'extraction et l'ouverture s'y croisent.

Aucune analyse n'est refaite. Les identifiants de l'archive portent déjà leur suffixe : sa carte n'en propose donc pas, et aucune capacité de traitement n'est estimée pour elle. Les décompositions qu'elle contient sont tenues pour validées, puisqu'elles l'ont été au moment de son export. Le bouton d'export annonce alors ce qu'il fait vraiment — « Réenregistrer », suivi de l'identifiant du dictionnaire.

Une extraction bloque, une archive rouverte signale. Le contrôle du tableau final reste bloquant tant qu'il porte sur une extraction en cours, dont ZepClicExtractor est le producteur. Il ne peut pas l'être sur une archive rouverte, pour deux raisons : son contenu peut venir d'un autre producteur que le pipeline S9C — une migration de données héritées, par exemple, dont le vocabulaire de types est plus large que celui du contrat — et son manifeste porte des empreintes d'intégrité, qui interdisent de la corriger hors de l'outil. Un refus d'enregistrer laisserait donc l'utilisateur sans aucune issue. Les anomalies sont reportées sur les lignes qui les portent, en alertes mineures, visibles et filtrables comme les autres ; le dialogue des alertes restantes demande confirmation avant le réenregistrement.

Les consignes déployées sont listées dans l'application, avec leur nombre de fiches, leur version et leur date d'application lues au dépôt. La liste se cherche par ce que l'agent connaît de la consigne — identifiant, PDF, périmètre — plutôt que par l'arborescence du dossier partagé. Elle s'appuie sur les mêmes éclats que les consolidés : une archive inchangée n'est pas rouverte. Une archive illisible y reste visible avec sa raison, mais ne s'ouvre pas ; la cacher laisserait croire qu'elle n'est pas déployée.

Une consigne ouverte depuis cette liste se réenregistre à sa place, sans passer par le dossier des téléchargements. L'écriture reprend les garde-fous des données locales : la révision attendue interdit d'écraser une modification survenue depuis l'ouverture — le message dit alors de rouvrir — une sauvegarde horodatée doublée d'un journal rend l'opération réversible, et le remplacement transactionnel interdit de laisser un fichier à moitié écrit. Le PDF n'est pas retransmis : il est repris de l'archive visée, qui fait foi. Une archive ouverte depuis l'explorateur n'a pas de place connue où retourner et conserve le seul téléchargement.

Le dossier `ZepClic3_Application/` est exclu du balayage des archives déployées : il porte la distribution et les sauvegardes d'écriture, jamais des données. Sans cette exclusion, une sauvegarde deviendrait choisissable dans la liste, et surtout réécrivable.

La reconnaissance des groupements est la même dans le catalogue et dans le contrôle du tableau. Un type hérité tel que `Gr SSr` est un groupement pour l'un comme pour l'autre : sans cela, sa décomposition redeviendrait une anomalie à chaque réouverture.

## Préparation et correction

Le dépôt de fichiers, les réglages d'extraction, la liste des consignes déployées et la qualité du lot forment la zone de préparation. Elle se replie d'un bouton placé au-dessus du tableau, et se replie d'elle-même dès que la session ne contient que des archives rouvertes : ces réglages ne décrivent alors plus rien, et repoussaient le tableau à 1 509 pixels du haut de la page contre 622 une fois repliés. Rien n'est retiré, tout reste à un clic.

Un choix explicite l'emporte ensuite sur cette règle, jusqu'à la fin de la session seulement : une préparation repliée au démarrage donnerait une application qui semble amputée de son dépôt de fichiers.

## Saisie du tableau

Corriger un dictionnaire à la main, c'est répéter une valeur sur une colonne et rapporter un bloc préparé dans un tableur. Le menu contextuel d'une cellule recopie sa valeur vers le bas ou sur toute la colonne, et un bloc copié depuis un tableur se colle à partir de la cellule en cours. Recopie et collage ne touchent que les lignes affichées : un filtre actif ne doit pas cacher des écritures. Le collage est borné par le tableau — il n'ajoute pas de lignes — et ce qui n'a pas tenu est annoncé plutôt que perdu en silence. Les valeurs qu'une ZE impose restent verrouillées dans les deux cas.

Entrée descend d'une ligne dans la même colonne, Échap abandonne la frappe en cours et rend la valeur retenue, `Ctrl+D` recopie depuis la ligne du dessus. Chaque geste est annulable — `Ctrl+Z`, `Ctrl+Y`, ou les deux boutons au-dessus du tableau — sur les quarante derniers. L'historique appartient au tableau affiché : passer à un autre document repart de zéro.

La décomposition se saisit directement dans sa cellule, où elle est normalisée. Sur les données héritées, la correction la plus fréquente est de vider une décomposition portée par une ligne qui n'est pas un groupement ; l'éditeur reste la voie des cas qui demandent une dérogation, où il faut voir à quoi chaque composant correspond.

Sur un lot de plusieurs documents, le contrôle croisé repart une fois la main levée et non à chaque cellule : il interroge le serveur sur tout le lot, et le relancer à chaque frappe rendait la saisie saccadée.

## Données héritées IPN

Les tables héritées séparent les composants d'un groupement par des espaces, là où le format attend des `+`. Reprises telles quelles, ces listes formaient un seul composant que personne ne pouvait résoudre : mesuré sur le corpus déployé, 199 groupements sur 1 278 se retrouvaient sans aucun composant résolvable, donc vides dans ZepClic3 — ni enfants, ni cadrage, ni composants sur la minimap. La migration les découpe désormais ; l'espace est le seul caractère étranger jamais rencontré dans un composant, et un identifiant ne peut pas en contenir.

Deux types hérités décomposent sans le dire dans leur nom : `SSr` et `Sr` portent une décomposition dans 100 % des cas, quand `SECTION`, `RT`, `SEL` et `ZEO` n'en portent jamais. Ils sont donc reconnus comme des groupements par le contrôle du tableau. Leur nom reste hors du vocabulaire du contrat S9C : si la migration finit par les traduire, cette exception disparaîtra.

## Index local et remplacement d'une source

L'index local est composé d'un fragment indépendant par CSV, SVG ou calque ZepClic. Une source inchangée réutilise son fragment ; une source modifiée reconstruit uniquement le sien ; une source retirée fait disparaître complètement son fragment et les identifiants qu'il contenait. Le cache complet est remplacé atomiquement après construction.

Lorsqu'une extraction correspond à une nouvelle version d'une consigne existante, l'analyse travaille sur une vue logique qui exclut l'ancien CSV. ZepClicExtractor affiche les identifiants ajoutés et retirés ainsi que les décompositions d'autres sources affectées. Le choix de remplacement appartient à l'utilisateur. Les décisions propres à l'ancien fichier ne sont pas réutilisées pour la nouvelle version.

L'index est rafraîchi avant chaque extraction individuelle et chaque proposition de suffixe. Un fichier arrivé ultérieurement est donc contrôlé contre l'état courant de la base, sans nécessiter le redémarrage de ZepClicExtractor.

Le serveur distribué reste actif pendant les sessions longues. Une purge de sécurité retire au démarrage les PDF temporaires de plus de 24 heures laissés par une fermeture anormale ; le PDF conservé dans le brouillon permet une reprise par réimport si nécessaire.