---
title: Concepts clés
slug: oip-next/v4/concepts-cles
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-07T11:51:34.000Z
---

# Vue d'ensemble

Un OAV désigne l'ensemble des écrans utilisés par les professionnels de l'assurance pour vendre un produit.

Le développement d'un OAV à l'aide de l'OIP repose sur le principe *convention over configuration* : le développeur décrit **ce qu'il veut** dans des fichiers de configuration, et l'outillage génère **le code qui le réalise**.

Quatre notions structurent un OAV :

| Notion         | Question à laquelle elle répond                      |
| -------------- | ---------------------------------------------------- |
| **Entité**     | Quelles données l'OAV manipule-t-il ?                |
| **Vue**        | Quels écrans l'OAV présente-t-il ?                   |
| **Transition** | Comment passe-t-on d'un écran à l'autre ?            |
| **Tâche**      | Quels traitements asynchrones l'OAV déclenche-t-il ? |

Les briques logicielles qui les mettent en œuvre sont décrites dans la section « [Architecture](./001_introduction/003_architecture.md) ».

# Modèle de données

## Structure générale

Un modèle de données OIP repose sur une structure entité–relation organisée de manière arborescente.
L'entité racine est toujours nommée `Project`.

:::BlockQuote
Techniquement, l'outillage impose qu'il existe exactement une entité racine. La nommer `Project` est une convention appliquée par l'ensemble des modèles de projet.
:::

Toute entité autre que la racine est portée par une entité parente : elle n'existe pas indépendamment de l'arbre du projet.

## Définition d'une entité

Une entité est définie par un ensemble de propriétés.
Chaque propriété est décrite par :

- un type (e.g. chaîne de caractères) ;
- un ou plusieurs validateurs (e.g. longueur égale à 14 caractères) ;
- une règle RGPD (e.g. purge automatique).

### Types disponibles

| Type      | Variante tableau |
| --------- | ---------------- |
| `boolean` | `boolean[]`      |
| `date`    | `date[]`         |
| `number`  | `number[]`       |
| `object`  | `object[]`       |
| `string`  | `string[]`       |

Une propriété peut également porter une énumération (liste fermée de valeurs), une valeur par défaut, ou être déclarée en lecture seule.

### Validateurs

Un validateur est une règle évaluée avant chaque écriture de la propriété.

Plusieurs validateurs peuvent être combinés sur une même propriété ; ils sont alors évalués en conjonction dans l'ordre de leur déclaration.

### Règles RGPD

Deux mécanismes sont disponibles :

- le **chiffrement au repos**, qui s'applique à des propriétés désignées d'une entité ;
- la **purge automatique**, qui s'applique à l'arbre des entités et le supprime en intégralité après une période d'inactivité.

## Exemple de modèle simplifié

Ce modèle permet de représenter :

- un projet OAV (`Project`) contenant des compagnies (`Company`) et des bénéficiaires (`Grantee`) ;
- des compagnies associées à des comptes bancaires (`BankAccount`) ;
- des bénéficiaires associés à des adresses (`Address`).

```mermaid
erDiagram
    Project {
        string externalId
    }
    Company {
        string siret
    }
    Grantee {
        string firstName
        string lastName
    }
    BankAccount {
        string iban
    }
    Address {
        string country
    }
    Project }o--o{ Company : has
    Project }o--o{ Grantee : has
    Company }o--o{ BankAccount : has
    Grantee }o--o{ Address : has
```

## Déclaration du modèle

Le modèle se déclare au format OpenAPI. Les entités sont des schémas, les relations des références (`$ref`) entre schémas.

```yaml
openapi: 3.1.2

info:
  title: MyOAV
  version: 4.0.0

components:
  schemas:
    Project:
      type: object
      x-fasst-entity-category: OIP_ENTITY_ROOT
      description: Root entity containing all other entities
      required: ["externalId"]
      properties:
        externalId:
          description: External project identifier
          type: string
        companies:
          type: array
          items:
            $ref: "#/components/schemas/Company"
        grantees:
          type: array
          items:
            $ref: "#/components/schemas/Grantee"

    Company:
      type: object
      x-fasst-entity-category: OIP_ENTITY
      properties:
        siret:
          type: string
          exactLength: 14
        bankAccounts:
          type: array
          items:
            $ref: "#/components/schemas/BankAccount"
```

## Génération du code

Le modèle n'est pas interprété à l'exécution : il est compilé.

Pour une entité `Company`, les fonctions suivantes sont générées :

| Fonction                              | Rôle                                           |
| ------------------------------------- | ---------------------------------------------- |
| `createCompany`                       | Crée une instance et la rattache à son parent. |
| `getCompany`                          | Récupère une entité.                           |
| `listCompany`                         | Récupère la liste des entités.                 |
| `updateCompany`                       | Persiste les modifications locales.            |
| `deleteCompany`                       | Supprime l'entité.                             |
| `setCompanySiret` / `getCompanySiret` | Écrit / lit la propriété `siret`.              |

:::BlockQuote
Chaque entité générée expose, en plus de ses propres propriétés, cinq propriétés techniques en lecture seule : `__id`, `__type`, `__createdAt`, `__updatedAt` et `__auditInfo`.
:::

# Manipulation des données

```javascript
// Create an entity `Project`
let project = await createProject();
// Create and link an entity `Company` to the entity `project`
let company = await createCompany(project);

// Set property `siret` of the entity `company`
company = setCompanySiret("12345678901234", company);
// Set property `externalId` of the entity `project`
project = setProjectExternalId("aab2d285-0efa-48b6-a222-deeb3c35f258", project);

// Update the entity `company`
company = await updateCompany(company);
// Update the entity `project`
project = await updateProject(project);

// Search for an entity `Company` given property `siret`
company = await getCompany(project, { siret: "12345678901234" });
// Search for an entity `Project` given property `externalId`
project = await getProject({
  externalId: "aab2d285-0efa-48b6-a222-deeb3c35f258",
});

// Delete the entity `company`
await deleteCompany(company);
// Delete the entity `project` and all its descendants
await deleteProject(project, { withChildren: true });
```

- Les accesseurs sont curryfiés et retournent une nouvelle entité ; ils ne modifient pas l'entité passée en argument et n'écrivent rien en base ;
- seul l'appel à `update<Entity>` déclenche la persistance ;
- les validateurs sont appliqués au moment de l'écriture de la propriété, et non à la persistance : une valeur invalide lève une erreur dès l'appel au *setter*.

# Cohérence des données

Un système de transactions permett de garantir la cohérence des données.

Une transaction assemble plusieurs opérations d'écriture en une seule opération « tout ou rien ».

```javascript
let project;
const transactionId = await transaction();

project = await createProject();
project = setProjectExternalId("1", project);
project = await updateProject(project, { transactionId });

// Here, project's external id is 1

await rollbackTransaction(transactionId);

// Here, project's external id is null
```

Le modèle transactionnel de l'OIP présente trois particularités :

- il n'y a pas de commit. Chaque écriture est appliquée immédiatement et est visible aussitôt. L'identifiant de transaction ne fait que marquer les écritures ;
- l'annulation est un rejeu inverse. `rollbackTransaction` relit les états enregistrés sous cet identifiant, du plus récent au plus ancien, et inverse chaque opération : une création devient une suppression, une mise à jour restaure la valeur précédente ;
- l'annulation est elle-même tracée, sous la forme d'une nouvelle transaction, ce qui préserve l'auditabilité.

:::BlockQuote
Il n'existe ni expiration, ni annulation automatique, ni imbrication : une transaction reste ouverte tant qu'elle n'a pas été annulée.
:::

# Vues et transitions

## Vues

Une vue représente un écran du parcours. Elle possède :

- un identifiant (`viewId`), utilisé par le moteur de navigation ;
- une route (`pathname`), exposée au navigateur ;
- un répertoire (`directory`), contenant le composant React et ses *resolvers* GraphQL.

## Transitions

Une transition décrit comment quitter une vue. Elle couvre deux directions : `next` et `prev`.

Chaque direction se compose d'une liste ordonnée de destinations candidates.

```javascript
export default {
  next: {
    transitions: [
      {
        viewId: VIEW_IDS.COMPANY_SIRET,
        handler: (ctx) => ctx.transitionData.isCompany ?? false,
      },
      // No handler: always satisfied, acts as a fallback
      {
        viewId: VIEW_IDS.CUSTOMER_IDENTITY,
      },
    ],
  },
};
```

Le moteur applique une règle simple : la première destination satisfaite l'emporte.

```mermaid
sequenceDiagram
    participant View
    participant Orchestrator
    participant Transitions
    View->>Orchestrator: onNext()
    Transitions-->>Orchestrator: ctx.setup
    Orchestrator->>Transitions: handlers, in declared order
    Transitions-->>Orchestrator: first satisfied destination
    Orchestrator->>View: resolved viewId, then navigation
```

Si aucune destination n'est satisfaite, la résolution échoue explicitement.

## Navigation

```javascript
// Resolve the next view, then navigate
onNext();
// Resolve the previous view, then navigate
onPrev();

// Resolve the next view according to the given args, then navigate
onNext({ transitionData: { foo: "bar" } });
// Resolve the previous view according to the given args, then navigate
onPrev({ transitionData: { bar: "foo" } });

// Resolve the next view, then navigate and attach given args to the next view's context
onNext({ resolvedViewData: { foo: "bar" } });
// Resolve the previous view, then navigate and attach given args to the previous view's context
onPrev({ resolvedViewData: { foo: "bar" } });
```

Les arguments `transitionData` et `resolvedViewData` ne jouent pas le même rôle :

|                    | Rôle                                    | Consommé par                                                 | Durée de vie                                           |
| ------------------ | --------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------ |
| `transitionData`   | Entrée de la décision.                  | Les `handler` et les `hooks`, via le contexte de transition. | Le temps de la résolution.                             |
| `resolvedViewData` | Sortie transportée vers la vue résolue. | La vue de destination, via le contexte de l'OAV.             | Persisté avec le `Process` ; survit à un rechargement. |

## Process

L'état courant de l'OAV est porté par un objet `Process`, accessible depuis n'importe quel composant ou *resolver* :

| Champ       | Description                                                               |
| ----------- | ------------------------------------------------------------------------- |
| `projectId` | Identifiant du projet courant.                                            |
| `viewId`    | Identifiant de la vue active.                                             |
| `viewData`  | Métadonnées fournies lors de la dernière transition (`resolvedViewData`). |
| `sessionId` | Identifiant de la session de navigation.                                  |

Le `Process` est mis à jour par le moteur à chaque transition, de manière transparente.

# Opérations asynchrones

## Tâches asynchrones

Des tâches asynchrones peuvent être exécutées et suivies (e.g. envoi d'un e-mail).

Une tâche peut être déclenchée à la demande ou programmée périodiquement (`cron`).

Le serveur exécute chaque tâche dans un processus dédié : une tâche longue ou en échec ne bloque donc pas l'application. La tâche communique sa progression par messages.

```javascript
const handler = async () => {
  try {
    const summary = await doSomething();
    process.send?.({ action: "complete", metadata: summary });
    process.exit(0);
  } catch (error) {
    process.send?.({ action: "cancel", error: error.message });
    process.exit(1);
  }
};

if (process.send) process.on("message", handler);
```

Une tâche traverse trois états : `executing`, puis `completed` ou `cancelled`.

Côté client, des fonctions permettent de déclencher la tâche et s'abonner à ses notifications :

```javascript
// Start an async task `SendEmail`
onRunTask({
  taskName: "SendEmail",
  metadata: { foo: "bar" },
});

// Subscribe to the task notifications
const { data, error } = useSubscription(TaskSubscription, {
  taskName: "SendEmail",
});
// data: { taskId, taskName, projectId, state, metadata, error }
```

:::BlockQuote
Le `projectId` n'est jamais transmis par le client : le serveur le déduit du `Process` courant et l'utilise pour filtrer les notifications. Un client ne reçoit donc que les évènements de son propre projet.
:::

## Enchaînement de tâches asynchrones

Des enchaînements (*workflows*) de tâches asynchrones peuvent également être exécutées (e.g. procédure de signature électronique).

Un *workflow* est un graphe orienté acyclique de tâches. Une tâche ne démarre que lorsque toutes ses tâches parentes sont terminées, et hérite automatiquement de leurs métadonnées.

```mermaid
flowchart LR
    A[GenerateDocument] --> C[SendToSignature]
    B[FetchCustomerData] --> C
    C --> D[NotifyAdvisor]
```

```javascript
// Start an async task workflow `SendToSignature`
onRunTaskWorkflow({
  workflowName: "SendToSignature",
  metadata: { foo: "bar" },
});

// Subscribe to the tasks workflow' notifications
const { data, error } = useSubscription(TaskWorkflowSubscription, {
  workflowName: "SendToSignature",
});
// data: { taskId, taskName, workflowName, projectId, state, metadata, error }
```

L'abonnement à un *workflow* notifie chaque changement d'état de chaque tâche du *workflow* : le champ `taskName` permet d'identifier l'étape concernée.

# Glossaire

| Terme                  | Définition                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------ |
| **OAV**                | Outil d'Aide à la Vente, aussi appelé parcours de vente.                                               |
| **Entité**             | Objet représentant une donnée métier ou technique, identifié et décrit par un dictionnaire clé/valeur. |
| **Propriété**          | Donnée élémentaire d'une entité, typée et validée.                                                     |
| **Relation**           | Lien de parenté entre deux entités, constitutif de l'arbre du projet.                                  |
| **Vue**                | Écran du parcours, identifié par un `viewId` et exposé sur une route.                                  |
| **Transition**         | Règle de passage d'une vue à une autre, évaluée côté serveur.                                          |
| **Process**            | État courant de l'OAV : projet, vue active, métadonnées de vue, session.                               |
| **Décrochage**         | Phase d'entrée dans l'OAV : résolution du contexte client, du projet et de la première vue.            |
| **Tâche**              | Traitement asynchrone exécuté hors du cycle de requête.                                                |
| **Workflow de tâches** | Enchaînement de tâches organisé en graphe orienté acyclique.                                           |
| **Transaction**        | Marqueur regroupant des écritures, permettant leur annulation groupée.                                 |
| **Trame projet**       | Arbre complet des entités.                                                                             |

# Résumé

- Un OAV se décrit par quatre notions : les entités, les vues, les transitions et les tâches ;
- le modèle de données est déclaratif et arborescent : il est compilé en code, jamais interprété à l'exécution ;
- les écritures sont immédiates, historisées et annulables par transaction ;
- la navigation est résolue côté serveur, à partir de gardes évalués dans l'ordre de déclaration ;
- les traitements longs sont exécutés hors du cycle de requête et suivis par souscription.
