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.sqlapp/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 parFEATURE_COMMANDE_FOURNISSEUR.commandes: page fournisseur, réservée aux comptesfournisseur.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 sirecipient_membre_idexiste.supplier: fournisseur enregistre localement dansfournisseurs.email: destinataire libre par email.
Types de bibliothèque :
cpt: menuiserie sur mesure.std: classique.
Types de produit en ligne :
cataloguecptstd
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 :
draften attenteincompletvalidéen fabricationexpédiéeréceptionnéearchivé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 produitscpt.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_pathoriginal_namemime_typefile_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_statusnew_statuschanged_by_membre_idchanged_by_type:supplier,member,admin, etc.notecreated_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_createdoustatus_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_idsource_modesource_quote_idrecipient_typerecipient_library_typerecipient_library_idrecipient_supplier_idrecipient_namerecipient_emailreferencecustomer_namecustomer_addresssite_addressobservationssave_modelines_jsonexisting_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
draftetincompletsont editables ; save_mode = draftgarde 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 = quoteconserve le lien verssource_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_keycorrect 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_idne 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 (
supplierouemailsans portail), l'entreprise peut appliqueren 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 depuisexpédiée. - aucun changement de statut depuis
draftouarchivéeviachangeStatus.
Dates obligatoires :
en fabricationexigefactory_departure_date.expédiéeexigeshipping_date.réceptionnéeremplitreceived_atavec 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_createdstatus_updated
Cycle d'envoi :
- insertion dans
supplier_order_notificationsavecstatus = pending; - envoi immédiat possible via
sendNotificationById; - claim atomique : passage
pendingversprocessing; - en cas de succès :
sent,sent_at,last_error = NULL; - en cas d'échec : retry ou échec définitif.
Parametres :
MAX_RETRIES = 3;RETRY_DELAY_SECONDS = 300;processPendingNotificationstraite 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_viewsen 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 :
ensureSupplierOrderLinesSchemaajoute ou corrigeproduct_typeetmeasure_basis.ensureSupplierOrdersStatusSchemacorrige l'enum de statut, ajoutefactory_departure_dateetshipping_date.SupplierOrderNotificationService::ensureStorageSchemacré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, tablesupplier_order_notifications. - Tracking :
DocumentEmailViewModel,document_email_views. - Feature plans : feature id
44, nomCommande 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
supplierouemail. - 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_keychange côté front ; - statut bloqué si
recipient_membre_idn'est pas synchronisé pour une bibliothèque ; - notifications restées en
processingsi un envoi est interrompu après claim.
Tests recommandés¶
- Création brouillon sans envoi.
- Soumission vers bibliothèque
cptavec 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_datepouren fabrication. - Obligation de
shipping_datepourexpédiée. - Confirmation entreprise
réceptionnéeaprèsexpédiée. - File de notifications : succès, retry, échec après 3 tentatives.
- Tracking d'ouverture email dans la timeline.
Commandes utiles¶
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, puisSupplierOrderModel.php. - Appliquer/vérifier
app/bd/supplier-orders.sql. - Vérifier que
FEATURE_COMMANDE_FOURNISSEURet la feature id44sont 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/attachmentsetpublic/uploads/supplier_orders/croquis. - Vérifier la table
supplier_order_notificationsavant d'accuser le SMTP. - Vérifier
document_email_viewssi la timeline ne montre pas les consultations.
Questions ouvertes¶
- Faut-il recreer un script
supplier-orders-tpe-feature.sqlou supprimer définitivement cette référence des traces historiques ? - Les notifications en
processingdoivent-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 ?