docs(readme) : comprehensive project documentation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Matthieu
264
README.md
264
README.md
@@ -1,92 +1,220 @@
|
|||||||
# Projet Inventory
|
# Inventory
|
||||||
|
|
||||||
## Installation du projet
|
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.
|
||||||
### 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)
|
|
||||||
|
|
||||||
### Linux
|
## Stack technique
|
||||||
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)
|
| 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
|
```bash
|
||||||
sudo apt install make -y
|
git clone --recurse-submodules <url-du-repo>
|
||||||
|
cd Inventory
|
||||||
make start
|
make start
|
||||||
make install
|
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
|
> Si `make start` échoue sur le port de la BDD, modifier `POSTGRES_PORT` dans `docker/.env.docker.local`.
|
||||||
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
|
|
||||||
|
|
||||||
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
|
### 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.
|
| Commande | Description |
|
||||||
C'est un bdd local dans le docker.
|
|----------|-------------|
|
||||||
|
| `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
|
### 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
|
```bash
|
||||||
make dev-nuxt
|
./scripts/release.sh patch # Bump patch (ou minor / major)
|
||||||
```
|
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Fonctionnement
|
Synchronise automatiquement la version dans `VERSION`, `api_platform.yaml` et `nuxt.config.ts`, crée le tag git et pousse les deux repos.
|
||||||
- À 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
|
|
||||||
|
|
||||||
### Compresser les PDFs existants
|
## Architecture
|
||||||
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
|
|
||||||
|
|
||||||
# Compresser tous les PDFs
|
### Structure du projet
|
||||||
php bin/console app:compress-pdf
|
|
||||||
|
```
|
||||||
|
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
|
### Entités principales
|
||||||
Pour restart le container
|
|
||||||
```bash
|
| Entité | Description |
|
||||||
make restart
|
|--------|-------------|
|
||||||
|
| `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
|
ROLE_ADMIN → ROLE_GESTIONNAIRE → ROLE_VIEWER → ROLE_USER
|
||||||
```bash
|
|
||||||
make test
|
|
||||||
```
|
```
|
||||||
Pour accéder au container et lance des commandes
|
|
||||||
```bash
|
- **ADMIN** : accès complet, gestion des profils
|
||||||
make shell
|
- **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
|
<type>(<scope>) : <message>
|
||||||
```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
|
||||||
|
|||||||
Reference in New Issue
Block a user