# AUDIT.md — ICAVI GESTION *Réalisé le 2026-10-08 — avant toute modification du projet* --- ## 1. ARCHITECTURE ACTUELLE ### Stack technique | Composant | Version | Note | |---|---|---| | PHP | ^8.2 | ✅ Bon | | Laravel | 11.44–11.54 | ⚠️ Fin de support sécurité mars 2026 | | Frontend | Blade + CSS custom + JS vanilla | Pas de framework JS | | BDD | MySQL (icaviss3) | | | Auth | Laravel session classique | Pas de Sanctum, pas de JWT | | PDF | Chrome headless (Symfony Process) | Pour bons de caisse uniquement | | Mail | SMTP OVH (ssl0.ovh.net:465) | Configuré | | Cache | File | | | Queue | Sync | Pas de worker | | CSS | Fichier statique custom (949 lignes) | Design system v2.0 maison | | JS | Fichier statique custom (638 lignes) | Vanilla JS | | Hébergement cible | OVH Mutualisé Pro | | ### Structure des dossiers ``` ICAVI_GESTION_MERGED/ ├── app/ │ ├── Console/ │ ├── Exceptions/ Handler.php │ ├── Helpers/ NumberToWords.php │ ├── Http/ │ │ ├── Controllers/ 11 contrôleurs (+ 3 copies "- Copie") │ │ └── Middleware/ Authenticate, RedirectIfAuthenticated, CheckRole │ ├── Mail/ RelanceReminderMail │ ├── Models/ 22 modèles │ ├── Notifications/ CashVoucherNotification, DocumentRequestNotification │ ├── Observers/ ClientObserver, ProductObserver │ ├── Providers/ AppServiceProvider │ └── Services/ DocumentService, StockService, GedService, CashVoucherArchiveService ├── config/ app, auth, cors, database, icavi, cash_vouchers, ... ├── database/ │ ├── import/ icaviss3.sql (dump prod) │ ├── migrations/ 30 migrations (2024–2026) │ └── seeders/ ├── docs/ AUDIT_MERGE, DEPLOIEMENT_*, INSTALL_LOCAL ├── public/ │ ├── assets/images/ Logo, cachet, signature, favicons │ ├── css/app.css Design system v2.0 (949 lignes) │ └── js/app.js JS vanilla (638 lignes) ├── resources/views/ ~55 vues Blade organisées par module └── routes/ ├── web.php 85 routes enregistrées └── api.php 1 seule route /health (placeholder) ``` --- ## 2. FONCTIONNALITÉS EXISTANTES ### ✅ Modules implémentés et fonctionnels #### Authentification & Utilisateurs - Login/logout Laravel session - 4 rôles : `super_admin`, `admin`, `commercial`, `storage_manager` - Flag `is_directeur` indépendant du rôle (pour approbation permissions) - Profil utilisateur modifiable - Middleware `CheckRole` personnalisé #### Clients - CRUD complet - Statuts : `prospect`, `active`, `inactive` - Suivi commercial (`ClientFollowUp`) avec rappels par email - Champs RC + NIU (fiscalité camerounaise) - Widgets GED associés #### Produits - CRUD complet - Référence unique - Catégorie et fournisseur (chaînes simples, pas de tables dédiées) - Prix d'achat / prix de vente / marge calculée - Stock + stock minimum + seuil d'alerte - Quantités décimales (depuis migration 08/2026) - Description (depuis migration 08/2026) - Recherche rapide (`/products/search`) + création rapide (`/products/quick-store`) - Observateurs (ProductObserver, ClientObserver) #### Stock & Mouvements - `StockService` : point d'entrée unique, verrouillage pessimiste (`lockForUpdate`) - Types : `in`, `out`, `adjustment`, `retour` - Traçabilité complète : quantité avant/après, utilisateur, date, motif, vente liée - Suppression de mouvements (⚠️ antipatterne — voir §6) #### Ventes - CRUD + pagination - Lignes avec produit, quantité, prix unitaire - Calcul automatique du montant total - Statuts : `draft`, `sent`, `accepted`, `refused`, `annulee` - Soft deletes - Lien automatique Document (facture) à partir d'une vente acceptée - Annulation avec motif #### Documents ERP - Types : `PRO` (Proforma), `DEV` (Devis), `FAC` (Facture), `BL` (Bon de livraison), `BC` (Bon de commande), `AVO` (Avoir) - Numérotation séquentielle par type/année/jour (`DocumentSequence`) - Workflow de statuts par type (machine d'état côté modèle) - Génération en chaîne : PRO → FAC → BL (idempotente) - Historique des changements de statut (`DocumentHistorique`) - Impression / PDF HTML natif - Workflow de suppression avec validation Direction (`pending_deletion`) - Champs client dénormalisés (nom, adresse, RC, NIU) pour documents archivés - Calculs : sous-total, remise globale, TVA, total TTC, total en lettres - Montant en lettres (`NumberToWords`) #### Bons de sortie de caisse - Demande par employé, signature par responsable désigné (`CASH_VOUCHER_SIGNER_USER_ID`) - Paiements partiels multiples - Journal d'événements d'audit - Archivage PDF via Chrome headless - Références séquentielles - Annulation avec motif #### Demandes de permission (congés/absences) - Demande, approbation/refus par Directeur - Séquence de références journalières - Historique des décisions - Impression du formulaire #### GED (Gestion Électronique des Documents) - Dossiers et fichiers - Upload de fichiers - Catégories - Téléchargement, prévisualisation - Corbeille + restauration + suppression définitive - Widget embarquable dans d'autres entités - Historique (`GedHistorique`) #### Chat interne - Groupes de discussion (`ChatGroup`, `ChatMessage`) - Modèles présents mais interface non vérifiée dans les vues #### Tableau de bord - Statistiques clients, produits, stock faible, CA, ventes - Graphique CA mensuel par année (sélecteur d'année) - 5 dernières ventes, 5 produits en stock faible, 5 derniers mouvements - 10 relances clients en attente - Section bons de caisse (vue selon rôle) #### Notifications - Table `notifications` (Laravel notifications standard) - `DocumentRequestNotification`, `CashVoucherNotification` - `RelanceReminderMail` (email de relance client) --- ## 3. BASE DE DONNÉES ### Tables identifiées (migrations) | Table | Description | |---|---| | `users` | Utilisateurs + rôle + is_directeur | | `clients` | Clients avec RC/NIU | | `client_follow_ups` | Relances commerciales | | `products` | Catalogue produits | | `sales` | Ventes (soft delete) | | `sale_items` | Lignes de vente | | `stock_movements` | Journal des mouvements de stock | | `document_types` | Types de documents configurables | | `document_sequences` | Compteurs de numérotation par type/année/jour | | `documents` | Documents ERP (PRO, DEV, FAC, BL, BC, AVO) | | `document_lines` | Lignes de document | | `document_historique` | Historique des changements de statut | | `cash_vouchers` | Bons de sortie de caisse | | `cash_voucher_payments` | Paiements des bons | | `cash_voucher_events` | Journal d'audit des bons | | `permissions` | Demandes de permission/congé | | `permission_historique` | Historique décisions | | `permission_sequences` | Numérotation des permissions | | `ged_categories` | Catégories GED | | `ged_dossiers` | Dossiers GED | | `ged_fichiers` | Fichiers GED | | `ged_historique` | Historique GED | | `chat_groups` | Groupes de chat | | `chat_messages` | Messages de chat | | `notifications` | Notifications Laravel standard | ### Observations sur la BDD - **Pas de tables dédiées** pour `categories`, `brands`, `suppliers` / `fournisseurs` — ces données sont stockées comme chaînes dans `products` et `documents`. Limitation pour la refonte. - **Dénormalisation intentionnelle** des données client dans `documents` (client_nom, client_adresse, RC, NIU) : correct pour l'archivage. - **Index présents** sur les colonnes clés (type_code, status, client_id, date_document). - **Quantités décimales** activées (migration 08/2026). - Dump SQL de production disponible dans `database/import/icaviss3.sql`. --- ## 4. PROBLÈMES DÉTECTÉS ### 🔴 Critiques **P1 — Laravel 11 hors support sécurité** Laravel 11.x a atteint la fin de ses correctifs de sécurité le 12 mars 2026. Le projet tourne sur 11.44–11.54 en production. La refonte doit migrer vers Laravel 12 ou 13. **P2 — Fichiers "- Copie" en production** Trois fichiers de travail traînent dans le dépôt : - `app/Http/Controllers/DashboardController - Copie.php` - `app/Http/Controllers/SaleController - Copie.php` - `app/Models/Document - Copie.php` - `app/Services/DocumentService - Copie.php` - `resources/views/documents/*.blade - Copie.php` - `resources/views/dashboard/index.blade - Copie.php` Ces fichiers sont hors autoload PSR-4 (espace dans le nom) mais peuvent générer de la confusion et des bugs si jamais l'autoloader les charge accidentellement. **P3 — MAIL_PASSWORD en clair dans .env versionné** Le `.env` de travail contient le mot de passe SMTP en clair. Il doit être exclu du dépôt Git systématiquement. **P4 — APP_DEBUG=true référencé** L'environnement de développement a `APP_DEBUG=true` et `APP_ENV=local` — normal pour le dev, mais signale qu'il faut s'assurer que le `.env` de production est séparé. **P5 — Suppression de mouvements de stock possible** `StockController::destroy()` permet de supprimer un `StockMovement`. Le `StockService` mentionne explicitement que les mouvements sont immuables, mais la route de suppression contredit cette règle. **P6 — Pas de rate limiting sur le login** `AuthController::login()` n'a pas de throttling explicite. Laravel 11 fournit `throttle:login` mais il n'est pas appliqué. ### 🟡 Importants **P7 — Rôles hardcodés dans CheckRole, pas de système de permissions granulaires** Les accès sont contrôlés par rôle (`role:super_admin,admin`) directement dans les routes. Pas de Policies Laravel, pas de granularité par action. Difficile à faire évoluer. **P8 — Pas d'API REST** `routes/api.php` ne contient qu'une route `/health`. Toute la logique passe par des routes web avec sessions. La transition vers React nécessite de créer une API complète. **P9 — Catégories et fournisseurs non normalisés** `products.category` et `products.supplier` sont des chaînes libres. Pas de table `categories` ni `suppliers`. La saisie est inconsistante (casse, typos). Bloquerait les filtres avancés. **P10 — Logique métier dans les contrôleurs** `DocumentController` contient `calculerMontants()` et `generateReference()`, des méthodes métier critiques qui devraient être dans `DocumentService`. `DocumentService::genererDepuisVente()` instancie même `DocumentController` pour réutiliser ces méthodes — couplage fort à supprimer. **P11 — Chrome headless requis pour les PDF** L'archivage des bons de caisse nécessite Chrome/Chromium installé sur le serveur. Sur OVH mutualisé, Chrome n'est pas disponible. Il faudra migrer vers une solution PHP pure (DomPDF, TCPDF, mPDF) ou un service externe. **P12 — Queue synchrone (`QUEUE_CONNECTION=sync`)** Tous les jobs/notifications s'exécutent en synchrone dans la requête HTTP. Sur OVH mutualisé, pas de worker disponible — c'est une contrainte connue, mais les notifications lourdes (email) ralentissent les réponses. **P13 — Pas de fournisseurs dédiés** Le module fournisseurs est absent (documents mentionnent `fournisseur_id` et `fournisseur_nom`, mais pas de table ni de CRUD fournisseurs). Les bons de commande (BC) ne peuvent pas être associés à un fournisseur géré. **P14 — Chat interne non finalisé** Les modèles `ChatGroup` et `ChatMessage` existent mais aucune vue de chat n'est dans `resources/views/`. Route absente. ### 🟢 Mineurs **P15 — CSS non compilé/minifié** `public/css/app.css` est un fichier statique non minifié (949 lignes). Pas de processus de build frontend — aucun `package.json`. **P16 — Pas de tests** Aucun test PHPUnit ni Pest fonctionnel trouvé. Seul PHPUnit est en `require-dev`. **P17 — Observers déclarés mais non vérifiés** `ClientObserver` et `ProductObserver` sont déclarés. Leur contenu et leur enregistrement dans `AppServiceProvider` n'ont pas été vérifiés côté comportement. **P18 — `config/icavi.php` minimal** Seuls `system_name`, `system_email` et `raymond_email` sont configurables. Beaucoup de valeurs métier (TVA par défaut, conditions de paiement, RIB) sont hardcodées dans les vues ou les modèles. --- ## 5. RISQUES | # | Risque | Probabilité | Impact | |---|---|---|---| | R1 | Données perdues lors de la migration BDD | Moyen | Critique | | R2 | Chrome headless absent sur OVH → PDF bons caisse cassé | Élevé | Élevé | | R3 | Laravel 11 sans patch sécurité en production | Élevé | Élevé | | R4 | Régression workflow documents lors de la refonte | Moyen | Élevé | | R5 | CORS mal configuré entre React (autre domaine) et Laravel | Élevé | Élevé | | R6 | Performance dégradée sur gros volumes (N+1 queries) | Moyen | Moyen | | R7 | Perte d'identité visuelle ICAVI | Faible | Moyen | --- ## 6. DETTE TECHNIQUE | Élément | Gravité | Action recommandée | |---|---|---| | Laravel 11 EOL | 🔴 | Migrer vers Laravel 12 lors de la refonte | | Fichiers "- Copie" | 🟡 | Supprimer avant migration | | Méthodes métier dans contrôleurs | 🟡 | Extraire vers Services | | Catégories/fournisseurs non normalisés | 🟡 | Créer tables dédiées avec migration de données | | Suppression StockMovement autorisée | 🟡 | Retirer la route, soft-delete uniquement | | Pas de tests | 🟡 | Écrire tests PHPUnit pour calculs et stock | | Chrome headless pour PDF | 🟡 | Migrer vers DomPDF ou solution PHP | | Pas d'API REST | 🔴 | Créer toute l'API pour React | | Pas de rate limiting login | 🟡 | Ajouter throttle middleware | | .env avec secrets | 🔴 | Exclure absolument du repo | --- ## 7. FONCTIONNALITÉS À CONSERVER ABSOLUMENT Ces fonctionnalités sont matures et représentent la valeur métier du projet : 1. **Workflow documentaire complet** (PRO → FAC → BL avec génération en chaîne idempotente) 2. **Machine d'états des documents** (statuts par type, transitions contrôlées) 3. **StockService** avec verrouillage pessimiste — à garder tel quel côté Laravel 4. **Numérotation séquentielle** des documents (`DocumentSequence`) 5. **Historique des changements de statut** (`DocumentHistorique`) 6. **Dénormalisation client dans documents** (correct pour archivage) 7. **Workflow bons de caisse** (demande → signature → paiement → restitution) 8. **Workflow permissions/direction** (demande → approbation directeur) 9. **GED** avec dossiers, corbeille, historique 10. **Suivi clients** avec relances (`ClientFollowUp`) 11. **Montants en lettres** (`NumberToWords`) 12. **Charte graphique ICAVI** : couleurs `--brand-500: #1e2c54` (bleu marine foncé), accent `#f8e800` (jaune vif), police Inter — à respecter dans le nouveau design 13. **Assets visuels** : logo, cachet, signature du directeur, watermark --- ## 8. FONCTIONNALITÉS À AMÉLIORER 1. **Catégories produits** → table dédiée (actuellement chaînes libres) 2. **Fournisseurs** → module CRUD complet (actuellement chaînes dans documents) 3. **PDF sans Chrome** → DomPDF pour tous les documents imprimables 4. **Permissions granulaires** → Laravel Policies par action 5. **API REST** → créer `/api/v1/*` complet pour React 6. **Dashboard** → enrichir avec graphiques interactifs et plus d'indicateurs 7. **Tableau de bord stock** → vue dédiée ruptures, historique, alertes 8. **Marques produits** → table dédiée si nécessaire au métier --- ## 9. FONCTIONNALITÉS À CRÉER (manquantes) 1. **Module fournisseurs** (CRUD + historique commandes) 2. **Catégories produits** (table dédiée + CRUD) 3. **Marques produits** (si pertinent métier) 4. **Inventaire** (ajustement en masse du stock) 5. **Tableau de bord financier** (paiements reçus, soldes clients) 6. **Notifications temps réel** (vue des notifications in-app) 7. **Export Excel/CSV** des listes (clients, produits, mouvements) --- ## 10. RECOMMANDATIONS ARCHITECTURALES ### Architecture cible confirmée L'architecture React SPA + Laravel API REST est pertinente et compatible OVH : ``` Utilisateur │ ▼ React (fichiers statiques, servis par OVH) │ HTTPS / JSON API ▼ Laravel 12 (API REST, PHP sur OVH mutualisé) │ ▼ MySQL (base existante icaviss3) ``` **Pourquoi c'est compatible OVH Mutualisé Pro :** - React buildé avec Vite → dossier `dist/` de fichiers statiques, servi comme un site HTML classique - Laravel API deployé dans le sous-dossier `backend/` avec `public/` comme document root - Pas de Node.js serveur, pas de Docker, pas de worker permanent - CORS configuré pour autoriser le domaine frontend → backend ### Stack recommandée #### Frontend - **React 18** + **Vite** + **TypeScript** — build statique, DX moderne - **React Router v6** — navigation SPA - **TanStack Query v5** — cache API, états de chargement, invalidation - **Tailwind CSS v3** — utilitaires, compatible avec le design system existant - **shadcn/ui** — composants headless accessibles (pas de vendor lock-in) - **Zustand** — état global léger (auth, préférences) uniquement si nécessaire - **React Hook Form + Zod** — formulaires typés avec validation client #### Backend - **Laravel 12** (migrer depuis 11) - **Laravel Sanctum** — authentification SPA via cookies httpOnly (parfait pour même domaine ou sous-domaine) - **Laravel API Resources** — sérialisation JSON cohérente - **Form Requests** — validation centralisée - **Policies** — autorisations par action et par ressource - **Services** existants conservés (StockService, DocumentService refactorisé) - **DomPDF** (via laravel-dompdf) — génération PDF sans Chrome ### Points OVH spécifiques - **Cron** : OVH mutualisé supporte les tâches cron → `php artisan schedule:run` chaque minute possible - **Pas de Redis** sur mutualisé → garder cache fichier et queue sync - **Storage** : `php artisan storage:link` crée le symlink dans `public/storage` - **HTTPS** : certificat Let's Encrypt inclus dans OVH Pro - **CORS** : configurer `config/cors.php` pour autoriser le domaine React --- ## 11. CONCLUSION Le projet ICAVI GESTION est une application métier **réelle et active**, bien structurée pour sa génération (Blade + Laravel 11), avec une logique métier solide notamment sur les documents, le stock et les bons de caisse. Les points critiques pour la refonte sont : 1. **Créer l'API REST Laravel** — il n'existe pratiquement rien côté API 2. **Migrer vers Laravel 12** — version 11 EOL depuis mars 2026 3. **Remplacer Chrome headless** par DomPDF 4. **Normaliser les catégories et fournisseurs** 5. **Respecter scrupuleusement l'identité ICAVI** (bleu #1e2c54, jaune #f8e800, Inter) La base de données est saine et peut être migrée progressivement sans perte de données.