---
title: 📘 Guidelines de développement OIP
slug: oip-next/guidelines-de-developpement-oip
createdAt: 2026-04-01T16:29:43.000Z
---

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

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

:::CodeblockTabs
server/index.mjs

```javascript
import { Something } from 'something';

...

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

***

### Ajouter des routes ou API

📍 Fichier :

:::CodeblockTabs
server/routes.mjs

```javascript
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.

```javascript
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 :

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

❌ Interdit :

```javascript
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 :

:::CodeblockTabs
server/controllers/project/project.mjs

```javascript
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 :

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

***

## 🌍 Frontend sur un autre domaine (MFE)

Si votre front est hébergé ailleurs :

1. Définir `SERVER_URL` côté frontend
2. Configurer le CORS côté serveur
3. 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
