================================================================================ MODULE BOUTIQUE/STOCK v2.0 - MANIFEST DES FICHIERS ================================================================================ Date: 2025-12-07 Type: Module PHP réutilisable Architecture: MVC avec ventes multi-lignes ================================================================================ STRUCTURE DU TEMPLATE: shop_module_template/ │ ├── README_TEMPLATE.md # Guide d'utilisation du template ├── MANIFEST.txt # Ce fichier (liste des fichiers) │ ├── app/ │ │ │ ├── Controllers/Shop/ # 6 controllers (1,234 lignes total) │ │ ├── ShopArticlesController.php # CRUD articles │ │ ├── ShopCategoriesController.php # CRUD catégories │ │ ├── ShopDashboardController.php # Dashboard + statistiques │ │ ├── ShopReportsController.php # Rapports PDF │ │ ├── ShopStockController.php # Gestion stock + mouvements │ │ └── ShopVentesController.php # Ventes multi-lignes (v2.0) │ │ │ ├── Models/Shop/ # 5 models (1,567 lignes total) │ │ ├── ShopArticleModel.php # Gestion articles + stock │ │ ├── ShopCategorieModel.php # Gestion catégories │ │ ├── ShopMouvementModel.php # Mouvements de stock │ │ ├── ShopVenteModel.php # En-têtes de vente (v2.0) │ │ └── ShopVenteLigneModel.php # Lignes de vente (v2.0) │ │ │ ├── Views/shop/ # Toutes les vues AdminLTE 3.x │ │ │ │ │ ├── articles/ │ │ │ ├── index.php # Liste des articles + filtres │ │ │ ├── create.php # Formulaire création article │ │ │ └── show.php # Détail article + mouvements │ │ │ │ │ ├── categories/ │ │ │ ├── index.php # Liste des catégories │ │ │ └── create.php # Formulaire catégorie │ │ │ │ │ ├── dashboard/ │ │ │ └── index.php # Dashboard avec KPIs │ │ │ │ │ ├── reports/ │ │ │ └── index.php # Page rapports + filtres │ │ │ │ │ ├── stock/ │ │ │ ├── index.php # État du stock actuel │ │ │ ├── alimenter.php # Formulaire entrée stock │ │ │ └── mouvements.php # Historique mouvements │ │ │ │ │ └── ventes/ │ │ ├── index.php # Liste des ventes + stats │ │ ├── create.php # Formulaire vente multi-lignes │ │ └── show.php # Détail vente + ticket │ │ │ └── Helpers/ │ └── shop_helpers.php # Fonctions utilitaires (à créer) │ ├── database/ │ └── database_shop_module_migration_ventes_multilignes.sql # Migration v2.0 │ └── docs/ # Documentation complète ├── SHOP_MODULE_README.md # Doc principale (500+ lignes) ├── SHOP_MODULE_DEPENDENCIES.md # Liste des dépendances ├── SHOP_MODULE_INTEGRATION_GUIDE.md # Guide d'intégration pas à pas ├── shop_module_config_template.php # Template configuration ├── SHOP_MODULE_ROUTES.txt # Routes à copier └── install_shop_module.php # Script installation auto ================================================================================ DÉTAIL DES FICHIERS ================================================================================ CONTROLLERS (app/Controllers/Shop/) ----------------------------------- 1. ShopArticlesController.php - Lignes: ~250 - Méthodes: index, create, store, show, edit, update, delete, etiquette - Dépendances: ShopArticleModel, ShopCategorieModel - Permissions: view_articles, create_article, edit_article, delete_article 2. ShopCategoriesController.php - Lignes: ~180 - Méthodes: index, create, store, show, edit, update, delete - Dépendances: ShopCategorieModel - Permissions: view_categories, manage_categories 3. ShopDashboardController.php - Lignes: ~120 - Méthodes: index - Dépendances: ShopArticleModel, ShopVenteModel, ShopMouvementModel - Permissions: view_shop_dashboard 4. ShopReportsController.php - Lignes: ~400 - Méthodes: index, ventes, ventesPdf, stock, stockPdf - Dépendances: ShopVenteModel, ShopArticleModel, DomPDF - Permissions: view_reports, export_reports 5. ShopStockController.php - Lignes: ~200 - Méthodes: index, createEntree, storeEntree, mouvements - Dépendances: ShopArticleModel, ShopMouvementModel - Permissions: view_stock, alimenter_stock, view_mouvements 6. ShopVentesController.php (VERSION 2.0 MULTI-LIGNES) - Lignes: ~390 - Méthodes: index, create, store, show, ticket, generateTicketContent - Dépendances: ShopVenteModel, ShopVenteLigneModel, ShopArticleModel, ClientModel - Permissions: create_vente, view_own_ventes, view_all_ventes, edit_prix_vente - Nouveauté v2.0: Support ventes multi-lignes avec validation stock MODELS (app/Models/Shop/) ------------------------- 1. ShopArticleModel.php - Lignes: ~450 - Table: shop_articles - Méthodes principales: * findWithDetails() - Articles avec catégorie et stats * findById() - Article par ID * updateStock() - Mise à jour stock * getStockAlerts() - Articles en stock faible - Validations: reference unique, prix positifs, stock >= 0 2. ShopCategorieModel.php - Lignes: ~150 - Table: shop_categories - Méthodes: CRUD standard + findBySite() 3. ShopMouvementModel.php - Lignes: ~350 - Table: shop_mouvements - Méthodes principales: * createMouvement() - Crée mouvement ET met à jour stock * findByArticle() - Historique d'un article * getStats() - Statistiques des mouvements - Types: entree_achat, entree_retour, sortie_vente, sortie_perte, etc. 4. ShopVenteModel.php (VERSION 2.0) - Lignes: ~550 - Table: shop_ventes - Méthodes principales: * createVente() - Transaction complète (vente + lignes + mouvements + stock) * findWithDetails() - Ventes avec infos vendeur/client * findWithFullDetails() - Vente + lignes + articles * getStats() - Statistiques période - Nouveauté v2.0: * Gestion transactionnelle correcte (BEGIN, COMMIT, ROLLBACK) * Support multi-lignes * Stock update APRÈS commit pour éviter auto-commit * Gestion des erreurs avec getLastError() et getLastErrorDetails() 5. ShopVenteLigneModel.php (NOUVEAU v2.0) - Lignes: ~250 - Table: shop_ventes_lignes - Méthodes principales: * createLignes() - Insère plusieurs lignes (dans transaction parent) * findByVente() - Lignes d'une vente avec détails articles * validateStockForLignes() - Vérifie stock disponible * getStatsArticlesByPeriode() - Stats par article - Note: PAS de beginTransaction() car gérée dans ShopVenteModel VUES (app/Views/shop/) ---------------------- Format: Toutes les vues utilisent AdminLTE 3.x avec Bootstrap 4.6 articles/index.php - Liste paginée des articles - Filtres: catégorie, statut, recherche - Colonnes: référence, nom, stock, prix, actions - Actions: voir, modifier, supprimer, étiquette articles/create.php - Formulaire création/édition article - Champs: référence, nom, catégorie, prix HT/TTC, TVA, stock min, unité - Validation côté client (JavaScript) articles/show.php - Détails article - Historique des mouvements de stock - Statistiques de ventes categories/index.php - Liste des catégories avec nombre d'articles - Actions: créer, modifier, supprimer categories/create.php - Formulaire simple: nom + description dashboard/index.php - KPIs: CA jour/mois, nb ventes, nb articles - Graphiques: ventes par jour, top articles - Alertes stock faible - Dernières ventes reports/index.php - Sélection du type de rapport (ventes, stock) - Filtres par période - Boutons génération PDF stock/index.php - État actuel du stock par article - Colonnes: article, stock actuel, stock mini, statut - Indicateurs visuels (badges vert/orange/rouge) stock/alimenter.php - Formulaire d'entrée de stock - Sélection article + quantité + type mouvement + commentaire stock/mouvements.php - Historique complet des mouvements - Filtres: article, type, période - Colonnes: date, article, type, quantité, stock avant/après ventes/index.php - Liste des ventes avec filtres - Stats période: CA brut/net, nb ventes, nb articles - Filtres: vendeur, mode paiement, période - Restriction: vendeur_boutique ne voit que ses ventes ventes/create.php (VERSION 2.0 MULTI-LIGNES) - Interface dynamique JavaScript - Fonctions JS: * ajouterLigne() - Ajoute une ligne article * supprimerLigne() - Retire une ligne * selectArticleLigne() - Auto-remplissage prix/stock * calculerLigneMontant() - Calcul total ligne * calculerTotal() - Calcul total global avec remise * validerStock() - Validation avant soumission - Champs par ligne: article, quantité, prix unitaire, total - Champs globaux: client, mode paiement, remise %, commentaire - Validation: stock disponible, prix modifiable selon permission ventes/show.php - Détails vente avec toutes les lignes - Tableau: article, quantité, prix, total, marge - Totaux: sous-total, remise, net - Bouton: générer ticket PDF - Infos: vendeur, client, mode paiement DATABASE (database/) -------------------- database_shop_module_migration_ventes_multilignes.sql - Lignes: ~247 - Actions: 1. Sauvegarde des données existantes (shop_ventes_backup) 2. Création table shop_ventes_lignes 3. Modification table shop_ventes (suppression id_article, ajout nb_articles) 4. Migration données v1.0 vers v2.0 5. Mise à jour vue v_shop_top_ventes 6. Vérifications de cohérence - Tables créées/modifiées: * shop_categories (catégories d'articles) * shop_articles (articles en vente) * shop_ventes (en-têtes de vente) - MODIFIÉE * shop_ventes_lignes (lignes de vente) - NOUVELLE * shop_mouvements (mouvements de stock) - Vues SQL: * v_shop_top_ventes (stats ventes par article) - Sécurité: * Foreign keys avec CASCADE/RESTRICT * Colonnes générées (montant_ligne) * Contraintes CHECK DOCUMENTATION (docs/) --------------------- 1. SHOP_MODULE_README.md (500+ lignes) - Vue d'ensemble du module - Architecture détaillée - Installation complète (7 étapes) - Configuration (devise, permissions, modes paiement) - Usage et exemples de code - API endpoints - Customisation - Troubleshooting - FAQ 2. SHOP_MODULE_DEPENDENCIES.md (400+ lignes) - Prérequis système (PHP, MySQL, Apache) - Extensions PHP requises - Packages Composer (DomPDF) - Dépendances frontend (AdminLTE, Bootstrap, jQuery) - Structure de dossiers requise - Système d'authentification attendu - Tables externes requises - Checklist de vérification - Dépannage des dépendances - Versions testées 3. SHOP_MODULE_INTEGRATION_GUIDE.md (600+ lignes) - Guide pas à pas d'intégration - Installation automatique vs manuelle - Migration de base de données détaillée - Configuration de l'adapter - Intégration du routage - Gestion des permissions - Personnalisation interface - Exemples d'utilisation (code) - Tests et validation - Résolution de problèmes 4. shop_module_config_template.php (350+ lignes) - Configuration globale (devise, modes paiement, permissions) - Fonctions d'adaptation (adapter pattern): * current_site_id() * current_user_id() * current_user() * check_shop_permission() * require_shop_permission() * format_shop_money() * get_shop_mode_paiement_label() * validate_shop_stock_disponible() * redirect() * e() (échappement HTML) - Fonctions PDF (DomPDF): * pdf_complete_html() * pdf_summary_card() - Hooks optionnels: * shop_after_vente_created() * shop_after_stock_movement() 5. SHOP_MODULE_ROUTES.txt - Toutes les routes du module (46 routes) - Format compatible routeur objet - Groupées par fonctionnalité 6. install_shop_module.php - Script CLI d'installation automatique - Options: --target, --dry-run - Vérifications: PHP version, extensions, structure - Actions: copie fichiers, génère config, affiche instructions - Gestion des erreurs ================================================================================ INFORMATIONS TECHNIQUES ================================================================================ TECHNOLOGIES UTILISÉES: ----------------------- - PHP 8.0+ (type hints, named parameters, null coalescing) - MySQL/MariaDB 5.7+ (transactions InnoDB, colonnes générées) - PDO (requêtes préparées, transactions) - AdminLTE 3.x (framework UI) - Bootstrap 4.6 (CSS framework) - jQuery 3.6+ (JavaScript) - Select2 4.1+ (sélecteurs améliorés) - DomPDF 2.0+ (génération PDF) ARCHITECTURE: ------------- - Pattern: MVC (Model-View-Controller) - Design: Repository pattern dans les Models - Sécurité: Prepared statements, échappement HTML, CSRF protection - Transactions: ACID compliant (Atomicity, Consistency, Isolation, Durability) - Permissions: RBAC (Role-Based Access Control) - Multi-tenant: Support via id_site PERFORMANCES: ------------- - Index sur toutes les foreign keys - Colonnes générées pour calculs (montant_ligne, montant_net) - Vues SQL pour requêtes complexes (v_shop_top_ventes) - Requêtes optimisées avec JOIN (éviter N+1) SÉCURITÉ: --------- - Validation côté serveur + client - Protection XSS (htmlspecialchars) - Protection SQL injection (PDO prepared statements) - Contrôle d'accès par permission - Audit trail (created_by, updated_by, created_at, updated_at) - Transactions pour intégrité des données ================================================================================ STATISTIQUES ================================================================================ Fichiers PHP: 11 controllers + 5 models = 16 fichiers Vues PHP: 17 fichiers Scripts SQL: 1 migration (247 lignes) Documentation: 6 fichiers (2000+ lignes) Total lignes de code: ~3500 lignes PHP Tables créées: 5 tables + 1 vue Routes: 46 endpoints Permissions: 14 permissions Modes de paiement: 5 modes configurables ================================================================================ CHANGELOG ================================================================================ Version 2.0 (2025-12-07) ------------------------ + FEATURE: Ventes multi-lignes (plusieurs articles par vente) + FEATURE: Table shop_ventes_lignes pour détail des ventes + FEATURE: Interface JavaScript dynamique pour formulaire vente + FEATURE: Validation stock par ligne avant création vente + FIX: Gestion transactionnelle corrigée (stock update après commit) + FIX: Éviter auto-commit lors des updates de stock + IMPROVEMENT: Méthodes getLastError() et getLastErrorDetails() + IMPROVEMENT: Support remise globale sur vente + IMPROVEMENT: Ticket PDF avec détail de toutes les lignes Version 1.0 (2025-11-xx) ------------------------ - Version initiale (mono-ligne par vente) ================================================================================ NOTES IMPORTANTES ================================================================================ 1. MIGRATION v1.0 -> v2.0: - OBLIGATOIRE: Sauvegarder la base avant migration - Le script crée automatiquement shop_ventes_backup - Migration préserve toutes les données existantes - Une vente v1.0 devient une vente v2.0 avec 1 ligne 2. TRANSACTIONS: - ShopVenteModel::createVente() gère la transaction globale - ShopVenteLigneModel::createLignes() NE DOIT PAS créer de transaction - Stock updates APRÈS commit pour éviter auto-commit MySQL - Toujours utiliser try/catch avec rollback 3. PERMISSIONS: - Mapper les permissions aux rôles de votre application - edit_prix_vente permet de modifier prix pendant vente - view_all_ventes vs view_own_ventes pour vendeurs 4. PERFORMANCE: - Pour >1000 ventes, mettre en cache les stats dashboard - Utiliser LIMIT dans les requêtes de liste - Éviter SELECT * (spécifier les colonnes) 5. SÉCURITÉ: - TOUJOURS valider permissions avec require_shop_permission() - TOUJOURS échapper sorties HTML avec e() - TOUJOURS utiliser requêtes préparées PDO ================================================================================ FIN DU MANIFEST ================================================================================