Conventions de nommage
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 |
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.
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 |
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 }] }
};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 |
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.