Aller au contenu

Module Catalogue main-d'oeuvre

Objectif

Le module Catalogue main-d'oeuvre séparé les prestations de main-d'oeuvre du catalogue produit standard.

Il couvre :

  • un type de catalogue dédié main_oeuvre ;
  • une navigation de premier niveau dans le catalogue ;
  • des familles et catégories métier ;
  • des prestations sans fournisseur ni image obligatoire ;
  • des options configurables ;
  • le choix entre options multipliees par quantite et options forfaitaires ;
  • l'utilisation dans les devis, factures et avoirs ;
  • le rendu PDF correct des lignes et options.

Emplacement du code

Fichiers principaux :

app/controllers/CatalogueController.php
app/models/CatalogueModel.php
app/models/CatalogueTaxonomyModel.php
app/views/catalogue.php
app/views/layout/catalogue.php
app/views/partials/catalogue.php
app/views/partials/modals/create-product-form-shared.php
app/views/partials/modals/modifier-produit-pour-catalogue.php
app/views/partials/modals/choisir-produit-pour-devis.php
app/views/partials/modals/price-simulator-modal.php
app/helpers/pdfDocumentGenerator.php
app/models/BaseDocumentModel.php

Migrations :

app/bd/catalogue-main-oeuvre.sql
app/bd/catalogue-taxonomies.sql

Tests de garde identifiés :

tests/catalogue_main_oeuvre_top_tab_test.php
tests/catalogue_toolbar_layout_test.php
tests/main_oeuvre_option_quantity_multiplier_test.php

Vue d'ensemble architecture

Catalogue UI
  |
  | catalogue_kind=main_oeuvre
  v
CatalogueController
  |
  v
CatalogueModel
  - catalogue
  - catalogue_options
  - catalogue_taxonomy_families
  - catalogue_taxonomy_categories
  |
  v
Documents
  - devis
  - factures
  - avoirs
  - PDF

Le point clé est catalogue_kind. Une ligne catalogue peut être :

  • standard : produit/prestation du catalogue classique ;
  • main_oeuvre : prestation de main-d'oeuvre dédiée.

Schéma de données

Catalogue

Migration :

  • app/bd/catalogue-main-oeuvre.sql

Ajouts sur catalogue :

catalogue_kind ENUM('standard','main_oeuvre') NOT NULL DEFAULT 'standard'
idx_catalogue_kind
taxonomy_family_id
taxonomy_category_id
idx_catalogue_taxonomy

catalogue_kind isole les prestations main-d'oeuvre sans créer une table séparée.

Options

Ajouts sur les options :

catalogue_options.image_option VARCHAR(500) NULL DEFAULT NULL
catalogue_options.multiply_with_quantity TINYINT(1) NOT NULL DEFAULT 1
devis_ligne_options.multiply_with_quantity TINYINT(1) NOT NULL DEFAULT 1
facture_ligne_options.multiply_with_quantity TINYINT(1) NOT NULL DEFAULT 1

multiply_with_quantity est le flag critique :

  • 1 : l'option suit la quantite de la ligne ;
  • 0 : l'option est forfaitaire et ne doit pas être remultipliee par la quantite.

Le défaut 1 conserve le comportement historique.

Taxonomies

Migration :

  • app/bd/catalogue-taxonomies.sql

Tables :

catalogue_taxonomy_families
catalogue_taxonomy_categories

Colonnes structurantes :

  • societe_id ;
  • scope : main_oeuvre ou ouvrage ;
  • name ;
  • sort_order ;
  • active.

Contraintes importantes :

  • unicite famille : societe_id, scope, name ;
  • unicite catégorie : family_id, name ;
  • suppression cascade des catégories quand une famille est supprimée.

Ces taxonomies sont partagees par la logique main-d'oeuvre et ouvrages, mais chaque ligne porte un scope.

Contrôleur

Fichier :

  • app/controllers/CatalogueController.php

Liste

Le contrôleur lit catalogue_kind depuis la query string.

Regle de normalisation :

catalogue_kind=main_oeuvre -> main_oeuvre
autre valeur ou absence     -> standard

Cette règle évite que le catalogue standard affiche la main-d'oeuvre par défaut.

Le contrôleur fournit aussi les taxonomies main-d'oeuvre a la vue :

listByScope('main_oeuvre')

Création

Endpoint logique :

CatalogueController::add()

Quand catalogue_kind = main_oeuvre, le contrôleur force :

  • type = prestation ;
  • marque = null ;
  • reference_fournisseur = null ;
  • fournisseur_id = null ;
  • recherche_fournisseur = '' ;
  • image ignoree même si un fichier est envoyé.

Les champs obligatoires restent :

nom
prix_achat_ht
prix_vente_ht
marge_value
type
unite

Le contrôleur decode aussi options si le payload en contient. Les options vides sont filtrees selon leur nom.

Edition

Endpoint logique :

CatalogueController::update()

L'édition reprend la même normalisation catalogue_kind. Si le produit est une main-d'oeuvre, les champs fournisseur/marque/image sont neutralises et les options peuvent être remplacees.

Taxonomies

Endpoints logique :

taxonomyList()
taxonomyCreateFamily()
taxonomyCreateCategory()

Ces actions délèguent à CatalogueTaxonomyModel.

Modèle catalogue

Fichier :

  • app/models/CatalogueModel.php

Filtrage

getPaginatedCatalogue() accepte :

catalogue_kind
family_id
category_id
prix_min
prix_max
type
search
created_by
date_debut
date_fin

Les filtres famille/catégorie ne s'appliquent que pour catalogue_kind = main_oeuvre.

Le modèle joint :

catalogue_taxonomy_families
catalogue_taxonomy_categories

en filtrant explicitement scope = 'main_oeuvre'.

Lecture d'une fiche

getById($id, true) peut charger :

  • la ligne catalogue ;
  • les taxonomies ;
  • les options ;
  • options_count.

Les options lues contiennent :

id
catalogue_id
nom
description
signe
unite
valeur
obligatoire
active
image_option
multiply_with_quantity

Remplacement des options

La méthode interne de remplacement supprime les options existantes du catalogue puis insère les nouvelles.

Règles appliquées à chaque option :

  • nom vide : option ignorée ;
  • signe limité à plus ou moins ;
  • unite limitée à euro ou pourcent ;
  • valeur forcée à un nombre positif ;
  • obligatoire converti en booléen ;
  • active converti en booléen ;
  • multiply_with_quantity conserve le défaut historique si absent.

Taxonomy model

Fichier :

  • app/models/CatalogueTaxonomyModel.php

Responsabilites :

  • lister familles et catégories actives par scope ;
  • créer/reactiver une famille ;
  • créer/reactiver une catégorie ;
  • normaliser un couple famille/catégorie ;
  • vérifier que la famille et la catégorie appartiennent à la société active.

Regle de scope :

scope=ouvrage -> ouvrage
autre valeur  -> main_oeuvre

normalizePair() retourne null pour la famille et la catégorie si la famille est invalide. Si la famille est valide mais la catégorie invalide, seule la catégorie est remise a null.

Point important : le modèle utilise $_SESSION['active_societe_id']. Les tests unitaires purs doivent donc initialiser la session ou passer par des tests de présence de code.

UI et navigation

La main-d'oeuvre est promue en onglet principal du catalogue.

Test de garde :

  • tests/catalogue_main_oeuvre_top_tab_test.php

Ce test vérifie que :

  • layout/catalogue.php contient id="main-oeuvre-btn" ;
  • l'onglet pointe vers catalogue_kind=main_oeuvre ;
  • l'onglet main-d'oeuvre est place avant Ouvrages ;
  • la main-d'oeuvre n'apparaît plus comme sous-onglet du catalogue standard ;
  • une ancienne URL Prestation sans catalogue_kind garde un comportement compatible.

La toolbar catalogue a aussi été simplifiee.

Test de garde :

  • tests/catalogue_toolbar_layout_test.php

Il vérifie que les vues catalogue, ouvrages et bibliothèques utilisent une structure :

catalogue-toolbar
catalogue-toolbar-title-row
catalogue-toolbar-search-row
catalogue-toolbar-actions-row

Interaction avec devis, factures et PDF

La main-d'oeuvre est selectionnable depuis les modales de document via :

  • choisir-produit-pour-devis.php ;
  • price-simulator-modal.php.

Le simulateur doit distinguer :

  • les options unitaires ;
  • les options forfaitaires.

Test de garde :

  • tests/main_oeuvre_option_quantity_multiplier_test.php

Ce test vérifie notamment que :

  • la migration ajouté multiply_with_quantity ;
  • le modèle lit et sauvegarde ce flag ;
  • les formulaires création/édition exposent le switch ;
  • le simulateur transmet multiply_with_quantity aux lignes document ;
  • le PDF ne remultiplie pas une option forfaitaire ;
  • BaseDocumentModel persisté le flag dans les options de ligne.

Point critique : si une option est forfaitaire, le prix unitaire transmis au document doit integrer correctement le total de ligne sans provoquer une double multiplication dans le PDF.

Invariants de reprise

  • catalogue_kind est la separation fonctionnelle centrale. Ne pas se baser uniquement sur type = prestation.
  • La main-d'oeuvre ne doit pas conserver de fournisseur, marque, référence fournisseur ou image produit.
  • Les taxonomies doivent toujours être vérifiées par societe_id et scope.
  • Une catégorie ne doit être acceptée que si elle appartient à la famille sélectionnée.
  • multiply_with_quantity doit être transporté du catalogue vers les lignes document puis jusqu'au PDF.
  • Les anciennes données doivent rester compatibles grâce aux valeurs par défaut standard et multiply_with_quantity = 1.

Points d'attention pour reprise

  • La création et l'édition remplacent les options en bloc. Si un futur besoin demande l'historique option par option, il faudra changer ce contrat.
  • Les migrations utilisent ADD COLUMN IF NOT EXISTS dans catalogue-taxonomies.sql, mais pas partout dans catalogue-main-oeuvre.sql. Vérifier l'idempotence avant exécution sur une base déjà partiellement migrée.
  • Les tests identifiés sont surtout des tests de présence de code et d'invariants structurels. Ils protègent les régressions grossières, mais ne remplacent pas un test bout-en-bout avec base SQL.
  • Les fonctions de taxonomie dépendent de la société active en session. Une reprise en CLI ou API devra fournir ce contexte explicitement.
  • Le scope ouvrage partage les tables de taxonomie. Une modification de schéma pour la main-d'oeuvre peut donc toucher les ouvrages.