MALIO-DEV/Inventory
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs(readme) : comprehensive project documentation

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Matthieu
2026-03-04 10:49:35 +01:00
parent 1483b0075b
commit fbc0372bd6
1 changed files with 196 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

264
README.md
View File

@@ -1,92 +1,220 @@
# Projet Inventory
# Inventory
## Installation du projet
### Windows
Pour windows, il faut installer le WSL2, Ubuntu, docker et nvm.
Il suffit de suivre cette [doc](https://wiki.malio.fr/bookstack/books/environnement-de-dev/chapter/windows)
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.
### Linux
Pour linux, il faut installer docker et nvm.
Il suffit de suivre cette [doc](https://wiki.malio.fr/bookstack/books/environnement-de-dev/chapter/linux)
## 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
### Installation du projet
Une fois les prérequis installés, il suffit de cloner le projet et de lancer les commandes suivantes
```bash
sudo apt install make -y
git clone --recurse-submodules <url-du-repo>
cd Inventory
make start
make install
```
Dans le cas ou le `make start` plante à cause du port de la bdd, il faut modifier **POSTGRES_PORT** dans le fichier .env.docker.local, remplacer le par un port disponible.
### Configuration xdebug
Pour configurer xdebug, il faut ajouter un serveur sur phpstorm. <br>
Pour cela, il faut aller dans **Settings > PHP > Servers** <br>
* Name : inventory-docker
* Host : localhost
* Port : 8080
* Path : File/Directory -> l'endroit où est stocké votre projet et le path -> /var/www/html
> Si `make start` échoue sur le port de la BDD, modifier `POSTGRES_PORT` dans `docker/.env.docker.local`.
Pour que xdebug fonctionne sur windows, il faut modifier la variable **XDEBUG_CLIENT_HOST** par votre ip 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) |
## Utilisation du projet
### Backend
L'api est disponible sur http://localhost:8080/api
Pour la bdd toutes les infos sont dans le fichier **docker/.env.docker.local**
Vous pouvez modifier le port si nécessaire.
La bdd est déja pré-configuré dans PhpStorm, il suffit de rentrer les infos du .env.docker.local pour se connecter.
C'est un bdd local dans le docker.
| 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
Le frontend utilise le dossier `Inventory_frontend/`.
Pour le frontend, il suffit de taper la commande suivante qui va lancer le serveur de dev
| Commande | Description |
|----------|-------------|
| `make dev-nuxt` | Serveur de dev Nuxt |
| `make build-nuxtJS` | Build de production |
### Release
```bash
make dev-nuxt
```
Le front sera accessible sur http://localhost:3000
## Compression automatique des PDFs
Les documents PDF uploadés sont automatiquement compressés sans perte de qualité grâce à **qpdf**.
### Prérequis
```bash
# Installation de qpdf (outil système)
sudo apt install qpdf
# Ou dans Docker
docker exec -it php-inventory-apache apt update && apt install -y qpdf
./scripts/release.sh patch # Bump patch (ou minor / major)
```
### Fonctionnement
- À chaque upload de PDF, le système compresse automatiquement le fichier
- Compression lossless (sans perte de qualité)
- Le PDF est compressé uniquement si la taille diminue
- Si qpdf n'est pas installé, le système fonctionne normalement sans compression
Synchronise automatiquement la version dans `VERSION`, `api_platform.yaml` et `nuxt.config.ts`, crée le tag git et pousse les deux repos.
### Compresser les PDFs existants
Pour compresser tous les PDFs déjà en base :
```bash
# Voir ce qui serait compressé (dry-run)
php bin/console app:compress-pdf --dry-run
## Architecture
# Compresser tous les PDFs
php bin/console app:compress-pdf
### 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
```
## Commandes utiles
Pour restart le container
```bash
make restart
### 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
```
Pour lancer les TU
```bash
make test
ROLE_ADMIN → ROLE_GESTIONNAIRE → ROLE_VIEWER → ROLE_USER
```
Pour accéder au container et lance des commandes
```bash
make shell
- **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
```
Pour clear le cache Symfony
```bash
make cache-clear
<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