Documenter le mapping colonnes DB ↔ labels API SUIT dans le wiki

[Viczei]

Contexte métier

La base de données EGAPRO contient des dizaines de colonnes dont les noms techniques (ex: remunerationsMoyennesParTrancheAgeFemmes0) ne correspondent pas aux libellés utilisés dans l'export JSON SUIT (ex: Rem_globale_annuelle_moyenne_F) ni aux champs d'origine GIP-MDS (indicateurs A–F pré-calculés à partir de la DSN).

Aujourd'hui, les équipes DARES, le support et les nouveaux développeurs doivent reconstituer mentalement cette correspondance en lisant plusieurs fichiers TypeScript, ce qui ralentit toute intervention (debug, support, onboarding, évolutions fonctionnelles).

L'objectif est de documenter de manière traçable et publiée la correspondance colonne DB → label API SUIT → origine GIP-MDS, directement à la source (schema.ts), et de l'exposer sur le wiki via le workflow existant db-schema.yaml.

User stories

• En tant que développeur egapro, je veux voir directement dans schema.ts le label SUIT correspondant à chaque colonne, afin de comprendre immédiatement ce que représente la donnée.
• En tant que agent support / DARES, je veux consulter une page wiki à jour qui donne la correspondance DB ↔ SUIT ↔ GIP-MDS, afin de répondre aux demandes sans lire le code.
• En tant que nouveau développeur onboardé, je veux savoir d'un coup d'œil si une donnée provient du GIP-MDS ou a été saisie par l'entreprise, afin de ne pas me tromper sur son mode de calcul.

Contexte technique

Fichiers clés pour l'architect :

• Schéma DB à annoter : packages/app/src/server/db/schema.ts
• Mapping JSON SUIT : packages/app/src/modules/export/shared/apiLabels.ts (constantes INDICATOR_A_LABELS … INDICATOR_F_LABELS)
• Assemblage du payload JSON SUIT : fonction assembleDeclaration() dans packages/app/src/app/api/v1/export/declarations/route.ts
• Workflow de publication wiki : .github/workflows/db-schema.yaml (outil db-schema-toolkit)
• Page wiki cible : https://github.com/SocialGouv/egapro/wiki/Schema-Egapro-V2

Rappel métier : les indicateurs A–F sont pré-calculés par le GIP-MDS à partir des DSN. L'indicateur G est calculé par l'entreprise elle-même (pas d'origine GIP-MDS).

Décisions cadrées (Q&A PO)

#	Question	Décision
Q1	Périmètre tables	Toutes les tables de schema.ts, pas seulement celles exposées via SUIT
Q2	Portée colonnes	Uniquement les colonnes qui ont un label SUIT JSON ; les autres restent sans commentaire
Q3	Format commentaire	Préfixe TS inline // SUIT: <label> ; si la donnée provient du GIP-MDS (indicateurs A–F pré-calculés), ajouter l'origine GIP au commentaire. Format suggéré : // GIP-MDS | SUIT: <label> — format final à formaliser par l'architect
Q4	Mapping XLSX ?	Non. On ignore DECLARATION_COLUMNS / INDICATOR_G_COLUMNS (libellés XLSX) — seuls les libellés JSON SUIT (apiLabels.ts + assembleDeclaration()) sont documentés
Q5	Garde-fou CI	Aucun. Documentation one-shot, pas de test automatisé pour détecter les colonnes manquantes à l'avenir
Q6	Critère de Done	Validation visuelle par l'utilisateur sur https://github.com/SocialGouv/egapro/wiki/Schema-Egapro-V2. Si db-schema-toolkit ne rend pas correctement les commentaires, l'architect découpera en ticket(s) de remédiation (switch d'outil / post-processing) — pas de scope créé upfront pour ça

Scénarios de test

S1 — Traçabilité côté code

• Étant donné un développeur qui lit packages/app/src/server/db/schema.ts
• Quand il se positionne sur une colonne qui a un label SUIT (ex: remunerationsMoyennesParTrancheAgeFemmes0)
• Alors il voit en commentaire TS le label SUIT correspondant (ex: // SUIT: Rem_globale_annuelle_moyenne_F ou // GIP-MDS | SUIT: ...)

S2 — Publication wiki

• Étant donné que schema.ts a été annoté et mergé sur master
• Quand le workflow db-schema.yaml s'exécute
• Alors la page https://github.com/SocialGouv/egapro/wiki/Schema-Egapro-V2 est mise à jour et affiche visuellement les commentaires SUIT/GIP-MDS à côté de chaque colonne documentée

S3 — Origine GIP-MDS visible

• Étant donné une colonne qui contient une donnée pré-calculée par le GIP-MDS (indicateurs A–F)
• Quand un utilisateur consulte le wiki ou lit schema.ts
• Alors le commentaire indique explicitement l'origine GIP-MDS (ex: GIP-MDS | SUIT: ...), permettant de distinguer ces données de celles saisies par l'entreprise (indicateur G, méta-données)

S4 — Couverture exhaustive

• Étant donné l'ensemble des libellés définis dans apiLabels.ts et utilisés par assembleDeclaration()
• Quand l'architect / dev passe en revue le mapping
• Alors chaque libellé JSON SUIT présent dans le payload d'export a une colonne DB commentée correspondante (aucun label SUIT orphelin, aucune colonne SUIT non commentée)

Hors scope

• Pas de validation automatisée (pas de test CI qui détecte les colonnes SUIT manquantes à l'avenir)
• Pas de documentation des libellés XLSX (DECLARATION_COLUMNS, INDICATOR_G_COLUMNS) — seuls les libellés JSON SUIT sont couverts
• Pas de refactor de apiLabels.ts ni de assembleDeclaration() — on documente ce qui existe
• Pas d'étape designer (feature backend + docs uniquement)
• Pas de création d'un nouvel outil de rendu wiki upfront — on utilise db-schema-toolkit existant ; un éventuel switch d'outil sera un ticket séparé si la validation utilisateur échoue

Critères d'acceptation de haut niveau

L'architect découpera ces critères en tickets exécutables.

• Chaque colonne de packages/app/src/server/db/schema.ts ayant un label SUIT JSON porte un commentaire TS au format // SUIT: <label> (ou // GIP-MDS | SUIT: <label> si la donnée provient du GIP-MDS — format final à arrêter par l'architect)
• Toutes les tables de schema.ts sont passées en revue (pas seulement celles exposées via SUIT)
• Chaque libellé défini dans INDICATOR_A_LABELS … INDICATOR_F_LABELS de apiLabels.ts est associé à exactement une colonne DB commentée
• Le workflow .github/workflows/db-schema.yaml a été déclenché avec succès après le merge sur master
• La page https://github.com/SocialGouv/egapro/wiki/Schema-Egapro-V2 affiche visuellement les commentaires — validation visuelle par l'utilisateur

Note pipeline

Pas d'étape designer (feature purement backend + documentation, aucun rendu UI dans l'app). Après validation de cet epic par l'utilisateur, l'architect prend le relais pour découper en tickets exécutables par code-dev.

[Viczei]

product-owner: demande de validation

Épic rédigé sur la base du Q&A. Récapitulatif :

Scénarios PO :

• S1 — le développeur voit le label SUIT directement dans schema.ts
• S2 — la page wiki Schema-Egapro-V2 est mise à jour après le workflow db-schema.yaml
• S3 — l'origine GIP-MDS est visible dans le commentaire pour les indicateurs A–F
• S4 — couverture exhaustive : chaque label SUIT a une colonne DB commentée
• S5 — pas de régression (pnpm typecheck / lint:check / test verts)

Décisions cadrées :

• Toutes les tables de schema.ts (pas seulement SUIT)
• Uniquement les colonnes avec un label SUIT sont commentées
• Format suggéré : // SUIT: <label> ou // GIP-MDS | SUIT: <label> — format final à arrêter par l'architect
• Libellés XLSX ignorés (JSON SUIT uniquement)
• Pas de garde-fou CI
• Done = validation visuelle de la page wiki par l'utilisateur

Hors scope : étape designer (feature backend + docs), validation automatisée, documentation XLSX, refactor du mapping.

Pipeline suivant : pas de designer, l'architect prend le relais après validation.

Merci de valider ou demander des ajustements — je ne passe l'epic en To Do qu'après validation explicite.

[Viczei]

Suppression du scénario S5 ("Absence d'effet de bord") — redondant avec les critères d'acceptation standards des tickets (typecheck, lint, tests sont déjà dans le format ticket par défaut).

[Viczei]

[Validation utilisateur] Epic validé — prêt pour dispatch par l'architect.

[Viczei]

architect: proposition de découpage — demande de validation

Analyse de l'epic + exploration du code (schema.ts, apiLabels.ts, fetchDeclarations.ts::assembleDeclaration, db-schema.yaml) + inspection du binaire db-schema-toolkit@1.1.13 utilisé par le workflow wiki.

Découverte critique à signaler

Le parser Drizzle de db-schema-toolkit@1.1.13 supprime explicitement tous les commentaires TS avant de parser le fichier (lignes 46, 1192-1193 du dist :

content = content.replace(/\/\/.*$/gm, "");
content = content.replace(/\/\*[\s\S]*?\*\//g, "");

). Le schéma interne de l'outil contient bien un champ comment sur les colonnes (z.string().optional()), mais il n'est populé qu'à partir de DBML Note: ou SQL COMMENT ON COLUMN — jamais depuis des commentaires TS. De plus, le rendu Markdown (exportDiagramToMarkdown) ne produit aucune colonne de description dans la table des champs — il imprime uniquement name | type | nullable | pk | unique | default.

Conséquence : l'annotation TS (// SUIT: ... ou // GIP-MDS | SUIT: ...) en l'état n'apparaîtra pas sur la page wiki. Le scénario S1 (lecture directe dans schema.ts) sera satisfait, S2 (publication wiki) ne le sera pas avec l'outil actuel. Le scénario S3 (origine GIP-MDS visible) est satisfait uniquement côté code.

Conformément à la décision Q6 de l'epic ("pas de scope créé upfront pour un switch d'outil / post-processing"), je ne crée pas de ticket de remédiation upfront. Un ticket de remédiation sera ouvert après validation utilisateur de la page wiki si le rendu est insuffisant.

Format de commentaire retenu

• Colonne pré-calculée par le GIP-MDS (indicateurs A–F sur table declarations) : // GIP-MDS | SUIT: <label>
• Colonne saisie par l'entreprise ou métadonnée (indicateur G, identité, CSE, files) : // SUIT: <label>

Justification : un seul format, préfixe GIP-MDS avant SUIT pour faire apparaître l'origine en premier à la lecture, pipe comme séparateur lisible, label JSON SUIT copié verbatim depuis apiLabels.ts / assembleDeclaration().

Tickets proposés

#	Titre	Table(s)	Scénarios	Dépend de
T1	chore(schema): annotate indicators A–F columns with GIP-MDS + SUIT labels	declarations (indicateurs A–F uniquement)	S1, S3, S4	—
T2	chore(schema): annotate non-GIP SUIT-exposed columns (identity, declarant, CSE, files, indicator G)	declarations (hors A–F), companies, users, cseOpinions, files, jobCategories, employeeCategories	S1, S4	—
T3	chore(schema): trigger db-schema wiki workflow and validate rendering	N/A (workflow dispatch + validation visuelle)	S2	#T1, #T2

Notes sur le découpage :

• T1 et T2 sont indépendants (pas de cycle) et peuvent être exécutés en parallèle par deux code-dev. Ils touchent la même table declarations mais sur des lignes disjointes — une merge sera mécanique.
• T3 dépend des deux pour déclencher le workflow après merge sur master.
• Aucun ticket marqué complexe : le travail d'annotation est mécanique (lecture du mapping dans apiLabels.ts et assembleDeclaration(), réécriture des lignes TS avec le préfixe correct). Sonnet largement suffisant.
• Aucune section Requires services (pas besoin de clamavd etc.).
• Aucune section Références visuelles (feature non-UI).

Couverture par table (pour aligner sur S4)

T1 couvre exactement ces colonnes de declarations (indicateurs A–F, tous GIP-MDS | SUIT:):

• A : indicatorAAnnualWomen/Men, indicatorAHourlyWomen/Men
• B : indicatorBAnnualWomen/Men, indicatorBHourlyWomen/Men
• C : indicatorCAnnualWomen/Men, indicatorCHourlyWomen/Men
• D : indicatorDAnnualWomen/Men, indicatorDHourlyWomen/Men
• E : indicatorEWomen/Men
• F : 4 thresholds annual + 4 thresholds hourly + 8 women counts + 8 men counts (labels composites calculés dans buildIndicators())

T2 couvre :

• declarations hors A–F : siren, year, status, compliancePath, totalWomen/Men, secondDeclarationStatus, secondDeclReferencePeriodStart/End, createdAt, updatedAt
• companies : siren (Raison_sociale → name), name, workforce, nafCode, address, hasCse
• users (déclarant) : firstName, lastName, email, phone
• cseOpinions : declarationNumber, type, opinion, opinionDate
• files : id, fileName, uploadedAt, type (cse vs joint_evaluation)
• jobCategories : name (→ Nom_categorie), detail (→ Detail_categorie)
• employeeCategories (indicateur G calculé par l'entreprise) : womenCount, menCount, annualBaseWomen/Men, annualVariableWomen/Men, hourlyBaseWomen/Men, hourlyVariableWomen/Men

Colonnes explicitement non commentées (pas de label SUIT JSON, conformément à Q2) : tout gipMdsData.* (non exposé via SUIT), users.id, users.isAdmin, users.emailVerified, toutes les colonnes campaignDeadlines, globalSettings, adminImpersonationEvents, referents, exports, userCompanies, tables techniques d'index, etc.

Prochaine étape

Si ce découpage est validé, je crée les 3 sub-issues avec le type Task, statut To Do, liées à l'epic #3308, avec les sections Depends on correctement renseignées (T3 dépend de T1 + T2).

Merci de confirmer ou demander des ajustements.