@fickou/cma-cgm-codeco

CMA CGM CODECO Generator

Un générateur TypeScript robuste pour créer des messages CODECO (Container Discharge/Loading Order) conformes aux standards EDI UN/EDIFACT D.95B et aux spécifications SMDG21.

À Propos

Ce projet développe une solution complète de génération de messages CODECO pour l'échange standardisé d'informations sur les mouvements de conteneurs entre les terminaux portuaires et les systèmes de gestion. Il implémente les spécifications du format EDI CODECO utilisé dans l'industrie maritime internationale.

Contexte Technique

CODECO (Container Discharge/Loading Order) est un message EDI standardisé défini par les Nations Unies dans le cadre UN/EDIFACT qui permet de communiquer les informations relatives aux mouvements de conteneurs dans les ports. Cette implémentation suit les directives SMDG (Ship Management and Cargo Data Group) version 21.

Fonctionnalités Principales

Génération de Messages

• ✅ Messages CODECO Gate In (34) : Entrée de conteneurs au terminal
• ✅ Messages CODECO Gate Out (36) : Sortie de conteneurs du terminal
• ✅ Format EDI UN/EDIFACT D.95B : Conformité aux standards internationaux
• ✅ Spécifications SMDG21 : Support complet des codes et segments

Validation et Qualité

• ✅ Validation stricte des données : Contrôle de cohérence et de format
• ✅ Types TypeScript complets : Sécurité de typage et IntelliSense
• ✅ Gestion des erreurs : Messages d'erreur détaillés et multilingues
• ✅ Validation des contraintes métier : Respect des règles CODECO

Support des Standards

• ✅ Formats de date multiples : 102, 203, 303, 610 selon les besoins
• ✅ Codes de scellement standardisés : CA, CU, SH, TO, AB
• ✅ Statuts d'équipement : Export, Import, Transbordement
• ✅ Indicateurs de conteneur : Plein, Vide

Architecture du Projet

cma-cgm-codeco/
├── src/
│   ├── index.ts          # API principale et générateur de messages
│   ├── interface.ts      # Définitions des types et énumérations
│   └── validator.ts      # Système de validation robuste
├── dist/                 # Code compilé (généré par build)
├── package.json          # Configuration NPM et dépendances
├── tsconfig.json         # Configuration TypeScript
└── README.md            # Documentation du projet

Composants Principaux

index.ts - Générateur Principal

• Fonction createMessage() : API principale de génération
• Fonction createMessageStream() : Génération de streams pour fichiers/HTTP
• Fonction formatDateHelper() : Utilitaire de formatage de dates
• Logique de construction des segments EDI
• Calcul automatique des longueurs de message

interface.ts - Définitions de Types

• Type Message : Structure complète du message CODECO
• Type ContainerMessage : Informations par conteneur
• Énumérations : MessageType, EquipmentStatus, ContainerIndicator, SealingPartyCoded
• Type MessageOptions : Options de génération

validator.ts - Système de Validation

• Validation par schémas configurables
• Support des types complexes (objets, tableaux, énumérations)
• Messages d'erreur localisés en français
• Modes de validation strict et permissif

Installation et Utilisation

Prérequis

• Node.js >= 14.x
• TypeScript >= 4.x

Installation des Dépendances

npm install

Compilation

npm run build

Utilisation Basique

import { 
  createMessage, 
  createMessageStream,
  MessageType, 
  EquipmentStatus, 
  ContainerIndicator, 
  SealingPartyCoded 
} from './dist/index.js';

// Configuration du message
const message = {
  controlRef: "12345",
  senderId: "MGEHLDTER",
  receiverId: "CMACGM",
  navireName: "MSC_OSCAR",
  containers: [
    {
      reference: "MSCU9876543",
      status: EquipmentStatus.export,
      indicator: ContainerIndicator.full,
      bookingRef: "BK2024001",
      sealNumber: "SEAL789456",
      sealingPartyCoded: SealingPartyCoded.Carrier,
      movementAt: new Date('2024-12-20T14:30:00Z')
    }
  ]
};

// Options de génération
const options = {
  generatedAt: new Date(),
  syntaxType: 2 // UNOA:2
};

// Génération du message CODECO
try {
  const codecoLines = createMessage(MessageType.gateIn, message, options);
  const codecoMessage = codecoLines.join('\n');
  console.log(codecoMessage);
} catch (error) {
  console.error('Erreur de génération:', error.message);
}

Validation Personnalisée

import { validateData, validateDataSafe, messageSchema } from './dist/validator.js';

// Validation avec exception
try {
  validateData(message);
  console.log('✅ Message valide');
} catch (error) {
  console.error('❌ Validation échouée:', error.message);
}

// Validation sécurisée (sans exception)
const errors = validateDataSafe(message);
if (errors.length === 0) {
  console.log('✅ Message valide');
} else {
  console.error('❌ Erreurs trouvées:', errors);
}

Génération de Stream (Nouveau)

La bibliothèque supporte maintenant la génération de streams pour une intégration facilité avec les systèmes de fichiers et les réponses HTTP.

import { createMessageStream } from './dist/index.js';
import { writeFile, createWriteStream } from 'fs';

// Génération de stream non compressé (avec sauts de ligne)
const streamOptions = {
  generatedAt: new Date(),
  syntaxType: 2,
  compress: false // Par défaut : false
};

const stream = createMessageStream(MessageType.gateIn, message, streamOptions);

// Utilisation 1: Écriture directe dans un fichier
const fileStream = createWriteStream('codeco-message.edi');
stream.pipe(fileStream);

// Utilisation 2: Réponse HTTP Express.js
app.get('/codeco/:messageId', (req, res) => {
  const stream = createMessageStream(MessageType.gateOut, message, {
    compress: true // Sans sauts de ligne pour HTTP
  });
  
  res.setHeader('Content-Type', 'application/edi-x12');
  res.setHeader('Content-Disposition', 'attachment; filename="codeco.edi"');
  stream.pipe(res);
});

// Utilisation 3: Lecture complète du stream
async function getMessageContent() {
  const stream = createMessageStream(MessageType.gateIn, message, streamOptions);
  
  let content = '';
  for await (const chunk of stream) {
    content += chunk.toString();
  }
  
  return content;
}

Options de Compression

• compress: false (défaut) : Les segments EDI sont séparés par des sauts de ligne (\n)
• compress: true : Les segments sont concaténés sans séparateur pour un format compact

// Mode non compressé - Lisible
const uncompressed = createMessageStream(MessageType.gateIn, message, { compress: false });
// Résultat:
// UNB+UNOA:2+...+12345'
// UNH+12345+...+12345'
// BGM+34+12345+5'
// ...

// Mode compressé - Compact pour transmission
const compressed = createMessageStream(MessageType.gateIn, message, { compress: true });
// Résultat:
// UNB+UNOA:2+...+12345'UNH+12345+...+12345'BGM+34+12345+5'...

Spécifications Techniques

Types de Messages Supportés

Type	Code	Description	Usage
Gate In	34	Entrée de conteneur	Arrivée au terminal
Gate Out	36	Sortie de conteneur	Départ du terminal

Statuts d'Équipement

Statut	Code	Description
Export	2	Conteneur à l'export
Import	3	Conteneur à l'import
Transbordement	6	Conteneur en transit

Indicateurs de Conteneur

Indicateur	Code	Description
Vide	4	Conteneur vide
Plein	5	Conteneur chargé

Parties Responsables du Scellement

Partie	Code	Description
Transporteur	CA	Carrier
Douanes	CU	Customs
Expéditeur	SH	Shipper
Opérateur Terminal	TO	Terminal Operator
Inconnu	AB	Unknown/Other

Formats de Date EDI

Code	Format	Exemple	Utilisation
102	YYYYMMDD	20241220	Dates simples
203	YYYYMMDDHHMM	202412201430	Dates avec heure
303	YYYYMMDDHHMMSS	20241220143045	Horodatage précis
610	WWYYYY	512024	Semaine/année

Structure du Message CODECO Généré

Un message CODECO complet suit cette structure EDI standardisée :

UNB+UNOA:2+MGEHLDTER+CMACGM+241220:1430+12345'          # En-tête interchange
UNH+12345+CODECO:D:95B:UN:SMDG21+12345'                 # En-tête message
BGM+34+12345+5'                                          # Début de message
TDT+20++1++:172:20'                                      # Transport
NAD+MS+MGEHLDTER'                                        # Expéditeur
NAD+CA+MSC_OSCAR:160:20'                                 # Navire
EQD+CN+MSCU9876543+4210:102:5++2+5'                    # Équipement
RFF+BN:BK2024001'                                       # Référence
DTM+203:20241220143000:203'                             # Date/heure
LOC+165+MGEHL:139:6+MGEHLDTER:TER:ZZZ'                  # Localisation
MEA+AAE+G+KGM:24280'                                    # Poids
SEL+SEAL789456+CA'                                       # Scellé
CNT+1:1'                                                # Compteur
UNT+13+12345'                                           # Fin message
UNZ+1+12345'                                            # Fin interchange

Explication des Segments

• UNB : En-tête d'interchange (expéditeur, destinataire, horodatage)
• UNH : En-tête de message (type CODECO, version D.95B)
• BGM : Début du message (type d'opération, référence)
• TDT : Informations de transport
• NAD : Nom et adresse (terminal, navire)
• EQD : Détails de l'équipement (conteneur, statut, indicateur)
• RFF : Référence de réservation
• DTM : Date et heure du mouvement
• LOC : Localisation géographique
• MEA : Mesures (poids, dimensions)
• SEL : Information de scellé
• CNT : Compteur de conteneurs
• UNT : Fin de message
• UNZ : Fin d'interchange

Validation et Contrôles Qualité

Règles de Validation Appliquées

Validation des Champs Obligatoires

• controlRef : Référence de contrôle (max 14 caractères)
• senderId, receiverId : Identifiants des parties (max 35 caractères)
• navireName : Nom du navire (max 35 caractères)
• containers : Liste non vide de conteneurs

Validation des Conteneurs

• reference : Référence conteneur (max 11 caractères, format ISO)
• status : Statut valide (export/import/transbordement)
• indicator : Indicateur valide (plein/vide)
• bookingRef : Référence de réservation (max 35 caractères)
• sealNumber : Numéro de scellé (max 20 caractères)
• sealingPartyCoded : Partie responsable valide
• movementAt : Date de mouvement valide

Validation des Formats

• Dates : Validation de la cohérence des dates
• Énumérations : Vérification des valeurs autorisées
• Longueurs : Respect des limites EDI
• Types : Contrôle de typage strict

Messages d'Erreur Localisés

Le système de validation produit des messages d'erreur en français, détaillés et précis :

Validation échouée :
message.controlRef est obligatoire
message.containers[0].reference ne peut dépasser 11 caractères
message.containers[0].status doit être parmi: 2, 3, 6
message.containers[1].movementAt doit être une date valide

Développement et Contribution

Structure de Développement

Le projet utilise TypeScript avec une configuration stricte pour assurer la qualité du code :

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs", 
    "strict": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "outDir": "dist"
  }
}

Workflow de Développement

• Développement : Modification des fichiers dans src/
• Compilation : npm run build pour générer dist/
• Test : Validation avec des cas de test réels
• Documentation : Mise à jour du README si nécessaire

Standards de Code

• Typage strict : Tous les types doivent être explicites
• Validation complète : Toute donnée d'entrée doit être validée
• Gestion d'erreurs : Messages d'erreur clairs et exploitables
• Documentation : Commentaires pour la logique métier complexe

Support et Maintenance

Compatibilité

• Node.js : Versions LTS supportées (14.x, 16.x, 18.x, 20.x)
• TypeScript : Compatible avec 4.x et 5.x
• Standards EDI : UN/EDIFACT D.95B, SMDG21

Dépendances

Le projet maintient un nombre minimal de dépendances :

• Production : dayjs pour la manipulation des dates
• Développement : typescript pour la compilation

Roadmap

• Support des messages CODECO additionnels (discharge, loading)
• Validation étendue avec règles métier CMA CGM
• Export en formats multiples (JSON, XML, CSV)
• Interface de test et d'validation interactive
• Documentation API complète avec exemples

Licence

Projet privé CMA CGM - Tous droits réservés

Ce logiciel est la propriété de CMA CGM et est destiné à un usage interne uniquement. Toute reproduction, distribution ou modification sans autorisation expresse est interdite.