# Architecture du Projet ## Vue d'ensemble Champion Spirit API suit une architecture **Laravel classique enrichie** avec des couches supplementaires (Actions, Services, Builders, Data) pour separer les responsabilites. Le projet est **API-first** : toutes les interactions client passent par des endpoints REST JSON. --- ## Arborescence des dossiers ``` championspirit-api/ | |-- app/ # Code applicatif principal | |-- Actions/ # Actions metier (logique transactionnelle) | | |-- Availability/ # Calcul et synchronisation des disponibilites | | |-- Booking/ # Creation, annulation, remboursement de reservations | | |-- Course/ # Determination de la disponibilite des cours | | |-- DoorAccess/ # Generation et purge des acces physiques | | |-- GuestInvitation/ # Liaison des invitations guest | | |-- Place/ # Operations specifiques aux lieux | | |-- User/ # Creation utilisateur, adhesion, achat de packs | | |-- ShopManager/ # Actions Shop Manager (stock, paiements POS/CASH, quick customer) | | |-- UpsertOrderAction.php | | | |-- BookingFactories/ # Factories pour creer des bookings par type | | | |-- Builders/ # Query Builders personnalises (extends Eloquent Builder) | | |-- PlaceBuilder.php | | |-- AvailabilityBuilder.php | | |-- BookingBuilder.php | | |-- OrderBuilder.php | | |-- UserBuilder.php | | |-- (+ 10 autres) | | | |-- Concerns/ # Traits partages (contracts/interfaces) | | |-- ShouldGenerateBlurHash.php | | |-- ShouldHaveOptions.php | | | |-- Console/ | | |-- Commands/ # 33+ commandes Artisan personnalisees | | |-- Kernel.php # Scheduler (cron jobs) | | | |-- Data/ # DTOs (Spatie Laravel Data) | | |-- ActivityData.php | | |-- OrderItemData.php | | |-- SlotData.php | | |-- SearchResultData.php | | |-- (+ autres) | | | |-- Enums/ # Enums PHP 8.1+ (31 fichiers) | | |-- Chat/ # Enums specifiques au chat | | |-- Traits/ # Traits utilitaires pour enums | | |-- OrderableType.php | | |-- OrderStatus.php | | |-- PaymentProvider.php | | |-- (+ 28 autres) | | | |-- Events/ # Evenements applicatifs | | |-- Chat/ # Typing, MessageSent, MessageDeleted, ReceiptUpdated | | |-- OrderPaid.php | | | |-- Exceptions/ # Exceptions metier (20 fichiers) | | | |-- Filament/ # Panneau d'administration | | |-- Auth/ # Login personnalise | | |-- Components/ # Composants reutilisables (AddressFieldset, etc.) | | |-- Concerns/ # Traits admin partages | | |-- Pages/ # Pages admin (Reports/, RolePermissions, etc.) | | |-- Policies/ # Politiques d'acces admin | | |-- Resources/ # 23+ ressources CRUD admin | | |-- Widgets/ # Widgets dashboard | | | |-- Http/ | | |-- Controllers/ | | | |-- Admin/Reports/ # Controleurs de rapports admin (legacy) | | | |-- Api/ # ~170 controleurs API organises par domaine | | | | |-- Account/ # Login, register, profil, notifications | | | | |-- Address/ # Recherche d'adresses (Google Geocoder) | | | | |-- Availability/# Listing et sync des disponibilites | | | | |-- Booking/ # Operations de reservation | | | | |-- Broadcasting/# Evenements temps reel | | | | |-- Category/ # Listing des categories | | | | |-- Chat/ # Messagerie, conversations, webhook IA | | | | |-- Coach/ # Endpoints coach | | | | |-- Device/ # Abonnements push notifications | | | | |-- Employee/ # Fonctionnalites employes (bookings, orders, tasks) | | | | | |-- ShopManager/ # 33 controleurs Shop Manager (produits, carts, paiements, dashboard) | | | | | | |-- Dashboard/ # 7 controleurs dashboard analytics (avec cache Redis) | | | | |-- Guest/ # Gestion des invites | | | | |-- Kid/ # Gestion des enfants | | | | |-- Orders/ # Commandes et paiements | | | | |-- Place/ # Informations sur les lieux | | | | |-- Product/ # Informations produits | | | | |-- Reports/ # Rapports | | | | |-- Tracking/ # Entrees de suivi | | | |-- Chatbot/ # Controleurs chatbot (Coach/, Customer/, Place/) | | | |-- Frontend/ # Interface web (booking, daypass, pre-arrival) | | | | | |-- Livewire/ # Composants Livewire (UI interactive admin) | | |-- Middleware/ # 20 middleware HTTP | | | |-- EnsureShopManagerMiddleware.php # Verifie role is_shop_manager + rattachement au lieu | | |-- Requests/ # Validation des requetes (Form Requests) | | | |-- ShopManager/ # 10 form requests Shop Manager (cart, paiement, stock, invoice) | | |-- Resources/ # Transformers API (JSON Resources) | | |-- Chat/ # Resources specifiques au chat | | |-- ShopManager/ # 8 resources Shop Manager (vendor product, cart, order, invoice) | | | |-- Interface/ # Interfaces/Contrats | | | |-- Jobs/ # Jobs en file d'attente (16 fichiers) | | |-- Quickbooks/ # 13 jobs de synchronisation QuickBooks | | | |-- Listeners/ # Ecouteurs d'evenements (7 fichiers) | | |-- Chat/ | | | |-- Models/ # Modeles Eloquent (54+ fichiers) | | |-- Casts/ # Casts personnalises | | |-- Chat/ # Modeles chat (Conversation, Message, etc.) | | |-- Concerns/ # Traits de modeles | | |-- Interfaces/ # Contrats modeles (Bookable, Orderable) | | |-- Quickbooks/ # Modeles QuickBooks | | |-- Scopes/ # Query Scopes globaux | | |-- Traits/ # Traits partages | | |-- BaseModel.php # Modele de base (ConvertDateTimeToUTC) | | | |-- Notifications/ # 39+ classes de notification | | |-- App/ # Notifications in-app / push | | | |-- Observers/ # 13 observers Eloquent | | | |-- OrderableConstraints/ # Contraintes pour items commandables | | | |-- Policies/ # Politiques d'autorisation | | | |-- Providers/ # 8 Service Providers | | | |-- Services/ # 34 fichiers de services metier | | |-- Access/ # Validation d'acces et portes | | |-- BioStar2/ # Integration systeme biometrique | | |-- Chat/ # Operations chat et IA | | | |-- Drivers/ # Drivers IA (BoldAI, OpenAI, Mistral, Claude) | | |-- GoogleGeocoder/ # Integration Google Maps | | |-- Presence/ # Tracking de presence | | |-- Quickbooks/ # Integration comptabilite QuickBooks | | |-- ShopManager/ # Services Shop Manager | | | |-- DashboardService.php # Utilitaires dashboard (periodes, sparklines, queries) | | | |-- DashboardCacheService.php # Cache Redis pre-compute + delta 5 min | | |-- Translate/ # Services de traduction | | |-- Providers/ # Providers traduction (Google, OpenAI) | | | |-- helpers.php # Fonctions helper globales | |-- bootstrap/ # Fichiers de demarrage Laravel | |-- config/ # 32 fichiers de configuration | |-- database/ | |-- migrations/ # 268 fichiers de migration | |-- seeders/ # 9 seeders | |-- factories/ # 22 factories | |-- public/ # Point d'entree web (index.php, assets) | |-- resources/ | |-- views/ # Templates Blade (admin, emails, frontend) | |-- css/ # Styles | |-- js/ # JavaScript | |-- routes/ | |-- api.php # Routes API v1 (~380 lignes) | |-- web.php # Routes web (admin, webhooks, frontend) | |-- chatbot.php # Routes chatbot IA | |-- channels.php # Canaux de broadcasting | |-- console.php # Commandes console | |-- storage/ | |-- languages/ # Fichiers de traduction JSON | | |-- back_office/ # Traductions back-office (en, es, fr, zh) | | |-- mobile_app/ # Traductions app mobile (en, es, fr, zh) | |-- translation_keys/ # Cles de traduction extraites | |-- packages/ # Packages locaux personnalises | | |-- yieldstudio/ | | |-- eloquent-public-id/ # Gestion UUID public | | |-- laravel-expo-notifier/ # Push notifications Expo | | |-- laravel-sendinblue-notifier/ # Email/SMS Sendinblue | |-- api-docs/ # Documentation Swagger generee | |-- tests/ | |-- Unit/ # Tests unitaires (Pest) | |-- Feature/ # Tests fonctionnels (Pest) | |-- .github/ | |-- workflows/ | | |-- tests.yml # Pipeline tests (Pest) | | |-- quality.yml # Pipeline qualite (Pint + PHPStan + Audit) | |-- actions/setup/ # Action reutilisable de setup PHP | |-- .husky/ # Git hooks (pre-commit, commit-msg) | |-- Scripts racine : | |-- gitCheck.sh # Pre-commit : lint + types | |-- gitMergeMain.sh # Promotion develop -> main | |-- reloadChanges.sh # Rechargement caches + swagger | |-- setPermissions.sh # Permissions fichiers | |-- exportSandboxSeed.sh # Export BDD sanitisee | |-- importSandboxSeed.sh # Import BDD sanitisee ``` --- ## Patterns Architecturaux ### 1. Action Pattern Les **Actions** encapsulent la logique metier transactionnelle. Chaque action a une responsabilite unique et est invokable (`__invoke`). ``` Controleur -> Action -> Modele(s) |-> Event (optionnel) |-> Notification (optionnel) ``` **Convention :** `{Verbe}{Sujet}Action.php` (ex: `CreateAttendeeBookingAction`, `RefundAttendeeBookingAction`) **Quand utiliser une Action :** - La logique implique plusieurs modeles - Il y a des effets de bord (notifications, events, wallet) - La logique est transactionnelle (DB::transaction) - La logique est reutilisee dans plusieurs controleurs ### 2. Service Pattern Les **Services** encapsulent la logique metier non-transactionnelle ou les integrations externes. ``` Controleur/Action/Job -> Service -> API externe / calcul complexe ``` **Convention :** `{Domaine}Service.php` (ex: `AccessValidationService`, `QuickbooksService`) **Quand utiliser un Service :** - Integration avec une API externe (Stripe, QuickBooks, BioStar2) - Logique de calcul complexe sans effet de bord - Abstraction d'un systeme externe ### 3. Builder Pattern (Query Builders) Les **Builders** etendent `Illuminate\Database\Eloquent\Builder` pour encapsuler les requetes complexes. ```php // Dans le modele : public function newEloquentBuilder($query): PlaceBuilder { return new PlaceBuilder($query); } // Usage : Place::query()->withAvailableServices()->nearLocation($lat, $lng); ``` **Convention :** `{Model}Builder.php` ### 4. Observer Pattern Les **Observers** reagissent aux evenements du cycle de vie Eloquent (created, updated, deleted). ``` Modele::create() -> Observer::created() -> Side effects (door access, QuickBooks sync, notifications) ``` **Convention :** `{Model}Observer.php`, enregistre dans `EventServiceProvider` ### 5. Event-Driven Architecture Le flux principal de paiement utilise des evenements : ``` Order paye -> OrderPaid event |-> CreateBookingWhenOrderConfirmed (listener) |-> CreditWalletWhenPackOrderConfirmed (listener) |-> FulfillFlexMembershipWhenOrderPaid (listener) |-> UpdateWalletWhenStripeOrderConfirmed (listener) ``` ### 6. Multi-Provider Pattern (Strategy) Plusieurs systemes supportent des backends interchangeables : - **IA Chat** : BoldAI, OpenAI, Mistral, Claude, SelfHosted (via `AiDriverInterface`) - **Traduction** : Google Translate, OpenAI (via `TranslationProviderInterface`) - **Paiement** : Stripe, Wallet, NowPayments (crypto), POS, CASH (Shop Manager) ### 7. Polymorphisme Eloquent Le systeme utilise intensivement les relations polymorphiques : - **Bookable** : PersonalCourse, GroupCourse, WellnessCourse, Activity, Event, Service, Place - **Orderable** : Pack, FlexMembership, Activity, Event, PersonalCourse, GroupCourse, Service, WellnessCourse, Product Les morph maps sont definies dans `AppServiceProvider::boot()`. --- ## Flux de Donnees Principaux ### Flux de Reservation (Booking) ``` 1. Client consulte les disponibilites GET /v1/places/{place}/availabilities/{type} 2. Client cree une commande POST /v1/orders (items = cours/service/activite) 3. Client paie la commande POST /v1/orders/{order}/stripe-pay (ou /wallet-pay ou /nowpayments-pay) 4. Webhook Stripe confirme le paiement POST /webhooks/stripe -> OrderPaid event 5. Listeners creent les bookings et creditent le wallet CreateBookingWhenOrderConfirmed CreditWalletWhenPackOrderConfirmed 6. Observer genere les acces physiques BookingObserver::created() -> GenerateUserAccessAction 7. Notifications envoyees (push + email) CustomerNewBookingNotification CoachNewBookingNotification ``` ### Flux d'Acces (Door Access) ``` 1. Booking cree -> BookingObserver genere un QR code 2. BioStar2Service cree/met a jour l'acces physique 3. Client scanne le QR code a l'entree 4. AccessValidationService valide le pass 5. PlaceAccessLog enregistre l'acces ``` ### Flux QuickBooks (Comptabilite) ``` 1. Evenement Eloquent (User/Order/WalletTransaction cree/modifie) 2. Observer dispatche un Job QuickBooks 3. Job execute via QuickbooksService avec : - Circuit Breaker (5 echecs = pause 5 min) - Rate Limiter (500 req/min) - Queue dediee (quickbooks, quickbooks-wallet, etc.) 4. QuickbooksClient gere OAuth2 refresh + retry ``` ### Flux Shop Manager (Vente POS/CASH) ``` 1. Shop Manager cree un cart pour un client POST /v1/places/{place}/shop/carts 2. Ajoute des produits au cart POST /v1/places/{place}/shop/carts/{order}/items 3. Processe le paiement (POS, CASH, Wallet, Stripe, Crypto) POST /v1/places/{place}/shop/carts/{order}/pay/{provider} 4. ProcessPosPaymentAction / ProcessCashPaymentAction : - Valide les metadata (montants, photo receipt) - Cree la WalletTransaction (POS -> CREDIT_CARD, CASH -> CASH) - Met a jour Order.status = PAID - Declenche OrderPaid event 5. OrderPaid listeners : - Decrement stock (soft failure si race condition -> auto-refund wallet) - Generation invoice (queued job) 6. Dashboard widgets mis a jour via cache delta (TTL 5 min) Cache pre-compute a minuit via `shop:dashboard:warm-cache` ``` --- ## Statistiques du Projet | Element | Nombre | |---------|--------| | Modeles Eloquent | 54+ | | Controleurs | 200+ | | Migrations | 268 | | Commandes Artisan | 33+ | | Notifications | 39+ | | Jobs | 16 | | Observers | 13 | | Enums | 31 | | Exceptions metier | 20 | | Resources Filament | 23 | | Factories | 22 | | Seeders | 9 | | Fichiers de config | 32 |