# Plan d'Implémentation POS - Phases Détaillées

## Vue d'ensemble des Phases

| Phase | Nom | Statut | Routes | Description |
|-------|-----|--------|--------|-------------|
| 0 | Socle & Infrastructure | TERMINE | 8 | Base technique, config, rôles, audit |
| 1 | Catalogue Produits | TERMINE | 10 | Gestion complète du catalogue |
| 2 | Gestion des Stocks | TERMINE | 12 | Stock, mouvements, fournisseurs |
| 3 | Ventes & Caisse | TERMINE | 7 | Historique ventes et caisses (manager) |
| 4 | Clients & Crédit | TERMINE | 8 | Gestion clients et crédit |
| 5 | Commandes & Approvisionnement | TERMINE | 7 | Bons de commande fournisseur |
| 6 | Inventaire | TERMINE | 8 | Inventaires physiques |
| 7 | Rapports & Statistiques | TERMINE | 5 | Tableaux de bord et rapports |
| 8 | Remboursements & Annulations | TERMINE | 5 | Gestion retours |
| 9 | Exports PDF & CSV | TERMINE | 8 | Génération PDF (dompdf) et CSV |
| 10 | Journal d'audit | TERMINE | 3 | Interface consultation audit logs |
| **Total** | | **81 routes** | | |

---

## Items restants à implémenter

### Priorité HAUTE — Fonctionnalités critiques manquantes

#### A. Interface Caissier (Employer SPA)
**Impact :** C'est l'interface que les employés utilisent pour traiter les ventes en temps réel.
Actuellement, les ventes sont créées via SaleService mais il n'y a pas d'interface caissier.

| Tâche | Statut | Notes |
|-------|--------|-------|
| CashierController (Employer) | A FAIRE | Interface SPA-like plein écran pour traiter les ventes |
| pos-cashier_controller.js | A FAIRE | Stimulus : recherche produit, panier, calcul auto, multi-paiement, raccourcis clavier |
| pos-payment_controller.js | A FAIRE | Stimulus : modal paiement multi-méthode |
| pos-product-search_controller.js | A FAIRE | Stimulus : recherche rapide + scan code-barres |
| pos-receipt_controller.js | A FAIRE | Stimulus : impression ticket après vente |
| templates/employer/pos/cashier/ | A FAIRE | index (interface caisse), open, close |
| Sélection client dans caisse | A FAIRE | Optionnel/obligatoire selon PosSettings.requireCustomer |
| Paiement par crédit client | A FAIRE | Méthode de paiement "crédit" avec vérification solde |
| Points fidélité à la vente | A FAIRE | Accumulation/utilisation selon PosSettings.enableLoyalty |

#### B. Isolation Média par Company
**Impact :** Les images produits n'ont pas de formulaire d'upload, et le stockage n'est pas isolé par company.

| Tâche | Statut | Notes |
|-------|--------|-------|
| CompanyMediaPathService | A FAIRE | Service de chemin isolé par company UUID (voir 06_MEDIA_ISOLATION.md) |
| Types Media POS dans Media.php | A FAIRE | TYPE_POS_PRODUCT, TYPE_POS_CATEGORY, TYPE_POS_RECEIPT, TYPE_POS_REPORT |
| Upload images produits (UI) | A FAIRE | ProductMedia entity existe mais pas de formulaire d'upload dans ProductController |
| pos-product-image_controller.js | A FAIRE | Stimulus : upload drag & drop, réordonnancement, suppression |
| Vérification accès renforcée | A FAIRE | isPathOwnedByCompany() pour bloquer path traversal |
| Quotas stockage par company | A FAIRE | Champ storageQuotaMb dans PosSettings |
| MigrateMediaToCompanyStructureCommand | A FAIRE | Commande CLI pour migrer fichiers existants |

#### C. Import/Export Produits
**Impact :** Import CSV en masse pour le chargement initial du catalogue.

| Tâche | Statut | Notes |
|-------|--------|-------|
| Import CSV produits | A FAIRE | ProductService.importProducts() + formulaire upload |
| templates/products/import.html.twig | A FAIRE | Template d'import avec mapping colonnes |
| Export CSV produits avancé | PARTIEL | Export basique existe (Phase 9), import manque |

### Priorité MOYENNE — Améliorations fonctionnelles

#### D. Commandes CLI
| Tâche | Statut | Notes |
|-------|--------|-------|
| PosStockAlertCommand | A FAIRE | Cron quotidien : vérifier seuils stock, envoyer emails d'alerte aux managers |
| PosDailyReportCommand | A FAIRE | Cron quotidien : générer et envoyer rapport journalier par email |

#### E. Stimulus Controllers manquants
| Tâche | Statut | Notes |
|-------|--------|-------|
| pos-product-form_controller.js | A FAIRE | Formulaire produit multi-étapes |
| pos-category-tree_controller.js | A FAIRE | Arbre catégories drag & drop |
| pos-product-variant_controller.js | A FAIRE | Ajout dynamique variantes dans formulaire produit |
| pos-barcode_controller.js | A FAIRE | Scan code-barres + affichage |
| pos-stock-alert_controller.js | A FAIRE | Indicateurs visuels alertes stock |
| pos-stock-movement_controller.js | A FAIRE | Formulaire dynamique mouvement stock |
| pos-inventory_controller.js | A FAIRE | Saisie rapide comptage + scan barcode |
| pos-dashboard_controller.js | A FAIRE | Graphiques Chart.js + refresh auto |

#### F. Gestion avancée des variantes
| Tâche | Statut | Notes |
|-------|--------|-------|
| ProductVariantFormType | A FAIRE | Formulaire création/édition variante |
| UI variantes dans product show/edit | A FAIRE | Onglet variantes avec ajout/suppression dynamique |
| Stock par variante | PARTIEL | Entity ProductVariant.currentStock existe, pas d'UI |

#### G. Employer Stock Reception
| Tâche | Statut | Notes |
|-------|--------|-------|
| StockReceptionController (Employer) | A FAIRE | Interface employé pour réceptionner du stock |

### Priorité BASSE — Nice-to-have

#### H. API Mobile POS
| Tâche | Statut | Notes |
|-------|--------|-------|
| POST /api/pos/sales | A FAIRE | Créer vente |
| GET /api/pos/products/search | A FAIRE | Recherche produits |
| GET /api/pos/products/{barcode} | A FAIRE | Lookup code-barres |
| POST /api/pos/register/open | A FAIRE | Ouvrir caisse |
| POST /api/pos/register/close | A FAIRE | Fermer caisse |
| GET /api/pos/dashboard | A FAIRE | Stats dashboard |
| GET /api/pos/customers/search | A FAIRE | Recherche clients |
| POST /api/pos/stock/receive | A FAIRE | Réception stock |
| Documentation OpenAPI/Swagger | A FAIRE | |

#### I. Fonctionnalités avancées
| Tâche | Statut | Notes |
|-------|--------|-------|
| PaymentService dédié | A FAIRE | Actuellement intégré dans SaleService |
| Intégration passerelle Mobile Money | A FAIRE | Orange Money, Wave, Free Money API |
| Admin dashboard POS consolidé | A FAIRE | Vue toutes companies pour ROLE_ADMIN |
| Rapport performance vendeurs | A FAIRE | Classement vendeurs par CA |
| Rapport marges | A FAIRE | Calcul marge par produit/catégorie |
| Rapport rotation stock | A FAIRE | Stock turnover analysis |
| Mode hors-ligne basique | A FAIRE | localStorage + synchronisation |
| Gestion multi-dépôts | A FAIRE | Transferts stock entre locations |

---

## Phases terminées — Détail

### Phase 0 : Socle & Infrastructure (TERMINE)

| Composant | Fichier | Statut |
|-----------|---------|--------|
| PosSettings entity | src/Entity/Pos/PosSettings.php | TERMINE |
| PosEmployeeRole entity | src/Entity/Pos/PosEmployeeRole.php | TERMINE |
| PosAuditLog entity | src/Entity/Pos/PosAuditLog.php | TERMINE |
| Repositories (3) | src/Repository/Pos/ | TERMINE |
| PosSettingsService | src/Service/Pos/PosSettingsService.php | TERMINE |
| PosAuditService | src/Service/Pos/PosAuditService.php | TERMINE |
| PosEmployeeService | src/Service/Pos/PosEmployeeService.php | TERMINE |
| CompanyVoter extension | src/Security/Voter/CompanyVoter.php | TERMINE |
| PosSettingsController | src/Controller/Manager/Pos/PosSettingsController.php | TERMINE |
| PosEmployeeController | src/Controller/Manager/Pos/PosEmployeeController.php | TERMINE |
| PosSettingsFormType | src/Form/Pos/PosSettingsFormType.php | TERMINE |
| PosEmployeeRoleFormType | src/Form/Pos/PosEmployeeRoleFormType.php | TERMINE |
| Templates (4) | templates/manager/pos/settings/, employees/ | TERMINE |
| pos-settings_controller.js | assets/controllers/ | TERMINE |
| Sidebar POS | templates/components/menus/_menu_manager.html.twig | TERMINE |

### Phase 1 : Catalogue Produits (TERMINE)

| Composant | Fichier | Statut |
|-----------|---------|--------|
| ProductCategory entity | src/Entity/Pos/ProductCategory.php | TERMINE |
| Product entity | src/Entity/Pos/Product.php | TERMINE |
| ProductVariant entity | src/Entity/Pos/ProductVariant.php | TERMINE |
| ProductMedia entity | src/Entity/Pos/ProductMedia.php | TERMINE |
| Barcode entity | src/Entity/Pos/Barcode.php | TERMINE |
| Repositories (5) | src/Repository/Pos/ | TERMINE |
| ProductService | src/Service/Pos/ProductService.php | TERMINE |
| ProductCategoryService | src/Service/Pos/ProductCategoryService.php | TERMINE |
| BarcodeService | src/Service/Pos/BarcodeService.php | TERMINE |
| ProductController | src/Controller/Manager/Pos/ProductController.php | TERMINE |
| ProductCategoryController | src/Controller/Manager/Pos/ProductCategoryController.php | TERMINE |
| ProductFormType | src/Form/Pos/ProductFormType.php | TERMINE |
| ProductCategoryFormType | src/Form/Pos/ProductCategoryFormType.php | TERMINE |
| Templates (11) | templates/manager/pos/products/, categories/ | TERMINE |
| ProductVariantFormType | — | A FAIRE |
| Import CSV (controller + template) | — | A FAIRE |
| Stimulus controllers (5) | — | A FAIRE |

### Phase 2 : Gestion des Stocks (TERMINE)

| Composant | Fichier | Statut |
|-----------|---------|--------|
| StockMovement entity | src/Entity/Pos/StockMovement.php | TERMINE |
| Supplier entity | src/Entity/Pos/Supplier.php | TERMINE |
| SupplierProduct entity | src/Entity/Pos/SupplierProduct.php | TERMINE |
| Repositories (3) | src/Repository/Pos/ | TERMINE |
| StockService | src/Service/Pos/StockService.php | TERMINE |
| SupplierService | src/Service/Pos/SupplierService.php | TERMINE |
| StockController (5 routes) | src/Controller/Manager/Pos/StockController.php | TERMINE |
| SupplierController (8 routes) | src/Controller/Manager/Pos/SupplierController.php | TERMINE |
| Forms (4) | src/Form/Pos/ | TERMINE |
| Templates (9) | templates/manager/pos/stock/, suppliers/ | TERMINE |
| StockReceptionController (Employer) | — | A FAIRE |
| PosStockAlertCommand | — | A FAIRE |

### Phase 3 : Ventes & Caisse (TERMINE — côté Manager)

| Composant | Fichier | Statut |
|-----------|---------|--------|
| Sale entity | src/Entity/Pos/Sale.php | TERMINE |
| SaleLine entity | src/Entity/Pos/SaleLine.php | TERMINE |
| Payment entity | src/Entity/Pos/Payment.php | TERMINE |
| Register entity | src/Entity/Pos/Register.php | TERMINE |
| RegisterSession entity | src/Entity/Pos/RegisterSession.php | TERMINE |
| CashMovement entity | src/Entity/Pos/CashMovement.php | TERMINE |
| Repositories (6) | src/Repository/Pos/ | TERMINE |
| SaleService | src/Service/Pos/SaleService.php | TERMINE |
| RegisterService | src/Service/Pos/RegisterService.php | TERMINE |
| ReceiptService | src/Service/Pos/ReceiptService.php | TERMINE |
| SaleController (5 routes) | src/Controller/Manager/Pos/SaleController.php | TERMINE |
| RegisterController (5 routes) | src/Controller/Manager/Pos/RegisterController.php | TERMINE |
| RegisterFormType | src/Form/Pos/RegisterFormType.php | TERMINE |
| Templates (9) | templates/manager/pos/sales/, registers/ | TERMINE |
| CashierController (Employer SPA) | — | A FAIRE |
| Stimulus caisse (4 controllers) | — | A FAIRE |

### Phase 4 : Clients & Crédit (TERMINE)

| Composant | Fichier | Statut |
|-----------|---------|--------|
| Customer entity | src/Entity/Pos/Customer.php | TERMINE |
| CustomerCredit entity | src/Entity/Pos/CustomerCredit.php | TERMINE |
| Repositories (2) | src/Repository/Pos/ | TERMINE |
| CustomerService | src/Service/Pos/CustomerService.php | TERMINE |
| CustomerController (7 routes) | src/Controller/Manager/Pos/CustomerController.php | TERMINE |
| CustomerFormType | src/Form/Pos/CustomerFormType.php | TERMINE |
| Templates (6) | templates/manager/pos/customers/ | TERMINE |
| Intégration client dans caisse | — | A FAIRE |

### Phase 5 : Commandes & Approvisionnement (TERMINE)

| Composant | Fichier | Statut |
|-----------|---------|--------|
| PurchaseOrder entity | src/Entity/Pos/PurchaseOrder.php | TERMINE |
| PurchaseOrderLine entity | src/Entity/Pos/PurchaseOrderLine.php | TERMINE |
| Repositories (2) | src/Repository/Pos/ | TERMINE |
| PurchaseOrderService | src/Service/Pos/PurchaseOrderService.php | TERMINE |
| PurchaseOrderController (7 routes) | src/Controller/Manager/Pos/PurchaseOrderController.php | TERMINE |
| PurchaseOrderFormType | src/Form/Pos/PurchaseOrderFormType.php | TERMINE |
| Templates (5) | templates/manager/pos/purchase-orders/ | TERMINE |
| purchase-order-lines_controller.js | assets/controllers/ | TERMINE |

### Phase 6 : Inventaire (TERMINE)

| Composant | Fichier | Statut |
|-----------|---------|--------|
| Inventory entity | src/Entity/Pos/Inventory.php | TERMINE |
| InventoryLine entity | src/Entity/Pos/InventoryLine.php | TERMINE |
| Repositories (2) | src/Repository/Pos/ | TERMINE |
| InventoryService | src/Service/Pos/InventoryService.php | TERMINE |
| InventoryController (8 routes) | src/Controller/Manager/Pos/InventoryController.php | TERMINE |
| Templates (4) | templates/manager/pos/inventories/ | TERMINE |

### Phase 7 : Rapports & Statistiques (TERMINE)

| Composant | Fichier | Statut |
|-----------|---------|--------|
| PosReportService | src/Service/Pos/PosReportService.php | TERMINE |
| ReportController (5 routes) | src/Controller/Manager/Pos/ReportController.php | TERMINE |
| Templates (5) | templates/manager/pos/reports/ | TERMINE |
| PosDailyReportCommand | — | A FAIRE |

### Phase 8 : Remboursements & Annulations (TERMINE)

| Composant | Fichier | Statut |
|-----------|---------|--------|
| Refund entity | src/Entity/Pos/Refund.php | TERMINE |
| RefundLine entity | src/Entity/Pos/RefundLine.php | TERMINE |
| RefundPayment entity | src/Entity/Pos/RefundPayment.php | TERMINE |
| Repositories (3) | src/Repository/Pos/ | TERMINE |
| RefundService | src/Service/Pos/RefundService.php | TERMINE |
| RefundController (5 routes) | src/Controller/Manager/Pos/RefundController.php | TERMINE |
| Templates (3) | templates/manager/pos/refunds/ | TERMINE |

### Phase 9 : Exports PDF & CSV (TERMINE)

| Composant | Fichier | Statut |
|-----------|---------|--------|
| PosExportService | src/Service/Pos/PosExportService.php | TERMINE |
| ExportController (8 routes) | src/Controller/Manager/Pos/ExportController.php | TERMINE |
| Templates PDF (7) | templates/manager/pos/exports/ | TERMINE |
| Boutons export sur pages existantes | 6 templates modifiés | TERMINE |

### Phase 10 : Journal d'audit (TERMINE)

| Composant | Fichier | Statut |
|-----------|---------|--------|
| AuditLogController (3 routes) | src/Controller/Manager/Pos/AuditLogController.php | TERMINE |
| Templates (2) | templates/manager/pos/audit-logs/ | TERMINE |
| Widget activité récente dashboard | templates/manager/pos/reports/dashboard.html.twig | TERMINE |

---

## Services POS (17 total)

| Service | Fichier | Statut |
|---------|---------|--------|
| PosSettingsService | src/Service/Pos/PosSettingsService.php | TERMINE |
| PosAuditService | src/Service/Pos/PosAuditService.php | TERMINE |
| PosEmployeeService | src/Service/Pos/PosEmployeeService.php | TERMINE |
| ProductService | src/Service/Pos/ProductService.php | TERMINE |
| ProductCategoryService | src/Service/Pos/ProductCategoryService.php | TERMINE |
| BarcodeService | src/Service/Pos/BarcodeService.php | TERMINE |
| StockService | src/Service/Pos/StockService.php | TERMINE |
| SupplierService | src/Service/Pos/SupplierService.php | TERMINE |
| SaleService | src/Service/Pos/SaleService.php | TERMINE |
| RegisterService | src/Service/Pos/RegisterService.php | TERMINE |
| ReceiptService | src/Service/Pos/ReceiptService.php | TERMINE |
| CustomerService | src/Service/Pos/CustomerService.php | TERMINE |
| PurchaseOrderService | src/Service/Pos/PurchaseOrderService.php | TERMINE |
| InventoryService | src/Service/Pos/InventoryService.php | TERMINE |
| PosReportService | src/Service/Pos/PosReportService.php | TERMINE |
| RefundService | src/Service/Pos/RefundService.php | TERMINE |
| PosExportService | src/Service/Pos/PosExportService.php | TERMINE |

---

## Stimulus Controllers POS

| Controller | Fichier | Statut | Phase |
|-----------|---------|--------|-------|
| pos-settings_controller.js | assets/controllers/ | TERMINE | 0 |
| purchase-order-lines_controller.js | assets/controllers/ | TERMINE | 5 |
| pos-product-form_controller.js | — | A FAIRE | 1 |
| pos-product-image_controller.js | — | A FAIRE | Média |
| pos-category-tree_controller.js | — | A FAIRE | 1 |
| pos-product-variant_controller.js | — | A FAIRE | 1 |
| pos-barcode_controller.js | — | A FAIRE | 1 |
| pos-stock-alert_controller.js | — | A FAIRE | 2 |
| pos-stock-movement_controller.js | — | A FAIRE | 2 |
| pos-cashier_controller.js | — | A FAIRE | Caisse |
| pos-payment_controller.js | — | A FAIRE | Caisse |
| pos-receipt_controller.js | — | A FAIRE | Caisse |
| pos-product-search_controller.js | — | A FAIRE | Caisse |
| pos-inventory_controller.js | — | A FAIRE | 6 |
| pos-dashboard_controller.js | — | A FAIRE | 7 |

---

## Commandes CLI POS

| Commande | Fichier | Statut |
|----------|---------|--------|
| PosStockAlertCommand | — | A FAIRE |
| PosDailyReportCommand | — | A FAIRE |
| MigrateMediaToCompanyStructureCommand | — | A FAIRE |

---

## Décisions d'Architecture

1. **Prefix `pos_`** pour toutes les tables BDD → évite les conflits
2. **Entités dans `src/Entity/Pos/`** → namespace séparé
3. **Soft-delete** sur Product, Customer, Supplier, ProductCategory → préserve l'historique
4. **Append-only** sur StockMovement, PosAuditLog, CustomerCredit → intégrité audit
5. **Dénormalisation** : stock sur Product, totaux sur Customer/Supplier → performance
6. **UUID v7** sur Sale, PurchaseOrder, Refund, Inventory, Customer, Supplier
7. **Transactions inline** : StockMovement dans executeInTransaction (PAS via StockService)
8. **bcmath** pour toutes les opérations monétaires
9. **Snapshots** : SaleLine, PurchaseOrderLine, RefundLine, InventoryLine
10. **Stimulus** : data-controller HTML attributes (PAS stimulus_controller() Twig)
11. **dompdf v3.1** pour génération PDF

## Risques Identifiés

1. **Performance caisse** : l'interface caissier doit être ultra-rapide → optimiser requêtes, cache
2. **Concurrence stock** : deux caissiers sur le même produit → verrouillage optimiste
3. **Volume données** : PosAuditLog/StockMovement croissance rapide → prévoir archivage
4. **Hors-ligne** : caisse sans réseau → localStorage + synchronisation (futur)