« 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 4 : Ligne 4 :


  '''Le 16/06/2026:'''
  '''Le 16/06/2026:'''
 
= pcCrudGen =
'''Le 02/06/2026:'''
= pcCrudGen (APSI.crudgen) =
 
''Générateur de CRUD expert — Debian / C++17''
 
{{TOC right}}
 
'''Cette documentation est disponible en trois formats''' (contenu identique) :
* <code>pcCrudGen.pcwiki</code> — MediaWiki 1.34 (ce fichier)
* <code>pcCrudGen.md</code> — Markdown
* <code>pcCrudGen.html</code> — 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|Tabulator]]), diagramme
ERD interactif et pages de documentation. L'outil est piloté par un simple
fichier <code>config.json</code> et un dictionnaire de métadonnées
<code>metadata.cfg</code>.
 
Le binaire produit s'appelle <code>crudgen</code>.
 
== Principe général ==
 
Le générateur applique le pipeline suivant :
 
# Lecture de <code>config.json</code> (connexion, chemins, site cible).
# Connexion au SGBD et '''introspection''' du schéma via
  <code>INFORMATION_SCHEMA</code> (tables, colonnes, types, clés primaires,
  clés étrangères).
# Chargement du dictionnaire <code>metadata.cfg</code> (titres, infobulles,
  options d'affichage par colonne).
# Génération '''table par table''' : sources C++ des contrôleurs, compilation
  en binaires, JS Tabulator, pages HTML/PHP, wrappers CGI bash.
# Génération des pages transversales : diagramme ERD, page « About », page
  « Description » des relations.
# Déploiement vers le <code>web_root</code> du site et création d'un paquet
  exportable.
 
L'orchestration est assurée par la classe <code>Generator</code>
(<code>Generator::generate()</code>), qui délègue à des générateurs
spécialisés (<code>ControllerGenerator</code>, <code>JsGenerator</code>,
<code>HtmlGenerator</code>, <code>DiagramGenerator</code>, etc.).
 
== SGBD supportés ==
 
L'accès est abstrait derrière l'interface <code>ClassIDatabase</code>, instanciée
par <code>ClassDatabaseFactory</code> selon le champ <code>type</code> de la
configuration :
 
{| class="wikitable"
{| class="wikitable"
! Type (<code>config.json</code>) !! Classe !! État
! Version !! Date !! Langage !! Licence
|-
| <code>postgresql</code> || <code>ClassPostgreSQL</code> || Cible principale
|-
| <code>mariadb</code> || <code>ClassMariaDB</code> || Supporté
|-
| <code>sqlite</code> || <code>ClassSQLite</code> || Supporté
|-
|-
| <code>mongodb</code> || <code>ClassMongoDB</code> || Expérimental
| 1.55 || 16/11/2026 || C++17 (g++), CMake ≥ 3.16 || Propriétaire (APSI)
|}
|}


== Configuration ==
== Présentation ==
'''pcCrudGen''' lit le schéma d'une base de données existante (PostgreSQL, MariaDB ou SQLite) et génère une interface web CRUD complète :
* un '''CGI C++''' par table (actions <code>list</code>, <code>create</code>, <code>update</code>, <code>delete</code>, <code>lock</code>, <code>unlock</code>), compilé avec <code>g++</code> ;
* une page PHP + une grille JavaScript '''Tabulator''' par table ;
* un <code>index.php</code> avec menu, thèmes, fontes, About ;
* des pages globales : ERD, Description, Doc, Manuel, Requis, Couleurs ;
* un vhost Apache, une configuration d'exécution des CGI, un script de post-installation et un '''tarball''' <code>pcCrudGen.<base>.tgz</code> prêt à être déployé.


=== config.json ===
Les clés étrangères sont détectées par le nom de colonne : <code>fk_<TABLE>_<colonne_affichée></code> (ex. <code>fk_CIP_nom</code>) produit une jointure et affiche <code>nom</code> au lieu de l'identifiant.


Fichier de configuration principal. Exemple :
== Installation ==
=== Paquets Debian ===
<pre>
apt install g++ cmake make ccache libpq-dev libmariadb-dev \
    libsqlite3-dev libboost-system-dev libboost-dev nlohmann-json3-dev
# Exécution / déploiement (cible) :
apt install apache2 php-fpm php-pgsql openssh-client tar gzip
# Facultatif (dumps SQL) : postgresql-client mariadb-client sqlite3
</pre>


=== Compilation ===
<pre>
<pre>
{
cd /home/local/src/Atelier/GENERATOR/V1.55.withClass
  "database": {
cmake -B build
    "type": "postgresql",
cmake --build build -j$(nproc)
    "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"
  }
}
</pre>
</pre>
 
Le binaire est <code>build/pcCrudGen</code> (lien symbolique <code>./pcCrudGen</code>). L'option CMake <code>-DWITH_THEMES=ON</code> active le sélecteur de thèmes dans <code>index.php</code>.
{| class="wikitable"
Installation système (pour déployer le générateur sur une VM vierge) :
! Clé !! Rôle
|-
| <code>database.type</code> || SGBD à utiliser (voir tableau ci-dessus)
|-
| <code>database.&lt;type&gt;</code> || Paramètres de connexion (host, port, user, password, name)
|-
| <code>site.base_url</code> || URL publique ; sert à construire les appels CGI côté JS
|-
| <code>site.web_root</code> || Racine du site où sont déployés les fichiers générés
|-
| <code>paths.*</code> || Répertoires de travail et de génération
|-
| <code>cgi.cgi_bin_dir</code> || 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 <code>#</code> sont des commentaires :
 
<pre>
<pre>
TABLE|colonne|titre|infobulle[|options]
cmake --install build      # /usr/local/{bin,include/pcCrudGen,lib}
</pre>
</pre>


Exemple :
== Syntaxe ==
 
<pre>
<pre>
ARME|strARME|Modèle d'Arme|Nom complet de l'arme
pcCrudGen <moteur> <base> [--deploy]
ARME|fk_CIP_strCalibre|Calibre CIP|Désignation officielle (CIP) du calibre
pcCrudGen -v | --version
pcCrudGen -h | --help
</pre>
</pre>
Chargé par <code>MetadataLoader</code> ; chaque entrée est indexée par la clé
<code>TABLE.colonne</code>.
== Convention de nommage des colonnes ==
pcCrudGen s'appuie sur des préfixes de type pour déduire le rendu :


{| class="wikitable"
{| class="wikitable"
! Préfixe !! Type logique !! Rendu
! Élément !! Description !! Exemple
|-
| <code>str</code> || texte || champ texte
|-
|-
| <code>int</code> || entier || champ numérique
| <code><moteur></code> || <code>postgresql</code>, <code>mariadb</code> ou <code>sqlite</code> (alias : <code>postgres</code>, <code>pg</code>, <code>mysql</code>) || <code>pcCrudGen pg tld2</code>
|-
|-
| <code>flt</code> || flottant || champ numérique décimal
| <code><base></code> || Nom de la base. Lettres, chiffres, <code>_ - .</code> ; 64 caractères max ; ne commence pas par <code>-</code> ni <code>.</code>. Pour SQLite : identifiant substitué dans <code>{dbname}</code> du chemin du fichier. || <code>pcCrudGen mariadb zorro</code>
|-
|-
| <code>bool</code> || booléen || case à cocher
| <code>--deploy</code> || Après génération, envoie le tarball vers <code>deploy.target</code> (scp), l'extrait (ssh <code>tar xzf</code>) et lance le post-installation distant. '''Sans cette option, rien ne quitte la machine.''' || <code>pcCrudGen postgresql tld2 --deploy</code>
|-
|-
| <code>date</code> / <code>created</code> / <code>modified</code> || date || champ date
| <code>-v</code>, <code>--version</code> || Affiche la version et la date du dernier build || <code>pcCrudGen -v</code>
|-
|-
| <code>fk_</code> || clé étrangère || '''liste déroulante''' (voir ci-dessous)
| <code>-h</code>, <code>--help</code> || Affiche l'aide || <code>pcCrudGen --help</code>
|}
|}
Toute autre option est refusée (code retour 1).


== Relier des champs entre deux tables (clés étrangères) ==
== Mode d'emploi ==
 
=== 1. Premier lancement : création de la configuration ===
C'est le mécanisme central de pcCrudGen. '''Deux sources''' sont utilisées
<pre>
'''simultanément''' pour relier des champs entre deux tables :
pcCrudGen postgresql tld2
 
</pre>
{| class="wikitable"
Si <code>/var/lib/<moteur>/pcCrudGen.config.json</code> n'existe pas, il est créé avec des valeurs par défaut (mot de passe <code><A_REMPLIR></code>) et le programme s'arrête en vous demandant de l'éditer.
! Source !! Détecte la relation !! Connaît la colonne d'affichage
|-
| <code>INFORMATION_SCHEMA</code> (contraintes SQL) || ✅ || ❌
|-
| Convention de nommage <code>fk_TABLE_COLONNE</code> || ✅ || ✅
|}
 
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 <code>fk_</code> est traitée comme une
'''clé étrangère implicite'''. Le nom encode deux informations :


=== 2. Éditer la configuration ===
<pre>
<pre>
fk_<TABLE_CIBLE>_<COLONNE_AFFICHAGE>
vim /var/lib/postgresql/pcCrudGen.config.json
</pre>
</pre>
 
Exemple :
* '''TABLE_CIBLE''' — la table référencée (ex. <code>CIP</code>, <code>ARME</code>, <code>CALIBRE</code>).
* '''COLONNE_AFFICHAGE''' — la colonne à montrer dans le dropdown à la place de l'identifiant brut.
 
Exemple décortiqué par <code>FkParser::parse()</code> :
 
<pre>
<pre>
fk_CIP_nom
{
│   │   └── displayColumn = "nom"  (libellé affiché)
   "database": { "type": "postgresql",
│   └────── targetTable   = "CIP"  (table cible)
    "postgresql": { "host": "127.0.0.1", "port": 5432, "user": "postgres",
└────────── isFk          = true
                    "password": "secret", "name": "{dbname}" } },
   "site":  { "server": "ovh2.pcstreet.org",
            "base_url": "https://{dbname}.{server}",
            "web_root": "/var/www/html/{dbname}.{server}" },
   "deploy": { "target": "ovh2", "php_fpm": "8.4" },
   "paths": { "generated_src": "GENERATED/{dbname}/controllers",
            "html_dir": "html/{dbname}", "web_dir": "web/{dbname}" },
   "cgi":   { "cgi_bin_dir": "/var/www/html/{dbname}.{server}/cgi-bin" }
}
</pre>
</pre>
{| class="wikitable"
{| class="wikitable"
! Nom de colonne !! Table cible !! Colonne affichée !! Effet
! Clé !! Rôle
|-
|-
| <code>fk_CIP_nom</code> || CIP || nom || Affiche <code>CIP.nom</code> dans le dropdown
| <code>database.<moteur>.*</code> || Connexion (host, port, user, password, name ; SQLite : seulement <code>name</code> = chemin du fichier)
|-
|-
| <code>fk_ARME_strDesignation</code> || ARME || strDesignation || Affiche la désignation de l'arme
| <code>site.server</code> || Suffixe DNS du vhost (<code>localhost</code> est remappé sur <code>pcstreet.org</code>)
|-
|-
| <code>fk_CALIBRE_id</code> || CALIBRE || id || Cas dégradé : la valeur d'affichage = la PK ; le JS cherche alors la première colonne <code>str*</code> de la cible
| <code>site.web_root</code> || Racine web générée/déployée
|-
| <code>deploy.target</code> || Alias <code>~/.ssh/config</code> ou <code>user@hôte</code> pour <code>--deploy</code> (vide = pas d'envoi)
|-
| <code>deploy.php_fpm</code> || Version PHP-FPM du socket (<code>php8.4-fpm.sock</code>)
|-
| <code>paths.*</code>, <code>cgi.cgi_bin_dir</code> || Répertoires de génération et de CGI
|}
|}
<code>{dbname}</code> (en minuscules) et <code>{server}</code> sont substitués partout.


=== Comment procéder concrètement ===
=== 3. Générer ===
 
Pour relier un champ de la table A vers la table B :
 
# Dans la table A, nommez la colonne de liaison <code>fk_B_&lt;colonneAffichage&gt;</code>.
#: Exemple : dans <code>MUNITION</code>, la colonne <code>fk_ARME_strARME</code> pointe vers <code>ARME</code> et affichera <code>ARME.strARME</code>.
# (Optionnel mais recommandé) déclarez aussi la contrainte <code>FOREIGN KEY</code> en SQL pour l'intégrité référentielle.
# (Optionnel) ajoutez une ligne dans <code>metadata.cfg</code> pour le titre et l'infobulle de la colonne.
# Relancez <code>crudgen</code>.
 
La colonne cible est liée à la '''clé primaire''' de la table référencée. Par
convention, la PK est <code>id</code>, sauf <code>CIP</code> où elle est
<code>id_cip</code> (cas particulier câblé dans le code).
 
=== Exemple complet : relier MUNITION à ARME ===
 
Objectif : chaque ligne de <code>MUNITION</code> doit pointer vers une
<code>ARME</code>, et l'interface doit afficher le '''nom de l'arme'''
(<code>ARME.strARME</code>) plutôt que son identifiant numérique.
 
'''1. Table cible — ARME''' (elle existe déjà, PK = <code>id</code>) :
 
<pre>
CREATE TABLE ARME (
    id      SERIAL PRIMARY KEY,
    strARME VARCHAR(120) NOT NULL    -- colonne d'affichage
);
</pre>
 
'''2. Table source — MUNITION''' : on nomme la colonne de liaison
<code>fk_ARME_strARME</code>. Le nom encode à lui seul la table cible
(<code>ARME</code>) et la colonne à afficher (<code>strARME</code>) :
 
<pre>
CREATE TABLE MUNITION (
    id            SERIAL PRIMARY KEY,
    fk_ARME_strARME INTEGER REFERENCES ARME(id),  -- relation vers ARME
    fltCBTOCalc    REAL
);
</pre>
 
''Note :'' la clause <code>REFERENCES ARME(id)</code> 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) :
 
<pre>
MUNITION|fk_ARME_strARME|Modèle d'Arme|Arme utilisée pour ce lot
</pre>
 
'''4. Régénération :'''
 
<pre>
clear; ./crudgen config.json
</pre>
 
'''Résultat :'''
* contrôleur <code>MUNITION_list</code> : <code>LEFT JOIN ARME ... AS fk_ARME_strARME_display</code> ;
* grille Tabulator de <code>MUNITION</code> : la colonne « Modèle d'Arme » devient une '''liste déroulante''' alimentée par <code>ARME_list.cgi</code>, affichant <code>strARME</code> et stockant l'<code>id</code>.
 
Pour ajouter une seconde relation (ex. vers <code>OGIVE</code> en affichant
<code>strOGIVE</code>), il suffit d'ajouter une colonne
<code>fk_OGIVE_strOGIVE</code> à <code>MUNITION</code> : chaque colonne
<code>fk_</code> 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, <code>FkParser::parse()</code>
utilise la surcharge <code>parse(colName, knownTables)</code> : elle teste les
préfixes successifs après <code>fk_</code> 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.
<code>fk_MON_TABLE_libelle</code> → table <code>MON_TABLE</code>, affichage
<code>libelle</code>). En l'absence de correspondance, on retombe sur la
découpe naïve <code>fk_&lt;tok1&gt;_&lt;reste&gt;</code>.
 
=== Ce que le générateur produit ===
 
==== Côté contrôleur (SQL) — ControllerGenerator ====
 
L'action <code>list</code> génère un <code>SELECT</code> avec un
<code>LEFT JOIN</code> par clé étrangère. Pour chaque colonne <code>fk_</code>,
la valeur d'affichage est ramenée sous l'alias <code>&lt;colonne&gt;_display</code> :
 
<pre>
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
</pre>
 
Dans la réponse JSON, la colonne FK reçoit le '''libellé''' (ou <code>"-"</code>
si NULL), tandis que la valeur brute (l'identifiant) est conservée sous
<code>_raw_&lt;colonne&gt;</code> pour permettre l'édition.
 
==== Côté interface (dropdown) — JsGenerator ====
 
Pour chaque colonne <code>fk_</code>, le JS charge les valeurs possibles de la
table cible via son endpoint CGI <code>&lt;TABLE&gt;_list.cgi</code> et construit
une liste déroulante :
 
<pre>
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']) };
      });
    })
);
</pre>
 
Si la <code>displayColumn</code> est en réalité la PK (cas <code>fk_TABLE_id</code>),
le générateur cherche automatiquement la première colonne <code>str*</code> 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 : <code>lock</code>,
<code>logs</code>, <code>LOCK</code>) le pipeline produit les actions
<code>list</code>, <code>create</code>, <code>update</code>,
<code>delete</code>, <code>lock</code>, <code>unlock</code> :
 
* '''Sources C++''' dans <code>GENERATED/controllers/&lt;TABLE&gt;_&lt;action&gt;.cpp</code> ;
* '''binaires compilés''' (<code>ControllerGenerator::compileBinaries()</code>) ;
* '''wrappers CGI bash''' exposant chaque binaire ;
* '''JS Tabulator''' dans <code>web/&lt;TABLE&gt;.js</code> ;
* '''page HTML/PHP''' de la table.
 
Puis les pages transversales : <code>diagram.php</code> (ERD vis-network),
<code>about</code>, <code>description.php</code> (relations entre tables).
 
Enfin, <code>Deployer</code> copie l'ensemble vers <code>web_root</code> et
fabrique un paquet exportable.
 
=== Verrouillage (lock) ===
 
Une table système <code>lock</code> permet de signaler les lignes verrouillées.
L'action <code>list</code> ajoute un <code>LEFT JOIN</code> sur cette table et
expose les colonnes <code>_locked</code>, <code>_locked_by</code>,
<code>_locked_at</code>. Les actions <code>lock</code> / <code>unlock</code>
gèrent la pose et la levée du verrou.
 
== Utilisation ==
 
<pre>
clear; ./crudgen config.json
</pre>
 
Sans argument, <code>config.json</code> du répertoire courant est utilisé.
<code>metadata.cfg</code> doit être présent dans le répertoire d'exécution.
 
Aide :
 
<pre>
clear; ./crudgen --help
</pre>
 
Scripts utilitaires PostgreSQL fournis :
 
* <code>createUsersInPostgresql.sh</code> — création des rôles ;
* <code>showPostgresql.sh</code> — inspection ;
* <code>verifPostgresql.sh</code> — 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 <code>myBase</code> avec deux tables
<code>myTable1</code> et <code>myTable2</code>, et une relation : chaque ligne de
<code>myTable2</code> pointe vers une ligne de <code>myTable1</code> en affichant
le champ <code>strChampX</code>.
 
''Correspondance avec une demande « champX / champEtrangerX » :'' pour que le
générateur comprenne la relation, les noms doivent suivre les conventions :
* le champ affiché <code>champX</code> devient <code>strChampX</code> (préfixe <code>str</code> = texte) ;
* le champ étranger <code>champEtrangerX</code> devient <code>fk_myTable1_strChampX</code>.
Le nom de la clé étrangère encode à lui seul la table cible
(<code>myTable1</code>) et la colonne à afficher (<code>strChampX</code>) : c'est
ce qui le rend exploitable par le générateur.
 
=== 1. Créer la base ===
 
<pre>
clear; createdb -h 127.0.0.1 -U postgres myBase
</pre>
 
=== 2. Créer les tables (fichier schema.sql) ===
 
<pre>
<pre>
CREATE TABLE myTable1 (
pcCrudGen postgresql tld2
    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)
);
</pre>
</pre>
Le programme travaille dans <code>/usr/local/IA/<base>/</code> (créé si besoin) et enchaîne :
# GRANT automatiques best-effort sur les bases locales (<code>sudo -n -u postgres psql</code> / <code>sudo -n mariadb</code>) ;
# connexion avec cascade d'hôtes : <code>host</code> du config → 10.0.2.18 → 10.0.1.18 → bois-dery.fr ;
# introspection du schéma ; création idempotente des tables internes <code>lock</code> et <code>labels_in_menu</code> ;
# métadonnées : lit <code>metadata.cfg</code> s'il existe, sinon les génère à partir des noms de colonnes ;
# génération et compilation des CGI (un PCH partagé accélère la compilation), pages PHP, JS, pages globales ;
# staging dans <code>web_root</code>, écriture du vhost, de la config CGI et du post-install, dump SQL, tarball.


Puis exécuter le fichier :
=== 4. Personnaliser les libellés (facultatif) ===
 
Fichier <code>metadata.cfg</code> dans <code>/usr/local/IA/<base>/</code> ; une ligne par colonne, séparateur <code>|</code> :
<pre>
<pre>
clear; psql -h 127.0.0.1 -U postgres -d myBase -f schema.sql
# table|colonne|titre|infobulle|options
CALIBRE|strNom|Nom du calibre|Nom commercial|
</pre>
</pre>
Table et colonne sont comparées sans accents ni casse.


=== 3. (Optionnel) données de test ===
=== 5. Déployer ===
 
<pre>
<pre>
INSERT INTO myTable1 (strChampX) VALUES ('Alpha'), ('Beta');
pcCrudGen postgresql tld2 --deploy
INSERT INTO myTable2 (fk_myTable1_strChampX, strLibelle)
  VALUES (1, 'ligne liée à Alpha');
</pre>
</pre>
 
ou manuellement sur le serveur cible :
=== 4. Configurer config.json ===
 
<pre>
<pre>
{
tar xzf pcCrudGen.tld2.tgz -C /
  "database": {
/home/local/bin/pcCrudGen.tld2.ovh2.pcstreet.org.postinstall.sh
    "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"
  }
}
</pre>
</pre>
Le post-install est idempotent : droits, bootstrap de <code>/etc/pcCrudGen/config.<vhost>.json</code> depuis le <code>.example</code> (à éditer pour la production), <code>a2ensite</code>, reload Apache. Si le certificat Let's Encrypt est absent : <code>certbot --apache -d <vhost></code>.


=== 5. (Optionnel) métadonnées dans metadata.cfg ===
== Exemple complet : base MariaDB pcArpScan ==
 
Le script <code>exemple_pcArpScan.sh</code> enchaîne compilation (si besoin), vérification de la configuration et génération :
<pre>
<pre>
myTable2|fk_myTable1_strChampX|Référence|Élément lié de myTable1
./exemple_pcArpScan.sh            # génération locale + tarball
./exemple_pcArpScan.sh --deploy  # idem + envoi vers deploy.target
./exemple_pcArpScan.sh --reconfigure  # refaire le questionnaire
</pre>
</pre>
Si <code>/var/lib/mariadb/pcCrudGen.config.json</code> n'existe pas, le script vous '''interroge''' (hôte, port, utilisateur, mot de passe saisi deux fois sans écho, domaine, cible ssh — « aucune » pour ne pas déployer —, version PHP-FPM), affiche un récapitulatif, demande confirmation puis écrit le fichier (droits 640). Les réponses sont validées avec la même liste blanche que le générateur. <code>--reconfigure</code> reposera les questions (ancien fichier sauvegardé en <code>.bak</code>). Ce fichier est commun à toutes les bases MariaDB générées sur la machine. Résultats : <code>/usr/local/IA/pcArpScan/GENERATED/pcarpscan/controllers</code> et <code>/usr/local/IA/pcArpScan/pcCrudGen.pcarpscan.tgz</code>.
Équivalent manuel : <code>pcCrudGen mariadb pcArpScan</code>.


=== 6. Générer ===
== Fichiers produits ==
 
<pre>
clear; ./crudgen config.json
</pre>
 
=== Résultat ===
 
crudgen découvre <code>myTable1</code> et <code>myTable2</code>, détecte la
colonne <code>fk_myTable1_strChampX</code> et génère pour <code>myTable2</code>
un <code>SELECT</code> avec jointure :
 
<pre>
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
</pre>
 
Dans la grille Tabulator de <code>myTable2</code>, la colonne devient une
'''liste déroulante''' alimentée par <code>myTable1_list.cgi</code>, affichant
<code>strChampX</code> et stockant l'<code>id</code> de <code>myTable1</code>.
 
=== Note importante sur le nom du champ étranger ===
 
Le nom <code>fk_myTable1_strChampX</code> '''est''' la configuration de la
relation : il encode à la fois la table cible (<code>myTable1</code>) et la
colonne d'affichage (<code>strChampX</code>).
 
* Un champ nommé librement (ex. <code>champEtrangerX</code>) ne serait '''pas''' reconnu comme FK par la convention de nommage.
* Il ne le serait que via une vraie contrainte SQL <code>FOREIGN KEY</code> (détectée par <code>INFORMATION_SCHEMA</code>) — mais dans ce cas crudgen ignore quelle colonne afficher et retombe sur la première colonne <code>str*</code> de la table cible.
 
Pour un dropdown affichant exactement <code>strChampX</code>, nommez donc la
colonne <code>fk_myTable1_strChampX</code>.
 
== Architecture du code ==
 
{| class="wikitable"
{| class="wikitable"
! Classe !! Rôle
! Chemin !! Contenu
|-
|-
| <code>Generator</code> || Orchestrateur ; coordonne tous les sous-générateurs
| <code>GENERATED/<base>/controllers/</code> || Sources C++ des CGI + <code>cgi_pch.hpp(.gch)</code>
|-
|-
| <code>Schema</code> / <code>loadSchema()</code> || Introspection <code>INFORMATION_SCHEMA</code> → <code>Table</code> / <code>Column</code> / <code>ForeignKey</code>
| <code>html/<base>/</code>, <code>web/<base>/</code> || Pages PHP, JavaScript Tabulator
|-
|-
| <code>FkParser</code> || Décodage des noms <code>fk_TABLE_COLONNE</code> → <code>ClassFkInfo</code>
| <code><web_root>/</code> || Site prêt à servir (<code>php/ js/ css/ cgi-bin/ sql/</code>)
|-
|-
| <code>MetadataLoader</code> || Lecture de <code>metadata.cfg</code>
| <code>/etc/apache2/sites-available/<vhost>.conf</code> || Vhost HTTP + HTTPS
|-
|-
| <code>ControllerGenerator</code> || Sources C++ + compilation des contrôleurs CGI (SQL, JOIN)
| <code>/etc/pcCrudGen/config.<vhost>[.example].json</code> || Configuration d'exécution des CGI (mot de passe : droits 0640, groupe <code>www-data</code>)
|-
|-
| <code>JsGenerator</code> || JS Tabulator, dropdowns FK, export, toolbar
| <code>pcCrudGen.<base>.tgz</code> || Tarball portable (site + vhost + config + post-install + toolkit sous <code>/usr/local</code>)
|}
 
== Sécurité ==
* Toutes les valeurs interpolées dans des commandes shell (chemins, hôtes, utilisateur, cible ssh, nom de base) sont validées par liste blanche avant usage ; une valeur douteuse arrête le programme avec un message explicite.
* Les CGI générés utilisent des requêtes préparées ; les noms de colonnes venant du JSON sont filtrés par une liste blanche issue du schéma.
* <code>web_root/sql/</code> (dumps schéma + données) est protégé par un <code>.htaccess</code> « Require all denied » ; il reste présent dans le tarball.
* Les mots de passe des dumps passent par l'environnement (<code>PGPASSWORD</code>, <code>MYSQL_PWD</code>) et non en argument visible dans <code>ps</code>.
* Attention : le fichier <code>.example.json</code> embarqué dans le tarball contient le mot de passe de la base de développement. Ne diffusez pas le tarball hors de vos serveurs.
 
== Dépannage ==
{| class="wikitable"
! Symptôme !! Cause / solution
|-
|-
| <code>HtmlGenerator</code> || Pages HTML/PHP, <code>index.php</code>, wrappers CGI
| « CONFIG CREEE — A REVISER » || Normal au premier lancement : éditer le JSON puis relancer.
|-
|-
| <code>DiagramGenerator</code> || Diagramme ERD interactif (vis-network)
| « Aucun hôte DB joignable » || Vérifier host/user/password ; la cascade essaie 4 hôtes.
|-
|-
| <code>DescriptionGenerator</code> || Page des relations entre tables
| « Configuration : caractère interdit dans … » || Une valeur du config contient un caractère non autorisé (espace, <code>;</code>, <code>'</code>…). La corriger.
|-
|-
| <code>AboutGenerator</code> || Page « About »
| « compile raté » (WARN) || Lire l'erreur g++ au-dessus ; vérifier que <code>build/libpccrudgen_multi.a</code> existe (sinon <code>cmake --build build</code>).
|-
|-
| <code>Deployer</code> || Déploiement <code>web_root</code> + paquet
| Reload Apache échoué || Certificat SSL absent : <code>certbot --apache -d <vhost></code>.
|-
|-
| <code>ClassIDatabase</code> + <code>ClassDatabaseFactory</code> || Abstraction multi-SGBD
| Pagination : une seule page || Corrigé en 1.55 (comptage exact sous 100 000 lignes).
|}
|}


Plusieurs méthodes et membres de <code>Generator</code>,
== Historique ==
<code>HtmlGenerator</code> et <code>DescriptionGenerator</code> sont
=== 1.55 (16/11/2026) ===
<code>virtual</code> pour permettre la dérivation par des produits métier
* '''Correctif''' : <code>--deploy</code> était ignoré ; scp/ssh partaient dès que <code>deploy.target</code> était renseigné. L'envoi n'a plus lieu que si <code>--deploy</code> est donné.
(ex. ''APSI.Load'', qui personnalise menu et descriptions).
* '''Correctif''' : options inconnues et arguments en trop refusés (une faute de frappe devenait un nom de base).
 
* '''Sécurité''' : validation par liste blanche (config + CLI) contre l'injection shell ; quoting des mots de passe de dump ; répertoire de staging créé par <code>mkdtemp</code> ; <code>sql/</code> interdit en HTTP ; config avec mot de passe en 0640 ; requêtes d'introspection échappées.
== Voir aussi ==
* '''CGI générés''' : clé primaire numérique acceptée (plantage <code>type_error 302</code>) ; paramètres de requête lus proprement (<code>page</code> ne matche plus <code>last_page</code>) ; pagination exacte pour les tables < 100 000 lignes (<code>reltuples = -1</code> sous PostgreSQL) ; SQL MariaDB sans nom de base figé (la base de production peut différer).
 
* '''Introspection''' : colonnes triées par <code>ordinal_position</code> (ordre déterministe).
* <code>README.clésEtrangères.FK</code> — charte de nommage des clés étrangères
* '''Interface''' : version affichée dans « About » dynamique (était « 1.45 » en dur) ; Tabulator 6.2 ; code mort supprimé.
* <code>CLAUDE.md</code> — conventions du projet


[[Category:APSI]]
== Améliorations suggérées (non faites) ==
[[Category:Générateurs]]
* Menu : la liste <code>CALIBRE, CIP, ARME…</code> est codée en dur dans <code>ClassHtmlGenerator</code> ; la sortir en configuration.
[[Category:C++]]
* <code>index.php</code> ne charge les libellés <code>labels_in_menu</code> que pour PostgreSQL (MariaDB/SQLite : repli sur le nom brut).
* Les <code>std::system()</code> restants gagneraient à être remplacés par <code>posix_spawn</code> sans shell.
* Les classes <code>ClassDatabase</code> / <code>ClassSchemaLoader</code> (mode MONOBASE) sont signalées orphelines.
* Ajouter des tests automatiques (génération sur SQLite temporaire + exécution du CGI).

Version du 16 novembre 2026 à 15:19

KEYWORDS: CRUDGEN, PCCRUDGEN

Info::pcCrudGen premiere version
Le 16/06/2026:

pcCrudGen

Version Date Langage Licence
1.55 16/11/2026 C++17 (g++), CMake ≥ 3.16 Propriétaire (APSI)

Présentation

pcCrudGen lit le schéma d'une base de données existante (PostgreSQL, MariaDB ou SQLite) et génère une interface web CRUD complète :

  • un CGI C++ par table (actions list, create, update, delete, lock, unlock), compilé avec g++ ;
  • une page PHP + une grille JavaScript Tabulator par table ;
  • un index.php avec menu, thèmes, fontes, About ;
  • des pages globales : ERD, Description, Doc, Manuel, Requis, Couleurs ;
  • un vhost Apache, une configuration d'exécution des CGI, un script de post-installation et un tarball pcCrudGen.<base>.tgz prêt à être déployé.

Les clés étrangères sont détectées par le nom de colonne : fk_

_<colonne_affichée> (ex. ) produit une jointure et affiche au lieu de l'identifiant.

Installation

Paquets Debian

apt install g++ cmake make ccache libpq-dev libmariadb-dev \
    libsqlite3-dev libboost-system-dev libboost-dev nlohmann-json3-dev
# Exécution / déploiement (cible) :
apt install apache2 php-fpm php-pgsql openssh-client tar gzip
# Facultatif (dumps SQL) : postgresql-client mariadb-client sqlite3

Compilation

cd /home/local/src/Atelier/GENERATOR/V1.55.withClass
cmake -B build
cmake --build build -j$(nproc)

Le binaire est build/pcCrudGen (lien symbolique ./pcCrudGen). L'option CMake -DWITH_THEMES=ON active le sélecteur de thèmes dans index.php. Installation système (pour déployer le générateur sur une VM vierge) :

cmake --install build      # /usr/local/{bin,include/pcCrudGen,lib}

Syntaxe

pcCrudGen <moteur> <base> [--deploy]
pcCrudGen -v | --version
pcCrudGen -h | --help

fk_CIP_nom

nom

Élément Description Exemple
<moteur> postgresql, mariadb ou sqlite (alias : postgres, pg, mysql) pcCrudGen pg tld2
<base> Nom de la base. Lettres, chiffres, _ - . ; 64 caractères max ; ne commence pas par - ni .. Pour SQLite : identifiant substitué dans {dbname} du chemin du fichier. pcCrudGen mariadb zorro
--deploy Après génération, envoie le tarball vers deploy.target (scp), l'extrait (ssh tar xzf) et lance le post-installation distant. Sans cette option, rien ne quitte la machine. pcCrudGen postgresql tld2 --deploy
-v, --version Affiche la version et la date du dernier build pcCrudGen -v
-h, --help Affiche l'aide pcCrudGen --help

Toute autre option est refusée (code retour 1).

Mode d'emploi

1. Premier lancement : création de la configuration

pcCrudGen postgresql tld2

Si /var/lib/<moteur>/pcCrudGen.config.json n'existe pas, il est créé avec des valeurs par défaut (mot de passe <A_REMPLIR>) et le programme s'arrête en vous demandant de l'éditer.

2. Éditer la configuration

vim /var/lib/postgresql/pcCrudGen.config.json

Exemple :

{
  "database": { "type": "postgresql",
    "postgresql": { "host": "127.0.0.1", "port": 5432, "user": "postgres",
                    "password": "secret", "name": "{dbname}" } },
  "site":  { "server": "ovh2.pcstreet.org",
             "base_url": "https://{dbname}.{server}",
             "web_root": "/var/www/html/{dbname}.{server}" },
  "deploy": { "target": "ovh2", "php_fpm": "8.4" },
  "paths": { "generated_src": "GENERATED/{dbname}/controllers",
             "html_dir": "html/{dbname}", "web_dir": "web/{dbname}" },
  "cgi":   { "cgi_bin_dir": "/var/www/html/{dbname}.{server}/cgi-bin" }
}
Clé Rôle
database.<moteur>.* Connexion (host, port, user, password, name ; SQLite : seulement name = chemin du fichier)
site.server Suffixe DNS du vhost (localhost est remappé sur pcstreet.org)
site.web_root Racine web générée/déployée
deploy.target Alias ~/.ssh/config ou user@hôte pour --deploy (vide = pas d'envoi)
deploy.php_fpm Version PHP-FPM du socket (php8.4-fpm.sock)
paths.*, cgi.cgi_bin_dir Répertoires de génération et de CGI

{dbname} (en minuscules) et {server} sont substitués partout.

3. Générer

pcCrudGen postgresql tld2

Le programme travaille dans /usr/local/IA/<base>/ (créé si besoin) et enchaîne :

  1. GRANT automatiques best-effort sur les bases locales (sudo -n -u postgres psql / sudo -n mariadb) ;
  2. connexion avec cascade d'hôtes : host du config → 10.0.2.18 → 10.0.1.18 → bois-dery.fr ;
  3. introspection du schéma ; création idempotente des tables internes lock et labels_in_menu ;
  4. métadonnées : lit metadata.cfg s'il existe, sinon les génère à partir des noms de colonnes ;
  5. génération et compilation des CGI (un PCH partagé accélère la compilation), pages PHP, JS, pages globales ;
  6. staging dans web_root, écriture du vhost, de la config CGI et du post-install, dump SQL, tarball.

4. Personnaliser les libellés (facultatif)

Fichier metadata.cfg dans /usr/local/IA/<base>/ ; une ligne par colonne, séparateur | :

# table|colonne|titre|infobulle|options
CALIBRE|strNom|Nom du calibre|Nom commercial|

Table et colonne sont comparées sans accents ni casse.

5. Déployer

pcCrudGen postgresql tld2 --deploy

ou manuellement sur le serveur cible :

tar xzf pcCrudGen.tld2.tgz -C /
/home/local/bin/pcCrudGen.tld2.ovh2.pcstreet.org.postinstall.sh

Le post-install est idempotent : droits, bootstrap de /etc/pcCrudGen/config.<vhost>.json depuis le .example (à éditer pour la production), a2ensite, reload Apache. Si le certificat Let's Encrypt est absent : certbot --apache -d <vhost>.

Exemple complet : base MariaDB pcArpScan

Le script exemple_pcArpScan.sh enchaîne compilation (si besoin), vérification de la configuration et génération :

./exemple_pcArpScan.sh            # génération locale + tarball
./exemple_pcArpScan.sh --deploy   # idem + envoi vers deploy.target
./exemple_pcArpScan.sh --reconfigure  # refaire le questionnaire

Si /var/lib/mariadb/pcCrudGen.config.json n'existe pas, le script vous interroge (hôte, port, utilisateur, mot de passe saisi deux fois sans écho, domaine, cible ssh — « aucune » pour ne pas déployer —, version PHP-FPM), affiche un récapitulatif, demande confirmation puis écrit le fichier (droits 640). Les réponses sont validées avec la même liste blanche que le générateur. --reconfigure reposera les questions (ancien fichier sauvegardé en .bak). Ce fichier est commun à toutes les bases MariaDB générées sur la machine. Résultats : /usr/local/IA/pcArpScan/GENERATED/pcarpscan/controllers et /usr/local/IA/pcArpScan/pcCrudGen.pcarpscan.tgz. Équivalent manuel : pcCrudGen mariadb pcArpScan.

Fichiers produits

Chemin Contenu
GENERATED/<base>/controllers/ Sources C++ des CGI + cgi_pch.hpp(.gch)
html/<base>/, web/<base>/ Pages PHP, JavaScript Tabulator
<web_root>/ Site prêt à servir (php/ js/ css/ cgi-bin/ sql/)
/etc/apache2/sites-available/<vhost>.conf Vhost HTTP + HTTPS
/etc/pcCrudGen/config.<vhost>[.example].json Configuration d'exécution des CGI (mot de passe : droits 0640, groupe www-data)
pcCrudGen.<base>.tgz Tarball portable (site + vhost + config + post-install + toolkit sous /usr/local)

Sécurité

  • Toutes les valeurs interpolées dans des commandes shell (chemins, hôtes, utilisateur, cible ssh, nom de base) sont validées par liste blanche avant usage ; une valeur douteuse arrête le programme avec un message explicite.
  • Les CGI générés utilisent des requêtes préparées ; les noms de colonnes venant du JSON sont filtrés par une liste blanche issue du schéma.
  • web_root/sql/ (dumps schéma + données) est protégé par un .htaccess « Require all denied » ; il reste présent dans le tarball.
  • Les mots de passe des dumps passent par l'environnement (PGPASSWORD, MYSQL_PWD) et non en argument visible dans ps.
  • Attention : le fichier .example.json embarqué dans le tarball contient le mot de passe de la base de développement. Ne diffusez pas le tarball hors de vos serveurs.

Dépannage

Symptôme Cause / solution
« CONFIG CREEE — A REVISER » Normal au premier lancement : éditer le JSON puis relancer.
« Aucun hôte DB joignable » Vérifier host/user/password ; la cascade essaie 4 hôtes.
« Configuration : caractère interdit dans … » Une valeur du config contient un caractère non autorisé (espace, ;, '…). La corriger.
« compile raté » (WARN) Lire l'erreur g++ au-dessus ; vérifier que build/libpccrudgen_multi.a existe (sinon cmake --build build).
Reload Apache échoué Certificat SSL absent : certbot --apache -d <vhost>.
Pagination : une seule page Corrigé en 1.55 (comptage exact sous 100 000 lignes).

Historique

1.55 (16/11/2026)

  • Correctif : --deploy était ignoré ; scp/ssh partaient dès que deploy.target était renseigné. L'envoi n'a plus lieu que si --deploy est donné.
  • Correctif : options inconnues et arguments en trop refusés (une faute de frappe devenait un nom de base).
  • Sécurité : validation par liste blanche (config + CLI) contre l'injection shell ; quoting des mots de passe de dump ; répertoire de staging créé par mkdtemp ; sql/ interdit en HTTP ; config avec mot de passe en 0640 ; requêtes d'introspection échappées.
  • CGI générés : clé primaire numérique acceptée (plantage type_error 302) ; paramètres de requête lus proprement (page ne matche plus last_page) ; pagination exacte pour les tables < 100 000 lignes (reltuples = -1 sous PostgreSQL) ; SQL MariaDB sans nom de base figé (la base de production peut différer).
  • Introspection : colonnes triées par ordinal_position (ordre déterministe).
  • Interface : version affichée dans « About » dynamique (était « 1.45 » en dur) ; Tabulator 6.2 ; code mort supprimé.

Améliorations suggérées (non faites)

  • Menu : la liste CALIBRE, CIP, ARME… est codée en dur dans ClassHtmlGenerator ; la sortir en configuration.
  • index.php ne charge les libellés labels_in_menu que pour PostgreSQL (MariaDB/SQLite : repli sur le nom brut).
  • Les std::system() restants gagneraient à être remplacés par posix_spawn sans shell.
  • Les classes ClassDatabase / ClassSchemaLoader (mode MONOBASE) sont signalées orphelines.
  • Ajouter des tests automatiques (génération sur SQLite temporaire + exécution du CGI).