221 lines
7.8 KiB
Markdown
221 lines
7.8 KiB
Markdown
# 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
|