# Arcadia API

**Arcadia API** est une API de référence conçue selon les principes de la **Clean Architecture**, du **Domain-Driven Design (DDD)** et de l'**Architecture Hexagonale (Ports & Adapters)**.

---

## 📚 Documentation pour les Développeurs

L'ensemble de la documentation technique et des guides pratiques est organisé dans le dossier [`documentation/`](documentation/) :

### 🏛️ Architecture & Fonctionnement
- **[01 - Architecture Globale](documentation/Architecture/01-architecture-globale.md)** : Vue d'ensemble des couches (`Domain`, `Application`, `Presentation`, `Infra`, `Shared`), responsabilités et règles de dépendances strictes.
- **[02 - Cycle de Vie d'une Requête (Bullet Tracer)](documentation/Architecture/02-cycle-de-vie-requete.md)** : Traçage pas-à-pas d'une requête HTTP depuis la route jusqu'à la sérialisation JSON.
- **[03 - Exécution, Transactions & Événements](documentation/Architecture/03-execution-et-transactions.md)** : `UsecaseBuilder`, `LaravelExecutor`, exécution transactionnelle et dispatch sécurisé post-commit (`TransactionalDomainEventDispatcher`).
- **[04 - Guide Nouveau Cas d'Usage](documentation/Architecture/04-guide-nouveau-usecase.md)** : Checklist pas-à-pas pour créer une nouvelle fonctionnalité de bout en bout.
- **[05 - Temps, Horloge PSR-20 & Base de Données](documentation/Architecture/05-temps-et-base-de-donnees.md)** : Contrat PSR-20 `Clock`, Façade `Utc`, tests avec `FrozenClock`, standardisation `DATETIME` et dérivation `created_at` depuis UUIDv7.

### 📐 Conventions & Standards
- **[Conventions de Tests](documentation/Conventions/tests.md)** : Principes F.I.R.S.T., structure GWT, pyramide de tests, **Test Data Builders** et **Object Mothers**.
- **[Gestion des Exceptions](documentation/Conventions/exceptions.md)** : Matrice de correspondance entre exceptions applicatives/domaine et codes HTTP RFC 7807 (400, 404, 409, 422, 429, 500).

### 🗄️ Métamodèle & Intégration Oracle
- **[Métamodèle Arcadia & Intégration Oracle](documentation/Arcadia/README.md)** : Guide d'intégration, requêtes SQL de référence et pointage vers la documentation vivante (`database/arcadia-replicate/`).

---

## 🚀 Commandes Utiles

### Développement & Qualité de Code

```bash
# Lancer la suite de tests Pest
composer test

# Lancer l'analyse statique PHPStan (Niveau 10)
vendor/bin/phpstan analyse

# Vérifier le formattage du code PSR-12 (Pint)
vendor/bin/pint --test

# Verifier les conventions et regles de lint (PHP Code Sniffer)
vendor/bin/phpcs

# Corriger automatiquement les conventiosn (PHP Code Beautifier)
vendor/bin/phpcbf
```

### Gestion de l'Application Arcadia


```bash
# Vérifier l'état de l'application
php artisan health

# List all Arcadia brands
php artisan arcadia:brand:list

# List all Arcadia clients
php artisan arcadia:client:list

# Create a new Arcadia client (interactive wizard)
php artisan arcadia:client:create

# Regenerate the secret of an API client
php artisan arcadia:client:regenerate-secret

# Toggle the status of an API client
php artisan arcadia:client:toggle-status

# Check schema and query conformity of the replicated Arcadia Oracle database
php artisan arcadia:database:check-conformity

# Display or export security audit events since a specified date
php artisan arcadia:security:audit-logs

```