# CLAUDE.md — ICAVI GESTION (Refonte v2)

> **Ce fichier est lu automatiquement par Claude CLI au démarrage.**
> Il transmet tout le contexte de la phase de conception pour démarrer l'implémentation.

---

## CONTEXTE PROJET

**Application :** ICAVI GESTION — ERP de gestion commerciale  
**Client :** ICAVI SECURE, Douala, Cameroun  
**Responsable :** Mc'clint (solo founder, full-stack)  
**URL production :** https://gst.icavi-secure.com  
**Hébergement :** OVH Mutualisé Pro (contrainte critique)

---

## ÉTAT ACTUEL

Ce dossier est l'ancienne application Laravel 11 avec UI Blade.  
La **refonte complète** est décidée. Les 4 documents de conception sont dans `docs/` :

| Document | Contenu |
|---|---|
| `docs/AUDIT.md` | Audit complet de l'existant — 18 problèmes identifiés, 7 risques |
| `docs/ARCHITECTURE.md` | Architecture cible React + Laravel 12 + MySQL |
| `docs/DESIGN-SYSTEM.md` | Charte UI/UX ICAVI (couleurs, composants, patterns) |
| `docs/MIGRATION-PLAN.md` | Plan de migration en 6 phases + ordre des tâches |

**Lire ces 4 documents avant toute action.**

---

## DÉCISIONS ARCHITECTURALES CLÉS

### Stack cible
- **Frontend :** React 18 + Vite + TypeScript → build statique dans `public/`
- **Backend :** Laravel 12 + Sanctum SPA (pas de JWT) → API REST pure `/api/v1/*`
- **Base de données :** MySQL `icaviss3` existante — **aucune perte de données**
- **PDF :** barryvdh/laravel-dompdf (remplace Chrome headless — OVH mutualisé incompatible Chrome)
- **Cache/Queue :** file/sync — pas de Redis, pas de worker permanent (contrainte OVH)

### Contrainte OVH absolue
OVH Mutualisé Pro = pas de Docker, pas de Node.js server, pas de Redis, pas de workers permanents.  
→ React = **fichiers statiques** servis par Apache  
→ Laravel = **PHP classique** via .htaccess  
→ Cron = interface OVH (1 tâche par heure minimum)

### Authentification
Sanctum SPA cookies (httpOnly, SameSite=Lax).  
Axios côté React : `withCredentials: true`.  
Flow : `GET /sanctum/csrf-cookie` → `POST /api/v1/auth/login` → cookie de session.

### Domaines
Même domaine pour React et Laravel (Option A) :
```
gst.icavi-secure.com/          → React SPA (static)
gst.icavi-secure.com/api/v1/   → Laravel API
gst.icavi-secure.com/sanctum/  → CSRF
```

---

## ORDRE D'IMPLÉMENTATION (6 phases)

```
Phase A : Infrastructure Laravel 12          ← COMMENCER ICI
Phase B : Shell React + Auth
Phase C : Modules critiques (Dashboard, Stock, Documents, Produits)
Phase D : Modules secondaires (Clients, Ventes, GED)
Phase E : Modules spéciaux (CashVouchers, Permissions, Notifications, Users)
Phase F : Cleanup, optimisations, déploiement OVH
```

**Détail complet dans `docs/MIGRATION-PLAN.md` section 6.**

---

## PHASE A — À FAIRE EN PREMIER

### A1. Laravel 11 → 12

```bash
# composer.json : mettre à jour laravel/framework ^12.0 + ajouter laravel/sanctum ^4.0 + barryvdh/laravel-dompdf ^3.0
composer update
php artisan install:api
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate
```

### A2. Corrections critiques AVANT tout autre code

**Bug 1 — `$typeCode` undefined dans `DocumentService::genererDepuisVente()` :**
```php
// Fichier : app/Services/DocumentService.php
// Ligne approx : dans la boucle de création des DocumentLine
// AVANT (bug) :
$line->type_code = $typeCode;
// APRÈS :
$line->type_code = $document->type_code;
```

**Bug 2 — Anti-pattern : `DocumentService` instancie `DocumentController` :**
```php
// Extraire calculerMontants() et generateReference() de DocumentController
// vers DocumentService — logique métier ne doit PAS être dans les controllers
```

### A3. Structure des dossiers à créer

```
app/Http/Controllers/Api/V1/
  Auth/, Dashboard/, Clients/, Products/, Stock/, Sales/,
  Documents/, CashVouchers/, Permissions/, Ged/, Users/
app/Http/Requests/   (un sous-dossier par module)
app/Http/Resources/Api/V1/
app/Policies/        (un Policy par modèle principal)
```

### A4. Policies à créer

```bash
php artisan make:policy ClientPolicy --model=Client
php artisan make:policy ProductPolicy --model=Product
php artisan make:policy DocumentPolicy --model=Document
php artisan make:policy SalePolicy --model=Sale
php artisan make:policy CashVoucherPolicy --model=CashVoucher
php artisan make:policy UserPolicy --model=User
```

### A5. Migrations à créer

```bash
php artisan make:migration create_categories_table
php artisan make:migration create_suppliers_table
php artisan make:migration add_category_id_to_products_table
php artisan make:migration add_supplier_id_to_products_table
# ⚠️ NE PAS supprimer les colonnes category/supplier texte avant data migration validée
```

### A6. Route API skeleton (routes/api.php)

Toutes les routes `/api/v1/*` définies dans `docs/ARCHITECTURE.md` section 4.
Les controllers peuvent retourner `response()->json(['message' => 'Not implemented'], 501)` temporairement.

---

## RÈGLES ABSOLUES

1. **Ne pas toucher à la base de données existante** — toutes les migrations sont ADDITIVE uniquement
2. **APP_DEBUG=false en production** — jamais exposer les stack traces
3. **Ne jamais committer `.env`** — contient SMTP password et APP_KEY
4. **La signature de M. Raymond (`Signature de Mr Raymond T..png`)** — accessible uniquement côté serveur pour les PDFs, jamais exposée en URL publique
5. **Toute la logique métier côté Laravel** — React = présentation uniquement, jamais de vérification de sécurité côté client
6. **Pas de Chrome headless** — OVH mutualisé incompatible → DomPDF uniquement pour les PDFs

---

## INFORMATIONS SENSIBLES (NE PAS COMMITTER)

- `MAIL_PASSWORD` : dans `.env` local uniquement
- `APP_KEY` : régénérer pour la production
- `CASH_VOUCHER_SIGNER_USER_ID=4` : ID de l'utilisateur signataire (M. Raymond)
- `RAYMOND_EMAIL` : email directionnel — dans `.env` uniquement

---

## RÉFÉRENCES RAPIDES

### Couleurs ICAVI SECURE
```
Bleu marine principal : #1e2c54  (brand-500)
Jaune accent :          #f8e800  (accent)
```

### Rôles utilisateurs
```
super_admin, admin, commercial, storage_manager
+ flag is_directeur (boolean, indépendant du rôle)
```

### Statuts documents
```
FAC  → VALIDE
PRO  → EN_COURS, VALIDE
BL   → EN_COURS_LIVRAISON, LIVRE
DEV/BC/AVO → ENVOYE, VALIDE, REFUSE, FACTURE
```

### URL API complètes
Voir `docs/ARCHITECTURE.md` section 4 pour la liste exhaustive des routes.

---

## POUR DÉMARRER

```bash
# 1. Lire les docs (obligatoire)
cat docs/AUDIT.md
cat docs/ARCHITECTURE.md
cat docs/MIGRATION-PLAN.md
cat docs/DESIGN-SYSTEM.md

# 2. Commencer par Phase A
# Suivre docs/MIGRATION-PLAN.md section 6, Phase A, étape par étape

# 3. Structure du nouveau projet
# backend/  → ce dossier Laravel (refactorisé)
# frontend/ → nouveau dossier React à créer
```