diff --git a/README.md b/README.md index 6b49eb9..d35708b 100644 --- a/README.md +++ b/README.md @@ -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 +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.
-Pour cela, il faut aller dans **Settings > PHP > Servers**
-* 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 +() : ``` + +**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