# Panneau d'Administration Filament

## Vue d'ensemble

Le panneau d'administration est **completement separe** de l'API REST. Ce sont deux systemes distincts :

| Aspect | API REST | Filament Admin |
|--------|----------|----------------|
| **Cible** | App mobile, chatbot, frontend web | Back-office interne |
| **Auth** | Sanctum Bearer tokens | Session web (guard `filament`) |
| **Acces** | Customers, Coaches, Employees | Employees uniquement |
| **URL** | `api.championspirit.com/v1/*` | `manager.championspirit.com/admin/*` |
| **UI Layer** | `app/Http/Controllers/Api/` | `app/Filament/V1/*` + `app/Filament/V2/*` |
| **Logique metier** | Actions + Services | Modeles directs + Policies |
| **Format** | JSON | HTML (Livewire) |

**Important :** Les controleurs API et les Resources Filament **ne partagent PAS** de code. La logique metier (Actions, Services) est parfois reutilisee, mais les couches de presentation sont independantes.

---

## Configuration

### Acces

```
URL        : /admin (configurable via FILAMENT_PATH)
Domaine    : FILAMENT_DOMAIN (ex: manager.championspirit.com)
Guard      : filament (session-based)
Dark mode  : Desactive
Police     : DM Sans (Google Fonts)
Layout     : Sidebar gauche, repliable
```

### Structure V1 / V2 (etat actuel)

- **V1** (legacy admin): `app/Filament/V1/*`
- **V2** (operational cockpit): `app/Filament/V2/*`
- V2 est expose sous `/admin/v2/*` pendant la transition.
- Le switch d'interface est place dans la **topbar** (pas dans la sidebar).

### Fichiers de config

| Fichier | Description |
|---------|-------------|
| `config/filament.php` | Path, guard, theme, layout, middleware |
| `config/filament-authentication.php` | Modeles User/Role/Permission |
| `config/filament-language-switch.php` | Switch de langue dans l'admin |
| `config/filament-fullcalendar.php` | Widget calendrier |

---

## Authentification Admin

### Login (`app/Filament/V1/Auth/Login.php`)

Login personnalise qui etend `Filament\Http\Livewire\Auth\Login` :
- **Condition d'acces** : L'utilisateur DOIT avoir un enregistrement `Employee` (seuls les employes/admins peuvent se connecter)
- **Switch de langue** : Charge les langues actives depuis la BDD, permet le changement de locale
- **Rate limiting** : 5 tentatives avant throttling

### Roles Admin

Les roles sont des **flags booleens** sur le modele Employee :

| Role | Flag | Acces |
|------|------|-------|
| Super Admin | `is_super_admin` | Acces total, bypass toutes les permissions |
| Hospitality | `is_hospitality` | Gestion des lieux et du personnel assigne |
| Manager | `is_manager` | Gestion de lieu |
| Coordinator | `is_coordinator` | Coordination operationnelle |
| Security | `is_security` | Controle d'acces et securite |
| Maintenance | `is_maintenance` | Gestion des taches de maintenance |
| Shop Manager | `is_shop_manager` | Vente POS/CASH, gestion stock, dashboard analytics (API uniquement, pas d'acces Filament) |

### Permissions (Spatie)

Le systeme utilise Spatie Permission avec le guard `filament` :

```
Format : {module}.{action}
Exemple : customers.view_any, customers.create, customers.update, customers.delete

Actions : view_any, view, create, update, delete, restore, force_delete
```

Les modules sont auto-derives du nom de la Resource : `CustomerResource` -> `customers`.

**Trait `HasPermissionChecks`** : Applique dans toutes les Resources, verifie les permissions automatiquement.

**Super Admin** : Bypass TOUTES les verifications de permissions (`$user->employee->is_super_admin`).

---

## Navigation

### Groupes de navigation

| Groupe | Contenu |
|--------|---------|
| **Settings** | Customers, Coaches, Employees, Families, Languages |
| **Data** | Places, Categories, Facilities, Orders, Products, Packs, Memberships |
| **Catalogue** | Products (sort 40) |
| **Reports** | Toutes les pages de rapports |
| **Operations** | Tasks, Reports |
| **Integrations** | QuickBooks Connections |
| **Administration** | QuickBooks Queue Monitor, Role Permissions Manager |

---

## Resources Filament (CRUD)

> Note: les chemins historiques `app/Filament/Resources/*`, `app/Filament/Pages/*`, etc. correspondent desormais a `app/Filament/V1/*`.

### Utilisateurs & Organisation

#### CustomerResource — Modele : User (type=customer)
**Fichier :** `app/Filament/Resources/CustomerResource.php`

**Formulaire (champs) :**
- firstname, lastname, email, email_2, phone, phone_2
- member_number, gender, member_type
- place_id, lang, is_vip
- unlimited_credits, allow_busy_bypass, force_vat_exclusive
- password

**Table (colonnes) :**
- fullname, family, gender, is_member, membership_place, phone, email, created_at

**Filtres :** place_id, statut abonnement (membre/non-membre), soft delete

**Relations managers :**
- Membership, Bookings, Wallet, WalletTransactions, TrackingEntries
- Kid, Guests, GuestInvitations

**Regles :** Impossible de supprimer un client avec des bookings futurs.

---

#### CoachResource — Modele : User (type=coach)
**Fichier :** `app/Filament/Resources/CoachResource.php`

**Formulaire :**
- firstname, lastname, email, phone, lang, gender, password
- places (affectation), hourly_price, member_hourly_price
- description, booking_delay, display_in_app
- chat_activated, ai_user_id, default_ai_enabled, default_ai_driver

**Table :** places, firstname, lastname, phone, email, created_at

**Filtrage automatique :** Si l'admin est hospitality, seuls les coaches de ses lieux assignes sont affiches.

**Relations managers :** Payments, Places, Categories, Availabilities, ViewGroupCourses

---

#### EmployeeResource — Modele : User (type=employee)
**Fichier :** `app/Filament/Resources/EmployeeResource.php`

**Formulaire :**
- Mode : nouveau utilisateur OU utilisateur existant (select)
- firstname, lastname, email, phone, lang, gender, password
- employment_start/end, employee_number, is_active
- receive_email/push_notifications, contract_details, comments
- places (affectation), roles (checkboxes)

**Actions personnalisees :** createWallet, deleteEmployee, restoreEmployee, bulkDeleteEmployees

**Acces :** Seuls les super_admin et hospitality peuvent creer des employes.

**Relations managers :** Places, AssignedTasks, GuestInvitations

---

#### FamilyResource — Modele : Family
**Fichier :** `app/Filament/Resources/FamilyResource.php`

**Formulaire :**
- name, place_id, member_type, member_number, registration_date
- is_vip, head_id (ou creation inline du chef de famille)

**Relations managers :** Membership, User, Wallet, WalletTransactions, Kid

---

### Lieux & Installations

#### PlaceResource — Modele : Place
**Fichier :** `app/Filament/Resources/PlaceResource.php`

**C'est la Resource la plus volumineuse du projet**, organisee en **7 onglets** :

| Onglet | Champs |
|--------|--------|
| **General** | picture, name, lang, timezone, description (traduisible), guest_passes, enable_flex_membership, adresse |
| **Financial** | currency, credit_to_currency, vat (%), vat_inclusive, daypass prices (standard/member/guest), non_member_resort_access_fee, topup_notifications |
| **Features** | internet_booking, courses_type, facilities (checkbox list) |
| **Schedule** | opening_hours (repeater 7 jours), exceptional_closing_dates |
| **Notifications** | planning_recipients, physical_assessment_recipients, physical_assessment_category |
| **Integrations** | door_system fieldset (cache pour non super_admin), chat_activated, ai_user_id, default_ai_driver |
| **Mobile App Config** | Settings d'affichage, homepage_configuration (OrderableRepeater), booking_configuration (OrderableRepeater), couleurs, icones |

**Relations managers (nombreuses) :**
- Departments, GroupCourses, Events, PersonalCourses, WellnessCourses
- Banners, Services, Activities, Categories, Products
- Bookings, RestaurantRevenues, FeaturedCategories, Reports, AccessLogs

**Pages personnalisees :** Calendar, Chat, Information, Tasks, Pre-arrival forms, Access logs, Reports, ProductsSettings (gestion produits/stock par lieu), pages de gestion par type de service, pages de parametrage

**Widget :** CalendarWidget (planning)

**Regle :** Impossible de supprimer un lieu.

---

#### CategoryResource — Modele : Category
**Fichier :** `app/Filament/Resources/CategoryResource.php`

**Formulaire :**
- name, department_id, description, parent_id (hierarchie)
- Checkboxes : group_course, personal_course, wellness_course, service, activity, product
- is_recreational_area, is_kids_zone, min_age, max_age
- icon (PNG obligatoire pour les categories parentes)

**Filtres :** parent_id, types de cours

**Regle :** Impossible de supprimer si bookings futurs lies.

---

#### FacilityResource — Modele : Facility
**Champs :** name (traduisible), icon (PNG)

---

### Produits & Offres

#### ProductResource — Modele : Product
**Formulaire :** place_id, department_id, category_id, name, description, can_buy, can_rent, is_active, pictures (multiples)
**Relations managers :** Variations (ProductVariationRelationManager), Stocks (ProductVariationStockRelationManager)

**Note Shop Manager :** Le champ `is_active` controle la visibilite des produits dans l'interface Shop Manager. Les relation managers Variations et Stocks permettent la gestion complete de l'inventaire depuis l'admin.

#### PackResource — Modele : Pack (non-membership, non-daypass)
**Formulaire :** name (traduisible), department_id, price, price_currency, credits, places (multiples)

#### MembershipOfferResource — Modele : Pack (is_membership=true)
**Formulaire :** name, price, price_currency, credits, places
**Filtre query :** `where('is_membership', true)`

#### DaypassOfferResource
Similaire aux packs mais filtre pour les daypasses.

#### FlexMembershipResource — Modele : FlexMembership
**Formulaire :** name (traduisible), description (traduisible), place_id, membership_pack_id, min_spend_amount/currency, is_active, comments
**Reactif :** Les options de pack se mettent a jour en fonction de la devise du lieu.

---

### Operations

#### OrderResource — Modele : Order
**Lecture seule** (pas de creation manuelle).

**Table :** user.fullname, status, updated_at, payment_provider
**Filtres :** payment_provider, plage de dates
**Relations :** Items (OrderItems)
**Tri par defaut :** updated_at desc

#### TaskResource — Modele : Task
**Formulaire :** place_id, service_id, user_id, status (enum), start_at, end_at, deadline_at, comment, assignees (employes maintenance), attachments (media)

#### ReportResource — Modele : Report
**Formulaire :** place_id, service_id, user_id, task_id, origin (customer/coach/employee), comment, attachments

#### AccessLogResource — Modele : PlaceAccessLog
CRUD pour les logs d'acces.

---

### Configuration & Langues

#### LanguageResource — Modele : Language
**Formulaire :** code (select parmi les langues inactives)
**Actions :** EditLanguageAction, SetDefaultLanguageAction, DeactivateLanguageAction

#### TranslationResource — Modele : Translation
**Formulaire modal multi-langue :** key, value_{lang_code} (pour chaque langue active)
**Actions :** Edit (modal multi-langue), Translate (auto-traduction), Delete

#### ActivityLogResource — Lecture seule
Liste des logs d'activite Spatie.

---

### QuickBooks

#### QuickbooksConnectionResource — Modele : QuickbooksConnection
**Formulaire :** place_id, environment, is_active, use_automated_sales_tax, realm_id, client_id, client_secret, authorization_code, access_token, refresh_token
**Relations :** AccountTypes, Accounts

---

## Pages Admin

### Pages de Rapports (`app/Filament/Pages/Reports/`)

Toutes heritent de `BaseReportPage` qui fournit :
- Interaction Table + Formulaire
- Export Excel/PDF
- Pagination (10, 25, 50, 100)
- Permission : `reports.view_any` ou super_admin

| Page | Description | Donnees cles |
|------|-------------|--------------|
| **OverviewReport** | Dashboard KPI | Revenus, clients/membres, top coaches, credits, restaurant |
| **ClientsReport** | Export clients | Donnees client completes |
| **CoachesReport** | Export coaches | Donnees coach completes |
| **CoursesReport** | Bookings cours | Cours reserves (+ export PDF) |
| **GroupCoursesReport** | Cours collectifs | Donnees cours de groupe |
| **MembershipsReport** | Abonnements | Donnees d'abonnement |
| **TransactionsReport** | Transactions | Donnees financieres |
| **FinanceReport** | Finance | Rapports financiers |
| **AccessReport** | Acces | Logs de controle d'acces |
| **GuestInvitationsReport** | Invitations | Donnees d'invitations guest |
| **BookableItemsPricingReport** | Tarification | Grille tarifaire |

### OverviewReport (Dashboard)

Le rapport principal avec les metriques cles :
- **Revenus** : Commandes, transactions wallet, cumul annuel
- **Clients** : Membres, clients, prospects (compteurs)
- **Top coaches/clients** : Classements
- **Credits** : Achetes, depenses, stock
- **Restaurant** : Revenus restauration
- **Filtre** : Selecteur de plage de dates (start_at, end_at)

### Pages d'Administration

#### RolePermissionsManager
**Fichier :** `app/Filament/Pages/RolePermissionsManager.php`
- **Acces :** Super admin uniquement
- Interface CRUD pour les associations role-permission
- Modules groupes par prefixe de permission
- Toggle par permission, par module, ou tout a la fois

#### QuickbooksQueueMonitor
**Fichier :** `app/Filament/Pages/QuickbooksQueueMonitor.php`
- **Acces :** Super admin uniquement
- Monitore les jobs pending/failed dans les queues QuickBooks
- Queues : default, catalog, customers, wallet, accounts
- Actions : retry failed, delete jobs, clear all failed

---

## Widgets Dashboard

| Widget | Description | Permission |
|--------|-------------|------------|
| `StatsOverview` | Cards compteurs (clients, coaches) | `dashboard.view_stats` ou super_admin |
| `LatestCoachesRegistration` | Derniers coaches inscrits | Dashboard |
| `LatestCustomersRegistration` | Derniers clients inscrits | Dashboard |
| `UpcomingBookings` | Prochaines reservations | Dashboard |
| `CalendarWidget` | Calendrier planning (dans PlaceResource) | Acces au lieu |

---

## Composants Reutilisables

### AddressFieldset (`app/Filament/Components/AddressFieldset.php`)

Fieldset d'adresse reutilisable :
- Champs : line1, line2, postcode, city, country, state

### DoorSystemFieldset (`app/Filament/Components/DoorSystemFieldset.php`)

Configuration du systeme de porte :
- **Visibilite :** Cache pour les admins hospitality/coordinator (super_admin uniquement)
- Champs : door_system (enum), credentials (encrypted)

### OrderableRepeater (`app/Filament/Components/OrderableRepeater.php`)

Repeater personnalise avec gestion de l'ordre (position) :
- Utilise pour : `homepage_configuration`, `booking_configuration` dans PlaceResource
- Support du drag-and-drop pour reordonner les blocs

---

## Traits Reutilisables (Concerns)

### HasTranslatableFields (`app/Filament/Concerns/HasTranslatableFields.php`)

Genere des champs de formulaire specifiques a chaque langue :
- Bouton auto-traduction (Google Translate API)
- Toggle pour afficher/masquer les autres langues
- Champs `required` uniquement sur la langue par defaut

### HasPermissionChecks
Verifie automatiquement les permissions `{module}.{action}` sur chaque Resource.

### CanManageBookings / CanManageGroupCourses / CanManageMemberships / CanManagePacks
Traits partages pour les Relation Managers recurrents.

### EditPagePolicyTrait / ViewPagePolicyTrait
Appliquent les politiques sur les pages Edit/View.

---

## Controleurs de Rapports Legacy

**Emplacement :** `app/Http/Controllers/Admin/Reports/`

Ces controleurs sont **legacy** et certains redirigent vers les pages Filament. Ils servent les routes :
- `/admin/report-clients`
- `/admin/report-coaches`
- `/admin/report-courses`
- `/admin/report-memberships`
- `/admin/report-transactions`
- `/admin/report-revenue`
- etc.

---

## Livewire

**Emplacement :** `app/Http/Livewire/`

Composants Livewire pour les interfaces interactives admin. Filament utilise Livewire sous le capot pour le rendu dynamique.

---

## Points Architecturaux Importants

### Separation Filament / API

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

### Filtrage par lieu (Place-Based)

Les admins hospitality ne voient que les donnees de **leurs lieux assignes** :
- Coaches filtres par les lieux de l'employe
- Employees filtres par les lieux de l'employe
- Resources filtrees automatiquement

### Soft Deletes dans Filament

La plupart des Resources gerent les enregistrements soft-deleted :
```php
->withoutGlobalScopes([SoftDeletingScope::class])
```
Avec des actions Restore pour recuperer les enregistrements supprimes.

### Gestion monetaire

Les prix dans Filament utilisent `Brick\Money\Money` :
- Stockage en centimes (minor amounts)
- Affichage formate avec devise
- Champs reactifs qui mettent a jour les options selon la devise du lieu