first commit

docs/DEVELOPMENT.md

@@ -0,0 +1,95 @@
+# Développement
+
+Ce document sert de guide quotidien pour travailler sur `netslim-core`.
+
+## Démarrage local
+
+Prérequis : PHP 8.4+, Composer, extensions `pdo`, `pdo_sqlite`, `fileinfo`, `gd`, `json`, `mbstring`, `session`, `dom`, `simplexml`.
+
+```bash
+composer install
+composer qa
+```
+
+## Ce que contient le dépôt
+
+- `Kernel/` : runtime, HTTP, persistence, mail, html, pagination, support
+- `Identity/` : authentification, utilisateurs et autorisation transverse
+- `Settings/` : paramètres applicatifs typés
+- `AuditLog/` : journal d'audit partagé
+- `Notifications/` : notifications et emails transactionnels
+- `Taxonomy/` : taxons réutilisables
+- `Media/` : médiathèque transverse
+
+Le dépôt ne contient pas d'application concrète : c'est le socle partagé.
+Une application consommatrice fournit son propre `config/modules.php`, son point d'entrée HTTP, ses templates applicatifs et ses assets.
+Les répertoires runtime (`var/`, `database/`, `public/media/`) appartiennent toujours au projet consommateur, même quand le core est installé sous `vendor/`.
+
+## Où placer une modification ?
+
+### Backend
+
+- `Domain/` : entités, règles métier, contrats métier
+- `Application/` : cas d'usage, services applicatifs, commandes, ports
+- `Infrastructure/` : implémentations concrètes, PDO, stockage, mail, bindings DI
+- `UI/` : contrôleurs, request objects, templates, extensions Twig
+
+### Code transverse
+
+`Kernel/` reste limité au transverse et se découpe en sous-modules explicites : `Runtime/`, `Http/`, `Persistence/`, `Mail/`, `Html/`, `Pagination/` et `Support/`.
+En cas d'hésitation, commencer dans le domaine concerné puis extraire vers `Kernel` à la deuxième vraie réutilisation.
+
+### Checklist avant d'ajouter quelque chose dans `Kernel/Support`
+
+Valider les trois points suivants :
+
+- ce code sert déjà à au moins deux domaines ou représente une primitive transverse évidente ;
+- il ne dépend ni d'un domaine métier, ni de Slim, Twig, PSR-7 ou d'une implémentation d'infrastructure ;
+- la PR met à jour à la fois la documentation et l'allow list des tests d'architecture.
+
+## Faire évoluer un domaine existant
+
+Ordre recommandé :
+
+1. adapter le contrat ou l'interface de service si nécessaire ;
+2. décider si la modification reste une lecture simple ou mérite un `UseCase` + éventuelle `Command` ;
+3. faire évoluer le repository ou le port technique ;
+4. adapter le contrôleur et les vues sans court-circuiter le service applicatif ;
+5. mettre à jour les tests et la documentation utile.
+
+## Ajouter un nouveau domaine
+
+Créer systématiquement :
+
+1. l'entité et les contrats du domaine ;
+2. l'interface de service ;
+3. le repository interface ;
+4. l'implémentation `Infrastructure/` ;
+5. le contrôleur et les templates ;
+6. `Infrastructure/dependencies.php` ;
+7. `UI/Http/Routes.php` ;
+8. `<Domaine>Module.php` ;
+9. les tests dans `tests/<Domaine>/`.
+
+Pour les frontières et dépendances autorisées, se reporter à [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Vérifications avant push
+
+```bash
+composer test
+composer stan
+composer cs:check
+```
+
+Raccourci utile :
+
+```bash
+composer qa
+```
+
+
+## Variables d'environnement et provisionnement
+
+Le bootstrap du noyau requiert seulement l'environnement technique commun (comme `APP_URL`). Les variables `ADMIN_*` sont nécessaires quand une application active `Identity` et exécute le provisionnement initial du compte administrateur. Les variables `MAIL_*` deviennent nécessaires uniquement si l'application active `Notifications` et envoie réellement des emails transactionnels.
+
+> Quand `netslim-core` est installé via Composer, les chemins runtime détectent automatiquement la racine du projet consommateur pour les scripts CLI et les suites de tests qui n'appellent pas explicitement `Bootstrap::create()`.