Aller au contenu

Guide de développement

Ce guide détaille l'environnement de développement et les bonnes pratiques.

Environnement de développement

Prérequis

  • Python 3.11+ avec uv
  • Node.js 18+ avec npm
  • Docker pour devcontainer (optionnel)
  • MongoDB local ou distant

Installation

# Cloner le projet
git clone https://github.com/castorfou/back-office-lmelp.git
cd back-office-lmelp

# Backend
uv sync --extra dev
pre-commit install

# Frontend
cd frontend && npm install

Structure du projet

back-office-lmelp/
├── src/                    # Code Python backend
│   └── back_office_lmelp/  # Package principal
├── frontend/               # Application Vue.js
│   ├── src/               # Code source frontend
│   └── tests/             # Tests frontend
├── tests/                 # Tests backend
├── docs/                  # Documentation
└── pyproject.toml         # Configuration Python

Développement

Backend (FastAPI)

# Lancer le serveur de développement (sélection automatique de port)
PYTHONPATH=/workspaces/back-office-lmelp/src python -m back_office_lmelp.app

# Ou spécifier un port manuellement
API_PORT=54325 PYTHONPATH=/workspaces/back-office-lmelp/src python -m back_office_lmelp.app

# Tests
uv run pytest tests/ -v --cov=src

# Qualité de code
uv run ruff check .
uv run ruff format .
uv run mypy src/

Frontend (Vue.js)

cd frontend

# Serveur de développement
npm run dev

# Tests
npm test
npm run test:coverage

# Build
npm run build

Sélection automatique de port

Le backend implémente une sélection automatique de port pour éviter les conflits lors du développement.

Stratégie de priorité

  1. Variable d'environnement : API_PORT si définie (comportement manuel)
  2. Port préféré : 54321 (essai automatique)
  3. Plage de fallback : 54322-54350 (scan séquentiel)
  4. Attribution OS : En dernier recours si tous les ports sont occupés

Utilisation

# Démarrage automatique (recommandé)
python -m back_office_lmelp.app
# 🚀 Démarrage du serveur sur 0.0.0.0:54323 (port automatiquement sélectionné)

# Démarrage manuel (si besoin de port spécifique)
API_PORT=8000 python -m back_office_lmelp.app
# 🚀 Démarrage du serveur sur 0.0.0.0:8000

Avantages

  • ✅ Zero configuration : python -m back_office_lmelp.app fonctionne toujours
  • ✅ Résistant aux conflits : Gère les ports occupés gracieusement
  • ✅ Compatible : Variable d'environnement API_PORT toujours supportée
  • ✅ Feedback clair : Indication quand le port est sélectionné automatiquement

Dynamic Port Discovery

Le système de découverte dynamique de port synchronise automatiquement les ports entre le backend FastAPI et le proxy Vite du frontend.

Fonctionnement

  1. Backend : Au démarrage, écrit ses informations de port dans .dev-ports.json
  2. Frontend : Vite lit ce fichier au démarrage pour configurer le proxy automatiquement
  3. Nettoyage : Le fichier est supprimé à l'arrêt du backend

Fichier de découverte (/.dev-ports.json)

{
  "port": 54323,
  "host": "localhost",
  "timestamp": 1640995200,
  "url": "http://localhost:54323"
}

Configuration

  • Sélection automatique : Aucune configuration requise, port auto-découvert
  • Fallback frontend : Port 54322 si le fichier est manquant ou obsolète (>30s)
  • Développement : Permet de démarrer backend/frontend dans n'importe quel ordre

Tests

# Tests sélection automatique de port
PYTHONPATH=/workspaces/back-office-lmelp/src uv run pytest tests/test_automatic_port_selection.py -v

# Tests backend port discovery
PYTHONPATH=/workspaces/back-office-lmelp/src uv run pytest tests/test_dynamic_port_discovery.py -v

# Tests frontend port discovery
cd frontend && npm test -- --run tests/unit/PortDiscovery.test.js

Qualité de code

Pre-commit hooks

  • Formatage : Ruff, Prettier
  • Linting : Ruff, ESLint
  • Sécurité : detect-secrets
  • Validation : YAML, JSON, TOML

Standards

  • Python : PEP 8 avec Ruff
  • JavaScript : Standard avec ESLint
  • Tests : Couverture minimale 40%
  • Documentation : Docstrings obligatoires

CI/CD Pipeline

Déclencheurs

Le pipeline CI/CD se déclenche automatiquement sur : - Tous les pushs sur n'importe quelle branche (branches: ['**']) - Pull requests vers main

Cette configuration offre un feedback immédiat sur chaque commit, permettant une détection précoce des régressions.

Jobs exécutés

  • ✅ Tests backend (Python 3.11 + 3.12)
  • ✅ Tests frontend (Node.js 18)
  • ✅ Security scan (detect-secrets)
  • ✅ Quality gate (validation de tous les jobs)
  • 🚀 Déploiements (uniquement sur main)

Optimisations

  • Concurrence : Isolation par branche (cancel-in-progress: true)
  • Cache : Dependencies Python (uv) et Node.js (npm)
  • Déploiement conditionnel : Staging/Production uniquement sur main

Workflow de documentation (MkDocs)

Le pipeline de documentation fonctionne séparément du pipeline principal avec des déclencheurs conditionnels optimisés.

Configuration spécifique

# .github/workflows/docs.yml
on:
  push:
    branches: [ main ]
    paths: [ 'docs/**', 'mkdocs.yml' ]  # ⬅️ Déclenchement conditionnel

Déclencheurs

Le workflow MkDocs ne s'exécute que si : - Des fichiers dans le dossier docs/ sont modifiés - OU le fichier mkdocs.yml est modifié - ET le push est sur la branche main

Comportement normal

🟢 Workflow déclenché : 

# Modifications qui déclenchent le build de documentation
git add docs/dev/api.md mkdocs.yml
git commit -m "docs: update API documentation"
git push origin main
# ➜ Le workflow docs.yml s'exécute

🔴 Workflow PAS déclenché : 

# Modifications de code qui n'affectent pas la documentation
git add frontend/src/components/EpisodeEditor.vue
git commit -m "refactor: improve UI interface"
git push origin main
# ➜ Le workflow docs.yml ne s'exécute PAS

Avantages

  • ✅ Optimisation ressources : Évite les builds inutiles de documentation
  • ✅ Feedback rapide : PRs de code non impactées par le build docs
  • ✅ Économie CI/CD : Moins de minutes consommées
  • ✅ Séparation des responsabilités : Pipeline docs indépendant

Notes pour les développeurs

  • Si vous ne voyez pas le job MkDocs dans votre PR, c'est normal si vous n'avez pas modifié la documentation
  • Pour forcer un rebuild de la documentation, modifiez un fichier dans docs/ ou mkdocs.yml
  • La documentation est automatiquement déployée sur GitHub Pages quand le workflow se déclenche