npm package: @sfp-group/cma-cgm-codeco
Description: Générateur de messages CODECO (EDI) pour CMA CGM - format SMDG21
Author: fickou
Latest version: 1.0.0

# 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

```bash
npm install
```

### Compilation

```bash
npm run build
```

### Utilisation Basique

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

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

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

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

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

### Workflow de Développement

1. **Développement** : Modification des fichiers dans `src/`
2. **Compilation** : `npm run build` pour générer `dist/`
3. **Test** : Validation avec des cas de test réels
4. **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.