# ICAVI Gestion — installation locale

## 1. Prérequis

Le projet est basé sur Laravel 11.54.0 et demande PHP 8.2 ou supérieur. Pour un environnement fonctionnel, activez au minimum `ctype`, `cURL`, `DOM`, `Fileinfo`, `Filter`, `Hash`, `mbstring`, `OpenSSL`, `PCRE`, `PDO`, `PDO MySQL`, `Session`, `Tokenizer` et `XML`.

Le dépôt ne contient pas de `package.json` : l'interface livrée utilise les assets statiques déjà présents. Node/NPM ne sont donc pas nécessaires pour le démarrage de cette version.

Vérification :

```bash
php -v
php -m
composer --version
```

## 2. Installer le projet

Depuis le dossier racine :

```bash
composer install
cp .env.example .env
php artisan key:generate
php artisan storage:link
```

Sous Windows PowerShell, remplacez le `cp` par :

```powershell
Copy-Item .env.example .env
```

Vous pouvez aussi utiliser `bash setup.sh` sous Linux/macOS/WSL. Le script ne lance volontairement aucune migration destructive.

## 3. Configurer `.env`

Renseignez la base existante :

```dotenv
APP_NAME="ICAVI Gestion"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=icaviss3
DB_USERNAME=votre_utilisateur
DB_PASSWORD=votre_mot_de_passe
```

Ne committez jamais `.env`.

## 4. Importer la base fournie

Le dump livré est : `database/import/icaviss3.sql`.

Créez une base vide si vous installez un environnement neuf, puis importez le dump :

```bash
mysql -u votre_utilisateur -p -h 127.0.0.1 -P 3306 icaviss3 < database/import/icaviss3.sql
```

Avec phpMyAdmin, créez/sélectionnez la base puis importez ce fichier SQL.

**Attention :** le dump contient des données métier. Ne l'importez pas par-dessus une base de production sans sauvegarde et procédure de restauration.

## 5. Appliquer les migrations du merge

Le dump SQL contient le schéma historique. Le merge ajoute les migrations suivantes :

- `permissions`, `permission_sequences`, `permission_historique` ;
- `users.is_directeur` ;
- `documents` : `EN_COURS`, `LIVRE`, `NON_LIVRE` en plus des statuts historiques ;
- `cash_voucher_sequences`, `cash_vouchers`, `cash_voucher_payments`, `cash_voucher_events` ;
- `notifications` ;
- champs supplémentaires du workflow de restitution caisse.

Après configuration DB :

```bash
php artisan migrate:status
php artisan migrate --force
```

Sur une base contenant déjà les données du dump, utilisez `migrate`, pas `migrate:fresh`.

Pour un environnement de test sans données à conserver, vous pouvez repartir de zéro avec :

```bash
php artisan migrate:fresh --seed --force
```

## 6. Lancer l'application

```bash
php artisan serve
```

Ouvrez `http://127.0.0.1:8000`.

Le serveur web doit servir le dossier `public/`, pas la racine du projet.

## 7. Compte et permissions

Le merge ajoute un attribut explicite `users.is_directeur`. La décision d'une demande de permission est contrôlée côté serveur par ce drapeau ; le simple rôle `admin` ne suffit pas.

La gestion des comptes reste protégée : un administrateur non-super-admin ne peut ni gérer ni promouvoir un compte `super_admin`.

Lors d'une nouvelle installation sans dump, vérifiez vos seeders avant de diffuser les identifiants générés. Ne réutilisez pas un mot de passe d'exemple en production.

## 8. Vérifications après installation

```bash
php artisan route:list
php artisan migrate:status
php artisan storage:link
```

Contrôler ensuite manuellement : connexion, clients, produits, ventes, documents, GED, permissions, bons de sortie de caisse.

Pour un diagnostic applicatif :

```bash
tail -f storage/logs/laravel.log
```

Sous PowerShell :

```powershell
Get-Content storage/logs/laravel.log -Wait
```

## 9. Tests de sécurité fonctionnelle à faire localement

1. Créer une permission avec un utilisateur standard : la demande doit être créée.
2. Tenter d'approuver avec un utilisateur non marqué `is_directeur` : le serveur doit refuser l'action.
3. Marquer un utilisateur `is_directeur` depuis un Super Admin : ce compte peut ensuite décider.
4. Vérifier qu'un compte non-Super Admin ne peut pas éditer un Super Admin par URL directe.
5. Vérifier qu'un document `LIVRE`, `FACTURE`, `VALIDE` ou `ANNULE` ne peut plus être modifié comme un brouillon.
6. Vérifier la génération et l'archivage d'un bon de sortie de caisse.

## 10. Points connus de l'environnement de validation

Le conteneur utilisé pour l'audit ne disposait ni de l'extension `DOM` ni de `PDO MySQL`. Il n'était donc pas possible d'exécuter ici une migration réelle ou une compilation complète des Blade avec les composants qui utilisent `mbstring`. Cela ne signifie pas que le projet nécessite des contournements : cela signifie que l'environnement d'exécution doit être complété conformément aux prérequis Laravel.

## 11. PDF des bons de sortie de caisse

L'archivage PDF des bons de sortie utilise Chrome/Chromium en mode headless. Le serveur de développement doit donc disposer de Chrome ou Chromium, ou renseigner son chemin explicitement :

```dotenv
CASH_VOUCHER_CHROME_PATH=/chemin/vers/google-chrome
```

Sous Windows, utilisez le chemin réel de `chrome.exe`. Sur Linux/OVH, les chemins automatiquement recherchés par l'application sont `/usr/bin/google-chrome`, `/usr/bin/chromium` et `/usr/bin/chromium-browser`.

Ce composant est surtout nécessaire lorsque le bon passe au statut signé/payé et doit être archivé en GED.