Inventory/README.md

# 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](https://github.com/nvm-sh/nvm))
- **make** (normalement déjà installé sur Linux/macOS)

### Guides d'installation de l'environnement

| OS | Documentation |
|----|---------------|
| Windows | [WSL2 + Ubuntu + Docker](https://wiki.malio.fr/bookstack/books/environnement-de-dev/chapter/windows) |
| Linux | [Docker + nvm](https://wiki.malio.fr/bookstack/books/environnement-de-dev/chapter/linux) |

## Installation rapide

```bash
# 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

```bash
./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](docs/BACKEND.md)** : guide complet du backend (entités, controllers, API, audit, tests)
- **[docs/FRONTEND.md](docs/FRONTEND.md)** : guide complet du frontend (pages, composables, composants, patterns)
- **[DEPLOY.md](DEPLOY.md)** : guide de déploiement serveur (Nginx, PHP-FPM, PostgreSQL)
- **[RELEASE.md](RELEASE.md)** : processus de release et versioning
- **[CHANGELOG.md](CHANGELOG.md)** : historique des versions
- **[Frontend README](frontend/README.md)** : documentation du frontend Nuxt