# Phase 3 — Clients et fournisseurs

## Installation

Après l’installation de la Phase 2, importer dans la même base :

`database/migrations/202608050001_phase3_third_parties.sql`

La migration est idempotente pour la création des tables, permissions, catégories et séquences initiales. Sauvegarder la base avant toute migration de production.

## Modèle de données

Le modèle commun évite de maintenir deux copies divergentes :

- `numbering_sequences` : préfixe, longueur et prochain numéro par société/type ;
- `third_parties` : clients et fournisseurs, différenciés par `party_type` ;
- `third_party_categories` : catégories typées ;
- `third_party_addresses` : adresses multiples ;
- `third_party_contacts` : contacts multiples ;
- `third_party_notes` : notes avec visibilité ;
- `third_party_documents` : fichiers privés et empreintes SHA-256 ;
- `third_party_history` : historique métier append-only.

Les futurs documents commerciaux référenceront `third_parties.id`. Aucun solde n’est stocké : il sera calculé depuis factures, avoirs et paiements.

## Permissions ajoutées

Pour `customers` et `suppliers` : `view`, `create`, `update`, `archive`, `export`, `import`, `view_financial`, `manage_documents`, `manage_notes`. Le rôle Administrateur reçoit automatiquement tous les droits. Les rôles existants doivent être ajustés depuis la matrice selon l’organisation.

## Données initiales minimales

- séquences `CLI-000001` et `FOUR-000001` ;
- six catégories client ;
- cinq catégories fournisseur ;
- aucun client ou fournisseur fictif n’est inséré.

## Recette manuelle

1. Importer la migration et se connecter comme administrateur.
2. Créer un client particulier avec nom, puis une entreprise avec raison sociale.
3. Vérifier les codes consécutifs et tenter un ICE/e-mail/téléphone déjà utilisé.
4. Modifier, désactiver, réactiver puis archiver une fiche.
5. Tester recherche, type, catégorie, ville, statut, commercial, date, tri et pagination.
6. Ajouter/modifier une adresse et un contact ; définir les valeurs principales.
7. Ajouter des notes avec les trois visibilités et contrôler leur lecture avec des rôles différents.
8. Téléverser un PDF autorisé, puis tenter un script ou un fichier de plus de 2 Mo.
9. Télécharger le document depuis la route protégée.
10. Télécharger le modèle CSV, prévisualiser un fichier valide/invalide, puis confirmer un import sans erreur.
11. Exporter avec filtres en CSV, Excel et PDF, puis utiliser l’impression navigateur.
12. Répéter ces scénarios pour un fournisseur.
13. Vérifier le journal global et l’onglet Historique.
14. Tester un rôle lecture seule et un compte sans permission par accès direct aux URL.
15. Soumettre une opération POST avec un jeton CSRF invalide et attendre HTTP 419.

## Tests automatisés exécutés pendant la livraison

Une MariaDB 10.4 isolée et temporaire a été initialisée puis supprimée après recette. Résultats :

- import du socle et de la migration : réussi, 17 tables ;
- connexion et changement obligatoire du mot de passe : réussis ;
- particulier `CLI-000001`, entreprise `CLI-000002`, fournisseur `FOUR-000001` : réussis ;
- ajout adresse, contact et note : réussi ;
- exports CSV, Excel et PDF : types de contenu corrects ;
- CSRF invalide : HTTP 419 ;
- rôle lecture seule : liste HTTP 200, création HTTP 403 ;
- utilisateur sans accès : liste et création HTTP 403 ;
- lint PHP 8.2 : réussi.

## Limites restantes

- Les onglets commerciaux affichent volontairement un état vide jusqu’aux phases Produits, Devis, Commandes, Stock, Factures, Paiements et Achats.
- Les relevés affichent zéro sans écriture manuelle ; les calculs réels dépendront des futurs documents.
- L’export Excel est un tableau HTML compatible Excel (`.xls`), pas un classeur OpenXML `.xlsx`.
- Le PDF est volontairement sobre et limité à une page ; une bibliothèque PDF dédiée pourra enrichir les éditions commerciales futures.
- Aucun e-mail automatique n’est envoyé lors d’un import ou d’une modification.