Inventory

Application de gestion d'inventaire industriel pour Malio. Gestion complète du parc machines, des pièces, composants, produits, fournisseurs et documents associés, avec traçabilité et contrôle d'accès par rôles.

C'est quoi ce projet ?

Inventory est une application web qui permet de gérer un parc de machines industrielles. Concrètement, elle permet de :

• Cataloguer les machines d'une usine, site par site
• Décomposer chaque machine en composants, pièces et produits (structure arborescente)
• Suivre les fournisseurs/constructeurs de chaque élément
• Stocker les documents techniques (PDF, images, fiches techniques)
• Tracer toutes les modifications (qui a changé quoi, quand) via un journal d'audit
• Commenter les fiches pour collaborer entre équipes
• Gérer les accès avec un système de rôles (admin, gestionnaire, lecteur)

L'application se compose de deux parties :

• Un backend (API REST) qui gère les données, la sécurité et la logique métier
• Un frontend (interface web) qui affiche les données et permet l'interaction utilisateur

Stack technique

Couche	Technologie	Version	Rôle
Backend	Symfony + API Platform	8.0 / 4.2	API REST, logique métier, sécurité
PHP	PHP	>= 8.4	Langage backend
Base de données	PostgreSQL	16	Stockage des données
Frontend	Nuxt (SPA, SSR off)	4	Framework web (rendu côté client)
UI	Vue 3 Composition API + TypeScript	3.5 / 5.7	Composants d'interface
CSS	TailwindCSS + DaisyUI	4 / 5	Mise en page et composants visuels
Conteneurs	Docker Compose		Environnement de développement

Prérequis

• Docker et Docker Compose (pour lancer le projet sans rien installer)
• Node.js >= 20 (via nvm)
• make (normalement déjà installé sur Linux/macOS)

Guides d'installation de l'environnement

OS	Documentation
Windows	WSL2 + Ubuntu + Docker
Linux	Docker + nvm

Installation rapide

# 1. Cloner le projet avec le frontend (submodule)
git clone --recurse-submodules <url-du-repo>
cd Inventory

# 2. Démarrer les conteneurs Docker (PHP, PostgreSQL, Adminer)
make start

# 3. Installer les dépendances et builder le projet
make install

Si make start échoue sur le port de la BDD, modifier POSTGRES_PORT dans docker/.env.docker.local.

Que fait make install ?

1. Installe les dépendances PHP (via Composer)
2. Installe les dépendances Node.js (via npm)
3. Build le frontend Nuxt

Premier lancement

Une fois l'installation terminée, tu peux :

1. Charger des données de test : make fixtures-load
2. Lancer le frontend en mode dev : make dev-nuxt
3. Ouvrir l'application : http://localhost:3001

URLs locales

Service	URL	Description
API Symfony	http://localhost:8081/api	Documentation interactive de l'API (Swagger)
Frontend Nuxt	http://localhost:3001	L'application web
Adminer (BDD)	http://localhost:5050	Interface web pour explorer la base de données
PostgreSQL	localhost:5433	Connexion directe (user: root, pass: root, db: inventory)

Commandes utiles

Docker

Commande	Description
make start	Démarrer les conteneurs
make stop	Arrêter les conteneurs
make restart	Redémarrer les conteneurs
make shell	Ouvrir un terminal dans le conteneur PHP (pour lancer des commandes Symfony)
make reset	Reset complet (supprime les volumes, réinstalle tout)

Backend

Commande	Description
make test	Lancer les tests PHPUnit
make test FILES=tests/Api/Entity/MachineTest.php	Lancer un test spécifique
make test-setup	Créer/mettre à jour la base de test
make php-cs-fixer-allow-risky	Formatter le code PHP (indentation, espaces, etc.)
make cache-clear	Vider le cache Symfony (à faire si tu as des erreurs bizarres)
make db-reset	Reset de la BDD (supprime toutes les données)
make fixtures-load	Charger les données de test
make fixtures-dump	Sauvegarder la BDD actuelle dans fixtures/data.sql

Frontend

Commande	Description
make dev-nuxt	Lancer le serveur de dev Nuxt (avec rechargement automatique)
make build-nuxtJS	Builder le frontend pour la production

Release

./scripts/release.sh patch    # Bump patch (ou minor / major)

Synchronise automatiquement la version dans VERSION, api_platform.yaml et nuxt.config.ts, crée le tag git et pousse les deux repos.

Architecture globale

Comment ça marche ?

┌──────────────────┐     HTTP (JSON)     ┌──────────────────┐     SQL      ┌────────────┐
│    Frontend      │ ◄─────────────────► │     Backend      │ ◄──────────► │ PostgreSQL │
│   (Nuxt/Vue)     │   cookies session   │  (Symfony/API)   │              │   (BDD)    │
│  localhost:3001   │                     │  localhost:8081   │              │  port 5433 │
└──────────────────┘                     └──────────────────┘              └────────────┘
       │                                         │
  Interface web                            API REST + logique
  pour l'utilisateur                       métier + sécurité

1. L'utilisateur ouvre le navigateur sur localhost:3001
2. Le frontend (Vue/Nuxt) affiche l'interface
3. Quand l'utilisateur fait une action (créer une machine, etc.), le frontend envoie une requête HTTP à l'API backend
4. Le backend valide la requête, vérifie les permissions, exécute la logique métier
5. Le backend lit/écrit dans PostgreSQL et renvoie une réponse JSON
6. Le frontend met à jour l'interface avec les nouvelles données

Structure du projet

Inventory/                          # Backend Symfony (repo principal)
├── src/
│   ├── Entity/                     # Les "modèles" de données (Machine, Piece, etc.)
│   ├── Controller/                 # Les endpoints API personnalisés
│   ├── EventSubscriber/            # Logique déclenchée automatiquement (audit, etc.)
│   ├── Command/                    # Commandes CLI (lancer via php bin/console)
│   ├── Service/                    # Services métier (stockage fichiers, PDF, etc.)
│   ├── State/                      # Processeurs API Platform (hashage mot de passe, upload)
│   ├── Repository/                 # Requêtes BDD personnalisées
│   ├── Security/                   # Authentification par session
│   └── Serializer/                 # Conversion entité ↔ JSON personnalisée
├── config/                         # Configuration Symfony (routes, sécurité, etc.)
├── migrations/                     # Scripts de modification de la BDD
├── fixtures/                       # Données de test (SQL)
├── tests/                          # Tests automatisés (PHPUnit)
├── scripts/                        # Utilitaires (release, migration, normalisation)
├── docker/                         # Dockerfile + config Docker
├── makefile                        # Commandes de dev raccourcies
├── VERSION                         # Version courante (ex: 1.8.1)
└── frontend/             # Submodule git (frontend, repo séparé)
    ├── app/pages/                  # Les pages de l'app (1 fichier = 1 route URL)
    ├── app/components/             # Composants Vue réutilisables
    ├── app/composables/            # Logique métier partagée (appels API, états)
    ├── app/shared/                 # Types TypeScript, utilitaires, validation
    ├── app/middleware/              # Vérification de session automatique
    └── app/services/               # Couche service (wrappers API)

Entités principales (les "tables" de la BDD)

Entité	Description	Exemple
Machine	Machines du parc industriel	"CNC Mazak 01"
Composant	Composants fonctionnels d'une machine	"Broche principale"
Piece	Pièces détachées/de rechange	"Roulement SKF 6205"
Product	Produits fournisseur (consommables, outillage)	"Huile de coupe X"
Site	Sites physiques / usines	"Usine de Strasbourg"
Constructeur	Fournisseurs / fabricants	"SKF", "Mazak"
ModelType	Catégories avec squelettes de structure	"Type: Moteur électrique"
CustomField / CustomFieldValue	Champs personnalisés (dynamiques)	"Tension : 220V"
Document	Documents uploadés (PDF, images, etc.)	"Fiche technique CNC.pdf"
AuditLog	Journal d'audit (historique des modifications)	"Machine X modifiée par Jean"
Comment	Commentaires / tickets sur les fiches	"Vérifier le roulement"
Profile	Comptes utilisateurs avec rôles	"admin@malio.fr (ADMIN)"

Structure hiérarchique d'une machine

Une machine peut contenir une arborescence de composants, pièces et produits :

Machine "CNC Mazak 01"
├── Composant "Broche principale"
│   ├── Pièce "Roulement avant"
│   │   └── Produit "Graisse SKF LGMT2"
│   └── Pièce "Joint d'étanchéité"
├── Composant "Système hydraulique"
│   ├── Pièce "Pompe HP"
│   └── Produit "Huile hydraulique ISO 46"
└── Produit "Filtre à air cabine"

Rôles et permissions

ROLE_ADMIN           → Tout faire + gérer les utilisateurs
  ↓ hérite de
ROLE_GESTIONNAIRE    → Créer, modifier, supprimer les données
  ↓ hérite de
ROLE_VIEWER          → Lecture seule sur toutes les données
  ↓ hérite de
ROLE_USER            → Accès de base (rôle minimum)

Authentification

Authentification par session (cookies), pas de JWT. Le profil actif est stocké en session côté serveur. Concrètement :

1. L'utilisateur choisit son profil sur la page de login
2. Il entre son mot de passe
3. Le backend crée une session et envoie un cookie au navigateur
4. À chaque requête suivante, le navigateur envoie automatiquement ce cookie
5. Le backend vérifie le cookie et identifie l'utilisateur

Base de données — Points importants

PostgreSQL 16 avec les particularités suivantes :

• IDs : chaînes CUID ('cl' + bin2hex(random_bytes(12))), pas d'auto-increment
• Noms de colonnes : toujours en minuscules dans PostgreSQL (Doctrine map typePieceId → typepieceid)
• Audit : les subscribers Doctrine onFlush capturent le diff + snapshot complet de chaque modification
• Migrations : SQL brut avec IF NOT EXISTS / IF EXISTS pour l'idempotence

Services Docker

Service	Image	Port	Rôle
web	PHP 8.4 + Apache + Node	8081, 3001	API Symfony + Nuxt dev
db	PostgreSQL 16 Alpine	5433	Base de données
adminer	Adminer	5050	Interface web pour explorer la BDD

Xdebug

Configuration PhpStorm / VSCode :

• Serveur : inventory-docker
• Host : localhost
• Port : 8081
• Path mapping : racine du projet → /var/www/html

Sous WSL, modifier XDEBUG_CLIENT_HOST dans docker/.env.docker.local avec votre IP locale.

Git

Branches

• master : production
• develop : branche principale de dev (cible des PR)
• feat/xxx, fix/xxx, refactor/xxx : branches de travail

Convention de commit (enforced par un hook)

<type>(<scope>) : <message>

Espace obligatoire autour du :. Types autorisés (minuscules) : feat, fix, perf, refactor, chore, docs, test, style, build, ci, revert, wip

Exemples :

feat(machines) : add clone functionality
fix(documents) : prevent duplicate upload
refactor(audit) : merge history controllers
chore(deps) : update composer packages

Pre-commit hook

Le hook pre-commit s'exécute automatiquement avant chaque commit :

1. php-cs-fixer — Formate automatiquement les fichiers PHP modifiés
2. PHPUnit — Lance les tests. Si un test échoue, le commit est bloqué

Submodule frontend

Le frontend est un submodule git dans frontend/ (c'est un repo git séparé, inclus dans le repo principal). Workflow de commit :

1. Commiter dans frontend/ d'abord
2. Commiter dans le repo principal pour mettre à jour le pointeur du submodule
3. Pousser les deux repos

Documentation détaillée

• docs/BACKEND.md : guide complet du backend (entités, controllers, API, audit, tests)
• docs/FRONTEND.md : guide complet du frontend (pages, composables, composants, patterns)
• DEPLOY.md : guide de déploiement serveur (Nginx, PHP-FPM, PostgreSQL)
• RELEASE.md : processus de release et versioning
• CHANGELOG.md : historique des versions
• Frontend README : documentation du frontend Nuxt