Migration

22 min

Documentation détaillée des changements requis au niveau de la code-base d'un projet v4.

Mise à jour des dépendances

Mettre à jour les versions des dépendances suivantes dans le fichier package.json du projet :

{
  "dependencies": {
    "@fasstech/oip-core": "4.0.0-rc.3",
    "@fasstech/oip-starter-utils": "4.0.0-rc.10",
    "@fasstech/rabbitmq-helper": "0.1.0",
    "dotenv": "17.2.3", // ajout
    "express": "5.2.1",
    "graphql-tag": "2.12.6",
    "node-pg-migrate": "8.0.4", // ajout
    "pg": "8.18.0" // ajout
  },
  "devDependencies": {
    "@apollo/client": "4.1.3",
    "@fasstech/oip-tools": "4.0.0-rc.6",
    "@vitejs/plugin-react-swc": "4.2.3",
    "react": "19.2.4",
    "react-dom": "19.2.4",
    "rxjs": "7.8.2",
    "vite": "7.3.1"
  }
}

Puis installer les mises à jour :

npm i

Suppression des commandes views:build et config:gen

Dans le fichier package.json supprimer :

le script views:build

le script config:gen

Le build des vues est maintenant fusionné avec la commande views:gen :

{
	"scripts": {
		"views:gen": "oip-tools views generate"
	}
}

Support des migrations automatisées du modèle de données

Ajout du script de migration

Créer le fichier scripts/run-migrations.sh à la racine du projet :

#!/bin/sh

DATABASE_URL=postgres://postgres:postgres@localhost:5432/<my-oav-database>

if [ -n "$1" ]; then
  DATABASE_URL=$1
fi

DATABASE_URL=$DATABASE_URL PGSSLMODE=disable node node_modules/.bin/node-pg-migrate up --migrations-table data_migrations

Éditer le script pour remplacer <my-oav-database> par le nom de la database de l'OAV du projet.

Ajout de la commande de migration

Ajouter la commande migrate:dev et start-server:dev dans le fichier package.json :

{
	"scripts": {
		"migrate:dev": "./scripts/run-migrations.sh",
		"start-server:dev": "npm run migrate:dev && npm run server:dev"
	}
}

La commande start-server:dev assure d'appliquer les migrations en attente avant le démarrage du serveur.

Dossier des fichiers de migration

Créer le dossier migrations à la racine du projet (créer un fichier .gitkeep à l'intérieur si le dossier est vide).

C'est dans ce dossier que sont placés les fichiers SQL relatifs aux migrations du modèle de données ainsi que le script d'initialisation de la donnée du projet.

À l'ajout d'un fichier de migration dans le dossier, penser à run la commande suivante pour appliquer la migration :

npm run migrate:dev

Mise à jour des fichiers des entités

Exécuter la commande suivante pour mettre à jour les fichiers générés des entités dans le dossier entities à la racine du projet.

npm run entities:gen

Dossier des fichiers de transition des vues

Déplacer le dossier des fichiers de transition des vues config/views/transitions à la racine du projet => transitions

Utiliser la fonctionnalité « Refactor » de l'IDE pour mettre à jour les chemins des imports impactés dans les fichiers de transition.

!! Ne pas utiliser des alias d'import comme @@entities dans les fichiers de transition !!

Fichier nodemon.json

Éditer le fichier nodemon.json à la racine du projet pour gérer le déplacement du dossier transitions des vues :

// before
{
	"watch": ["config/views/transitions/*", "./server/**/*", "./views/server.mjs", "./views/**/server/**/*"]
}

// after
{
  "watch": ["./server/**/*", "./transitions/**/*", "./views/**/server/**/*"]
}

Dossier des vues

Racine du dossier des vues

Supprimer les fichiers client.js et server.mjs à la racine du dossier views.

Dossier _common

supprimer les fichiers TaskSubscription.js et TaskWorkflowSubscription.js du dossier _common/client/graphql/subscriptions

supprimer les fichiers useCommitMutation.js et useSubscription.js du dossier _common/client/hooks

supprimer le fichier validateResolverContext.js du dossier _common/server/helpers

→ Ces fichiers sont maintenant exportés depuis la lib @fasstech/oip-starter-utils

Fichiers client non-générés

Dans les fichiers client non-générés des vues (qui ne possèdent pas le commentaire en en-tête indiquant que le fichier est généré par CLI), remplacer le path d'import de useCommitMutation, useSubscription, TaskSubscription et TaskWorkflowSubscription par @fasstech/oip-starter-utils/app.

Exemple :

// after
import { useCommitMutation, useSubscription, TaskSubscription, TaskWorkflowSubscription } from '@fasstech/oip-starter-utils/app';

Resolvers des vues

Remplacer le path d'import de l'helper validateResolverContext si utilisé dans les resolvers :

// before
import { validateResolverContext } from '_common/server/helpers/validateResolverContext.js';

// after
import { validateResolverContext } from '@fasstech/oip-starter-utils/server';

Header des fichiers générés

Remplacer le commentaire des fichiers générés :

// before
/**
 *
 * WARNING : fichier généré par cli, ne pas le modifier directement
 *
 */

// after
// Code generated by gen. DO NOT EDIT.

Lancer la génération des vues

Enfin, lancer la commande de génération des vues pour terminer la migration des vues :

npm run views:gen

Vérification de la configuration de Jest côté serveur

Dans le cas où les resolvers graphQL des vues sont testés via Jest, s'assurer d'avoir mocké les fonctions importées dans les resolvers depuis @fasstech/oip-starter-utils/server.

Exemple d'un fichier server/__mocks__/oip-server-mock.mjs qui mock les appels OK, KO et validateResolverContext :

/**
 * Mock pour @fasstech/oip-starter-utils/server
 */

export const validateResolverContext = (expectedViewId, actualViewId) => {
  // Lance une exception si les viewIds ne correspondent pas
  if (expectedViewId !== actualViewId) {
    throw new Error(`Invalid resolver context: expected ${expectedViewId} but got ${actualViewId}`);
  }

  return true;
};

// Export OK et KO qui sont également utilisés dans les resolvers
export const OK = (data) => ({ ok: true, ...data });
export const KO = (error) => ({ ok: false, error });

export default {
  validateResolverContext,
  OK,
  KO
};

Puis au niveau du fichier de configuration de Jest côté serveur, s'assurer de charger correctement le mock grâce à la propriété moduleNameMapper :

export default {
  moduleNameMapper: {
    // ...
    '^@fasstech/oip-starter-utils/server$': '<rootDir>/server/__mocks__/oip-server-mock.mjs'
  }
};

Index du serveur

Dans le fichier server/index.mjs du projet :

supprimer l'import et l'utilisation des définitions des types graphQL des vues loadSchemaTypes

ajouter le chargement de la config dotenv en 1ère position des imports du fichier

Exemple :

import 'dotenv/config'; // ajout

import loadSchemaTypes from '../views/server.mjs'; // suppression

const schemaTypes = await loadSchemaTypes(); // suppression

// before
let serverConfig = {
	// ...
	graphql: {
    resolvers: R.concat(R.pipe(R.map(R.prop('resolvers')), R.reject(R.anyPass([R.isNil, R.isEmpty])))([...schemaTypes, ...myCustomTypesWithResolvers]), [myCustomResolvers]),
    typeDefs: R.concat(R.map(R.prop('typeDefs'), schemaTypes), [ExtendedProcessType, ...myCustomTypes])
  },
};

// after
let serverConfig = {
	// ...
	graphql: {
    resolvers: R.concat(R.pipe(R.map(R.prop('resolvers')), R.reject(R.anyPass([R.isNil, R.isEmpty])))(myCustomTypesWithResolvers), [myCustomResolvers]),
    typeDefs: [ExtendedProcessType, ...myCustomTypes]
  },
};

Build et déploiement

Attention, les instructions suivantes sont peut-être à adaptées si besoin, selon les spécificités du projet.

Fichier Dockerfile

Dans le fichier Dockerfile du projet, appliquer les changements suivants :

Supprimer la totalité du stage config

Supprimer les instructions qui font référence au stage config dans le fichier (notamment les instructions avec --from=config)

S'assurer que les instructions suivantes existent dans le dernier stage du fichier, les ajouter si nécessaire :

COPY --chown=node:node ./migrations /usr/src/app/migrations
COPY --chown=node:node ./entities /usr/src/app/entities
COPY --chown=node:node ./transitions /usr/src/app/transitions

Éditer l'instruction finale CMD :

# before
CMD ["dumb-init", "node", "server/index.mjs"]

# after
ENTRYPOINT ["dumb-init", "--"]
CMD ["sh", "-c", "DATABASE_URL=$DATABASE_URL PGSSLMODE=$DATABASE_SSLMODE node node_modules/.bin/node-pg-migrate up --migrations-table data_migrations && node server/index.mjs"]

Tester le build de l'image de l'OAV avec la commande suivante :

docker buildx build --build-arg BUILD_DATE=<DATE> --secret id=npmrc,src=<PATH> -t fasstech/oip-starter-v4:latest --no-cache .

Fichiers docker-compose.yml et les environnements Portainer (dev, recette, prod, etc.)

Mettre à jour le tag de l'image fasstech/oip-headless des services oip-headless-api en 0.0.22

Au niveau de l'environnement du service de l'OAV :

ajouter la variable DATABASE_URL, la valeur attendue correspond à l'URL de la database de l'OAV de votre projet

ajouter la variable DATABASE_SSLMODE, avec pour valeur require pour un env de production ou disable pour un env de développement