OmniRoute/docs/i18n/fr/CONTRIBUTING.md

Contributing to OmniRoute (Français)

🌐 Languages: 🇺🇸 English · 🇪🇸 es · 🇫🇷 fr · 🇩🇪 de · 🇮🇹 it · 🇷🇺 ru · 🇨🇳 zh-CN · 🇯🇵 ja · 🇰🇷 ko · 🇸🇦 ar · 🇮🇳 hi · 🇮🇳 in · 🇹🇭 th · 🇻🇳 vi · 🇮🇩 id · 🇲🇾 ms · 🇳🇱 nl · 🇵🇱 pl · 🇸🇪 sv · 🇳🇴 no · 🇩🇰 da · 🇫🇮 fi · 🇵🇹 pt · 🇷🇴 ro · 🇭🇺 hu · 🇧🇬 bg · 🇸🇰 sk · 🇺🇦 uk-UA · 🇮🇱 he · 🇵🇭 phi · 🇧🇷 pt-BR · 🇨🇿 cs · 🇹🇷 tr

---

Merci de votre intérêt à contribuer ! Ce guide couvre tout ce dont vous avez besoin pour commencer.---

Development Setup

Prerequisites

-Node.js>= 18 < 24 (recommandé : 22 LTS) -npm10+ -Git### Clone & Install

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm install

Environment Variables

# Create your .env from the template
cp .env.example .env

# Generate required secrets
echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env
echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env

Variables clés pour le développement :

Variables	Développement par défaut	Descriptif
PORT	'20128'	Port du serveur
NEXT_PUBLIC_BASE_URL	http://localhost:20128	URL de base pour le frontend
JWT_SECRET	(générer ci-dessus)	Secret de signature JWT
INITIAL_PASSWORD	CHANGEME	Mot de passe de première connexion
APP_LOG_LEVEL	informations	Niveau de verbosité du journal	### Dashboard Settings

Le tableau de bord fournit des bascules d'interface utilisateur pour les fonctionnalités qui peuvent également être configurées via des variables d'environnement :

Emplacement du paramètre	Basculer	Descriptif
Paramètres → Avancé	Mode débogage	Activer les journaux de demandes de débogage (UI)
Paramètres → Général	Visibilité de la barre latérale	Afficher/masquer les sections de la barre latérale

Ces paramètres sont stockés dans la base de données et persistent lors des redémarrages, remplaçant les valeurs par défaut de la variable d'environnement lorsqu'elles sont définies.### Running Locally

# Development mode (hot reload)
npm run dev

# Production build
npm run build
npm run start

# Common port configuration
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

URL par défaut :

-Tableau de bord : http://localhost:20128/dashboard -API : http://localhost:20128/v1---

Git Workflow

⚠️**NE JAMAIS vous engager directement dans main.**Utilisez toujours des branches de fonctionnalités.```bash git checkout -b feat/your-feature-name

... make changes ...

git commit -m "feat: describe your change" git push -u origin feat/your-feature-name

Open a Pull Request on GitHub

### Branch Naming

| Préfixe | Objectif |
| ----------- | ------------------------- |
| `exploit/` | Nouvelles fonctionnalités |
| `réparer/` | Corrections de bugs |
| `refactor/` | Restructuration du code |
| `docs/` | Modifications de la documentation |
| `tester/` | Tester les ajouts/correctifs |
| `corvée/` | Outillage, CI, dépendances |### Commit Messages

Suivez [Conventional Commits](https://www.conventionalcommits.org/) :```
feat: add circuit breaker for provider calls
fix: resolve JWT secret validation edge case
docs: update SECURITY.md with PII protection
test: add observability unit tests
refactor(db): consolidate rate limit tables

Portées : db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.---

Running Tests

# All tests (unit + vitest + ecosystem + e2e)
npm run test:all

# Single test file (Node.js native test runner — most tests use this)
node --import tsx/esm --test tests/unit/your-file.test.mjs

# Vitest (MCP server, autoCombo, cache)
npm run test:vitest

# E2E tests (requires Playwright)
npm run test:e2e

# Protocol clients E2E (MCP transports, A2A)
npm run test:protocols:e2e

# Ecosystem compatibility tests
npm run test:ecosystem

# Coverage (60% min statements/lines/functions/branches)
npm run test:coverage
npm run coverage:report

# Lint + format check
npm run lint
npm run check

Notes de couverture :

• npm run test:coverage mesure la couverture des sources pour la suite de tests unitaires principale, exclut tests/** et inclut open-sse/**
• Les demandes d'extraction doivent maintenir la couverture globale à60 % ou pluspour les instructions, les lignes, les fonctions et les branches.
• Si un PR modifie le code de production dans src/, open-sse/, electron/ ou bin/, il doit ajouter ou mettre à jour des tests automatisés dans le même PR
• npm run cover:report imprime le rapport détaillé fichier par fichier de la dernière exécution de couverture
• npm run test:coverage:legacy préserve l'ancienne métrique pour une comparaison historique
• Voir docs/COVERAGE_PLAN.md pour la feuille de route d'amélioration progressive de la couverture### Pull Request Requirements

Avant d'ouvrir ou de fusionner un PR :

• Exécutez npm run test:unit
• Exécutez npm run test:coverage
• Assurez-vous que la porte de couverture reste à**60 %+**pour toutes les mesures
• Inclure les fichiers de test modifiés ou ajoutés dans la description du PR lorsque le code de production a changé
• Vérifiez le résultat SonarQube sur le PR lorsque les secrets du projet sont configurés dans CI

État actuel des tests :122 fichiers de tests unitairescouvrant :

• Fournisseur de traducteurs et conversion de format
• Limitation de débit, disjoncteur et résilience
• Cache sémantique, idempotence, suivi des progrès
• Opérations et schéma de base de données (21 modules DB)
• Flux OAuth et authentification
• Validation des points de terminaison API (Zod v4)
• Outils du serveur MCP et application de la portée
• Systèmes de mémoire et de compétences---

Code Style

-ESLint— Exécutez npm run lint avant de valider -Plus joli— Formatage automatique via lint-staged lors de la validation (2 espaces, points-virgules, guillemets doubles, largeur de 100 caractères, virgules finales es5) -TypeScript— Tout le code src/ utilise .ts/.tsx ; open-sse/ utilise .ts/.js ; document avec TSDoc ($@param, @returns, @throws) -Pas de eval()— ESLint applique no-eval, no-implicit-eval, no-new-func -Validation Zod— Utilisez les schémas Zod v4 pour toutes les validations d'entrée d'API -Nom : Fichiers = camelCase/kebab-case, composants = PascalCase, constantes = UPPER_SNAKE---

Project Structure

src/                        # TypeScript (.ts / .tsx)
├── app/                    # Next.js 16 App Router
│   ├── (dashboard)/        # Dashboard pages (23 sections)
│   ├── api/                # API routes (51 directories)
│   └── login/              # Auth pages (.tsx)
├── domain/                 # Policy engine (policyEngine, comboResolver, costRules, etc.)
├── lib/                    # Core business logic (.ts)
│   ├── a2a/                # Agent-to-Agent v0.3 protocol server
│   ├── acp/                # Agent Communication Protocol registry
│   ├── compliance/         # Compliance policy engine
│   ├── db/                 # SQLite database layer (21 modules + 16 migrations)
│   ├── memory/             # Persistent conversational memory
│   ├── oauth/              # OAuth providers, services, and utilities
│   ├── skills/             # Extensible skill framework
│   ├── usage/              # Usage tracking and cost calculation
│   └── localDb.ts          # Re-export layer only — never add logic here
├── middleware/              # Request middleware (promptInjectionGuard)
├── mitm/                   # MITM proxy (cert, DNS, target routing)
├── shared/
│   ├── components/         # React components (.tsx)
│   ├── constants/          # Provider definitions (60+), MCP scopes, routing strategies
│   ├── utils/              # Circuit breaker, sanitizer, auth helpers
│   └── validation/         # Zod v4 schemas
└── sse/                    # SSE proxy pipeline

open-sse/                   # @omniroute/open-sse workspace
├── executors/              # 14 provider-specific request executors
├── handlers/               # 11 request handlers (chat, responses, embeddings, images, etc.)
├── mcp-server/             # MCP server (25 tools, 3 transports, 10 scopes)
├── services/               # 36+ services (combo, autoCombo, rateLimitManager, etc.)
├── translator/             # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama)
├── transformer/            # Responses API transformer
└── utils/                  # 22 utility modules (stream, TLS, proxy, logging)

electron/                   # Electron desktop app (cross-platform)

tests/
├── unit/                   # Node.js test runner (122 test files)
├── integration/            # Integration tests
├── e2e/                    # Playwright tests
├── security/               # Security tests
├── translator/             # Translator-specific tests
└── load/                   # Load tests

docs/                       # Documentation
├── ARCHITECTURE.md         # System architecture
├── API_REFERENCE.md        # All endpoints
├── USER_GUIDE.md           # Provider setup, CLI integration
├── TROUBLESHOOTING.md      # Common issues
├── MCP-SERVER.md           # MCP server (25 tools)
├── A2A-SERVER.md           # A2A agent protocol
├── AUTO-COMBO.md           # Auto-combo engine
├── CLI-TOOLS.md            # CLI tools integration
├── COVERAGE_PLAN.md        # Test coverage improvement plan
├── openapi.yaml            # OpenAPI specification
└── adr/                    # Architecture Decision Records

---

Adding a New Provider

Step 1: Register Provider Constants

Ajouter à src/shared/constants/providers.ts — Validé par Zod au chargement du module.### Step 2: Add Executor (if custom logic needed)

Créez un exécuteur dans open-sse/executors/your-provider.ts en étendant l'exécuteur de base.### Step 3: Add Translator (if non-OpenAI format)

Créez des traducteurs de requête/réponse dans open-sse/translator/.### Step 4: Add OAuth Config (if OAuth-based)

Ajoutez les informations d'identification OAuth dans src/lib/oauth/constants/oauth.ts et le service dans src/lib/oauth/services/.### Step 5: Register Models

Ajoutez des définitions de modèle dans open-sse/config/providerRegistry.ts.### Step 6: Add Tests

Écrivez des tests unitaires dans tests/unit/ couvrant au minimum :

• Inscription du fournisseur
• Traduction requête/réponse
• Gestion des erreurs---

Pull Request Checklist

• Les tests réussissent (npm test)
• Passes de peluchage (npm run lint)
• La construction réussit (npm run build) -[ ] Types TypeScript ajoutés pour les nouvelles fonctions et interfaces publiques
• Pas de secrets codés en dur ni de valeurs de secours -[ ] Toutes les entrées validées avec les schémas Zod
• CHANGELOG mis à jour (si changement destiné à l'utilisateur)
• Documentation mise à jour (le cas échéant)---

Releasing

Les versions sont gérées via le workflow /generate-release. Lorsqu'une nouvelle version de GitHub est créée, le package estautomatiquement publié sur npmvia GitHub Actions.---

Getting Help

-Architecture : Voir docs/ARCHITECTURE.md -Référence API : Voir docs/API_REFERENCE.md -Problèmes : github.com/diegosouzapw/OmniRoute/issues -ADR : voir docs/adr/ pour les enregistrements de décisions architecturales