264 lines
9.4 KiB
Markdown
264 lines
9.4 KiB
Markdown
# 🏭 API d'Inventaire Industriel
|
|
|
|
API NestJS pour la gestion d'inventaire industriel avec architecture hiérarchique des machines, composants et pièces.
|
|
|
|
## 🚀 Installation
|
|
|
|
### Prérequis
|
|
- Node.js 18+
|
|
- PostgreSQL
|
|
- Fedora Linux (pour le script d'installation automatique)
|
|
|
|
### Configuration rapide
|
|
|
|
1. **Installer les dépendances**
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
2. **Configurer la base de données PostgreSQL**
|
|
```bash
|
|
# Option 1: Installation automatique (Fedora)
|
|
chmod +x setup-database.sh
|
|
./setup-database.sh
|
|
|
|
# Option 2: Installation manuelle
|
|
sudo dnf install postgresql postgresql-server postgresql-contrib
|
|
sudo postgresql-setup --initdb
|
|
sudo systemctl start postgresql
|
|
sudo systemctl enable postgresql
|
|
|
|
# Créer la base de données
|
|
sudo -u postgres psql -c "CREATE DATABASE inventory_db;"
|
|
sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'password';"
|
|
```
|
|
|
|
3. **Générer le client Prisma et appliquer les migrations**
|
|
```bash
|
|
npx prisma generate
|
|
npx prisma migrate dev --name init
|
|
```
|
|
|
|
4. **Démarrer l'API**
|
|
```bash
|
|
npm run start:dev
|
|
```
|
|
|
|
L'API sera disponible sur `http://localhost:3000/api`
|
|
|
|
## 🌾 Données de démonstration (usine de triage de céréales)
|
|
|
|
Le script `npm run seed:demo` permet de remplir la base avec un jeu de données complet représentant une ligne de triage et de séchage de céréales. Il supprime toutes les données existantes (machines, composants, pièces, champs personnalisés, modèles, types...) tout en conservant les sites et profils déjà enregistrés.
|
|
|
|
### Contenu généré
|
|
|
|
- Catégories de composants et de pièces avec champs personnalisés adaptés (élévateurs à godets, convoyeurs à bande, table densimétrique, séchoir, vis sans fin, benne peseuse, armoire de contrôle, Manitou, etc.).
|
|
- Modèles de composants multi-niveaux et modèles de pièces cohérents (moteurs, capteurs, courroies, roulements, réducteurs, capteurs de pesage, sondes PT100...).
|
|
- Type de machine « Ligne de triage et séchage céréales 120 t/h » incluant exigences de composants/pièces, pièces critiques et champs personnalisés.
|
|
- Machine réelle "Ligne de triage Valgrain 2024" avec hiérarchie complète de composants, sous-composants, pièces associées et valeurs de champs personnalisés.
|
|
- Pièces de réserve répondant aux exigences de stock (moteur de secours, capteur de vitesse).
|
|
|
|
### Exécution
|
|
|
|
```bash
|
|
npm run seed:demo
|
|
```
|
|
|
|
Assurez-vous que la variable d'environnement `DATABASE_URL` pointe vers votre base PostgreSQL avant l'exécution. Le script utilise Prisma et se termine automatiquement en cas d'erreur.
|
|
|
|
## 📊 Structure de la base de données
|
|
|
|
### Entités principales
|
|
- **Site** : Représente un site/usine
|
|
- **Machine** : Appartient à un site, peut contenir des composants et des pièces
|
|
- **Composant** : Peut appartenir à une machine ou à un autre composant (arborescence infinie)
|
|
- **Piece** : Peut appartenir à une machine ou à un composant
|
|
- **TypeMachine/TypeComposant/TypePiece** : Définissent l'architecture et les champs personnalisés
|
|
- **Document** : Fichiers/images liés aux éléments
|
|
- **CustomField/CustomFieldValue** : Champs personnalisés dynamiques
|
|
|
|
### Relations
|
|
```
|
|
Site → Machine → Composant → Sous-composant → ...
|
|
↓ ↓
|
|
Machine → Piece
|
|
Composant → Piece
|
|
```
|
|
|
|
## 🔌 API Endpoints
|
|
|
|
### Sites
|
|
- `GET /api/sites` - Liste tous les sites avec leur hiérarchie complète
|
|
- `GET /api/sites/:id` - Détails d'un site
|
|
- `POST /api/sites` - Créer un site
|
|
- `PATCH /api/sites/:id` - Modifier un site
|
|
- `DELETE /api/sites/:id` - Supprimer un site
|
|
|
|
### Machines
|
|
- `GET /api/machines` - Liste toutes les machines
|
|
- `GET /api/machines/:id` - Détails d'une machine
|
|
- `POST /api/machines` - Créer une machine
|
|
- `PATCH /api/machines/:id` - Modifier une machine
|
|
- `DELETE /api/machines/:id` - Supprimer une machine
|
|
|
|
#### Payloads `componentSelections` / `pieceSelections`
|
|
|
|
Lors de la création d'une machine à partir d'un type, il est possible de fournir des sélections de composants et de pièces qui viendront remplir les exigences définies dans le type de machine.
|
|
|
|
```json
|
|
{
|
|
"name": "Presse HP-2000",
|
|
"siteId": "<identifiant du site>",
|
|
"typeMachineId": "<identifiant du type de machine>",
|
|
"componentSelections": [
|
|
{
|
|
"requirementId": "<id d'une TypeMachineComponentRequirement>",
|
|
"componentModelId": "<optionnel : modèle existant>",
|
|
"definition": {
|
|
"name": "Bloc moteur série X",
|
|
"reference": "COMP-001",
|
|
"prix": "12000.00",
|
|
"customFields": [
|
|
{
|
|
"name": "Puissance nominale",
|
|
"type": "text",
|
|
"required": true,
|
|
"value": "7 kW"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
],
|
|
"pieceSelections": [
|
|
{
|
|
"requirementId": "<id d'une TypeMachinePieceRequirement>",
|
|
"pieceModelId": "<optionnel : modèle existant>",
|
|
"definition": {
|
|
"name": "Kit maintenance niveau 1",
|
|
"reference": "KIT-001",
|
|
"customFields": [
|
|
{
|
|
"name": "Référence fournisseur",
|
|
"type": "text",
|
|
"value": "STD-002"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Principales règles de validation :
|
|
|
|
- `requirementId` doit correspondre à une exigence déclarée dans le type de machine (composant ou pièce).
|
|
- Le nombre de sélections pour une exigence doit respecter `minCount` et `maxCount` (si défini). Les exigences marquées `required` imposent au moins une sélection.
|
|
- Si `allowNewModels` vaut `false`, il est obligatoire de fournir un `componentModelId`/`pieceModelId` existant. Sinon un `definition` sans modèle peut être utilisé pour créer un nouvel élément.
|
|
- Les modèles sélectionnés doivent appartenir au type attendu (`typeComposantId` ou `typePieceId`) sous peine d'échec de la création.
|
|
- Les champs personnalisés du `definition.customFields` permettent de surcharger la valeur par défaut définie au niveau du type; la valeur est automatiquement injectée dans les `customFieldValues` de la machine, du composant ou de la pièce créée.
|
|
|
|
### Composants
|
|
- `GET /api/composants` - Liste tous les composants
|
|
- `GET /api/composants/:id` - Détails d'un composant
|
|
- `POST /api/composants` - Créer un composant
|
|
- `PATCH /api/composants/:id` - Modifier un composant
|
|
- `DELETE /api/composants/:id` - Supprimer un composant
|
|
|
|
### Pièces
|
|
- `GET /api/pieces` - Liste toutes les pièces
|
|
- `GET /api/pieces/:id` - Détails d'une pièce
|
|
- `POST /api/pieces` - Créer une pièce
|
|
- `PATCH /api/pieces/:id` - Modifier une pièce
|
|
- `DELETE /api/pieces/:id` - Supprimer une pièce
|
|
|
|
### Types
|
|
- `GET /api/types/machines` - Liste tous les types de machines
|
|
- `GET /api/types/composants` - Liste tous les types de composants
|
|
- `GET /api/types/pieces` - Liste tous les types de pièces
|
|
- `POST /api/types/machines` - Créer un type de machine
|
|
- `POST /api/types/composants` - Créer un type de composant
|
|
- `POST /api/types/pieces` - Créer un type de pièce
|
|
|
|
### Documents
|
|
- `GET /api/documents` - Liste tous les documents
|
|
- `POST /api/documents` - Uploader un document
|
|
- `DELETE /api/documents/:id` - Supprimer un document
|
|
|
|
## 🛠️ Développement
|
|
|
|
### Scripts disponibles
|
|
```bash
|
|
npm run start # Démarrer en mode production
|
|
npm run start:dev # Démarrer en mode développement avec hot reload
|
|
npm run build # Compiler le projet
|
|
npm run test # Lancer les tests
|
|
npm run test:e2e # Lancer les tests end-to-end
|
|
npm run test:cov # Lancer les tests avec couverture
|
|
```
|
|
|
|
### Variables d'environnement
|
|
Créer un fichier `.env` :
|
|
```env
|
|
DATABASE_URL="postgresql://postgres:password@localhost:5432/inventory_db?schema=public"
|
|
PORT=3000
|
|
NODE_ENV=development
|
|
```
|
|
|
|
### Prisma
|
|
```bash
|
|
npx prisma studio # Interface graphique pour la base de données
|
|
npx prisma migrate dev # Créer et appliquer une migration
|
|
npx prisma generate # Régénérer le client Prisma
|
|
npx prisma db push # Pousser les changements sans migration
|
|
```
|
|
|
|
## 📁 Structure du projet
|
|
|
|
```
|
|
src/
|
|
├── sites/ # Module de gestion des sites
|
|
├── machines/ # Module de gestion des machines
|
|
├── composants/ # Module de gestion des composants
|
|
├── pieces/ # Module de gestion des pièces
|
|
├── documents/ # Module de gestion des documents
|
|
├── types/ # Module de gestion des types
|
|
├── prisma/ # Configuration Prisma
|
|
└── shared/ # DTOs et utilitaires partagés
|
|
```
|
|
|
|
## 🔧 Configuration Docker (optionnel)
|
|
|
|
Pour utiliser Docker avec PostgreSQL :
|
|
|
|
```bash
|
|
# Démarrer PostgreSQL avec Docker
|
|
docker run --name postgres-inventory \
|
|
-e POSTGRES_PASSWORD=password \
|
|
-e POSTGRES_DB=inventory_db \
|
|
-p 5432:5432 \
|
|
-d postgres:15
|
|
|
|
# Modifier le DATABASE_URL dans .env
|
|
DATABASE_URL="postgresql://postgres:password@localhost:5432/inventory_db?schema=public"
|
|
```
|
|
|
|
## 🎯 Fonctionnalités
|
|
|
|
- ✅ Architecture hiérarchique infinie (sites → machines → composants → sous-composants → pièces)
|
|
- ✅ Gestion des types avec champs personnalisés dynamiques
|
|
- ✅ Upload et gestion de documents
|
|
- ✅ Validation des données avec class-validator
|
|
- ✅ API REST complète avec NestJS
|
|
- ✅ Base de données PostgreSQL avec Prisma ORM
|
|
- ✅ Support CORS pour le frontend
|
|
- ✅ Structure modulaire et extensible
|
|
|
|
## 🚧 Prochaines étapes
|
|
|
|
- [ ] Implémentation complète des contrôleurs et services
|
|
- [ ] Gestion des champs personnalisés
|
|
- [ ] Upload de fichiers
|
|
- [ ] Tests unitaires et d'intégration
|
|
- [ ] Documentation Swagger/OpenAPI
|
|
- [ ] Frontend Nuxt 3
|