« Info::pcGrudGen README » : différence entre les versions

De wiki_pcwiki2
Aller à la navigationAller à la recherche
Aucun résumé des modifications
Aucun résumé des modifications
Ligne 400 : Ligne 400 :
CREATE TABLE myTable1 (
CREATE TABLE myTable1 (
     id        SERIAL PRIMARY KEY,
     id        SERIAL PRIMARY KEY,
     '''strChampX''' VARCHAR(120) NOT NULL      -- colonne affichée dans le dropdown
     strChampX VARCHAR(120) NOT NULL      -- colonne affichée dans le dropdown
);
);


CREATE TABLE myTable2 (
CREATE TABLE myTable2 (
     id                    SERIAL PRIMARY KEY,
     id                    SERIAL PRIMARY KEY,
     '''fk_myTable1_strChampX''' INTEGER REFERENCES myTable1(id),  -- clé étrangère
     fk_myTable1_strChampX INTEGER REFERENCES myTable1(id),  -- clé étrangère
     strLibelle            VARCHAR(120)
     strLibelle            VARCHAR(120)
);
);

Version du 2 juin 2026 à 06:55

KEYWORDS: CRUDGEN, PCCRUDGEN

Le 02/06/2026:
= pcCrudGen (APSI.crudgen) =

Générateur de CRUD expert — Debian / C++17

Cette documentation est disponible en trois formats (contenu identique) :

  • pcCrudGen.pcwiki — MediaWiki 1.34 (ce fichier)
  • pcCrudGen.md — Markdown
  • pcCrudGen.html — HTML autonome (ouvrable dans un navigateur)

pcCrudGen lit le schéma d'une base de données existante et génère automatiquement une application web CRUD complète : contrôleurs CGI compilés (C++), pages HTML/PHP, JavaScript (grilles Tabulator), diagramme ERD interactif et pages de documentation. L'outil est piloté par un simple fichier config.json et un dictionnaire de métadonnées metadata.cfg.

Le binaire produit s'appelle crudgen.

Principe général

Le générateur applique le pipeline suivant :

  1. Lecture de config.json (connexion, chemins, site cible).
  2. Connexion au SGBD et introspection du schéma via
 INFORMATION_SCHEMA (tables, colonnes, types, clés primaires,
 clés étrangères).
  1. Chargement du dictionnaire metadata.cfg (titres, infobulles,
 options d'affichage par colonne).
  1. Génération table par table : sources C++ des contrôleurs, compilation
 en binaires, JS Tabulator, pages HTML/PHP, wrappers CGI bash.
  1. Génération des pages transversales : diagramme ERD, page « About », page
 « Description » des relations.
  1. Déploiement vers le web_root du site et création d'un paquet
 exportable.

L'orchestration est assurée par la classe Generator (Generator::generate()), qui délègue à des générateurs spécialisés (ControllerGenerator, JsGenerator, HtmlGenerator, DiagramGenerator, etc.).

SGBD supportés

L'accès est abstrait derrière l'interface ClassIDatabase, instanciée par ClassDatabaseFactory selon le champ type de la configuration :

Type (config.json) Classe État
postgresql ClassPostgreSQL Cible principale
mariadb ClassMariaDB Supporté
sqlite ClassSQLite Supporté
mongodb ClassMongoDB Expérimental

Configuration

config.json

Fichier de configuration principal. Exemple :

{
  "database": {
    "type": "postgresql",
    "postgresql": {
      "host": "127.0.0.1",
      "port": 6432,
      "user": "postgres",
      "password": "fergusonN11",
      "name": "tld2"
    }
  },
  "site": {
    "server":   "ovh1.pcstreet.org",
    "base_url": "https://tld2.ovh1.pcstreet.org",
    "web_root": "/var/www/html/tld2.ovh1.pcstreet.org"
  },
  "paths": {
    "generated_src":   "GENERATED/controllers",
    "web_controllers": "controllers",
    "web_dir":         "web",
    "html_dir":        "html"
  },
  "cgi": {
    "cgi_bin_dir": "/var/www/html/tld2.ovh1.pcstreet.org/cgi-bin"
  }
}
Clé Rôle
database.type SGBD à utiliser (voir tableau ci-dessus)
database.<type> Paramètres de connexion (host, port, user, password, name)
site.base_url URL publique ; sert à construire les appels CGI côté JS
site.web_root Racine du site où sont déployés les fichiers générés
paths.* Répertoires de travail et de génération
cgi.cgi_bin_dir Emplacement des binaires CGI compilés

metadata.cfg

Dictionnaire SGBD-indépendant qui enrichit les colonnes (titres lisibles, infobulles, options Tabulator). Format pipe-séparé, une ligne par colonne ; les lignes débutant par # sont des commentaires :

TABLE|colonne|titre|infobulle[|options]

Exemple :

ARME|strARME|Modèle d'Arme|Nom complet de l'arme
ARME|fk_CIP_strCalibre|Calibre CIP|Désignation officielle (CIP) du calibre

Chargé par MetadataLoader ; chaque entrée est indexée par la clé TABLE.colonne.

Convention de nommage des colonnes

pcCrudGen s'appuie sur des préfixes de type pour déduire le rendu :

Préfixe Type logique Rendu
str texte champ texte
int entier champ numérique
flt flottant champ numérique décimal
bool booléen case à cocher
date / created / modified date champ date
fk_ clé étrangère liste déroulante (voir ci-dessous)

Relier des champs entre deux tables (clés étrangères)

C'est le mécanisme central de pcCrudGen. Deux sources sont utilisées simultanément pour relier des champs entre deux tables :

Source Détecte la relation Connaît la colonne d'affichage
INFORMATION_SCHEMA (contraintes SQL) ✅ ❌
Convention de nommage fk_TABLE_COLONNE ✅ ✅

Le SGBD fournit les contraintes formelles ; la convention de nommage fournit le libellé à afficher dans les listes déroulantes. La convention est le moyen recommandé car elle suffit à elle seule à générer une relation exploitable.

Charte de nommage

Une colonne dont le nom commence par fk_ est traitée comme une clé étrangère implicite. Le nom encode deux informations :

fk_<TABLE_CIBLE>_<COLONNE_AFFICHAGE>
  • TABLE_CIBLE — la table référencée (ex. CIP, ARME, CALIBRE).
  • COLONNE_AFFICHAGE — la colonne à montrer dans le dropdown à la place de l'identifiant brut.

Exemple décortiqué par FkParser::parse() :

fk_CIP_nom
 │   │   └── displayColumn = "nom"   (libellé affiché)
 │   └────── targetTable   = "CIP"   (table cible)
 └────────── isFk          = true
Nom de colonne Table cible Colonne affichée Effet
fk_CIP_nom CIP nom Affiche CIP.nom dans le dropdown
fk_ARME_strDesignation ARME strDesignation Affiche la désignation de l'arme
fk_CALIBRE_id CALIBRE id Cas dégradé : la valeur d'affichage = la PK ; le JS cherche alors la première colonne str* de la cible

Comment procéder concrètement

Pour relier un champ de la table A vers la table B :

  1. Dans la table A, nommez la colonne de liaison fk_B_<colonneAffichage>.
    Exemple : dans MUNITION, la colonne fk_ARME_strARME pointe vers ARME et affichera ARME.strARME.
  2. (Optionnel mais recommandé) déclarez aussi la contrainte FOREIGN KEY en SQL pour l'intégrité référentielle.
  3. (Optionnel) ajoutez une ligne dans metadata.cfg pour le titre et l'infobulle de la colonne.
  4. Relancez crudgen.

La colonne cible est liée à la clé primaire de la table référencée. Par convention, la PK est id, sauf CIP où elle est id_cip (cas particulier câblé dans le code).

Exemple complet : relier MUNITION à ARME

Objectif : chaque ligne de MUNITION doit pointer vers une ARME, et l'interface doit afficher le nom de l'arme (ARME.strARME) plutôt que son identifiant numérique.

1. Table cible — ARME (elle existe déjà, PK = id) :

CREATE TABLE ARME (
    id      SERIAL PRIMARY KEY,
    strARME VARCHAR(120) NOT NULL     -- colonne d'affichage
);

2. Table source — MUNITION : on nomme la colonne de liaison fk_ARME_strARME. Le nom encode à lui seul la table cible (ARME) et la colonne à afficher (strARME) :

CREATE TABLE MUNITION (
    id             SERIAL PRIMARY KEY,
    fk_ARME_strARME INTEGER REFERENCES ARME(id),  -- relation vers ARME
    fltCBTOCalc    REAL
);

Note : la clause REFERENCES ARME(id) est optionnelle pour pcCrudGen (la convention de nommage suffit), mais recommandée pour l'intégrité référentielle côté SGBD.

3. Métadonnées — metadata.cfg (titre et infobulle de la colonne) :

MUNITION|fk_ARME_strARME|Modèle d'Arme|Arme utilisée pour ce lot

4. Régénération :

clear; ./crudgen config.json

Résultat :

  • contrôleur MUNITION_list : LEFT JOIN ARME ... AS fk_ARME_strARME_display ;
  • grille Tabulator de MUNITION : la colonne « Modèle d'Arme » devient une liste déroulante alimentée par ARME_list.cgi, affichant strARME et stockant l'id.

Pour ajouter une seconde relation (ex. vers OGIVE en affichant strOGIVE), il suffit d'ajouter une colonne fk_OGIVE_strOGIVE à MUNITION : chaque colonne fk_ génère son propre JOIN et son propre dropdown, indépendamment.

Analyse fine du nom (tables à underscores)

Quand la liste des tables connues est disponible, FkParser::parse() utilise la surcharge parse(colName, knownTables) : elle teste les préfixes successifs après fk_ contre les tables réellement existantes et retient la plus longue correspondance. Cela permet de gérer des noms de table contenant des underscores (ex. fk_MON_TABLE_libelle → table MON_TABLE, affichage libelle). En l'absence de correspondance, on retombe sur la découpe naïve fk_<tok1>_<reste>.

Ce que le générateur produit

Côté contrôleur (SQL) — ControllerGenerator

L'action list génère un SELECT avec un LEFT JOIN par clé étrangère. Pour chaque colonne fk_, la valeur d'affichage est ramenée sous l'alias <colonne>_display :

SELECT T.*,
       J_fk_CIP_nom.nom AS fk_CIP_nom_display
FROM   tld2.ARME AS T
LEFT JOIN tld2.CIP AS J_fk_CIP_nom
       ON T.fk_CIP_nom::text = J_fk_CIP_nom.id::text

Dans la réponse JSON, la colonne FK reçoit le libellé (ou "-" si NULL), tandis que la valeur brute (l'identifiant) est conservée sous _raw_<colonne> pour permettre l'édition.

Côté interface (dropdown) — JsGenerator

Pour chaque colonne fk_, le JS charge les valeurs possibles de la table cible via son endpoint CGI <TABLE>_list.cgi et construit une liste déroulante :

fkData['fk_CIP_nom'] = [];
fkPromises.push(
  fetch(base_url + '/cgi-bin/CIP_list.cgi')
    .then(function (r) { return r.json(); })
    .then(function (data) {
      fkData['fk_CIP_nom'] = data.map(function (r) {
        return { label: String(r['nom'] || r['id_cip']),
                 value: String(r['id_cip']) };
      });
    })
);

Si la displayColumn est en réalité la PK (cas fk_TABLE_id), le générateur cherche automatiquement la première colonne str* non primaire de la table cible comme libellé ; à défaut, la deuxième colonne non-PK.

Génération et déploiement

Pour chaque table (hors tables système exclues : lock, logs, LOCK) le pipeline produit les actions list, create, update, delete, lock, unlock :

  • Sources C++ dans GENERATED/controllers/<TABLE>_<action>.cpp ;
  • binaires compilés (ControllerGenerator::compileBinaries()) ;
  • wrappers CGI bash exposant chaque binaire ;
  • JS Tabulator dans web/<TABLE>.js ;
  • page HTML/PHP de la table.

Puis les pages transversales : diagram.php (ERD vis-network), about, description.php (relations entre tables).

Enfin, Deployer copie l'ensemble vers web_root et fabrique un paquet exportable.

Verrouillage (lock)

Une table système lock permet de signaler les lignes verrouillées. L'action list ajoute un LEFT JOIN sur cette table et expose les colonnes _locked, _locked_by, _locked_at. Les actions lock / unlock gèrent la pose et la levée du verrou.

Utilisation

clear; ./crudgen config.json

Sans argument, config.json du répertoire courant est utilisé. metadata.cfg doit être présent dans le répertoire d'exécution.

Aide :

clear; ./crudgen --help

Scripts utilitaires PostgreSQL fournis :

  • createUsersInPostgresql.sh — création des rôles ;
  • showPostgresql.sh — inspection ;
  • verifPostgresql.sh — vérifications.

Exemple de bout en bout : créer et générer la base myBase

Scénario complet, de la création de la base PostgreSQL jusqu'à la génération de l'application. On crée la base myBase avec deux tables myTable1 et myTable2, et une relation : chaque ligne de myTable2 pointe vers une ligne de myTable1 en affichant le champ strChampX.

Correspondance avec une demande « champX / champEtrangerX » : pour que le générateur comprenne la relation, les noms doivent suivre les conventions :

  • le champ affiché champX devient strChampX (préfixe str = texte) ;
  • le champ étranger champEtrangerX devient fk_myTable1_strChampX.

Le nom de la clé étrangère encode à lui seul la table cible (myTable1) et la colonne à afficher (strChampX) : c'est ce qui le rend exploitable par le générateur.

1. Créer la base

clear; createdb -h 127.0.0.1 -U postgres myBase

2. Créer les tables (fichier schema.sql)

CREATE TABLE myTable1 (
    id        SERIAL PRIMARY KEY,
    strChampX VARCHAR(120) NOT NULL       -- colonne affichée dans le dropdown
);

CREATE TABLE myTable2 (
    id                    SERIAL PRIMARY KEY,
    fk_myTable1_strChampX INTEGER REFERENCES myTable1(id),  -- clé étrangère
    strLibelle            VARCHAR(120)
);

Puis exécuter le fichier :

clear; psql -h 127.0.0.1 -U postgres -d myBase -f schema.sql

3. (Optionnel) données de test

INSERT INTO myTable1 (strChampX) VALUES ('Alpha'), ('Beta');
INSERT INTO myTable2 (fk_myTable1_strChampX, strLibelle)
  VALUES (1, 'ligne liée à Alpha');

4. Configurer config.json

{
  "database": {
    "type": "postgresql",
    "postgresql": {
      "host": "127.0.0.1",
      "port": 5432,
      "user": "postgres",
      "password": "monMotDePasse",
      "name": "myBase"
    }
  },
  "site": {
    "server":   "localhost",
    "base_url": "http://localhost",
    "web_root": "/var/www/html/myBase"
  },
  "paths": {
    "generated_src":   "GENERATED/controllers",
    "web_controllers": "controllers",
    "web_dir":         "web",
    "html_dir":        "html"
  },
  "cgi": {
    "cgi_bin_dir": "/var/www/html/myBase/cgi-bin"
  }
}

5. (Optionnel) métadonnées dans metadata.cfg

myTable2|fk_myTable1_strChampX|Référence|Élément lié de myTable1

6. Générer

clear; ./crudgen config.json

Résultat

crudgen découvre myTable1 et myTable2, détecte la colonne fk_myTable1_strChampX et génère pour myTable2 un SELECT avec jointure :

SELECT T.*,
       J_fk_myTable1_strChampX.strChampX AS fk_myTable1_strChampX_display
FROM   myBase.myTable2 AS T
LEFT JOIN myBase.myTable1 AS J_fk_myTable1_strChampX
       ON T.fk_myTable1_strChampX::text = J_fk_myTable1_strChampX.id::text

Dans la grille Tabulator de myTable2, la colonne devient une liste déroulante alimentée par myTable1_list.cgi, affichant strChampX et stockant l'id de myTable1.

Note importante sur le nom du champ étranger

Le nom fk_myTable1_strChampX est la configuration de la relation : il encode à la fois la table cible (myTable1) et la colonne d'affichage (strChampX).

  • Un champ nommé librement (ex. champEtrangerX) ne serait pas reconnu comme FK par la convention de nommage.
  • Il ne le serait que via une vraie contrainte SQL FOREIGN KEY (détectée par INFORMATION_SCHEMA) — mais dans ce cas crudgen ignore quelle colonne afficher et retombe sur la première colonne str* de la table cible.

Pour un dropdown affichant exactement strChampX, nommez donc la colonne fk_myTable1_strChampX.

Architecture du code

Classe Rôle
Generator Orchestrateur ; coordonne tous les sous-générateurs
Schema / loadSchema() Introspection INFORMATION_SCHEMA → Table / Column / ForeignKey
FkParser Décodage des noms fk_TABLE_COLONNE → ClassFkInfo
MetadataLoader Lecture de metadata.cfg
ControllerGenerator Sources C++ + compilation des contrôleurs CGI (SQL, JOIN)
JsGenerator JS Tabulator, dropdowns FK, export, toolbar
HtmlGenerator Pages HTML/PHP, index.php, wrappers CGI
DiagramGenerator Diagramme ERD interactif (vis-network)
DescriptionGenerator Page des relations entre tables
AboutGenerator Page « About »
Deployer Déploiement web_root + paquet
ClassIDatabase + ClassDatabaseFactory Abstraction multi-SGBD

Plusieurs méthodes et membres de Generator, HtmlGenerator et DescriptionGenerator sont virtual pour permettre la dérivation par des produits métier (ex. APSI.Load, qui personnalise menu et descriptions).

Voir aussi

  • README.clésEtrangères.FK — charte de nommage des clés étrangères
  • CLAUDE.md — conventions du projet