# Champion Spirit API - Documentation Technique Exhaustive

## Presentation du Projet

**Champion Spirit** est une plateforme SaaS de gestion de centres de fitness, wellness et coworking. L'API REST constitue le backend principal, alimentant une application mobile (Expo/React Native), un panneau d'administration (Filament), un chatbot IA, et des interfaces web de booking.

**Stack technique :**
- **Framework :** Laravel 10.12.0
- **PHP :** 8.2+
- **Base de donnees :** MySQL (utf8mb4_bin)
- **File d'attente :** Sync (dev) / Redis (prod)
- **Cache :** File (dev) / Redis (prod)
- **Stockage fichiers :** MinIO (dev) / AWS S3 Scaleway (prod)
- **Temps reel :** Pusher (WebSocket broadcasting)
- **Authentification :** Laravel Sanctum (Bearer tokens)
- **Admin Panel :** Filament 2.x
- **Tests :** Pest 2.6
- **Analyse statique :** PHPStan niveau 7 + Larastan
- **Linting :** Laravel Pint (preset Laravel)
- **Monitoring :** Sentry (erreurs + tracing)
- **CI/CD :** GitHub Actions

---

## Index de la Documentation

| Document | Description |
|----------|-------------|
| [ARCHITECTURE.md](ARCHITECTURE.md) | Structure des dossiers, patterns architecturaux, flux de donnees |
| [MODELS_DATABASE.md](MODELS_DATABASE.md) | Tous les modeles Eloquent, migrations, relations, traits, casts |
| [API_ROUTES.md](API_ROUTES.md) | Routes API/Web/Chatbot, controleurs, middleware, resources, requests |
| [OPENCLAW_CHATBOT_API.md](OPENCLAW_CHATBOT_API.md) | Guide d'integration OpenClaw (analytics + booking via chatbot API) |
| [OPENCLAW_TOOL_CONTRACT.json](OPENCLAW_TOOL_CONTRACT.json) | Contrat machine-readable des outils OpenClaw (schemas + mapping HTTP) |
| [FILAMENT_ADMIN.md](FILAMENT_ADMIN.md) | Panneau d'administration Filament (Resources, Pages, Widgets, Policies) |
| [implementation/admin-v2/00-MASTER-PLAN.md](implementation/admin-v2/00-MASTER-PLAN.md) | Plan directeur de migration Admin V2 (V1/V2 split, phases, contraintes) |
| [implementation/admin-v2/logs/PHASE-11-DONE.md](implementation/admin-v2/logs/PHASE-11-DONE.md) | Changelog structurel consolide (dernier commit + updates post-commit) |
| [BUSINESS_LOGIC.md](BUSINESS_LOGIC.md) | Services, Actions, Jobs, Events, Listeners, Observers, Notifications |
| [CONFIGURATION.md](CONFIGURATION.md) | Fichiers de config, variables d'environnement, CI/CD, scripts DevOps |
| [CODING_STANDARDS.md](CODING_STANDARDS.md) | Conventions de code, annotations, patterns, regles PHPStan/Pint |
| [AGENT_INIT.md](AGENT_INIT.md) | Instructions d'initialisation pour un agent de developpement |

---

## Demarrage Rapide

```bash
# 1. Cloner le repo
git clone <repo-url> championspirit-api
cd championspirit-api

# 2. Installer les dependances
composer install
yarn install

# 3. Configurer l'environnement
cp .env.example .env
php artisan key:generate

# 4. Configurer la base de donnees (MySQL requis)
php artisan migrate --seed

# 5. Compiler les assets
yarn build

# 6. Permissions
./setPermissions.sh

# 7. Lancer le serveur
php artisan serve
```

## Pre-commit obligatoire

Avant tout commit sur l'environnement de developpement, **toujours** executer :

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

Ce script execute :
1. `composer lint` - Verification du style de code (Laravel Pint)
2. `composer types` - Analyse statique PHPStan niveau 7

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

---

## Roles Utilisateur

Le systeme supporte 3 profils par utilisateur (cumulables) :

| Role | Description | Middleware |
|------|-------------|------------|
| **Customer** | Client final, reserve des cours/services, gere wallet | `customer` |
| **Coach** | Formateur, gere ses disponibilites et planning | `coach` |
| **Employee** | Personnel du centre (admin, hospitality, coordinator, security, maintenance) | `EnsureEmployeeOfPlace` |
| **Shop Manager** | Employe vendeur : vente de produits, gestion de carts, paiements POS/CASH, dashboard ventes | `EnsureShopManagerMiddleware` |

Un utilisateur peut switcher de profil via `POST /v1/profile`.

---

## Shop Manager

Le **Shop Manager** est un profil mobile pour les employes ayant le role `is_shop_manager`. Il permet de :

- **Catalogue produits** : Lister, consulter, activer/desactiver les produits, scanner des codes-barres
- **Gestion de panier** : Creer des carts pour des clients, ajouter/modifier/supprimer des items
- **Paiements** : POS (TPE), Cash, Wallet, Stripe, Crypto — avec generation d'invoices
- **Inventaire** : Ajustement de stock, alertes stock bas, generation de codes-barres
- **Historique commandes** : Liste et detail des commandes passees
- **Dashboard analytics** : Revenue, checkout snapshot, sales performance, best sellers, top categories, recent activity, inventory alerts — avec cache Redis pre-compute a minuit et delta 5 min

**Prefix API :** `/v1/places/{place}/shop/*`
**33 controleurs** | **4 actions** | **10 form requests** | **8 resources** | **2 services** | **10 fichiers de tests**

---

## Integrations Externes

| Service | Usage | Config |
|---------|-------|--------|
| **Stripe** | Paiements CB | `config/services.php` |
| **NowPayments** | Paiements crypto | `.env` |
| **QuickBooks** | Comptabilite | `config/quickbooks.php` |
| **Sendinblue** | Emails/SMS transactionnels | `config/sendinblue.php` |
| **Expo** | Push notifications mobile | `config/expo-notifications.php` |
| **Pusher** | WebSocket temps reel | `config/broadcasting.php` |
| **Google Maps** | Geocoding adresses | `config/maps.php` |
| **BioStar2** | Controle d'acces physique (portes) | `Place.door_system_credentials` |
| **OpenAI / Mistral / Claude / BoldAI** | Chat IA | `config/chat.php` |
| **POEditor** | Gestion des traductions | `config/translation.php` |
| **Sentry** | Error tracking & APM | `config/sentry.php` |
| **OAuth** | Google, Facebook, LinkedIn, Instagram, Apple | `config/services.php` |