# Script d'Initialisation - Agent de Developpement

## Instructions pour un Agent IA de Developpement

Ce document constitue le **briefing complet** pour initialiser un agent de developpement (Claude, Cursor, Copilot, ou tout autre assistant IA) qui travaillera sur le projet Champion Spirit API.

---

## CONTEXTE DU PROJET

Tu travailles sur **Champion Spirit API**, une plateforme SaaS de gestion de centres de fitness/wellness/coworking. C'est une API REST Laravel qui alimente :
- Une **application mobile** Expo/React Native
- Un **panneau d'administration** Filament
- Un **chatbot IA** multi-provider
- Des **interfaces web** de booking et validation d'acces

---

## STACK TECHNIQUE

```
Framework       : Laravel 10.12.0
PHP             : 8.2+ (strict_types obligatoire)
Base de donnees : MySQL (utf8mb4_bin)
Auth            : Laravel Sanctum (Bearer tokens)
Admin           : Filament 2.x
Tests           : Pest 2.6
Analyse statique: PHPStan niveau 7 (Larastan)
Linting         : Laravel Pint (preset Laravel)
CI/CD           : GitHub Actions (tests + quality)
Monitoring      : Sentry
Queue           : sync (dev) / redis (prod)
Stockage        : MinIO (dev) / S3 Scaleway (prod)
Temps reel      : Pusher
```

---

## REGLES ABSOLUES

### 1. Pre-Commit Obligatoire

**AVANT TOUT COMMIT**, tu DOIS executer :

```bash
./gitCheck.sh
```

Ce script lance :
- `composer lint` — Verification du style de code (Laravel Pint)
- `composer types` — Analyse statique PHPStan niveau 7

**Si l'un de ces checks echoue, NE PAS commiter.** Corriger les erreurs d'abord.

### 2. Strict Types

**CHAQUE fichier PHP** doit commencer par :

```php
<?php

declare(strict_types=1);
```

### 3. Public ID

**JAMAIS exposer l'ID auto-increment** dans l'API. Toujours utiliser `public_id` (UUID).

Dans les Resources API :
```php
'id' => $this->public_id,  // CORRECT
'id' => $this->id,          // INTERDIT
```

### 4. Classes Final

Par defaut, toutes les classes sont `final` sauf si l'heritage est explicitement necessaire.

### 5. Conventional Commits

Les messages de commit suivent le format :

```
type(scope): description

Types: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
```

### 6. Documentation Swagger Obligatoire

**Chaque nouveau controleur API** DOIT avoir des annotations OpenAPI `@OA\` :
- `@OA\Get/Post/Put/Delete` sur la methode `__invoke`
- `@OA\Parameter` pour chaque parametre (path, query)
- `@OA\RequestBody` pour les POST/PUT
- `@OA\Response` pour chaque code HTTP possible
- `@OA\Schema` sur les Resources et Modeles exposes

Apres ajout d'endpoints : `php artisan l5-swagger:generate`

### 7. Tests Obligatoires

**Chaque nouvelle fonctionnalite DOIT avoir des tests Pest :**
- Nouveau controleur API → `tests/Feature/Controllers/{Domaine}/`
- Nouvelle Action → `tests/Feature/Actions/{Domaine}/`
- Nouveau Listener/Observer → `tests/Feature/Listeners/` ou `tests/Feature/Observers/`
- Nouvelle Resource Filament → `tests/Feature/Filament/`
- Nouvel Enum/Trait → `tests/Unit/`

### 8. Traductions

**Chaque champ texte user-facing** sur un modele DOIT etre traduisible :
- Ajouter le trait `HasDatabaseTranslations` au modele
- Declarer les champs dans `protected array $translatable = ['name', ...]`
- Utiliser `HasTranslatableFields` dans le formulaire Filament
- Apres modification de traductions : `php artisan translations:clear-cache`

### 9. PHPDoc Systematique

- **`@throws`** pour chaque exception possible dans les Actions/Services
- **`@param Collection<int, Model>`** pour les collections generiques
- **`@property-read`** pour les relations Eloquent sur les modeles
- **`@mixin Model`** sur les Resources API

---

## DEUX SYSTEMES SEPARES : API REST vs FILAMENT ADMIN

Le projet a **deux couches de presentation completement independantes** :

```
+-------------------+     +--------------------+
|   APP MOBILE      |     |   BACK-OFFICE      |
|   (React Native)  |     |   (Navigateur)     |
+--------+----------+     +--------+-----------+
         |                          |
    Sanctum Token             Session Web
         |                          |
+--------v----------+     +--------v-----------+
|   API REST        |     |   FILAMENT ADMIN   |
|   Controllers/Api |     |   Resources/Pages  |
+--------+----------+     +--------+-----------+
         |                          |
         +----------+  +-----------+
                    |  |
              +-----v--v------+
              |   COUCHE      |
              |   PARTAGEE    |
              |   Models      |
              |   Actions     |
              |   Services    |
              |   Observers   |
              +---------------+
```

| Aspect | API REST | Filament Admin |
|--------|----------|----------------|
| **Cible** | App mobile, chatbot, frontend | Back-office employes |
| **Auth** | Sanctum Bearer tokens | Session web |
| **Utilisateurs** | Customers, Coaches, Employees | Employees uniquement (avec roles) |
| **URL** | `/v1/*` | `/admin/*` |
| **Code** | `app/Http/Controllers/Api/` | `app/Filament/Resources/` |
| **Format** | JSON | HTML (Livewire) |

**Ne PAS confondre** les deux. Si tu travailles sur une fonctionnalite, demande-toi :
- C'est pour l'**app mobile / les clients** ? -> API REST (Controller + Resource)
- C'est pour le **back-office / les admins** ? -> Filament (Resource + RelationManager)
- C'est de la **logique metier partagee** ? -> Action ou Service (reutilise par les deux)

---

## ARCHITECTURE DU CODE

### Ou placer ton code

| Type de code | Emplacement | Convention de nommage |
|-------------|-------------|----------------------|
| **--- API REST ---** | | |
| Controleur API | `app/Http/Controllers/Api/{Domaine}/` | `{Verbe}{Sujet}Controller.php` |
| Controleur Chatbot | `app/Http/Controllers/Chatbot/{Role}/` | `{Verbe}{Sujet}Controller.php` |
| Action metier | `app/Actions/{Domaine}/` | `{Verbe}{Sujet}Action.php` |
| Service | `app/Services/{Domaine}/` | `{Domaine}Service.php` |
| Modele | `app/Models/` | `{Entite}.php` |
| Enum | `app/Enums/` | `{Nom}.php` |
| Event | `app/Events/` | `{Nom}.php` |
| Listener | `app/Listeners/` | `{Verbe}{Sujet}.php` |
| Observer | `app/Observers/` | `{Model}Observer.php` |
| Job | `app/Jobs/` | `{Verbe}{Sujet}Job.php` |
| Notification | `app/Notifications/` | `{Role}{Action}Notification.php` |
| Form Request | `app/Http/Requests/` | `{Action}{Sujet}Request.php` |
| Resource API | `app/Http/Resources/` | `{Model}Resource.php` |
| **--- FILAMENT ADMIN ---** | | |
| Resource Filament (CRUD) | `app/Filament/Resources/` | `{Model}Resource.php` |
| Page Filament | `app/Filament/Pages/` | `{Nom}Page.php` |
| Widget Filament | `app/Filament/Widgets/` | `{Nom}Widget.php` |
| Relation Manager | `app/Filament/Resources/{Resource}/RelationManagers/` | `{Relation}RelationManager.php` |
| Composant Filament | `app/Filament/Components/` | `{Nom}Fieldset.php` |
| **--- COUCHE PARTAGEE ---** | | |
| Builder | `app/Builders/` | `{Model}Builder.php` |
| DTO | `app/Data/` | `{Nom}Data.php` |
| Exception | `app/Exceptions/` | `{ProblemeExplicite}Exception.php` |
| Middleware | `app/Http/Middleware/` | `{Action}Middleware.php` |
| Policy | `app/Policies/` | `{Model}Policy.php` |
| Migration | `database/migrations/` | Timestamp + description snake_case |
| Factory | `database/factories/` | `{Model}Factory.php` |
| Seeder | `database/seeders/` | `{Nom}Seeder.php` |
| Test | `tests/Feature/` ou `tests/Unit/` | `{Description}Test.php` |

### Pattern de flux

```
Route -> Middleware -> Controller -> FormRequest (validation)
                          |
                          v
                    Action/Service (logique metier)
                          |
                          v
                    Model (persistence)
                          |
                          v
                    Observer (side effects)
                          |
                          v
                    Event -> Listener (workflow async)
                          |
                          v
                    Resource (transformation JSON)
```

### Quand creer quoi

| Situation | Creer |
|-----------|-------|
| Nouvel endpoint API | Controller + FormRequest + Resource + Route + Test |
| Nouvelle logique metier transactionnelle | Action (dans app/Actions/) |
| Integration avec un service externe | Service (dans app/Services/) |
| Side effect automatique apres CRUD Eloquent | Observer |
| Workflow declenche par un evenement | Event + Listener |
| Traitement en arriere-plan | Job |
| Communication vers l'utilisateur | Notification |
| Requete complexe reutilisable | Builder (dans app/Builders/) |
| Nouvelle constante metier | Enum PHP 8.1+ |
| Nouveau champ sur un modele | Migration + mise a jour $fillable + $casts |

---

## MODELES EXISTANTS PRINCIPAUX

Avant de creer un nouveau modele, verifie qu'il n'existe pas deja :

| Modele | Description | Relations cles |
|--------|-------------|----------------|
| `User` | Utilisateur (customer/coach/employee) | Coach, Employee, Wallet, Orders, Bookings |
| `Coach` | Profil coach | User, Places, Categories, PersonalCourses |
| `Employee` | Profil employe | User, Places |
| `Place` | Centre (gym, spa, coworking) | Services, Activities, Coaches, Categories |
| `Booking` | Reservation | Bookable (morph), Coach, Place, User |
| `Order` | Commande | User, Place, OrderItems |
| `OrderItem` | Ligne de commande | Order, Orderable (morph) |
| `Wallet` | Portefeuille credits | User ou Family |
| `WalletTransaction` | Transaction wallet | Wallet |
| `Membership` | Abonnement | User, Family, Place |
| `Service` | Service reservable | Category, Place |
| `Activity` | Activite reservable | Category, Place |
| `PersonalCourse` | Cours individuel | Coach, Category, Place |
| `GroupCourse` | Cours collectif | Coaches, Category, Place |
| `Event` | Evenement | Coaches, Category, Place |
| `Pack` | Forfait (credits, daypass, etc.) | Place |
| `Guest` | Invite | Users, Places |
| `Kid` | Enfant | User, Family |
| `Category` | Categorie | Parent (self), Place |
| `Department` | Departement | Place |

---

## POLYMORPHISME

Le systeme utilise intensivement les relations polymorphiques :

**Bookable** (ce qui peut etre reserve) :
`PersonalCourse`, `WellnessCourse`, `GroupCourse`, `Service`, `Activity`, `Event`, `Place`

**Orderable** (ce qui peut etre commande) :
Tous les Bookable + `Pack`, `FlexMembership`, `Product`

Les morph maps sont dans `AppServiceProvider::boot()`.

---

## SYSTEME MONETAIRE

Les prix utilisent le pattern Money (brick/money) :
- En migration : `{field}_amount` (bigint) + `{field}_currency` (string 3)
- En modele : Cast `AsMoney`
- En code : Objet `Brick\Money\Money`

**3 niveaux de prix** sur les cours/services :
1. `price` — Prix standard
2. `member_price` — Prix membre
3. `resort_money_price` — Prix en credits resort

---

## SYSTEME DE WALLET

```
Credit  = Unite de valeur interne
Daypass = Acces journee
Guest Pass = Acces invite

Wallet.balance        -> Solde credits (float)
Wallet.balance_daypass -> Solde daypasses (int)
Wallet.balance_guest_pass -> Solde guest passes (int)
```

Chaque operation cree un `WalletTransaction`.

---

## FLUX DE PAIEMENT

```
1. POST /v1/orders          -> Cree/modifie la commande (UpsertOrderAction)
2. POST /v1/orders/{id}/stripe-pay  -> Cree une session Stripe
3. Stripe Webhook            -> Confirme le paiement
4. OrderPaid event           -> Declenche les listeners :
   - CreateBookingWhenOrderConfirmed
   - CreditWalletWhenPackOrderConfirmed
   - FulfillFlexMembershipWhenOrderPaid
```

---

## NOTIFICATIONS

**Canaux disponibles :**
- `sendinblue_email` — Emails via Sendinblue (templates)
- `expo` — Push notifications mobiles (Expo)
- `database` — Notifications in-app

**Convention :** `{Role}{Action}Notification.php` (ex: `CustomerNewBookingNotification`)

---

## TRADUCTIONS

**4 langues supportees :** en, es, fr, zh

**2 systemes de traduction :**
1. **Fichiers JSON** (`storage/languages/`) — Pour l'app mobile et le back-office
2. **Base de donnees** (`model_translations`) — Pour les champs de modeles (via trait `HasDatabaseTranslations`)

---

## COMMANDES UTILES

```bash
# Lint (verification style)
composer lint

# Lint (correction automatique)
composer lint

# Analyse statique
composer types

# Tests
composer test

# Pre-commit (OBLIGATOIRE)
./gitCheck.sh

# Rechargement caches
./reloadChanges.sh

# Permissions fichiers
./setPermissions.sh

# Migration
php artisan migrate

# Seeding
php artisan db:seed

# Regenerer Swagger
php artisan l5-swagger:generate

# Vider tous les caches
php artisan cache:clear && php artisan config:clear && php artisan route:clear && php artisan view:clear
```

---

## CHECKLIST AVANT COMMIT

- [ ] `./gitCheck.sh` passe sans erreur
- [ ] `declare(strict_types=1)` dans chaque fichier PHP
- [ ] Pas de `dd()`, `dump()`, `var_dump()` dans le code
- [ ] Classes `final` par defaut
- [ ] `public_id` utilise dans l'API (jamais `id`)
- [ ] Relations typees avec type de retour explicite
- [ ] `$fillable` explicite (pas de `$guarded = []`)
- [ ] Casts declares pour les champs non-string
- [ ] Tests ajoutes pour les nouvelles fonctionnalites
- [ ] Migration reversible (methode `down()`)
- [ ] Pas de credentials en dur
- [ ] Message de commit en Conventional Commits

---

## CHECKLIST AVANT PULL REQUEST

- [ ] Tout ce qui est dans la checklist pre-commit
- [ ] Branch a jour avec `develop`
- [ ] Tous les tests passent (`composer test`)
- [ ] Pas de conflits de merge
- [ ] Description PR claire avec contexte
- [ ] Screenshots si changement UI (admin Filament)

---

## FICHIERS A NE JAMAIS MODIFIER SANS RAISON

| Fichier | Raison |
|---------|--------|
| `composer.lock` | Genere automatiquement |
| `package-lock.json` / `yarn.lock` | Genere automatiquement |
| `phpstan-baseline.neon` | Modifier uniquement avec `--generate-baseline` |
| `storage/packages/` | Packages locaux geres separement |
| `.env` | Specifique a l'environnement |
| `public/build/` | Genere par Vite |
| `storage/api-docs/` | Genere par l5-swagger |

---

## ERREURS COURANTES A EVITER

| Erreur | Solution |
|--------|----------|
| Exposer `$model->id` dans l'API | Utiliser `$model->public_id` |
| Oublier `strict_types` | Ajouter en premiere ligne |
| Classe non `final` | Ajouter `final` sauf heritage explicite |
| `$guarded = []` | Utiliser `$fillable` explicite |
| Logique metier dans le controleur | Extraire dans une Action ou Service |
| Side effect dans un controleur | Utiliser un Observer ou Listener |
| Dates sans timezone | Utiliser `immutable_datetime` cast + BaseModel UTC |
| Query complexe dans le controleur | Creer un Builder personnalise |
| Test sans assertion | Toujours verifier le resultat |
| Migration sans `down()` | Toujours fournir le rollback |
| Commiter sans `./gitCheck.sh` | Le hook Husky devrait l'empecher |

---

## DOCUMENTATION DE REFERENCE

Pour plus de details, consulter les fichiers suivants dans `docs/` :

| Document | Contenu |
|----------|---------|
| [README.md](README.md) | Vue d'ensemble et demarrage rapide |
| [ARCHITECTURE.md](ARCHITECTURE.md) | Structure des dossiers et patterns |
| [MODELS_DATABASE.md](MODELS_DATABASE.md) | Tous les modeles et le schema BDD |
| [API_ROUTES.md](API_ROUTES.md) | Tous les endpoints API REST |
| [FILAMENT_ADMIN.md](FILAMENT_ADMIN.md) | Panneau admin Filament (Resources, Pages, Widgets, Policies) |
| [BUSINESS_LOGIC.md](BUSINESS_LOGIC.md) | Services, Actions, Jobs, Events |
| [CONFIGURATION.md](CONFIGURATION.md) | Config, CI/CD, scripts DevOps |
| [CODING_STANDARDS.md](CODING_STANDARDS.md) | Conventions de code detaillees |

---

## PROMPT D'INITIALISATION RAPIDE

Copier-coller ce prompt pour initialiser rapidement un agent :

```
Tu es un developpeur senior travaillant sur Champion Spirit API, une plateforme Laravel 10 / PHP 8.2 de gestion de centres de fitness/wellness.

Regles critiques :
1. TOUJOURS executer ./gitCheck.sh avant de commiter (lint Pint + PHPStan niveau 7)
2. declare(strict_types=1) dans chaque fichier PHP
3. Classes final par defaut
4. Utiliser public_id (UUID) dans l'API, jamais l'ID auto-increment
5. Pattern : Controller -> Action/Service -> Model -> Observer -> Event/Listener
6. Champs monetaires : {field}_amount + {field}_currency avec cast AsMoney
7. Tests Pest OBLIGATOIRES pour chaque nouvelle fonctionnalite
8. Documentation Swagger @OA\ OBLIGATOIRE sur chaque controleur/resource API
9. Traductions : champs texte user-facing doivent utiliser HasDatabaseTranslations
10. PHPDoc : @throws sur les Actions, @property-read sur les modeles, @mixin sur les Resources
11. Notifications via Sendinblue (email) et Expo (push)
12. Conventional Commits pour les messages
13. Timezone : UTC en BDD, timezone du Place pour les queries temporelles
14. Pagination : page + size, format reponse data/totalItems/totalPages
15. Deux systemes separes : API REST (app mobile) vs Filament (back-office admin)

Lire docs/ pour la documentation complete du projet.
```