📘 Guidelines de développement OIP

22 min

🎯 Objectif

Pour faciliter les évolutions et les migrations de votre projet via les scripts de migration, il est important de respecter certaines bonnes pratiques.

Ces guidelines ont pour but de garantir :

une structure de projet claire et homogène

une meilleure maintenabilité dans le temps

des migrations simplifiées entre versions OIP

🧱 Structure du projet

Les dossiers principaux du projet sont :

app → partie front-end (interface utilisateur)

server → partie back-end (logique serveur)

Le fonctionnement standard de ces éléments est déjà pris en charge par la dépendance @fasstech/oip-starter-utils, maintenue par l’équipe OIP.

👉 Important : Certains fichiers présents dans ces dossiers sont essentiels au bon fonctionnement de l’application.

➡️ Ne pas :

supprimer ces fichiers

les renommer

modifier leur structure sans indication

Des commentaires dans le code vous guideront sur les zones modifiables.

🔧 Ce que vous pouvez adapter

Vous pouvez personnaliser votre projet, notamment :

Les dossiers app et server (en respectant leur structure)

La configuration des vues (viewsConfig)

Les composants d’interface (views/[view]/client)

Les logiques serveur liées aux vues (views/[view]/server)

Les logiques partagées (views/_common)

Les fichiers de configuration (ex : vite.config.js)

✨ Bonnes pratiques de code

Pour garantir un code lisible et maintenable :

Utiliser des noms clairs et explicites

Respecter les conventions :

kebab-case → fichiers et dossiers

camelCase → variables et fonctions

PascalCase ou UPPER_SNAKE_CASE → constantes

📦 Gestion des dépendances

Versions

Toujours utiliser des versions fixes dans le package.json :

"dependencies": {
  "my-package": "1.0.0"
}

❌ Éviter les versions dynamiques (^1.0.0) qui peuvent créer des instabilités.

Organisation

Pour optimiser la qualité et la taille de votre application :

devDependencies → outils de développement (frontend + backend)

dependencies → uniquement ce qui est nécessaire en production

⚙️ Configuration du projet

Fichier de configuration OIP

📍 Emplacement :

server/oip.config.mjs

Initialisation du serveur

Pour ajouter de la logique au démarrage :

📍 Fichier :

import { Something } from 'something';

...

// init your business logic here
Something.start();

Ajouter des routes ou API

📍 Fichier :

import express from 'express';

const router = express.Router();

// a custom middleware on /api
router.use('/api', (req, res, next) => {
  console.log('My beautiful API');
  next();
});

// a custom endpoint on /api
router.get('/api/test', (req, res) => {
  res.send({ message: 'Dans la vie, il y a des cactus!' })
});

export default router;

⚠️ Pensez également à déclarer vos endpoints dans vite.config.js si nécessaire.

import { defineConfig, loadEnv } from 'vite';

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');

  return {
    ...
    server: {
      port: 8000,
      proxy: {
        ...
        // custom endpoint /api
        '/api': {
          target: `http://localhost:${env.PORT}`,
          changeOrigin: true
        }
      }
    }
  };
});

🧠 Gestion des données (OIP)

⚠️ Règle essentielle

Toujours utiliser les getters et setters OIP pour lire et écrire les données.

✅ Exemple :

getCustomerFirstName(customer);
setCustomerFirstName('John', customer);

❌ Interdit :

const lastName = customer.LastName;
customer.firstName = 'John';

👉 Pourquoi ? Sinon, si la donnée est chiffrée, elle ne sera pas déchiffrée sans passer par le getter; les scripts de migration ne fonctionneront pas correctement.

🚀 Initialisation du projet métier

Lors de la récupération du contexte utilisateur (via token), vous pouvez :

créer un projet

initialiser ses données

📍 Fichier :

import { Entities } from '@fasstech/oip-core';

export const initProjectFromContext = async (context) => {
  // setup your init logic project here

  const { externalId } = context;
  let project = await Entities('Project').get({ externalId });
  if (project) {
    return project;
  }

  project = await Entities('Project').create({ externalId });
  project = await Entities('Project').save(project);
  return project;
};

🔌 Extensions possibles

Vous pouvez étendre le framework OIP :

Ajouter des handlers personnalisés

Étendre le process métier

Ajouter des types GraphQL

👉 Pour ces cas, se référer à la documentation dédiée.

🌐 Gestion du CORS

Le serveur autorise par défaut toutes les origines.

Vous pouvez restreindre cela en configurant :

📍 server/index.mjs

Exemple :

corsOptions: {
  origin: [...],
  credentials: true
}

🌍 Frontend sur un autre domaine (MFE)

Si votre front est hébergé ailleurs :

Définir SERVER_URL côté frontend

Configurer le CORS côté serveur

Vérifier la gestion des sessions (cross-site)

🧩 À retenir

✔ Respecter la structure du projet ✔ Ne pas modifier les fichiers critiques ✔ Utiliser les outils fournis par OIP ✔ Écrire un code simple et clair ✔ Toujours passer par les getters/setters