---
title: Conventions de nommage
slug: oip-next/v4/conventions-de-nommage
icon: {"lucideIcon":"📘"}
createdAt: 2026-08-18T09:40:00.000Z
---

# 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`                               |

:::BlockQuote
**\[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`.

:::BlockQuote
**\[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`    |

:::BlockQuote
**\[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`               |

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

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

:::BlockQuote
**\[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`           |

:::BlockQuote
**\[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.
