# 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.

## Stack technique

| Couche | Technologie | Version |
|--------|-------------|---------|
| Backend | Symfony + API Platform | 8.0 / 4.2 |
| PHP | PHP | >= 8.4 |
| Base de données | PostgreSQL | 16 |
| Frontend | Nuxt (SPA, SSR off) | 4 |
| UI | Vue 3 Composition API + TypeScript | 3.5 / 5.7 |
| CSS | TailwindCSS + DaisyUI | 4 / 5 |
| Conteneurs | Docker Compose | |

## Prérequis

- **Docker** et **Docker Compose**
- **Node.js** >= 20 (via nvm)
- **make**

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

```bash
git clone --recurse-submodules <url-du-repo>
cd Inventory
make start
make install
```

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

## URLs locales

| Service | URL |
|---------|-----|
| API Symfony | http://localhost:8081/api |
| Frontend Nuxt | http://localhost:3001 |
| Adminer (BDD) | http://localhost:5050 |
| PostgreSQL | `localhost:5433` (user: root, pass: root, db: inventory) |

## Commandes

### Docker

| Commande | Description |
|----------|-------------|
| `make start` | Démarrer les conteneurs |
| `make stop` | Arrêter les conteneurs |
| `make restart` | Redémarrer les conteneurs |
| `make shell` | Shell bash dans le conteneur PHP |
| `make reset` | Reset complet (supprime volumes, réinstalle) |

### Backend

| Commande | Description |
|----------|-------------|
| `make test` | Lancer les tests PHPUnit |
| `make php-cs-fixer-allow-risky` | Formatter le code PHP |
| `make cache-clear` | Vider le cache Symfony |
| `make db-reset` | Reset de la BDD (supprime les données) |
| `make fixtures-load` | Charger les fixtures SQL |
| `make fixtures-dump` | Dumper la BDD dans fixtures/data.sql |

### Frontend

| Commande | Description |
|----------|-------------|
| `make dev-nuxt` | Serveur de dev Nuxt |
| `make build-nuxtJS` | Build de 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

### Structure du projet

```
Inventory/                          # Backend Symfony (repo principal)
├── src/
│   ├── Entity/                     # 20 entités Doctrine (attributs PHP 8)
│   ├── Controller/                 # 16 contrôleurs custom
│   ├── EventSubscriber/            # 9 subscribers (audit onFlush)
│   ├── EventListener/              # Listeners documents (cleanup, compression)
│   ├── Command/                    # 3 commandes CLI
│   ├── Service/                    # 3 services (stockage, conversion, PDF)
│   ├── State/                      # 3 processeurs API Platform
│   ├── Repository/                 # 19 repositories Doctrine
│   ├── Security/                   # Authenticateur session
│   └── Serializer/                 # Normalizer custom (Document)
├── config/                         # Configuration Symfony
├── migrations/                     # 4 migrations Doctrine (SQL PostgreSQL)
├── fixtures/                       # Données de test (SQL)
├── scripts/                        # Utilitaires (release, migration, normalisation)
├── docker/                         # Dockerfile + config Docker
├── makefile                        # Commandes de dev
├── VERSION                         # Version courante (semver)
└── Inventory_frontend/             # Submodule git (repo séparé)
    ├── app/pages/                  # 36 pages Nuxt (file-based routing)
    ├── app/components/             # 57 composants Vue
    ├── app/composables/            # 45 composables
    └── app/shared/                 # Types, utils, validation
```

### Entités principales

| Entité | Description |
|--------|-------------|
| `Machine` | Machines du parc industriel |
| `Composant` | Composants rattachés aux machines |
| `Piece` | Pièces détachées |
| `Product` | Produits (consommables, outillage) |
| `Site` | Sites physiques / usines |
| `Constructeur` | Fournisseurs / fabricants |
| `TypeMachine` | Types de machines avec squelettes de structure |
| `ModelType` | Catégories (pièce, composant, produit) avec champs personnalisés |
| `CustomField` / `CustomFieldValue` | Champs personnalisés extensibles |
| `Document` | Documents uploadés (stockage fichier + compression PDF) |
| `AuditLog` | Journal d'audit (diff + snapshot) |
| `Comment` | Commentaires / tickets sur les fiches |
| `Profile` | Utilisateurs avec rôles |

### Commandes Symfony

| Commande | Description |
|----------|-------------|
| `app:compress-pdf` | Compresser les PDFs existants (supporte `--dry-run`) |
| `app:migrate-documents-to-filesystem` | Migrer les documents Base64 vers le système de fichiers |
| `app:init-profile-passwords` | Initialiser mots de passe et rôles en masse |

### Rôles et permissions

```
ROLE_ADMIN → ROLE_GESTIONNAIRE → ROLE_VIEWER → ROLE_USER
```

- **ADMIN** : accès complet, gestion des profils
- **GESTIONNAIRE** : CRUD sur toutes les entités, résolution des commentaires
- **VIEWER** : lecture seule sur toutes les entités
- **USER** : accès de base

### Authentification

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

### Base de données

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 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

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

**Espace obligatoire autour du `:`**. Types : `feat`, `fix`, `perf`, `refactor`, `chore`, `docs`, `test`, `style`, `build`, `ci`, `revert`, `wip`.

### Pre-commit hook

1. php-cs-fixer sur les fichiers PHP stagés
2. PHPUnit — bloque le commit si les tests échouent

### Submodule frontend

Le frontend est un **submodule git** dans `Inventory_frontend/`. Workflow :

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

## Documentation complémentaire

- [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](Inventory_frontend/README.md) : documentation du frontend Nuxt