# 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()`.