# Glossaire Métier — Inventory

## Contexte

**Inventory** est une application de gestion de parc machines industriel. Elle permet aux équipes de maintenance de cataloguer leurs machines, leurs sous-ensembles (composants), les pièces de rechange et les consommables associés. Chaque machine est rattachée à un site physique (usine, atelier). L'application gère la hiérarchie complète : Machine → Composants → Pièces/Produits, avec traçabilité (audit), documentation technique et champs personnalisables.

---

## Concepts Métier

### Hiérarchie principale

| Terme | Définition | Exemples concrets |
|-------|-----------|-------------------|
| **Site** | Lieu physique (usine, atelier, entrepôt). Regroupe les machines d'un même emplacement. | Usine de Lyon, Atelier Nord |
| **Machine** | Équipement industriel installé sur un site. C'est l'unité de base du parc. Contient des composants, pièces et produits. | Presse hydraulique, Tour CNC, Ligne d'embouteillage |
| **Composant** | Sous-ensemble fonctionnel d'une machine. Peut contenir des pièces, des produits, et d'autres sous-composants (imbrication). | Moteur, Pompe, Tableau électrique, Vérin |
| **Pièce** | Pièce mécanique/physique qu'on monte ou remplace. C'est l'unité de maintenance. | Joint, Écrou, Roulement, Capteur, Courroie |
| **Produit** | Consommable qu'on utilise sans monter. S'use et se renouvelle. | Huile, Dégraissant, Graisse, Liquide de refroidissement |

### Configuration et templates

| Terme | Définition |
|-------|-----------|
| **Modèle Type** (ModelType) | Template réutilisable qui définit la composition attendue d'un composant, d'une pièce ou d'un produit. Par exemple : "Pompe centrifuge XYZ nécessite 2 joints, 1 roulement et de l'huile hydraulique". |
| **Skeleton** (squelette) | La structure "vide" définie par un modèle type : la liste des emplacements requis (pièces, produits, sous-composants) avant qu'on y mette les éléments réels. |
| **Slot** (emplacement) | Emplacement concret dans un composant ou une pièce, créé à partir du skeleton. Chaque slot est à remplir avec une pièce, un produit ou un sous-composant réel. Un slot peut rester vide (pas encore sourcé). |
| **Sync** (synchronisation) | Propagation des modifications d'un modèle type vers tous les composants existants de ce type. Par exemple : ajouter un slot "filtre" au modèle type met à jour tous les composants de ce type. Surtout utilisé en phase de saisie initiale, quand on ajuste les modèles au fur et à mesure qu'on découvre la vraie composition des machines. |
| **Catégorie de modèle** | Un modèle type est classé en 3 catégories : Composant, Pièce ou Produit. Détermine quels skeletons il peut définir. |

### Transverse

| Terme | Définition |
|-------|-----------|
| **Constructeur** | Fournisseur ou fabricant. Peut être associé à une machine, un composant, une pièce ou un produit. Permet de tracer la chaîne d'approvisionnement. |
| **Champ personnalisé** (CustomField) | Attribut dynamique défini par l'utilisateur et attaché à une machine ou à un modèle type. Les composants/pièces/produits d'un même modèle type partagent les mêmes champs personnalisés. Exemples : "N° de série", "Date de garantie", "Intervalle de maintenance". |
| **Document** | Fichier attaché à n'importe quelle entité (machine, composant, pièce, produit, site, commentaire). Typé : Documentation, Devis, Facture, Plan, Photo, Autre. |
| **Commentaire** | Annotation utilisateur sur une entité, avec un statut ouvert ou résolu. Permet de signaler un problème, poser une question ou laisser une note. Peut contenir des pièces jointes. |
| **Journal d'audit** (AuditLog) | Historique automatique et immuable de toutes les créations, modifications et suppressions. Enregistre qui a fait quoi, quand, avec le détail des changements. |

### Utilisateurs et rôles

| Rôle | Droits |
|------|--------|
| **Admin** | Accès complet : gestion des utilisateurs, configuration, toutes les opérations |
| **Gestionnaire** | Créer, modifier, supprimer des machines/composants/pièces/produits |
| **Viewer** | Consultation seule, pas de modification |
| **User** | Rôle de base (accès minimal) |

---

## Workflows Utilisateur

### 1. Créer une machine
1. Choisir le **site** où la machine est installée
2. Renseigner nom, référence, prix, fournisseur(s)
3. Ajouter des **composants** à la machine (voir workflow 2)
4. Ajouter des **pièces** et **produits** directement sur la machine si nécessaire
5. Ajouter des **champs personnalisés** et des **documents**

### 2. Ajouter un composant à une machine
1. Choisir un **modèle type** pour le composant (ex: "Pompe centrifuge XYZ")
2. Les **slots** sont pré-créés automatiquement à partir du skeleton du modèle type
3. Remplir chaque slot en sélectionnant la pièce/produit/sous-composant réel
4. Les slots peuvent rester vides et être remplis plus tard

### 3. Créer ou modifier un modèle type
1. Nommer le modèle type et choisir sa catégorie (Composant, Pièce ou Produit)
2. Définir les emplacements requis : quelles pièces, quels produits, quels sous-composants
3. Définir les champs personnalisés (métadonnées) pour les entités de ce type
4. Si des composants existent déjà avec ce modèle type → utiliser le **sync** (workflow 4)

### 4. Synchroniser un modèle type
1. Modifier les emplacements du modèle type (ajout/suppression de slots)
2. Lancer un **sync preview** : visualiser l'impact sur les composants existants
3. Confirmer → les slots sont ajoutés/supprimés sur tous les composants du type
4. Surtout utile en phase de saisie initiale quand les données sont ajustées progressivement

### 5. Cloner une machine
1. Sélectionner une machine existante
2. Lancer le clonage → copie complète (composants, pièces, produits, liens, champs personnalisés)
3. Renommer la machine clonée et l'affecter à un site

### 6. Gérer les documents
1. Sélectionner une entité (machine, composant, pièce, produit, site)
2. Uploader un fichier (PDF, image, etc.)
3. Choisir le type : Documentation, Devis, Facture, Plan, Photo, Autre
4. Les documents sont consultables et téléchargeables depuis la fiche de l'entité

---

## Relations — Vue d'ensemble

```
Site
 └── Machine
      ├── Composant (→ défini par un Modèle Type)
      │    ├── Slot Pièce → Pièce (joint, écrou…)
      │    ├── Slot Produit → Produit (huile, dégraissant…)
      │    └── Slot Sous-composant → Composant (imbrication)
      ├── Pièce (directement sur la machine)
      │    └── Slot Produit → Produit
      └── Produit (directement sur la machine)

Modèle Type (template)
 ├── Skeleton Pièce Requirement → "il faut une pièce de type X"
 ├── Skeleton Produit Requirement → "il faut un produit de type Y"
 └── Skeleton Sous-composant Requirement → "il faut un composant de type Z"

Transverse (attachable à toute entité) :
 • Constructeur (fournisseur)
 • Document (fichier)
 • Commentaire (annotation)
 • Champ personnalisé (métadonnée dynamique)
 • Journal d'audit (historique automatique)
```

---

## Correspondance Métier ↔ Code

| Terme métier | Entité code | Table PG |
|-------------|-------------|----------|
| Site | `Site` | `site` |
| Machine | `Machine` | `machine` |
| Composant | `Composant` | `composant` |
| Pièce | `Piece` | `piece` |
| Produit | `Product` | `product` |
| Modèle Type | `ModelType` | `model_type` |
| Slot pièce (composant) | `ComposantPieceSlot` | `composant_piece_slot` |
| Slot produit (composant) | `ComposantProductSlot` | `composant_product_slot` |
| Slot sous-composant | `ComposantSubcomponentSlot` | `composant_subcomponent_slot` |
| Slot produit (pièce) | `PieceProductSlot` | `piece_product_slot` |
| Skeleton pièce | `SkeletonPieceRequirement` | `skeleton_piece_requirement` |
| Skeleton produit | `SkeletonProductRequirement` | `skeleton_product_requirement` |
| Skeleton sous-composant | `SkeletonSubcomponentRequirement` | `skeleton_subcomponent_requirement` |
| Constructeur | `Constructeur` | `constructeur` |
| Champ personnalisé | `CustomField` | `custom_field` |
| Valeur champ perso | `CustomFieldValue` | `custom_field_value` |
| Document | `Document` | `document` |
| Commentaire | `Comment` | `comment` |
| Journal d'audit | `AuditLog` | `audit_log` |
| Utilisateur | `Profile` | `profile` |
| Lien machine-composant | `MachineComponentLink` | `machine_component_link` |
| Lien machine-pièce | `MachinePieceLink` | `machine_piece_link` |
| Lien machine-produit | `MachineProductLink` | `machine_product_link` |