Conventions de nommage

14 min

Vue d'ensemble

Le nommage est, avec l'arborescence, le second pilier du principe convention over configuration. Plusieurs correspondances de noms sont vérifiées par l'outillage : un écart provoque une erreur de génération ou un comportement silencieusement inopérant.

Cette page recense les règles applicables à chaque catégorie d'objet d'un OAV.

Modèle de données

Entités et propriétés

Objet	Convention	Exemple
Nom d'entité	PascalCase, au singulier.	Project, Company, BankAccount
Nom de propriété	camelCase.	externalId, firstName, siret
Relation vers une collection	Nom de propriété au pluriel, de type tableau.	companies, grantees, bankAccounts
Entité racine	Nommée Project, de catégorie OIP_ENTITY_ROOT.	Project
Autres entités	Catégorie OIP_ENTITY.	Company

[info] L'outillage impose qu'il existe exactement une entité racine, identifiée par la catégorie OIP_ENTITY_ROOT. La nommer Project est une convention, appliquée par l'ensemble des modèles de projet.

Propriétés techniques

Chaque entité générée expose cinq propriétés techniques en lecture seule, préfixées de deux tirets bas : __id, __type, __createdAt, __updatedAt et __auditInfo.

[warn] Le préfixe __ est réservé à l'outillage. N'introduisez jamais de propriété métier portant ce préfixe.

Fonctions générées

Pour une entité Company, l'outillage produit des fonctions dont le nom est dérivé du nom de l'entité :

Fonction	Forme	Rôle
createCompany	create<Entity>	Crée une instance et la rattache à son parent.
getCompany	get<Entity>	Récupère une entité.
listCompany	list<Entity>	Récupère la liste des entités correspondant au critère.
updateCompany	update<Entity>	Persiste les modifications locales.
deleteCompany	delete<Entity>	Supprime l'entité.
getCompanySiret	get<Entity><Property>	Lit une propriété.
setCompanySiret	set<Entity><Property>	Écrit une propriété.

Vues

Objet	Convention	Exemple
viewId	Identifiant unique de la vue dans le parcours.	customer
Fichier de configuration	config/views/<NN>-<viewId>.yml, où <NN> indique l'ordre d'apparition dans le parcours.	01-customer.yml
directory	Nom du répertoire de génération du code de la vue.	customer
pathname	Chemin de la vue dans l'URL.	/customer
Composant React	PascalCase, dérivé du nom du répertoire.	Customer.jsx

[info] Le préfixe numérique du fichier de configuration est facultatif : il ne sert qu'à rendre l'ordre du parcours lisible dans l'arborescence. Le nom du fichier, préfixe retiré, correspond au viewId.

La casse retenue pour un viewId relève du projet. La seule règle stricte est la correspondance exacte entre le viewId et le nom du fichier de transition.

Transitions

Objet	Convention	Exemple
Fichier de transition	transitions/<viewId>.mjs.	transitions/customer.mjs
Handler d'une transition next	next__<viewId cible>.	next__company
Handler d'une transition prev	prev__<viewId cible>.	prev__home

const prev__home = () => true;
const next__company = () => true;

export default {
  prev: { transitions: [{ viewId: 'home', handler: prev__home }] },
  next: { transitions: [{ viewId: 'company', handler: next__company }] }
};

[warn] Chaque vue doit disposer de son fichier de transition. Si ce fichier est absent, mal nommé ou invalide, la génération des vues échoue.

GraphQL

Objet	Convention	Exemple
Resolver	camelCase, de la forme verbe + objet.	getCustomer, createCustomer
Fichier de resolver	views/<directory>/server/graphql/resolver/<resolver>.mjs.	getCustomer.mjs
Test de resolver	<resolver>.test.js.	getCustomer.test.js
Types GraphQL de la vue	QueryType.mjs, MutationType.mjs, queryTypeResolvers.mjs.	—
Query côté client	<Resolver>Query.js, en PascalCase.	GetCustomerQuery.js
Mutation côté client	<Resolver>Mutation.js, en PascalCase.	CreateCustomerMutation.js
Hook de query	use<Resolver>Query.	useGetCustomerQuery
Hook de mutation	use<Resolver>Mutation.	useCreateCustomerMutation

Tâches asynchrones

Objet	Convention	Exemple
Type de tâche	snake_case.	my_task, send_email
Fichier d'implémentation	tasks/<type>.mjs.	tasks/my_task.mjs
Type de workflow	snake_case.	my_workflow

[warn] La correspondance entre le type d'une tâche et le nom de son fichier d'implémentation est stricte. Un écart ne produit aucune erreur à la génération : la tâche est programmée, mais son code n'est jamais exécuté.

Fichiers et extensions

Catégorie	Convention	Exemple
Fichier de configuration	kebab-case.	env-vars.yml, vite.config.js
Module serveur	Extension .mjs.	server/index.mjs
Module client	Extension .js ou .jsx.	app/App.jsx
Configuration de vue	Extension .yml.	01-customer.yml
Migration	<timestamp>_migration.js.	1774963667201_migration.js
Test unitaire	<nom>.test.js.	getCustomer.test.js
Test d'intégration de vue	<Composant>.inte.test.jsx.	Customer.inte.test.jsx

Variables d'environnement

Les variables d'environnement s'écrivent en majuscules, les mots séparés par un tiret bas : SESSION_COOKIE_MAX_AGE, OIP_API_URL.

Les constantes exposées au client par Vite reprennent le nom de la variable, encadré de deux tirets bas de part et d'autre : CLIENT_ID devient __CLIENT_ID__.

Tableau récapitulatif

Élément	Nommage	Vérifié par l'outillage
Entité	PascalCase singulier	Oui
Propriété d'entité	camelCase	Oui
Fichier de configuration de vue	<NN>-<viewId>.yml	Partiellement
Fichier de transition	<viewId>.mjs	Oui
Handler de transition	next__<viewId> / prev__<viewId>	Non
Resolver	camelCase	Oui
Hook client	use<Resolver>Query / use<Resolver>Mutation	Généré
Type de tâche	snake_case	Non
Fichier de tâche	tasks/<type>.mjs	Oui, à l'exécution
Variable d'environnement	MAJUSCULES avec tirets bas	Oui, au démarrage

Résumé

Le nom d'une entité, d'une vue ou d'une tâche détermine celui des fichiers et des fonctions qui en découlent ;

trois correspondances sont strictes : viewId et fichier de transition, type de tâche et fichier d'implémentation, nom d'entité et répertoire généré ;

les modules serveur utilisent l'extension .mjs, les modules client .js ou .jsx ;

le préfixe __ est réservé aux propriétés techniques des entités et aux constantes exposées au client.