# 1. Architecture du projet

## Style architectural

L’application adoptera un **MVC modulaire en couches** :

- la couche HTTP reçoit la requête, applique les middlewares et appelle un contrôleur ;
- le contrôleur orchestre un cas d’usage sans contenir les règles métier ;
- les services portent les transactions et règles métier ;
- les repositories isolent PDO et la persistance ;
- les modèles/entités représentent les données métier ;
- les vues produisent uniquement le HTML échappé.

Sens autorisé des dépendances : `public/routes → middleware → controllers → services → repositories → PDO`. Les vues reçoivent des données préparées par les contrôleurs. Une vue ne requête jamais la base.

## Arborescence cible

```text
gestioncomercialvv/
├── app/
│   ├── Controllers/
│   ├── Models/
│   ├── Repositories/
│   ├── Services/
│   ├── Validators/
│   ├── Policies/
│   ├── Middleware/
│   ├── DTO/
│   ├── Exceptions/
│   └── Support/
├── bootstrap/
├── config/
├── database/
│   ├── migrations/
│   ├── seeders/
│   └── fixtures/
├── docs/
├── helpers/
├── public/
│   ├── assets/
│   │   ├── css/
│   │   ├── js/
│   │   ├── img/
│   │   └── vendor/
│   ├── .htaccess
│   └── index.php
├── resources/
│   ├── views/
│   │   ├── layouts/
│   │   ├── components/
│   │   ├── errors/
│   │   └── modules/
│   ├── lang/
│   └── templates/
├── routes/
├── storage/
│   ├── cache/
│   ├── logs/
│   ├── sessions/
│   ├── exports/
│   └── uploads/
├── tests/
│   ├── Unit/
│   ├── Integration/
│   └── Feature/
├── tools/
├── .env.example
├── composer.json
└── README.md
```

## Rôle des dossiers

| Dossier | Responsabilité |
|---|---|
| `app/Controllers` | Adaptation HTTP, lecture de la requête, appel des services, choix de la réponse. |
| `app/Models` | Entités et objets métier simples, sans accès direct à PDO. |
| `app/Repositories` | Requêtes SQL préparées, hydratation et accès aux données. |
| `app/Services` | Cas d’usage, règles métier, transactions, numérotation et orchestration. |
| `app/Validators` | Validation structurée des commandes/formulaires et messages d’erreur. |
| `app/Policies` | Autorisations contextuelles : action, propriétaire, entrepôt, statut. |
| `app/Middleware` | Authentification, CSRF, permissions, limitation de débit, en-têtes HTTP. |
| `app/DTO` | Données validées échangées entre contrôleurs et services. |
| `app/Exceptions` | Exceptions métier, validation, conflit et accès interdit. |
| `app/Support` | Abstractions techniques : horloge, générateur d’identifiants, pagination. |
| `bootstrap` | Chargement de l’environnement, conteneur léger, gestion d’erreurs et démarrage. |
| `config` | Configuration PHP retournant des tableaux ; aucune donnée secrète versionnée. |
| `database/migrations` | Versions réversibles du schéma, créées lors de la phase de développement. |
| `database/seeders` | Données initiales contrôlées : permissions, pays, unités, statuts. |
| `database/fixtures` | Données de test uniquement. |
| `helpers` | Fonctions pures, rares et transversales : échappement, formatage, montants. |
| `public` | Seule racine Web ; contient le front controller et les ressources publiques. |
| `public/assets` | CSS, JavaScript, images et bibliothèques front publiques. |
| `resources/views` | Gabarits PHP, layouts, composants et écrans par module. |
| `resources/lang` | Traductions et libellés. |
| `resources/templates` | Modèles d’e-mail et documents imprimables. |
| `routes` | Déclarations des routes Web et, si nécessaire, JSON internes. |
| `storage` | Fichiers non publics, journaux, cache, exports et téléversements. |
| `tests` | Tests unitaires, intégration SQL et parcours HTTP. |
| `tools` | Scripts CLI d’installation, cron, maintenance et sauvegarde. |

## Déploiement cPanel

- La racine du domaine doit pointer vers `public/`. Si cPanel ne le permet pas, `public_html/` ne contient qu’un point d’entrée relais contrôlé et les assets ; les sources restent hors de `public_html`.
- Secrets dans `.env`, droits minimaux, `display_errors=Off` en production.
- `storage/` accessible en écriture par PHP mais interdit en HTTP.
- Les pièces jointes sont servies par un contrôleur après autorisation, jamais par URL directe devinable.
- Cron cPanel lance les rappels, sauvegardes, nettoyages et tâches différées via des commandes PHP CLI idempotentes.

## Composants transversaux prévus

- routeur et pipeline de middlewares ;
- conteneur de dépendances minimal ;
- gestionnaire d’erreurs central ;
- service de transactions ;
- service de numérotation ;
- stockage de fichiers privé ;
- génération PDF et exports ;
- notifications et tâches cron ;
- journal d’audit ;
- pagination, filtres et recherche ;
- configuration multi-société prête dès le schéma, même si la première version n’exploite qu’une société.