Catalogue
Référence technique du domaine Catalogue — produits, catégories hiérarchiques, variantes, attributs et modalités de vente.
Catalogue
Périmètre : produits (équipements et services), catégories hiérarchiques,
attributs, variantes et modalités de vente (achat, abonnement, location,
service). Le catalogue est la source de vérité pour la tarification et la
configuration des devis/commandes/contrats. À distinguer des Asset (instances
physiques d'un produit).
Tous les écrans vivent sous
/workspace/catalog/* et les routes API sous
/api/workspace/catalog/*. Source de cette page : docs/12-domain-catalog.md.Vocabulaire & entités
| Terme | Entité | Définition |
|---|---|---|
| Produit | Product | Référence catalogue (modèle, forfait…). Distinct de l'instance physique Asset. |
| Catégorie | ProductCategory | Classification hiérarchique drag-drop pour la navigation. |
| Variante | ProductVariant | Déclinaison d'un produit (taille, couleur, capacité). Hérite du prix parent si non surchargé. |
| Attribut | ProductAttribute | Caractéristique technique key/value/unit (puissance kW, dimensions mm, fluide frigorigène…). |
| Modalité | ProductSellModality | Façon de vendre/louer : ONE_SHOT, SUBSCRIPTION, LEASE, SERVICE. Un produit peut en avoir plusieurs. |
| SKU | Product.sku | Référence unique par organisation, immuable. |
Le schéma complet est dans
docs/04-data-model.md§5. Le stock est porté parProduct.stockQuantity/stockThreshold; les variantes ont leur propre stock.
Écrans
| Écran | Route | Contenu |
|---|---|---|
| Liste produits | /workspace/catalog/products | DataTable : référence, nom, catégorie, prix HT, stock, modalités, statut. Filtres + recherche nom/ref/EAN. Export/import CSV, duplication. |
| Création / édition | /workspace/catalog/products/[id|new] | 8 onglets : Identité, Tarification, Stock, Attributs, Variantes, Modalités, Médias, SEO/portail. |
| Catégories | /workspace/catalog/categories | Arbre hiérarchique drag-drop. CRUD + réorganisation (position / parentId). |
| Catalogue client | /client/catalog | (futur) Vue portail client — navigation catégorie, filtres, demande de devis. |
Modèle de données (points clés)
Product.skuest unique par organisation ; la contrainte DB est à l'index composite(organizationId, sku).ProductVariant.priceHt: si renseigné, prime surProduct.priceHt; sinon héritage automatique.- Soft delete via
Product.deletedAt— hard delete interdit si le produit est référencé dans un devis, une commande ou une facture. - Stock négatif autorisé (back-order) mais alerte visuelle déclenchée.
ProductSellModalityporte les paramètres propres à chaque type de vente (cf. tableau des modalités ci-dessous).
Types de modalités
| Type | Paramètres principaux |
|---|---|
ONE_SHOT (achat) | Prix HT, TVA, conditions |
SUBSCRIPTION | Prix HT/période, période (mensuel/trimestriel/annuel), durée min d'engagement |
LEASE (location) | Durée min/max (mois), caution éventuelle, conditions LLD/LCD |
SERVICE | Unité (intervention, heure, km), tarif HT/unité |
API
Toutes les routes exigent une permission catalog.* (vérifiée côté API et UI).
| Méthode | Route | Permission |
|---|---|---|
GET | /api/workspace/catalog/products | catalog.product:read |
POST | /api/workspace/catalog/products | catalog.product:create |
GET | /api/workspace/catalog/products/[id] | catalog.product:read |
PATCH | /api/workspace/catalog/products/[id] | catalog.product:update |
POST | /api/workspace/catalog/products/[id]/archive | catalog.product:archive |
POST | /api/workspace/catalog/products/import | catalog.product:create |
GET | /api/workspace/catalog/categories | catalog.product:read |
POST | /api/workspace/catalog/categories | catalog.category:manage |
PATCH | /api/workspace/catalog/categories/[id] | catalog.category:manage |
POST | /api/workspace/catalog/categories/reorder | catalog.category:manage |
Exemple de référence d'endpoint :
POST
/api/workspace/catalog/products/importAuth Importe en masse des produits depuis un fichier CSV/XLSX. Crée ou met à jour selon la présence du SKU. Retourne un rapport lignes créées / modifiées / en erreur.
Corps (multipart/form-data)
file
File required
Fichier CSV ou XLSX ; colonnes attendues :
sku, name, priceHt, vat, stock, category.updateExisting
boolean
Si
true, met à jour les produits dont le SKU existe déjà (défaut : true).Requête
curl -s -X POST "$API/api/workspace/catalog/products/import" \
-H "Cookie: $SESSION" \
-F "file=@catalogue.csv" \
-F "updateExisting=true"
Réponse
{
"created": 42,
"updated": 8,
"errors": [
{ "row": 5, "sku": "REF-99", "message": "priceHt manquant" }
]
}
Workflows
Import en masse (CSV / XLSX)
Upload fichier → mapping colonnes → aperçu 10 lignes → validation Zod par ligne
├──→ SKU inconnu → création Product
├──→ SKU existant → mise à jour (si updateExisting)
└──→ Erreur ligne → rejet, reste du fichier traité
Rapport final : N créées · N modifiées · N erreurs
Stock & alertes
OrderLine / MaintenanceOperationPart validée
→ décrément Product.stockQuantity
→ si stock ≤ stockThreshold → notification responsable achats
→ (futur) création SupplierQuote pré-remplie (réapprovisionnement)
Archivage produit
POST .../archive → Product.deletedAt = now()
├──→ produit masqué dans le sélecteur de devis / commande
└──→ visible en lecture dans l'historique contrats / factures passées
Règles métier
- SKU unique par organisation (contrainte DB) — immuable après création.
- TVA par défaut éditable parmi les taux légaux FR : 20 %, 10 %, 5,5 %.
- Variante : prix surchargé prime ; sinon héritage du produit parent.
- Suppression hard interdite si produit référencé dans devis, commande ou facture — soft delete uniquement.
- Stock négatif autorisé temporairement (back-order) — alerte visuelle déclenchée, aucun blocage automatique.
- Un produit peut cumuler plusieurs modalités (
ONE_SHOT+LEASEpar exemple).