Aller au contenu principal

🔧 Microservices

Détail de chaque microservice de l'architecture Commerce Tracking.

🌐 API Gateway​

Vue d'ensemble​

Le Gateway API est le point d'entrée unique pour toutes les requêtes client. Il orchestre les communications entre les clients et les microservices backend.

Technologies​

  • Framework : NestJS 11.x
  • Langage : TypeScript 5.7.x
  • Communication : NATS Client
  • Validation : Class Validator & Class Transformer
  • Cache : Cache Manager (Redis compatible)

Structure du projet​

gateway-api/
├── src/
│   ├── admin/                    # Module d'administration
│   ├── auth/                    # Module d'authentification
│   │   ├── dto/                 # Data Transfer Objects
│   │   ├── auth.controller.ts   # Contrôleur d'authentification
│   │   ├── auth.service.ts      # Service d'authentification
│   │   ├── auth.guard.ts        # Guard d'authentification
│   │   └── auth.module.ts       # Module d'authentification
│   ├── common-data/             # Module des données communes
│   ├── trade-flow/              # Module des flux commerciaux
│   ├── filters/                 # Filtres d'exception
│   ├── interceptors/            # Intercepteurs
│   ├── nats-client/             # Client NATS
│   ├── shared/                  # Utilitaires partagés
│   ├── app.controller.ts        # Contrôleur principal
│   ├── app.module.ts           # Module principal
│   └── main.ts                 # Point d'entrée

Endpoints principaux​

// Authentification
POST /auth/login          # Connexion
POST /auth/logout         # Déconnexion
POST /auth/refresh        # Rafraîchissement token
GET  /auth/profile        # Profil utilisateur

// Collections
POST   /trade-flow/collections                    # Créer une collection
GET    /trade-flow/collections                    # Lister les collections
GET    /trade-flow/collections/:id                # Obtenir une collection
PUT    /trade-flow/collections/:id                # Modifier une collection
DELETE /trade-flow/collections/:id                # Supprimer une collection

// Données communes
GET /common-data/countries           # Pays
GET /common-data/currencies          # Devises
GET /common-data/products            # Produits

🔐 Auth Service​

Vue d'ensemble​

Le Auth Service gère l'authentification et l'autorisation des utilisateurs du système.

Technologies​

  • Framework : NestJS
  • Base de données : MySQL avec TypeORM
  • Communication : NATS Server
  • JWT : jsonwebtoken
  • Hashing : bcrypt

Fonctionnalités​

  • Authentification des utilisateurs
  • Génération et validation des tokens JWT
  • Gestion des sessions utilisateur
  • Contrôle d'accès basé sur les rôles
  • Rafraîchissement des tokens

Queues NATS​

// Messages d'authentification
'auth.login'           // Processus de connexion
'auth.validate'        // Validation des tokens
'auth.refresh'         // Rafraîchissement des tokens
'auth.logout'          // Déconnexion
'auth.profile'         // Récupération du profil

Modèle de données​

// User Entity
interface User {
  id: number;
  username: string;
  email: string;
  password: string;
  role_id: number;
  country_id: number;
  is_active: boolean;
  created_at: Date;
  updated_at: Date;
}

// Role Entity
interface Role {
  id: number;
  name: string;
  permissions: string[];
  level: number;
}

Workflow d'authentification​

sequenceDiagram
    participant C as Client
    participant G as Gateway
    participant A as Auth Service
    participant D as Database
    
    C->>G: POST /auth/login {credentials}
    G->>A: auth.login {username, password}
    A->>D: SELECT user WHERE username = ?
    D-->>A: User data
    A->>A: bcrypt.compare(password, hash)
    A->>A: Generate JWT token
    A-->>G: { token, user, expires_in }
    G-->>C: Authentication success

⚙️ Admin Service​

Vue d'ensemble​

Le Admin Service gère l'administration du système, les utilisateurs, les rôles et les données de référence.

Technologies​

  • Framework : NestJS
  • Base de données : MySQL avec TypeORM
  • Communication : NATS Server
  • Validation : Class Validator

Fonctionnalités​

  • Gestion des utilisateurs et rôles
  • Administration des acteurs commerciaux
  • Gestion des données de référence
  • Configuration système
  • Audit et logs d'administration

Queues NATS​

// Messages d'administration
'admin.users.create'     // Créer un utilisateur
'admin.users.update'     // Modifier un utilisateur
'admin.users.delete'     // Supprimer un utilisateur
'admin.roles.manage'     // Gestion des rôles
'admin.actors.manage'    // Gestion des acteurs
'admin.config.update'    // Configuration système

Modèles de données​

// Actor Entity
interface Actor {
  id: number;
  actor_role: string;
  first_name: string;
  last_name: string;
  email: string;
  phone: string;
  country_id: number;
  is_active: boolean;
  created_at: Date;
  updated_at: Date;
}

// Reference Data
interface ReferenceData {
  id: number;
  type: string; // 'country', 'currency', 'product', etc.
  code: string;
  name: string;
  description?: string;
  metadata?: any;
}

💰 TradeFlow Service​

Vue d'ensemble​

Le TradeFlow Service est le cœur métier du système, gérant les flux commerciaux, les collections et les validations.

Technologies​

  • Framework : NestJS
  • Base de données : MySQL avec TypeORM
  • Communication : NATS Server
  • Validation : Class Validator
  • Reporting : Custom reporting engine

Fonctionnalités​

  • Création et gestion des collections
  • Workflow de validation multi-niveaux
  • Collectes digitalisées
  • Génération de rapports et statistiques
  • Gestion des états et transitions

Queues NATS​

// Messages TradeFlow
'tradeflow.collections.create'     // Créer une collection
'tradeflow.collections.update'     // Modifier une collection
'tradeflow.collections.delete'     // Supprimer une collection
'tradeflow.collections.get'        // Récupérer une collection
'tradeflow.collections.list'       // Lister les collections
'tradeflow.validation.submit'      // Soumettre pour validation
'tradeflow.validation.approve'     // Approuver une validation
'tradeflow.validation.reject'      // Rejeter une validation
'tradeflow.reports.generate'       // Générer des rapports
'tradeflow.statistics.calculate'   // Calculer les statistiques

Modèles de données​

// Collection Entity
interface Collection {
  id: number;
  public_id: string;
  collection_date: Date;
  collector_id: number;
  status: 'draft' | 'submitted' | 'validated' | 'rejected';
  validation_level: number;
  data: any; // JSON data
  created_at: Date;
  updated_at: Date;
}

// Validation Entity
interface Validation {
  id: number;
  collection_id: number;
  validator_id: number;
  level: number;
  status: 'pending' | 'approved' | 'rejected';
  comments?: string;
  validated_at?: Date;
  created_at: Date;
}

Workflow de validation​

stateDiagram-v2
    [*] --> Draft: Create Collection
    Draft --> Submitted: Submit for Validation
    Submitted --> TeamManagerValidation: Level 1 Validation
    TeamManagerValidation --> Approved: Approve
    TeamManagerValidation --> Rejected: Reject
    TeamManagerValidation --> SupervisorValidation: Level 2 Validation
    SupervisorValidation --> Approved: Approve
    SupervisorValidation --> Rejected: Reject
    Rejected --> Draft: Return for Correction
    Approved --> [*]

📦 Model Service​

Vue d'ensemble​

Le Model Service gère les définitions de modèles de données, les types et les métadonnées du système.

Technologies​

  • Framework : NestJS
  • Base de données : MySQL avec TypeORM
  • Communication : NATS Server
  • Validation : JSON Schema

Fonctionnalités​

  • Définition des modèles de données
  • Gestion des types de produits et animaux
  • Configuration des workflows
  • Métadonnées système
  • Validation des schémas

Queues NATS​

// Messages Model
'model.definitions.get'    // Récupérer les définitions
'model.definitions.create' // Créer une définition
'model.types.list'         // Lister les types
'model.schemas.validate'   // Valider un schéma
'model.metadata.get'       // Récupérer les métadonnées

Modèles de données​

// Model Definition Entity
interface ModelDefinition {
  id: number;
  name: string;
  version: string;
  schema: any; // JSON Schema
  fields: ModelField[];
  created_at: Date;
  updated_at: Date;
}

// Model Field Entity
interface ModelField {
  id: number;
  model_definition_id: number;
  name: string;
  type: string;
  required: boolean;
  validation_rules?: any;
  metadata?: any;
}

🗄️ Base de données MySQL​

Configuration​

  • Port : 3340
  • Engine : InnoDB
  • Charset : UTF8MB4
  • ORM : TypeORM
  • Migrations : Automatiques

Schéma principal​

-- Tables principales
users                    # Utilisateurs du système
roles                    # Rôles et permissions
actors                   # Acteurs commerciaux
collections             # Collections de données
validations             # Validations multi-niveaux
reference_data          # Données de référence
model_definitions       # Définitions de modèles
audit_logs              # Logs d'audit

-- Tables de référence
countries               # Pays
currencies              # Devises
products                # Produits
animals                 # Animaux
transport_modes         # Modes de transport
regions                 # Régions géographiques
districts               # Districts
cities                  # Villes

Relations principales​

erDiagram
    users ||--o{ collections : creates
    users ||--o{ validations : validates
    roles ||--o{ users : assigned_to
    collections ||--o{ validations : has
    countries ||--o{ users : located_in
    countries ||--o{ actors : located_in
    actors ||--o{ collections : collects

📡 Communication NATS​

Configuration NATS​

// Configuration du client NATS
{
  servers: ['nats://localhost:4222'],
  reconnect: true,
  maxReconnectAttempts: 10,
  reconnectTimeWait: 2000,
  timeout: 5000,
  maxPayload: 1024 * 1024, // 1MB
}

Patterns de communication​

// Request-Response Pattern
const response = await natsClient.send('auth.validate', { token });

// Publish-Subscribe Pattern
natsClient.emit('tradeflow.collection.created', { collectionId });

// Queue Groups
natsClient.subscribe('tradeflow.validation', { queue: 'validation-workers' });

Gestion des erreurs​

// Timeout handling
try {
  const response = await natsClient.send('auth.validate', { token }, { timeout: 5000 });
} catch (error) {
  if (error.code === 'TIMEOUT') {
    // Handle timeout
  }
}

// Retry mechanism
const maxRetries = 3;
for (let i = 0; i < maxRetries; i++) {
  try {
    const response = await natsClient.send('service.action', data);
    break;
  } catch (error) {
    if (i === maxRetries - 1) throw error;
    await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
  }
}

Cette architecture microservices permet une évolution indépendante de chaque service tout en maintenant la cohérence globale du système. Chaque service peut être développé, testé et déployé séparément.