FutureKawa Central

Application Laravel 13 / React / Inertia dockerisée pour l’équipe FutureKawa.

Objectif

Ce dépôt est pensé pour un démarrage simple et homogène sur toutes les machines de l’équipe. Le projet fournit :

• une application Laravel exécutée dans Docker ;
• une base de données MySQL ;
• phpMyAdmin ;
• un service Node pour Vite / React ;
• un script fkc pour éviter d’écrire les longues commandes docker compose exec ... (linux uniquement pour l'instant).

---

Prérequis

• Docker et Docker Compose installés ;
• accès au groupe docker sur Linux pour éviter sudo à chaque commande ;
• Git ;
• Bash.

Vérification utile :

docker ps
docker compose version

---

Démarrage rapide avec Docker

Depuis la racine du projet :

docker compose up -d --build

Puis, si c’est le premier lancement ou après une grosse mise à jour :

fkc composer install
fkc art key:generate
fkc art migrate

Si tu n’as pas encore créé le fichier .env, copie-le depuis .env.example puis adapte les variables si besoin.

---

URL utiles

• Application : http://localhost:8082
• Vite / HMR : http://localhost:5173
• phpMyAdmin : http://localhost:8081

Identifiants MySQL locaux actuels :

• base : futurekawacentral
• utilisateur : futurekawa
• mot de passe : futurekawa
• root MySQL : root

---

Structure Docker

Le docker-compose.yml démarre les services suivants :

• app : PHP-FPM 8.4 + Composer ;
• web : Nginx ;
• node : Node 22 pour Vite ;
• mysql : MySQL 8.4 ;
• phpmyadmin : interface web pour MySQL.

Les ports exposés sont :

• 8082 → application Laravel ;
• 8081 → phpMyAdmin ;
• 5173 → Vite en développement ;
• 3307 → MySQL local.

---

Script fkc

Le script bin/fkc permet d’exécuter les commandes courantes dans les bons conteneurs, avec le bon utilisateur Linux.

Astuce : si besoin, rends le script exécutable une seule fois :

chmod +x bin/fkc

Commandes disponibles

Commande	Rôle
fkc art ...	Lance une commande Artisan dans le conteneur app
fkc artisan ...	Alias de fkc art ...
fkc migrate	Lance php artisan migrate
fkc fresh	Lance php artisan migrate:fresh --seed
fkc tinker	Ouvre php artisan tinker
fkc composer ...	Lance Composer dans app
fkc npm ...	Lance npm dans node
fkc npx ...	Lance npx dans node
fkc sh	Ouvre un shell dans app
fkc pint	Lance Laravel Pint

Exemples d’utilisation

fkc art cache:clear
fkc art make:controller Auth/LoginController
fkc migrate
fkc fresh
fkc tinker
fkc composer require laravel/pint --dev
fkc npm run dev
fkc npx shadcn@latest add dropdown-menu
fkc pint

Parité Windows

La même liste de commandes est disponible sous Windows via bin\fkc.bat.

Exemples :

bin\fkc.bat art cache:clear
bin\fkc.bat artisan make:controller Auth/LoginController
bin\fkc.bat migrate
bin\fkc.bat fresh
bin\fkc.bat tinker
bin\fkc.bat composer install
bin\fkc.bat npm run dev
bin\fkc.bat npx shadcn@latest add dropdown-menu
bin\fkc.bat sh
bin\fkc.bat pint

bin\fkc.cmd est conservé comme alias et redirige vers bin\fkc.bat.

Si besoin, tu peux définir FKC_COMPOSE_USER pour imposer un utilisateur Docker précis sur Windows.

---

Bonnes pratiques Linux

Si tu modifies des fichiers depuis Docker, évite de travailler en root dans les conteneurs afin de ne pas casser les droits sur le volume monté.

En cas de problème de permissions sur le projet :

sudo chown -R "$USER":"$(id -gn)" .

Si Docker n’est pas accessible sans sudo, ajoute ton utilisateur au groupe docker.

---

Lancer les tests (§IV.6)

La suite de tests est lançable en une commande grâce au Makefile :

make test

Pré-requis

• La stack Docker doit être démarrée (make up) — les containers fkc_app et fkc_node doivent être présents
• Les dépendances installées (make install)
• Aucune base réelle n'est nécessaire : la suite PHPUnit utilise SQLite en mémoire (configuré dans phpunit.xml)

Variables d'environnement

PHPUnit lit phpunit.xml qui force :

Variable	Valeur de test
APP_ENV	testing
DB_CONNECTION	sqlite
DB_DATABASE	:memory:
CACHE_STORE	array
SESSION_DRIVER	array
MAIL_MAILER	array
QUEUE_CONNECTION	sync

Vitest utilise jsdom — aucune variable n'est requise.

Jeux de données

• PHPUnit : utilise RefreshDatabase à chaque test → les migrations sont rejouées sur SQLite en mémoire. Les factories (UserFactory, LotFactory, MeasurementFactory) génèrent les données nécessaires à chaque cas.
• Vitest : global.fetch est mocké à la main avec vi.spyOn, les payloads d'API sont décrits inline dans chaque test.

Commandes principales

Commande	Effet
make test	Lance PHPUnit (--testdox) + Vitest
make test-backend	PHPUnit seul, rendu lisible
make test-frontend	Vitest seul
make test-watch	Vitest en mode watch (relance auto sur modif)
make test-ci	Génère les rapports JUnit XML pour Jenkins
make coverage	Rapport HTML coverage backend + frontend
make lint	Laravel Pint + Prettier check

Rapports produits

Rapport	Chemin	Format
PHPUnit JUnit XML	storage/test-reports/phpunit.xml	JUnit (Jenkins)
Vitest JUnit XML	storage/test-reports/vitest-junit.xml	JUnit (Jenkins)
Coverage backend	storage/coverage-backend/index.html	HTML (PCOV)
Coverage frontend	storage/coverage-frontend/index.html	HTML (V8)

Périmètre actuel (à fin Phase 2)

• PHPUnit : 29 tests / 57 assertions
  • Unit : CountryApiClient (HTTP mock, cache, retry), Models Country, enum LotStatus
  • Feature : routes API /api/countries*, /api/dashboard-stats, auth /login, /logout
• Vitest : 11 tests
  • CountrySelector (fetch, disabled, auto-select, click)
  • DashboardCardSection (skeleton, KPIs, refresh 15 s, échec API)

---

Dépannage rapide

1. Réinitialiser les caches Laravel

fkc art optimize:clear

2. Relancer le frontend Vite

fkc npm run dev -- --host 0.0.0.0 --port 5173

3. Reconstruire complètement

docker compose down
docker compose up -d --build

4. Ouvrir phpMyAdmin

Connecte-toi sur http://localhost:8081 avec les identifiants MySQL de développement.

---

Notes équipe

• Le projet fonctionne mieux si tout le monde utilise les commandes fkc.
• Le service node peut être long au premier lancement car il installe les dépendances front.
• En cas de lenteur sur Windows, privilégier WSL2 et un dossier projet côté Linux.