Configuration & Reference

Prérequis

Arborescence du projet

RetroDoc Tagetik/
├── build.py                         ← Script de génération principal
├── rd_render_runner.py              ← Runner de rendu parallèle (ProcessPoolExecutor)
├── rd_form_parser.py                ← Parser XML forms parallèle (ProcessPoolExecutor)
├── rd_helpers.py                    ← Helpers purs partagés (decode_form_oid, etc.)
├── serve.py                         ← Serveur de prévisualisation local (file://)
├── annotate_sql.py                  ← Annotation SQL (utilitaire optionnel)
├── CLAUDE.md                        ← Guide de projet (conventions, règles UI)
├── RETRODOC_DESIGN_SYSTEM.md        ← Spécification UI/UX (lire avant tout travail UI)
│
├── annotations/                     ← Surcharges YAML par objet (descriptions, notes)
│   ├── processes.yaml
│   └── dimensions.yaml
│
├── inputs/                          ← Données sources
│   ├── processes.csv                ← ) Sorties de requêtes SQL sur la base Tagetik
│   ├── process_steps.csv            ← )   (voir dossier queries/ pour les scripts)
│   ├── dimensions.csv               ← )
│   ├── aih_dtps.csv                 ← )
│   ├── aih_datasets.csv             ← )
│   ├── aih_process_links.csv        ← )   (optionnel)
│   ├── app_setup.csv                ← )   (optionnel)
│   │
│   └── raw_schema/                  ← Exports directs depuis Tagetik
│       ├── configurazione.xlsx
│       ├── WORKBOOK - OWS.xlsx         ← ows · ows_dtp · ows_attivita · ows_operazione
│       │                                  ows_operazione_parametro · ows_abbinamento_campo
│       │                                  ows_tabella · ows_tabella_campo · ows_tabella_tipologia
│       │                                  ows_metodo_speciale · ows_metodo_speciale_parametro
│       │                                  ows_metodo_speciale_valore
│       ├── ows_dimensione.xlsx         (optionnel — dims analytiques ; séparé du workbook)
│       ├── WORKBOOK - raccolta.xlsx
│       ├── WORKBOOK - Workflow.xlsx
│       ├── WORKBOOK - ETL.xlsx
│       ├── WORKBOOK - ETL Jobs.xlsx            (optionnel)
│       ├── WORKBOOK - Forms.xlsx               (optionnel)
│       ├── WORKBOOK - CPM Dimension.xlsx       ← (peut aussi être dans data_model/)
│       ├── WORKBOOK - FST.xlsx                 ← (optionnel ; peut aussi être dans data_model/)
│       └── data_model/                         ← Variante de placement pour les dims CPM
│           ├── WORKBOOK - CPM Dimension.xlsx
│           └── WORKBOOK - FST.xlsx
│
│   └── backup_export/               ← (optionnel) Exports binaires Tagetik — fallback zip
│       ├── *.zip                    ← Un ou plusieurs zips Tagetik (.TABLE + metadata_*.txt)
│       ├── read_tagetik_export.py   ← Décodeur inclus dans le projet (Base64 → valeurs Python)
│       └── .row_cache.pkl.gz        ← (auto-généré) Cache des lignes décodées — économise ~90s/build
│
│   └── .ctx_cache/                  ← (auto-généré) Cache de contexte par page (mode --only)
│       └── *.pkl                    ← Un fichier par page ; alimenté par --only, consommé par --fast
│
├── knowledge/                       ← Documentation de référence Tagetik
├── queries/                         ← Requêtes SQL sources (PostgreSQL / Tagetik schema)
│   ├── 02_processes.sql             →  inputs/processes.csv
│   ├── 03_process_steps.sql         →  inputs/process_steps.csv
│   └── ...
├── templates/                       ← Templates Jinja2
│   ├── base.html                    ← Layout partagé (sidebar, topbar, dark mode, JS)
│   ├── style.css                    ← Design system tokens + breakpoints responsive
│   └── *.html                       ← ~40 pages spécialisées
└── output/                          ← Généré par build.py (ne pas versionner)
    ├── index.html
    ├── style.css
    ├── search_index.json
    ├── build_manifest.json          ← Présent seulement si le build est complet (crash = absent)
    ├── build_stats.js               ← Timings + refs non résolues du dernier build (chargé par index.html)
    └── *.html                       ← 968 pages HTML statiques

Procédure de mise à jour

1. Exécuter les requêtes SQL du dossier queries/ sur la base Tagetik (PostgreSQL on-prem)
2. Déposer les CSV générés dans inputs/ — encodage UTF-8 ; délimiteur , ou ; auto-détecté
3. Ré-exporter les workbooks Excel depuis Tagetik et les déposer dans inputs/raw_schema/
4. S'assurer que tous les fichiers Excel sont fermés dans Excel et que OneDrive a fini de synchroniser (sinon build.py les ignore avec un message [WARN] … is locked)
5. Lancer py build.py depuis la racine du projet — build complet en ~50s ; pour itérer sur une seule page : py build.py --only rules.html (~8s, crée un cache de contexte dans inputs/.ctx_cache/) ; puis py build.py --fast --only rules.html pour re-générer cette page seule en ~1s (charge le cache, évite tout rechargement de données)
6. Vérifier la sortie console : elle doit se terminer par ✓ No warnings — chaque warning pointe une incohérence de données ou un fichier manquant
7. Ouvrir output/index.html directement ou lancer py serve.py pour prévisualiser via http://localhost:8080

Options de build.py

Cinq flags contrôlent le build. Ils se combinent ; l'ordre n'a pas d'importance. Sans aucun flag, py build.py fait un build complet de toutes les pages (~50s avec les runners parallèles).

Combinaisons utiles

• py build.py --only rules.html — premier rendu de rules.html seule (~265s) ; amorce .ctx_cache/rules.pkl.
• py build.py --fast --only rules.html — re-rend rules.html en ~1s depuis le cache. La combinaison d'itération par défaut.
• py build.py --fast --only 'dimension_*' — re-rend toutes les pages de dimension d'un coup depuis le cache (glob).
• py build.py --clean --only 'dimension_*' — supprime les anciennes pages dimension_* puis les régénère (sans --fast : recharge les données). À utiliser après un split / renommage de pages de dimension.
• py build.py --clean — build complet propre : purge tout output/*.html et inputs/.ctx_cache/*.pkl puis régénère. Le build de référence avant livraison.

Attention : --fast ne recopie pas style.css vers output/ (seul un build complet le fait). Après une modif CSS testée en --fast, lancer un build complet pour propager la feuille de style. Le lien CSS porte un cache-buster (style.css?v=…) régénéré à chaque build complet.

Points d'attention

• Fichiers Excel verrouillés — un fichier ouvert dans Excel ou en cours de sync OneDrive est ignoré silencieusement ; la section correspondante apparaît vide dans l'output. Fermer tous les fichiers avant le build.
• Noms de feuilles — la correspondance est insensible à la casse (MAP_IMPORT et map_import sont équivalents) ; si une feuille est introuvable, build.py liste les feuilles disponibles dans le warning.
• Encodage CSV — UTF-8 obligatoire (UTF-8-sig avec BOM accepté) ; Latin-1 / Windows-1252 provoquera des caractères corrompus dans les descriptions.
• Fichiers manquants ≠ erreur fatale — chaque section est masquée gracieusement si son fichier source est absent. Aucun fichier n'est strictement bloquant ; un warning BUILD_WARNINGS signale les sections vides.
• Placement des workbooks CPM — WORKBOOK - CPM Dimension.xlsx et WORKBOOK - FST.xlsx peuvent être dans raw_schema/ ou raw_schema/data_model/ indifféremment.
• Nouvelles dimensions CPM — ajouter 3 feuilles dans le workbook : {dim}, {dim}_gerarchia, {dim}_gerarchia_abbi ou {dim}_gerarchia_abbim. Pas de modification de code nécessaire.
• Nouvelles dimensions Analytiques — déposer WORKBOOK - ed_{dim}.xlsx dans inputs/raw_schema/data_model/ (ou inputs/raw_schema/ en nommage plat ed_{dim}.xlsx). Le workbook doit contenir 3 feuilles : ed_{dim}, ed_{dim}_gerarchia, ed_{dim}_gerarchia_abbi (ou _abbim). La dimension est auto-détectée au build suivant, sans modification de code. Pour personnaliser le libellé affiché, ajouter "{DIM}": "Libellé" dans le dict _AIH_DIM_NAMES de build.py. Alternativement, si un zip dans backup_export/ contient la table DIMENSIONE_ANALITICA, les dimensions sont auto-détectées depuis la colonne ID_DIMENSIONE sans déposer de fichier Excel.
• Design system lint — build.py vérifie 7 règles CSS/HTML à chaque build (tokens indéfinis, collapse-first, hex brut en inline style, table non wrappée, budget font-size inline, et — depuis la session 37 — hex codé en dur dans style.css sans override [data-theme="dark"], qui rendrait la couleur illisible en dark mode) ; un warning de lint = régression à corriger avant livraison.
• Control Groups (CONTROLLO*) — tables CONTROLLO, CONTROLLO_CONTO_DEF, CONTROLLO_CONTO, CONTROLLO_GERARCHIA, CONTROLLO_GERARCHIA_ABBIM chargées exclusivement depuis le zip backup_export/. La section Control Groups (sidebar Dimensions) est masquée si CONTROLLO est absent ou vide. La sous-page Grouping n'est générée que si CONTROLLO_GERARCHIA contient au moins une hiérarchie.
• prospetto_xml.csv — généré hors pipeline standard (export XML Tagetik ou requête ad-hoc) en raison de sa volumétrie ; à déposer dans inputs/raw_schema/ si disponible. Auto-chargé également depuis un zip dans backup_export/ si le CSV est absent. La section détail PROSPETTO reste masquée si ni l'un ni l'autre n'est présent.
• Caches de build — deux caches auto-générés accélèrent les itérations : (1) row cache (inputs/backup_export/.row_cache.pkl.gz) — lignes zip décodées, invalidé automatiquement quand un .zip est plus récent, économise ~90s par build complet ; (2) context cache (inputs/.ctx_cache/*.pkl) — contexte Jinja par page, alimenté par --only, consommé par --fast (~1s de re-génération). Pour forcer le recalcul d'une page : supprimer son .pkl. Pour forcer la re-lecture complète du zip : supprimer .row_cache.pkl.gz.
• Zip backup export (fallback) — si un workbook ou CSV est absent, build.py cherche la table Tagetik correspondante dans tout *.zip déposé dans inputs/backup_export/ (décodé via read_tagetik_export.py). xlsx/csv ont toujours priorité ; le zip est le dernier recours. Ce mécanisme permet d'alimenter le build depuis un export Tagetik natif sans accès SQL direct. Plusieurs zips peuvent coexister — build.py parcourt tous dans l'ordre alphabétique et utilise le premier qui contient la table cherchée.

Annotations YAML

Les fichiers annotations/*.yaml permettent d'enrichir descriptions, notes et métadonnées sans modifier les sources Excel. build.py les fusionne à la génération. Tous les champs sont optionnels.

CLOSE_MONTHLY_2025:
  note: "Main monthly close cycle. Replaces legacy MAP_IMPORT_GL routine from v4."
  owner: "Group Consolidation Team"
  status: active          # active | deprecated | under-review
  last_reviewed: "2026-05"
  tags: [critical, statutory]
  known_issues: "Step 3 IC elimination takes ~45min on large periods — known perf issue."

CONTO:
  note: "5,234 active accounts. ST hierarchy used for statutory reporting."
  owner: "Group Accounting"
  status: active
  last_reviewed: "2026-05"
  known_issues: "CF hierarchy has FLAG_GENERA_FLAT=0 — use recursive CTE for tree."

Fichiers sources 4 fichier(s) — dates de modification issues du système de fichiers

Entités — couleurs et classes

Chaque entité Tagetik a une couleur dédiée. Utiliser code.{entity} pour les identifiants ; var(--c-{entity}) pour les points de couleur dans les templates.

Règle : <code class="process">CODE</code> — jamais de couleur inline sur un identifiant. Les codes form (PROSPETTO) utilisent color:var(--c-form) en foreground, sans classe ni fond coloré.

Pills — statuts et types

Règle : pill-ok/warn/danger = statuts SP (ouvert/verrouillé/vide) et états génériques. Ne pas utiliser pill-ok pour une entité — utiliser code.{entity} ou son pill dédié.

Typographie — classes de scale

Tableaux et navigation