Aller au contenu

Module Commandes fournisseurs

Objectif

Le module Commandes fournisseurs permet à une entreprise de préparer, envoyer et suivre une commande destinée à un fournisseur. Il couvre plusieurs sources de produits, plusieurs types de destinataires, des pièces jointes, des croquis de ligne, une conversation, un suivi de statut et une file de notifications email.

Le point important pour la reprise : ce module n'est pas seulement un formulaire. Il relie catalogue, bibliothèques fournisseurs, devis, fournisseurs internes, portail fournisseur, messagerie, tracking email et feature plan.

Périmètre documenté

Cette page documente les fichiers listés dans les points d'entrée ci-dessous. Avant une correction, ouvrir ces fichiers dans la branche de travail concernée et vérifier l'historique git du module si le comportement observé ne correspond pas à la documentation.

Architecture fonctionnelle

flowchart LR
  Router[Router.php] --> Controller[SupplierOrderController]
  Controller --> Model[SupplierOrderModel]
  Model --> DB[(MySQL)]
  Model --> Messaging[MessagingModel]
  Model --> Devis[DevisModel]
  Model --> Notify[SupplierOrderNotificationService]
  Notify --> Mailer[MailerService]
  Notify --> Tracking[DocumentEmailViewModel]
  Cron[supplier_order_notifications_cron.php] --> Notify
  Controller --> View[supplier-orders.php]

Points d'entrée

Backend

  • app/controllers/SupplierOrderController.php : routes HTTP, payloads JSON/form-data, chargement de page entreprise et fournisseur.
  • app/models/SupplierOrderModel.php : règles métier, droits, sauvegarde, statuts, pièces jointes, conversations, catalogue, devis.
  • app/services/SupplierOrderNotificationService.php : file de notifications, rendu email, tracking, retry.
  • app/cron/supplier_order_notifications_cron.php : traitement CLI des notifications en attente.

Front et stockage

  • app/views/supplier-orders.php : interface principale, modales, wizard, timeline, conversation.
  • public/uploads/supplier_orders/.gitkeep : racine de stockage des fichiers du module.

SQL

  • app/bd/supplier-orders.sql
  • app/bd/supplier-orders-pme-feature.sql

La page squelette historique mentionnait app/bd/supplier-orders-tpe-feature.sql, mais ce fichier n'est pas présent dans le checkout actuel. Si un environnement attend ce script, retrouver son origine avant migration.

Routes

Routes principales dans app/core/Router.php :

  • commandes-fournisseurs : page entreprise, protégée par FEATURE_COMMANDE_FOURNISSEUR.
  • commandes : page fournisseur, réservée aux comptes fournisseur.
  • commande-fournisseur/get : détail commande.
  • commande-fournisseur/conversation : conversation liee.
  • commande-fournisseur/pdf : export PDF.
  • commande-fournisseur/save : création ou mise à jour.
  • commande-fournisseur/change-status : changement de statut, utilisable par entreprise ou fournisseur selon le contexte.
  • commande-fournisseur/libraries : bibliothèques accessibles.
  • commande-fournisseur/recipients : fournisseurs enregistres.
  • commande-fournisseur/quotes : devis disponibles.
  • commande-fournisseur/quote-draft : brouillon de commande depuis devis.
  • commande-fournisseur/products : produits disponibles selon source.
  • commande-fournisseur/product-config : configurateur produit.

Permissions, feature et contextes utilisateur

La feature fonctionnelle est FEATURE_COMMANDE_FOURNISSEUR.

Le modèle distingue trois contextes :

  • admin : traite comme contexte membre pour la société active ;
  • membre : entreprise qui créé et suit la commande ;
  • fournisseur : destinataire qui consulte et met à jour certains statuts.

checkMemberFeatureAccess ne bloque pas les fournisseurs. Les fournisseurs doivent pouvoir accéder à leurs commandes sans posséder la feature entreprise.

Sources et destinataires

Modes source (source_mode) :

  • partner_library : commande depuis bibliothèque fournisseur partenaire.
  • direct_catalog : commande depuis catalogue direct.
  • quote : commande pre-remplie depuis un devis.

Types de destinataire (recipient_type) :

  • library : bibliothèque fournisseur, avec portail fournisseur si recipient_membre_id existe.
  • supplier : fournisseur enregistre localement dans fournisseurs.
  • email : destinataire libre par email.

Types de bibliothèque :

  • cpt : menuiserie sur mesure.
  • std : classique.

Types de produit en ligne :

  • catalogue
  • cpt
  • std

SupplierOrderModel normalise les anciennes valeurs standard vers std et carpentry vers cpt. Ne pas changer ces valeurs sans migration des données existantes.

Donnees et schéma

supplier_orders

Table principale.

Colonnes structurantes :

  • societe_id : société emettrice.
  • source_mode, source_quote_id : origine de la commande.
  • recipient_type, recipient_library_type, recipient_library_id, recipient_supplier_id, recipient_name, recipient_email, recipient_membre_id : destinataire.
  • created_by_membre_id : membre createur.
  • conversation_id : conversation liee.
  • reference : référence commande.
  • customer_name, customer_email, customer_phone, customer_address, site_address : client et lieu.
  • requested_delivery_date, delivery_week, delivery_week_status : livraison demandee ou annoncee.
  • factory_departure_date, shipping_date, received_at : jalons de production/livraison.
  • status, submitted_at, last_status_changed_at, archived_at, deleted_at : workflow.

Statuts SQL :

  • draft
  • en attente
  • incomplet
  • validé
  • en fabrication
  • expédiée
  • réceptionnée
  • archivée

La migration convertit l'ancien statut terminée vers réceptionnée.

supplier_order_lines

Lignes de commande.

Colonnes importantes :

  • product_type, product_id, source_library_id, source_library_name_snapshot.
  • product_name_snapshot, product_reference_snapshot : snapshots pour garder la commande stable si le catalogue évolue.
  • quantity, line_reference, width, height.
  • measure_basis : ajouté runtime si absent ; valeurs métier pour les produits cpt.
  • configuration_json, configuration_summary_json.
  • croquis_file_path, croquis_original_name, croquis_mime_type, croquis_file_size.
  • sort_order.

replaceOrderLines supprime toutes les lignes d'une commande puis les réinsère. Toute modification de ce flux doit donc prendre en compte la perte potentielle d'identifiants de ligne.

supplier_order_attachments

Pieces jointes globales de la commande :

  • file_path
  • original_name
  • mime_type
  • file_size

syncAttachments supprime les pièces non conservées via existing_attachment_ids, puis ajoute les nouveaux fichiers attachments.

supplier_order_status_history

Historique des statuts :

  • old_status
  • new_status
  • changed_by_membre_id
  • changed_by_type : supplier, member, admin, etc.
  • note
  • created_at

La timeline combine cet historique, l'événement de création, l'envoi au fournisseur et les consultations email.

supplier_order_notifications

File des emails :

  • source_type : order_created ou status_updated.
  • payload_json : payload rendu par le service.
  • status : pending, processing, sent, failed.
  • retry_count, next_retry_at, last_error, sent_at.

La table est créée par migration SQL et aussi assurée dans SupplierOrderNotificationService::ensureStorageSchema. Garder les deux en cohérence.

document_email_views

Table de tracking partagee avec d'autres documents. Ici elle suit les ouvertures de liens email pour document_type = supplier_order.

Création et sauvegarde

SupplierOrderController::save envoie au modèle :

  • order_id
  • source_mode
  • source_quote_id
  • recipient_type
  • recipient_library_type
  • recipient_library_id
  • recipient_supplier_id
  • recipient_name
  • recipient_email
  • reference
  • customer_name
  • customer_address
  • site_address
  • observations
  • save_mode
  • lines_json
  • existing_attachment_ids
  • $_FILES

Règles importantes :

  • seuls les contextes entreprise peuvent créer ou éditer ;
  • un fournisseur ne peut jamais éditer une commande ;
  • une commande n'est éditable par l'entreprise que si elle appartient à la société active ;
  • seuls les statuts draft et incomplet sont editables ;
  • save_mode = draft garde un brouillon ;
  • une soumission passe en en attente.

Apres sauvegarde, le modèle remplace les lignes, synchronisé les pièces jointes, créé ou synchronisé la conversation et planifie la notification de création si la commande est envoyée.

Devis vers commande

getQuoteDraft charge un devis via DevisModel, puis transforme certaines lignes en lignes de commande.

Points de vigilance :

  • toutes les lignes de devis ne sont pas forcement compatibles ;
  • le modèle retourne aussi des lignes exclues ;
  • source_mode = quote conserve le lien vers source_quote_id ;
  • le destinataire choisi influence la compatibilité des lignes.

Avant de modifier le mapping devis, tester un devis avec lignes catalogue, cpt, std, lignes sans produit et lignes avec dimensions.

Produits et configurateur

Le module interroge trois univers :

  • catalogue interne (catalogue) ;
  • bibliothèques cpt ;
  • bibliothèques std.

getProductSourceConfig centralise les noms de tables et colonnes par source. Pour cpt, la référence fournisseur vient de reference_fournisseur. Pour std, elle vient de reference. Pour le catalogue, il n'y a pas de colonne de référence produit dédiée dans cette configuration.

Le configurateur lit les options, valeurs et compatibilités propres à chaque source. Ne pas dupliquer ces requêtes dans le contrôleur.

Uploads et fichiers

Constantes :

  • module upload : supplier_orders;
  • dossier pièces jointes : attachments;
  • dossier croquis : croquis;
  • taille maximum : 5 Mio.

Pieces jointes :

  • champ attachments;
  • plusieurs fichiers ;
  • suppression des anciens fichiers non conserves en base.

Croquis de ligne :

  • champ attendu : line_croquis_<client_key>;
  • utilise seulement pour les produits cpt;
  • si aucun nouveau fichier n'est envoyé, le modèle conserve existing_croquis_*.

Risques :

  • une ligne sans client_key correct ne pourra pas rattacher son croquis ;
  • supprimer/réinsèrer toutes les lignes impose de bien transporter les anciens chemins de croquis ;
  • les suppressions base ne garantissent pas, a elles seules, la suppression physique des fichiers.

Statuts et transitions

Statuts métier :

  • draft : brouillon entreprise.
  • en attente : commande envoyée au fournisseur.
  • incomplet : fournisseur ou entreprise signale un complement nécessaire.
  • validé : fournisseur valide.
  • en fabrication : fournisseur indique la fabrication.
  • expédiée : fournisseur indique l'expedition.
  • réceptionnée : entreprise confirme la reception.
  • archivée : archive logique.

Transitions fournisseur :

  • interdit si la commande ne supporte pas le portail fournisseur ;
  • interdit si recipient_membre_id ne correspond pas au fournisseur connecte ;
  • interdit depuis réceptionnée ;
  • peut choisir en attente, incomplet, validé, en fabrication, expédiée.

Transitions entreprise :

  • pour flux fournisseur externe (supplier ou email sans portail), l'entreprise peut appliquer en attente, incomplet, validé, en fabrication, expédiée, réceptionnée.
  • pour flux portail fournisseur, l'entreprise ne peut confirmer que réceptionnée, et seulement depuis expédiée.
  • aucun changement de statut depuis draft ou archivée via changeStatus.

Dates obligatoires :

  • en fabrication exige factory_departure_date.
  • expédiée exige shipping_date.
  • réceptionnée remplit received_at avec maintenant si la date est absente.

Chaque changement écrit supplier_order_status_history. Les notifications de statut ne sont planifiees que si le statut change vraiment ; une modification de date seule ajouté l'historique mais ne déclenche pas la notification de statut.

Notifications

SupplierOrderNotificationService gère deux sources :

  • order_created
  • status_updated

Cycle d'envoi :

  1. insertion dans supplier_order_notifications avec status = pending ;
  2. envoi immédiat possible via sendNotificationById ;
  3. claim atomique : passage pending vers processing ;
  4. en cas de succès : sent, sent_at, last_error = NULL ;
  5. en cas d'échec : retry ou échec définitif.

Parametres :

  • MAX_RETRIES = 3 ;
  • RETRY_DELAY_SECONDS = 300 ;
  • processPendingNotifications traite 1 a 100 notifications, 50 par défaut.

Le cron app/cron/supplier_order_notifications_cron.php appelle processPendingNotifications. Il retourne un JSON avec processed, sent, failed.

Tracking email et lien document

Les emails peuvent construire une URL de document suivie via DocumentEmailViewModel. La timeline commande lit ensuite les ouvertures pour ajouter des événements "Commande consultee".

Points de reprise :

  • ne pas supprimer document_email_views en pensant qu'il s'agit d'un détail email ;
  • une commande peut être consultee via lien email sans connexion au portail fournisseur ;
  • le tracking contribue à la timeline fonctionnelle visible dans l'interface.

Conversations

Le lien de conversation utilise :

  • type : supplier_order ;
  • clé : supplier_order:<id>.

ensureConversation retrouve une conversation existante via MessagingModel::findConversationIdByLink, sinon elle en crée une et synchronise le destinataire fournisseur. Les commandes vers fournisseur externe ou email peuvent ne pas avoir le même comportement qu'une commande vers bibliothèque avec recipient_membre_id.

Schéma runtime vs migrations

Le modèle contient des vérifications runtime :

  • ensureSupplierOrderLinesSchema ajoute ou corrige product_type et measure_basis.
  • ensureSupplierOrdersStatusSchema corrige l'enum de statut, ajoute factory_departure_date et shipping_date.
  • SupplierOrderNotificationService::ensureStorageSchema crée la table de notifications si absente.

Ces garde-fous ne remplacent pas les migrations SQL. Pour une installation neuve ou une base staging, appliquer d'abord app/bd/supplier-orders.sql, puis vérifier que les ensure runtime ne masquent pas une migration oubliee.

Integrations internes

  • Bibliotheques fournisseurs : cpt_libraries, std_libraries, accès publics ou demandes acceptées.
  • Produits : cpt_products, std_products, catalogue.
  • Devis : DevisModel, source_quote_id, generation de brouillon.
  • Fournisseurs locaux : table fournisseurs.
  • Messagerie : conversation liée à la commande.
  • Emails : MailerService, table supplier_order_notifications.
  • Tracking : DocumentEmailViewModel, document_email_views.
  • Feature plans : feature id 44, nom Commande fournisseurs.

Risques et points d'attention

  • Ne pas autoriser l'édition après envoi sauf retour en incomplet.
  • Ne pas laisser un fournisseur confirmer réceptionnée : cette action revient à l'entreprise.
  • Ne pas envoyer une commande sans destinataire email valide pour les flux supplier ou email.
  • Ne pas confondre pièces jointes de commande et croquis de ligne.
  • Ne pas casser les snapshots de lignes : ils garantissent la lisibilite historique si le produit source change.
  • Ne pas oublier les statuts accentues dans les comparaisons (validé, expédiée, réceptionnée, archivée).
  • Ne pas supposer que toutes les commandes ont un portail fournisseur.
  • Ne pas rendre les notifications bloquantes pour la sauvegarde si le code les traite comme secondaires.

Bugs connus ou signales

Aucun bug confirmé n'est documenté dans le code pour ce module. Zones à surveiller en reprise :

  • divergence entre fichiers en base et fichiers physiques après édition ;
  • croquis perdu si client_key change côté front ;
  • statut bloqué si recipient_membre_id n'est pas synchronisé pour une bibliothèque ;
  • notifications restées en processing si un envoi est interrompu après claim.

Tests recommandés

  • Création brouillon sans envoi.
  • Soumission vers bibliothèque cpt avec portail fournisseur.
  • Soumission vers bibliothèque std.
  • Soumission vers fournisseur local.
  • Soumission vers email libre.
  • Création depuis devis avec lignes compatibles et incompatibles.
  • Upload pièces jointes multiples.
  • Upload croquis sur ligne cpt.
  • Edition d'une commande incomplet.
  • Refus d'édition sur commande en attente.
  • Transition fournisseur vers validé, en fabrication, expédiée.
  • Obligation de factory_departure_date pour en fabrication.
  • Obligation de shipping_date pour expédiée.
  • Confirmation entreprise réceptionnée après expédiée.
  • File de notifications : succès, retry, échec après 3 tentatives.
  • Tracking d'ouverture email dans la timeline.

Commandes utiles

php app/cron/supplier_order_notifications_cron.php

Il n'y a pas de test automatisé dédié au module dans le checkout actuel. Ajouter en priorité des tests de modèle sur transitions, sauvegarde, uploads et notifications.

Checklist de reprise

  • Lire SupplierOrderController.php, puis SupplierOrderModel.php.
  • Appliquer/vérifier app/bd/supplier-orders.sql.
  • Vérifier que FEATURE_COMMANDE_FOURNISSEUR et la feature id 44 sont coherentes en base.
  • Tester un compte entreprise et un compte fournisseur.
  • Tester un destinataire avec portail et un destinataire externe.
  • Vérifier les permissions d'édition par statut.
  • Vérifier les fichiers dans public/uploads/supplier_orders/attachments et public/uploads/supplier_orders/croquis.
  • Vérifier la table supplier_order_notifications avant d'accuser le SMTP.
  • Vérifier document_email_views si la timeline ne montre pas les consultations.

Questions ouvertes

  • Faut-il recreer un script supplier-orders-tpe-feature.sql ou supprimer définitivement cette référence des traces historiques ?
  • Les notifications en processing doivent-elles être recyclees automatiquement après un timeout ?
  • La suppression des lignes devrait-elle conserver les ids pour faciliter l'audit des croquis ?
  • Une commande externe sans portail fournisseur doit-elle créer une conversation ou seulement utiliser l'email ?