# Architecture POS - 2AB Portal

## Vue d'ensemble

Le module POS (Point of Sale) transforme chaque Company en boutique autonome, gérée par son ROLE_MANAGER. Les employés (ROLE_EMPLOYER) opèrent sous la responsabilité du manager. Chaque boutique est entièrement isolée et paramétrable.

---

## Principes Fondamentaux

### 1. Isolation Totale par Company
- Chaque Company = 1 boutique indépendante
- Produits, stocks, ventes, clients, caisses : tous scopés à la Company
- Aucun croisement de données entre entreprises
- Le CompanyVoter existant est étendu avec de nouveaux attributs POS

### 2. Hiérarchie des Rôles POS

```
ROLE_ADMIN
  └── Supervision globale, rapports inter-entreprises, configuration système
  
ROLE_MANAGER (scopé à sa Company)
  └── Gestion complète de SA boutique :
      - Catalogue produits, catégories, fournisseurs
      - Gestion des stocks et inventaires
      - Configuration des caisses et moyens de paiement
      - Rapports de vente et statistiques
      - Paramétrage boutique (TVA, devise, seuils, alertes)
      - Gestion des employés POS (caissiers, magasiniers)
      
ROLE_EMPLOYER (scopé à sa Company)
  └── Opérations quotidiennes selon permissions :
      - Caissier : encaissement, consultation produits
      - Magasinier : réception stock, inventaire
      - Vendeur : ventes, consultation stock
```

### 3. Paramétrage par Company

Chaque boutique dispose de sa propre configuration :

```yaml
# Exemple de configuration POS par Company
pos_settings:
  general:
    shop_name: "Ma Boutique"
    currency: "XOF"                    # Devise (FCFA par défaut)
    tax_rate: 18.0                     # TVA en %
    tax_included: true                 # Prix TTC par défaut
    decimal_places: 0                  # Pas de centimes pour XOF
    receipt_header: "Bienvenue !"
    receipt_footer: "Merci de votre visite"
    
  inventory:
    low_stock_threshold: 10            # Alerte stock bas
    critical_stock_threshold: 3        # Alerte critique
    enable_negative_stock: false       # Autoriser stock négatif
    auto_reorder: false                # Commande auto fournisseur
    reorder_point: 5                   # Seuil de réapprovisionnement
    
  sales:
    allow_discount: true               # Autoriser remises
    max_discount_percent: 50           # Remise max (%)
    require_customer: false            # Client obligatoire
    allow_credit_sales: false          # Vente à crédit
    credit_limit: 0                    # Plafond crédit client
    enable_loyalty: false              # Programme fidélité
    
  payment:
    accepted_methods:                  # Moyens de paiement
      - cash
      - mobile_money
      - card
      - transfer
    mobile_money_providers:
      - orange_money
      - wave
      - free_money
      
  employees:
    require_pin: true                  # PIN caissier obligatoire
    auto_logout_minutes: 30            # Déconnexion auto caisse
    allow_void: false                  # Autoriser annulation (manager only sinon)
    allow_refund: false                # Autoriser remboursement (manager only sinon)
    
  notifications:
    low_stock_alert: true
    daily_report: true
    large_sale_alert: false
    large_sale_threshold: 500000       # Seuil alerte (FCFA)
```

---

## Architecture des Entités

### Diagramme Relationnel

```
Company (existant)
├── PosSettings (1:1)           ← Configuration boutique
├── ProductCategory (1:N)       ← Catégories produits
│   └── Product (1:N)           ← Produits
│       ├── ProductVariant (1:N)    ← Variantes (taille, couleur)
│       ├── ProductMedia (1:N)      ← Images produits → Media
│       ├── StockMovement (1:N)     ← Mouvements de stock
│       └── SupplierProduct (N:M)   ← Lien fournisseurs
├── Supplier (1:N)              ← Fournisseurs
│   └── PurchaseOrder (1:N)     ← Bons de commande
│       └── PurchaseOrderLine (1:N)
├── Customer (1:N)              ← Clients boutique
│   ├── Sale (1:N)              ← Ventes
│   └── CustomerCredit (1:N)    ← Crédits clients
├── Register (1:N)              ← Caisses enregistreuses
│   ├── RegisterSession (1:N)   ← Sessions de caisse
│   └── CashMovement (1:N)     ← Mouvements de caisse
├── Sale (1:N)                  ← Toutes les ventes
│   ├── SaleLine (1:N)         ← Lignes de vente
│   └── Payment (1:N)          ← Paiements
├── Inventory (1:N)             ← Sessions d'inventaire
│   └── InventoryLine (1:N)    ← Lignes d'inventaire
└── PosEmployeeRole (1:N)      ← Rôles POS des employés
```

### Nouvelles Entités (24)

**Core POS :**
1. `PosSettings` - Configuration boutique par Company
2. `ProductCategory` - Catégories de produits (hiérarchique)
3. `Product` - Produits
4. `ProductVariant` - Variantes produit (taille, couleur, etc.)
5. `ProductMedia` - Images/médias des produits
6. `Barcode` - Codes-barres produits

**Stock :**
7. `Supplier` - Fournisseurs
8. `SupplierProduct` - Produits par fournisseur (prix d'achat, ref)
9. `StockMovement` - Mouvements de stock (entrée/sortie/ajustement)
10. `PurchaseOrder` - Bons de commande fournisseur
11. `PurchaseOrderLine` - Lignes de bon de commande
12. `Inventory` - Sessions d'inventaire
13. `InventoryLine` - Comptage par produit

**Ventes :**
14. `Customer` - Clients de la boutique
15. `CustomerCredit` - Crédits/dettes clients
16. `Sale` - Transactions de vente
17. `SaleLine` - Lignes de vente (produit, quantité, prix)
18. `Payment` - Paiements (multiples par vente possible)
19. `Refund` - Remboursements

**Caisse :**
20. `Register` - Caisses enregistreuses
21. `RegisterSession` - Ouverture/fermeture de caisse
22. `CashMovement` - Entrées/sorties de caisse hors vente

**Employés & Audit :**
23. `PosEmployeeRole` - Rôle POS par employé par Company
24. `PosAuditLog` - Journal d'audit POS

---

## Architecture Technique

### Structure des Fichiers

```
src/
├── Controller/
│   ├── Manager/
│   │   ├── Pos/
│   │   │   ├── PosDashboardController.php
│   │   │   ├── ProductController.php
│   │   │   ├── ProductCategoryController.php
│   │   │   ├── StockController.php
│   │   │   ├── SupplierController.php
│   │   │   ├── PurchaseOrderController.php
│   │   │   ├── CustomerController.php
│   │   │   ├── SaleController.php
│   │   │   ├── RegisterController.php
│   │   │   ├── InventoryController.php
│   │   │   ├── PosSettingsController.php
│   │   │   ├── PosReportController.php
│   │   │   └── PosEmployeeController.php
│   │   └── ...
│   ├── Employer/
│   │   └── Pos/
│   │       ├── CashierController.php        # Interface caissier
│   │       ├── StockReceptionController.php  # Réception stock
│   │       └── EmployerSaleController.php    # Ventes employé
│   └── Api/
│       └── Pos/
│           ├── PosProductApiController.php
│           ├── PosSaleApiController.php
│           └── PosStockApiController.php
├── Entity/
│   └── Pos/
│       ├── PosSettings.php
│       ├── ProductCategory.php
│       ├── Product.php
│       ├── ProductVariant.php
│       ├── ProductMedia.php
│       ├── Barcode.php
│       ├── Supplier.php
│       ├── SupplierProduct.php
│       ├── StockMovement.php
│       ├── PurchaseOrder.php
│       ├── PurchaseOrderLine.php
│       ├── Inventory.php
│       ├── InventoryLine.php
│       ├── Customer.php
│       ├── CustomerCredit.php
│       ├── Sale.php
│       ├── SaleLine.php
│       ├── Payment.php
│       ├── Refund.php
│       ├── Register.php
│       ├── RegisterSession.php
│       ├── CashMovement.php
│       ├── PosEmployeeRole.php
│       └── PosAuditLog.php
├── Repository/
│   └── Pos/
│       └── ... (1 par entité)
├── Service/
│   └── Pos/
│       ├── PosSettingsService.php
│       ├── ProductService.php
│       ├── StockService.php
│       ├── SaleService.php
│       ├── PaymentService.php
│       ├── CustomerService.php
│       ├── RegisterService.php
│       ├── InventoryService.php
│       ├── PurchaseOrderService.php
│       ├── PosReportService.php
│       ├── PosAuditService.php
│       ├── BarcodeService.php
│       └── ReceiptService.php
├── Form/
│   └── Pos/
│       └── ... (formulaires POS)
└── Command/
    └── Pos/
        ├── PosStockAlertCommand.php
        └── PosDailyReportCommand.php

templates/
├── manager/
│   └── pos/
│       ├── dashboard/
│       ├── products/
│       ├── categories/
│       ├── stock/
│       ├── suppliers/
│       ├── customers/
│       ├── sales/
│       ├── registers/
│       ├── inventory/
│       ├── reports/
│       ├── settings/
│       └── employees/
├── employer/
│   └── pos/
│       ├── cashier/          # Interface caisse
│       ├── stock/            # Réception stock
│       └── sales/            # Historique ventes
└── admin/
    └── pos/
        ├── dashboard/        # Vue globale toutes boutiques
        └── reports/          # Rapports consolidés

assets/controllers/
├── pos-cashier_controller.js        # Interface caisse temps réel
├── pos-product-search_controller.js # Recherche produits rapide
├── pos-barcode_controller.js        # Scan code-barres
├── pos-payment_controller.js        # Gestion paiements
├── pos-stock-alert_controller.js    # Alertes stock
├── pos-receipt_controller.js        # Impression ticket
├── pos-inventory_controller.js      # Saisie inventaire
└── pos-dashboard_controller.js      # Dashboard temps réel
```

### Extension du CompanyVoter

```php
// Nouveaux attributs à ajouter au CompanyVoter
const POS_ACCESS = 'POS_ACCESS';                   // Accès au module POS
const POS_MANAGE = 'POS_MANAGE';                   // Gestion POS (manager)
const POS_SELL = 'POS_SELL';                       // Droit de vendre
const POS_STOCK = 'POS_STOCK';                     // Gestion stock
const POS_REPORTS = 'POS_REPORTS';                 // Accès rapports
const POS_SETTINGS = 'POS_SETTINGS';               // Configuration POS
```

### Routes POS

```yaml
# Manager POS Routes
/manager/pos/                          # Dashboard POS
/manager/pos/products/                 # Gestion produits
/manager/pos/products/{id}             # Détail produit
/manager/pos/categories/               # Catégories
/manager/pos/stock/                    # Vue stock
/manager/pos/stock/movements           # Mouvements
/manager/pos/suppliers/                # Fournisseurs
/manager/pos/purchase-orders/          # Bons de commande
/manager/pos/customers/                # Clients
/manager/pos/sales/                    # Historique ventes
/manager/pos/registers/                # Caisses
/manager/pos/inventory/                # Inventaires
/manager/pos/reports/                  # Rapports
/manager/pos/settings/                 # Paramètres
/manager/pos/employees/                # Employés POS

# Employer POS Routes
/employer/pos/cashier/                 # Interface caisse
/employer/pos/sales/                   # Mes ventes
/employer/pos/stock/reception          # Réception stock

# API POS Routes
/api/pos/products/search               # Recherche produits
/api/pos/sales/                        # Créer vente
/api/pos/stock/check                   # Vérifier stock
```

---

## Sécurité POS

### Couches de Sécurité

1. **Route-level** : `#[IsGranted('ROLE_MANAGER')]` ou `#[IsGranted('ROLE_EMPLOYER')]`
2. **Voter-level** : `CompanyVoter` étendu avec attributs POS
3. **Service-level** : Vérification Company dans chaque service POS
4. **Employee-level** : `PosEmployeeRole` pour permissions granulaires
5. **PIN caissier** : Authentification supplémentaire pour opérations sensibles
6. **Audit** : `PosAuditLog` pour traçabilité complète

### Matrice des Permissions

| Action | ADMIN | MANAGER | EMPLOYER (Caissier) | EMPLOYER (Magasinier) |
|--------|-------|---------|--------------------|-----------------------|
| Config boutique | Lecture | CRUD | - | - |
| Produits | Lecture | CRUD | Lecture | Lecture |
| Stock | Lecture | CRUD | Lecture | Réception |
| Ventes | Lecture | CRUD + Annulation | Créer | - |
| Remboursements | Lecture | Approuver | Demander | - |
| Clients | Lecture | CRUD | Lecture + Créer | - |
| Rapports | Global | Company | Mes ventes | - |
| Caisses | Lecture | CRUD | Ouvrir/Fermer | - |
| Inventaire | Lecture | CRUD | Saisir comptage | Saisir comptage |
| Fournisseurs | Lecture | CRUD | - | Lecture |
| Employés POS | Lecture | CRUD | - | - |

---

## Intégration avec l'Existant

### Entités Existantes Réutilisées
- `Company` : Propriétaire de la boutique
- `User` : Employés et managers
- `UserCompany` : Lien utilisateur-entreprise (rôle existant)
- `Media` : Images produits, logos, documents
- `DocumentCategory` : Catégorisation documents POS
- `UserActivity` : Audit des actions utilisateur

### Services Existants Réutilisés
- `EntityManagerService` : Transactions sécurisées
- `FileLogger` : Logging structuré
- `MediaService` : Upload images produits
- `EmailService` : Alertes stock, rapports quotidiens
- `NavigationService` : Breadcrumbs POS (nouveaux contextes)
- `RoleManagerService` : Extension pour rôles POS

### Patterns Respectés
- Soft-delete sur Product, Customer, Supplier, ProductCategory
- TimestampableEntity sur toutes les entités
- Try-catch + FileLogger dans tous les contrôleurs
- EntityManagerService.safePersist() pour toutes les écritures
- Pagination KnpPaginator pour les listes
- Stimulus controllers pour l'interactivité
- Templates étendant authenticated.html.twig