« Info::pcGrudGen README » : différence entre les versions
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 | |||
); | ); | ||
CREATE TABLE myTable2 ( | CREATE TABLE myTable2 ( | ||
id SERIAL PRIMARY KEY, | id SERIAL PRIMARY KEY, | ||
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— MarkdownpcCrudGen.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 :
- Lecture de
config.json(connexion, chemins, site cible). - Connexion au SGBD et introspection du schéma via
INFORMATION_SCHEMA (tables, colonnes, types, clés primaires,
clés étrangères).
- Chargement du dictionnaire
metadata.cfg(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
web_rootdu 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 :
- Dans la table A, nommez la colonne de liaison
fk_B_<colonneAffichage>.- Exemple : dans
MUNITION, la colonnefk_ARME_strARMEpointe versARMEet afficheraARME.strARME.
- Exemple : dans
- (Optionnel mais recommandé) déclarez aussi la contrainte
FOREIGN KEYen SQL pour l'intégrité référentielle. - (Optionnel) ajoutez une ligne dans
metadata.cfgpour le titre et l'infobulle de la colonne. - 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 parARME_list.cgi, affichantstrARMEet 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é
champXdevientstrChampX(préfixestr= texte) ; - le champ étranger
champEtrangerXdevientfk_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 parINFORMATION_SCHEMA) — mais dans ce cas crudgen ignore quelle colonne afficher et retombe sur la première colonnestr*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èresCLAUDE.md— conventions du projet