# 02 — Modèle de données

> Modèle **cible**. Les entités marquées ✅ existent déjà ; les autres sont à créer par module. Toutes suivent les conventions du projet (Gedmo soft-delete + index `idx_*_deleted` où pertinent, `TimestampableEntity`, `EntityManagerService`).

## Base centrale (source de vérité)

### Socle existant ✅

| Entité | Rôle |
|---|---|
| `User` ✅ | Comptes (rôles globaux JSON, sécurité, 2FA, appareils) |
| `Company` ✅ | Boutique |
| `UserCompany` ✅ | Appartenance user↔boutique + rôle boutique (`boutiqueRole` RBAC) |
| `CompanyDatabase` ✅ | Connexion chiffrée à la base client (multi-tenant) |
| `Role`, `Permission` ✅ | RBAC (rôles/permissions par boutique) |
| `Media`, `DocumentCategory`, `Tag` ✅ | GED / médias par boutique |
| `SmtpConfiguration`, `SmsConfiguration` ✅ | Canaux de notification |
| Entités sécurité/audit ✅ | `JwtToken`, `RefreshToken`, `LoginAttempt`, `IpBlock`, `HttpRequestLog`, `UserActivity`… |

### Domaine POS à créer (par module)

Rattachées à une **boutique** (`company_id`) et scopées par RBAC. Nommage indicatif.

| Entité | Module | Notes |
|---|---|---|
| `Product` | Catalogue | nom, sku, code-barres, prix, TVA, catégorie, actif |
| `ProductVariant` | Catalogue | déclinaisons (taille/couleur), sku propre |
| `ProductCategory` | Catalogue | arborescence par boutique |
| `StockItem` / `StockMovement` | Stock | quantité par produit/dépôt ; mouvements (entrée, sortie, ajustement, vente) |
| `Warehouse` | Stock | dépôt/point de stock (optionnel multi-dépôt) |
| `Sale` | POS/Ventes | ticket de vente ; **client nullable (vente anonyme)** ; statut, totaux, remises, taxes |
| `SaleLine` | POS/Ventes | ligne (produit, qté, prix unitaire, remise, TVA) |
| `Payment` | Caisse | paiement d'une vente (espèces, mobile money, carte…), montant, référence |
| `CashSession` | Caisse | session de caisse (ouverture/fermeture, fond, écarts, employé) |
| `Customer` | Clients/CRM | client de la boutique (nullable dans Sale) ; fidélité optionnelle |
| `Supplier` | Achats | fournisseur |
| `PurchaseOrder` / `PurchaseLine` | Achats | commande fournisseur, réception → stock |
| `Promotion` / `PriceRule` | Promotions | règles de remise, coupons, périodes |
| `Invoice` | Facturation | facture (numérotation, TVA, NINEA/RCCM) |
| `TaxRate` | Facturation | taux de TVA par produit/catégorie |
| `WooCommerceConnection` | Connecteur WooCommerce | 1:1 boutique : URL + clés API **chiffrées**, options de synchro, statut |
| `WooCommerceProductMap` / `WooCommerceSyncLog` | Connecteur WooCommerce | mapping produit central ↔ WooCommerce ; journal de synchro (append-only) |

### Relations clés

- `Sale (1) ── (N) SaleLine` ; `Sale (1) ── (N) Payment` ; `Sale (N) ── (0..1) Customer` (**null = vente anonyme**) ; `Sale (N) ── (1) CashSession` ; `Sale (N) ── (1) User` (caissier) ; `Sale (N) ── (1) Company`.
- `SaleLine (N) ── (1) Product/ProductVariant`.
- `StockMovement (N) ── (1) Product` ; une vente confirmée génère des `StockMovement` de sortie.
- Tout est scopé `Company` (isolation par boutique + RBAC).

### Conventions transverses

- **Montants** : entiers en **centimes FCFA** (éviter les flottants) ; devise `XOF` par défaut.
- **Horodatage** : `TimestampableEntity` ; fuseau `Africa/Dakar`.
- **Soft-delete** : produits, catégories, clients, promotions (Gedmo) ; **jamais** sur les écritures comptables/ventes (append-only : une vente s'annule par un avoir, pas par suppression).
- **Numérotation** : séquences par boutique et par exercice (ventes, factures) — service dédié.
- **UUID** : exposer un `uuid` public (comme `Company`) pour les entités adressées par l'API/PWA.

## Cibles e-commerce (deux canaux)

Le catalogue/stock central alimente l'e-commerce du client par l'un des deux canaux (ADR-007) :

- **Base client projetée** (clients sans site) : sous-ensemble **en lecture** synchronisé depuis le centre (voir [`ARCHITECTURE_MULTITENANT.md` §4bis](../portail-manager/docs/ARCHITECTURE_MULTITENANT.md)). Tables candidates : `product` (publiables), `product_category`, `price`, `stock`, `order` (commandes du site → remontées au centre). Schéma défini en **phase 4** ([roadmap](05-roadmap.md)).
- **WooCommerce existant** (clients avec site) : pas de base projetée — la synchro écrit directement dans **leur** WooCommerce via l'API REST (produits/prix/stock) et importe les commandes ([fiche connecteur](modules/woocommerce-connector.md)).

Principes communs : upsert idempotent par clé métier (SKU) ; **le central gagne** ; côté client, seules ses données propres (panier, comptes du site) sont écrites localement.

## Schéma d'implémentation

Le projet utilise `doctrine:schema:update` en dev (voir CLAUDE.md). Chaque module ajoute ses tables de façon **additive** ; toujours vérifier `--dump-sql` (aucun DROP) avant `--force`. Migrations réelles en prod.

## Suite

Sécurité & autorisation : [03 — Sécurité](03-securite.md).