Skip to content

FFCK/kpi

BranchesTags

Repository files navigation

KPI - Système de gestion sportive

KPI est un système de gestion pour les compétitions de kayak-polo, gérant les équipes, matchs, joueurs et statistiques.

🏗️ Architecture

Le projet combine plusieurs technologies :

  • Backend PHP : PHP 7.4/8.x avec API REST
  • Frontend moderne : Nuxt 4 (Vue 3 + TypeScript + Tailwind CSS) dans sources/app2/
  • Applications legacy : Vue.js dans sources/app_dev/, app_live_dev/, app_wsm_dev/
  • CMS : WordPress pour le contenu éditorial
  • Infrastructure : Docker Compose avec Traefik pour le reverse proxy
  • Base de données : MySQL/MariaDB (2 bases : KPI + WordPress)

🚀 Quick Start

Prérequis

  • Docker et Docker Compose
  • Make
  • Git

Installation initiale

  1. Cloner le repository
git clone https://github.com/FFCK/kpi.git
cd kpi
  1. Initialisation complète
make init

Cette commande va :

  • Créer le fichier docker/.env depuis docker/.env.dist
  • Créer les fichiers .env.development et .env.production pour app2
  • Créer les réseaux Docker nécessaires (network_kpi, pma_network, traefiknetwork)
  1. Configurer les variables d'environnement

Éditer docker/.env et configurer :

APPLICATION_NAME=kpi              # Nom de l'application (change selon l'environnement)
USER_ID=1000
GROUP_ID=33
DB_ROOT_PASSWORD=votre_mot_de_passe
DB_USER=votre_utilisateur
DB_PASSWORD=votre_mot_de_passe
# ... etc

Important : Le APPLICATION_NAME définit le nom du réseau Docker (network_${APPLICATION_NAME}).

  • Développement local : APPLICATION_NAME=kpi → réseau network_kpi
  • Pré-production : APPLICATION_NAME=kpi_preprod → réseau network_kpi_preprod
  • Production : APPLICATION_NAME=kpi ou kpi_prod selon votre configuration
  1. Démarrer l'environnement de développement
make dev_up
  1. Installer les dépendances Node
make npm_install_app2
  1. Lancer le serveur Nuxt
make run_dev

L'application est accessible sur :

Configuration des hôtes locaux

Ajouter à /etc/hosts :

127.0.0.1 kpi.localhost kpi-8.localhost kpi-myadmin.localhost kpi-node.localhost

📋 Commandes Make principales

Utilisez make help pour voir toutes les commandes disponibles.

Initialisation

make init              # Initialisation complète (recommandé)
make init_env          # Créer docker/.env
make init_env_app2     # Créer les .env de app2
make init_networks     # Créer les réseaux Docker

Développement

make dev_up            # Démarrer les containers
make dev_down          # Arrêter les containers
make dev_restart       # Redémarrer les containers
make dev_logs          # Voir les logs en temps réel
make dev_status        # Statut des containers

Pré-production

make preprod_up        # Démarrer la pré-production
make preprod_down      # Arrêter la pré-production
make preprod_logs      # Voir les logs

Production

make prod_up           # Démarrer la production
make prod_down         # Arrêter la production
make prod_logs         # Voir les logs

Nuxt (App2)

make run_dev           # Serveur dev Nuxt (port 3002)
make run_build         # Build pour production
make run_generate      # Génération statique
make run_lint          # Linter ESLint

NPM

make npm_install_app2                    # Installer les dépendances
make npm_clean_app2                      # Nettoyer node_modules
make npm_add_app2 package=nom-package    # Ajouter un package

Accès aux containers

make php_bash          # Shell PHP 7.4
make php8_bash         # Shell PHP 8
make node_bash         # Shell Node/App2
make db_bash           # Shell MySQL

Réseaux Docker

make networks_create   # Créer les réseaux nécessaires (utilise APPLICATION_NAME)
make networks_list     # Lister les réseaux du projet
make networks_clean    # Supprimer les réseaux (si non utilisés)

Note : Les réseaux sont créés en fonction de APPLICATION_NAME dans docker/.env :

  • Réseau KPI : network_${APPLICATION_NAME}
  • Réseau phpMyAdmin : pma_network (partagé)
  • Réseau Traefik : traefiknetwork (partagé)

WordPress

make wordpress_backup  # Créer une sauvegarde

🗂️ Structure du projet

kpi/
├── docker/                      # Configuration Docker
│   ├── compose.dev.yaml         # Docker Compose développement
│   ├── compose.preprod.yaml     # Docker Compose pré-production
│   ├── compose.prod.yaml        # Docker Compose production
│   ├── .env                     # Variables d'environnement (non versionné)
│   ├── .env.dist                # Template des variables
│   ├── wordpress/               # Contenu WordPress (non versionné)
│   └── config/                  # Dockerfiles et configurations
├── sources/
│   ├── app2/                    # Application Nuxt 4 (principale)
│   ├── app_dev/                 # Application Vue.js legacy
│   ├── app_live_dev/            # Application live Vue.js
│   ├── app_wsm_dev/             # Application WSM Vue.js
│   ├── api/                     # API REST PHP
│   ├── commun/                  # Classes PHP partagées
│   └── wordpress_archive/       # Archive WordPress
├── SQL/                         # Scripts SQL
├── WORKFLOW_AI/                 # Documentation technique détaillée
│   ├── README.md                # Index de la documentation
│   ├── PHP8_GESTIONDOC_FIXES.md # Correctifs PHP 8
│   ├── MIGRATION.md             # Guide de migration
│   └── ... (18 fichiers)        # Guides, audits, fixes
├── Makefile                     # Commandes Make
├── CLAUDE.md                    # Documentation pour Claude Code
├── GEMINI.md                    # Documentation pour Gemini
└── README.md                    # Ce fichier

🔧 Configuration

Fichiers d'environnement

docker/.env (non versionné)

  • Configuration Docker principale
  • Ports, chemins, credentials
  • Créé depuis docker/.env.dist

sources/app2/.env.development (non versionné)

  • Configuration Nuxt en développement
  • Variables : API_BASE_URL, BACKEND_BASE_URL
  • Utilisé automatiquement par npm run dev

sources/app2/.env.production (non versionné)

  • Configuration Nuxt en production
  • Utilisé pour npm run build et npm run generate

WordPress

Le contenu WordPress est stocké dans docker/wordpress/ et n'est pas versionné dans Git.

Configuration :

  • Le chemin est défini par HOST_WORDPRESS_PATH dans docker/.env
  • Les fichiers de config WordPress sont dans docker/wordpress/wp-config.php*
  • Faire une sauvegarde avec make wordpress_backup

Base de données

Deux bases de données MySQL/MariaDB :

  1. KPI : Base principale de l'application
  2. WordPress : Base pour le CMS

Accès via phpMyAdmin : http://kpi-myadmin.localhost

🌐 Environnements

Développement

  • Fichier : docker/compose.dev.yaml
  • Ports exposés : 8003 (PHP 7.4), 8803 (PHP 8), 3002 (Nuxt)
  • Hot reload activé
  • Logs verbeux

Pré-production

  • Fichier : docker/compose.preprod.yaml
  • Configuration proche de la production
  • Pour tester avant déploiement

Production

  • Fichier : docker/compose.prod.yaml
  • Optimisé pour les performances
  • Utilise Traefik avec SSL/TLS

📦 Technologies utilisées

Frontend

  • Nuxt 4 : Framework Vue.js avec rendu SSR/SSG
  • Vue 3 : Framework JavaScript réactif
  • TypeScript : Typage statique
  • Tailwind CSS : Framework CSS utility-first
  • Pinia : Gestion d'état
  • Nuxt UI : Composants UI

Backend

  • PHP 7.4 / 8.x : Langage serveur
  • MySQL/MariaDB 10.4 : Base de données
  • WordPress : CMS

Infrastructure

  • Docker : Conteneurisation
  • Docker Compose : Orchestration
  • Traefik : Reverse proxy
  • Apache : Serveur web

🔐 Sécurité

  • Les fichiers .env ne sont jamais versionnés
  • Les credentials sont dans les fichiers .env
  • WordPress est isolé dans un volume séparé
  • Traefik gère les certificats SSL en production

🐛 Dépannage

Les containers ne démarrent pas

make networks_create   # Créer les réseaux manquants
make dev_status        # Vérifier le statut
make dev_logs          # Voir les erreurs

Erreur "network not found"

Le nom du réseau dépend de APPLICATION_NAME dans docker/.env.

Solution :

# Vérifier le nom attendu
grep APPLICATION_NAME docker/.env

# Créer les réseaux avec le bon nom
make networks_create

# Vérifier que les réseaux sont créés
make networks_list

Si vous avez plusieurs environnements (dev, preprod, prod) sur le même serveur, utilisez des APPLICATION_NAME différents :

  • Dev : APPLICATION_NAME=kpi
  • Preprod : APPLICATION_NAME=kpi_preprod
  • Prod : APPLICATION_NAME=kpi_prod

Port déjà utilisé

Modifier les ports dans docker/.env :

DOCKER_SUFFIXE_PORT=03  # Changer ce suffixe

Nuxt ne démarre pas

make npm_clean_app2    # Nettoyer
make npm_install_app2  # Réinstaller
make run_dev           # Relancer

📚 Documentation complémentaire

  • CLAUDE.md : Guide complet des commandes pour Claude Code
  • WORKFLOW_AI/ : Documentation technique détaillée
    • Guides de migration (PHP 8, FPDF → mPDF)
    • Fixes et optimisations
    • Audits de code et recommandations
    • Configuration Docker et infrastructure
    • Voir WORKFLOW_AI/README.md pour l'index complet
  • Makefile : Toutes les commandes disponibles (make help)
  • Wiki GitHub : https://github.com/FFCK/kpi/wiki

🔄 Workflow de développement

  1. Démarrer la journée
make dev_up
make run_dev
  1. Développer
  • Modifier le code dans sources/app2/
  • Hot reload automatique
  1. Tester
make run_lint          # Vérifier le code
make run_build         # Tester le build
  1. Fin de journée
make dev_down

🚢 Déploiement

Configuration multi-environnements

Si vous déployez plusieurs environnements (dev, preprod, prod) sur le même serveur, vous devez configurer des APPLICATION_NAME différents pour éviter les conflits de réseaux et containers.

1. Sur le serveur de pré-production :

Éditer docker/.env :

APPLICATION_NAME=kpi_preprod    # Nom unique pour la préprod

Puis initialiser :

make init              # Crée network_kpi_preprod

2. Sur le serveur de production :

Éditer docker/.env :

APPLICATION_NAME=kpi_prod       # Nom unique pour la prod

Puis initialiser :

make init              # Crée network_kpi_prod

Préparer pour la production

make run_build         # Build Nuxt
make run_generate      # Génération statique (si nécessaire)

Déployer en pré-production

make preprod_up        # Tester en préprod
make preprod_logs      # Vérifier les logs

Déployer en production

make prod_up           # Lancer en production
make prod_status       # Vérifier le statut

📝 CRON

Tâches planifiées :

  • Mise à jour des licenciés : commun/cron_maj_licencies.php (quotidien)
  • Verrouillage des feuilles de présence : commun/cron_verrou_presences.php (quotidien, J-6 avant événement)

🤝 Contribution

  1. Créer une branche pour votre fonctionnalité
  2. Développer et tester localement
  3. Faire un build de production : make run_build
  4. Créer une Pull Request

📄 Licence

Propriété de la FFCK (Fédération Française de Canoë-Kayak)

🆘 Support

Pour toute question ou problème :

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

1 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Contributors 3

  •  
  •  
  •  

Languages