cesizen/docs/DOCUMENTATION.md

# Documentation Technique — CESIZen

## Table des matières

1. [Présentation du projet](#1-présentation-du-projet)
2. [Architecture globale](#2-architecture-globale)
3. [Application Web (Laravel)](#3-application-web-laravel)
   - [Stack technique](#31-stack-technique)
   - [Structure des dossiers](#32-structure-des-dossiers)
   - [Modèles de données](#33-modèles-de-données)
   - [Routes & Contrôleurs Web](#34-routes--contrôleurs-web)
   - [API REST](#35-api-rest)
   - [Administration Filament](#36-administration-filament)
   - [Services](#37-services)
4. [Application Mobile (Flutter)](#4-application-mobile-flutter)
   - [Stack technique](#41-stack-technique)
   - [Architecture](#42-architecture)
   - [Fonctionnalités](#43-fonctionnalités)
5. [Application Wear OS](#5-application-wear-os)
   - [Stack technique](#51-stack-technique)
   - [Fonctionnement](#52-fonctionnement)
6. [Base de données](#6-base-de-données)
7. [Déploiement](#7-déploiement)

---

## 1. Présentation du projet

**CESIZen** est une application de bien-être mental destinée aux étudiants et collaborateurs CESI. Elle propose :

- Un **diagnostic de stress** basé sur l'échelle Holmes & Rahe (événements de vie stressants cotés en points)
- Un **tracker émotionnel** pour enregistrer et suivre son humeur au quotidien
- Des **activités de relaxation** (méditation, respiration, yoga, etc.) avec gestion des favoris
- Des **informations / articles** bien-être publiés par les administrateurs
- Une **application Wear OS** pour enregistrer son humeur directement depuis la montre

---

## 2. Architecture globale

```
CESIZen/
├── WEB/          → Backend Laravel + Frontend Blade + API REST + Admin Filament
├── mobile/       → Application Flutter (iOS & Android)
└── Wear/         → Application Wear OS (Kotlin/Jetpack Compose)
```

La communication entre les composants :

```
[Navigateur]  ←→  [Laravel WEB (Blade + Sanctum)]
[App Flutter] ←→  [Laravel API REST (Sanctum Token)]
[Montre Wear] ←→  [App Flutter] ←→  [Laravel API REST]
                  (via Wearable Data Layer API)
```

---

## 3. Application Web (Laravel)

### 3.1 Stack technique

| Élément | Technologie |
|---|---|
| Framework | Laravel 11 |
| Admin Panel | Filament 3 |
| Auth API | Laravel Sanctum |
| Base de données | SQLite (dev) / MySQL (prod) |
| Frontend | Blade + Vite |
| Tests | PHPUnit |
| Conteneurisation | Docker + Nginx |

### 3.2 Structure des dossiers

```
WEB/
├── app/
│   ├── Filament/
│   │   └── Resources/
│   │       └── UserResource/     ← CRUD utilisateurs dans l'admin
│   ├── Http/
│   │   └── Controllers/
│   │       ├── Api/              ← Contrôleurs pour l'API mobile
│   │       │   ├── AuthController.php
│   │       │   ├── EmotionController.php
│   │       │   ├── InformationController.php
│   │       │   └── StressDiagnosticController.php
│   │       └── Web/              ← Contrôleurs pour les pages Blade
│   │           ├── AuthController.php
│   │           ├── DiagnosticController.php
│   │           ├── EmotionController.php
│   │           ├── InformationController.php
│   │           ├── ProfileController.php
│   │           └── RelaxationController.php
│   ├── Models/                   ← Modèles Eloquent
│   └── Services/
│       └── StressCalculator.php  ← Logique de calcul du score de stress
├── database/
│   ├── migrations/
│   └── seeders/
├── routes/
│   ├── api.php                   ← Routes API (préfixe /api)
│   └── web.php                   ← Routes Web (Blade)
├── Dockerfile
└── docker-compose.yml
```

### 3.3 Modèles de données

#### `User`
| Champ | Type | Description |
|---|---|---|
| `id` | int | Clé primaire |
| `name` | string | Nom complet |
| `email` | string | Adresse email (unique) |
| `password` | string | Mot de passe hashé |
| `id_role` | int | FK → `roles` |
| `is_active` | boolean | Compte actif/désactivé |

Relations :
- `role()` → `BelongsTo(Role)` — rôle de l'utilisateur
- `emotionRecords()` → `HasMany(EmotionRecord)` — historique émotionnel
- `favoritedActivities()` → `BelongsToMany(RelaxationActivity)` via table `favorites`

> L'accès au panel Filament est restreint aux utilisateurs avec `is_active = true` ET rôle `Admin`.

#### `Role`
Rôles disponibles : `Admin`, `User`.

#### `StressEvent`
Événements de vie stressants de l'échelle Holmes & Rahe.

| Champ | Type | Description |
|---|---|---|
| `event_name` | string | Nom de l'événement |
| `points` | int | Valeur en points de stress |

#### `ResultatDiag`
Résultat d'un diagnostic de stress effectué par un utilisateur.

Champs : `user_id`, `score` (total des points), `level` (Faible / Modéré / Élevé), `events` (JSON des événements cochés).

#### `EmotionRecord`
Enregistrement d'une émotion quotidienne.

| Champ | Type | Description |
|---|---|---|
| `user_id` | int | FK → `users` |
| `emotion` | string | Nom de l'émotion |
| `intensity` | int | Intensité (1–5) |
| `note` | string (nullable) | Note libre |

#### `RelaxationActivity`
Activité de relaxation disponible dans le catalogue.

| Champ | Type | Description |
|---|---|---|
| `title` | string | Titre de l'activité |
| `type` | string | Type : méditation, respiration, yoga, etc. |
| `duration` | int | Durée en minutes |
| `url` | string | Lien vers la ressource (vidéo, audio…) |
| `description` | string | Description |

Relations :
- `favoritedBy()` → `BelongsToMany(User)` via table `favorites`

#### `Information`
Articles bien-être publiés par les administrateurs.

| Champ | Type | Description |
|---|---|---|
| `title` | string | Titre de l'article |
| `content` | text | Contenu |
| `category` | string | Catégorie |
| `image_url` | string (nullable) | URL de l'image |
| `is_published` | boolean | Visibilité publique |

### 3.4 Routes & Contrôleurs Web

#### Routes publiques (sans authentification)

| Méthode | URL | Contrôleur | Description |
|---|---|---|---|
| GET | `/` | `DashboardController@index` | Page d'accueil |
| GET | `/diagnostics` | `DiagnosticController@index` | Formulaire de diagnostic |
| GET | `/relaxation` | `RelaxationController@index` | Catalogue d'activités |
| GET | `/informations` | `InformationController@index` | Liste des articles |
| GET | `/informations/{id}` | `InformationController@show` | Détail d'un article |
| GET | `/login` | `AuthController@showLogin` | Page de connexion |
| POST | `/login` | `AuthController@login` | Traitement connexion |
| GET | `/register` | `AuthController@showRegister` | Page d'inscription |
| POST | `/register` | `AuthController@register` | Traitement inscription |
| POST | `/logout` | `AuthController@logout` | Déconnexion |

#### Routes protégées (middleware `auth`)

| Méthode | URL | Contrôleur | Description |
|---|---|---|---|
| GET | `/profile` | `ProfileController@index` | Page profil |
| PATCH | `/profile` | `ProfileController@update` | Mise à jour infos |
| PUT | `/profile/password` | `ProfileController@updatePassword` | Changement de mot de passe |
| DELETE | `/profile` | `ProfileController@destroy` | Suppression du compte |
| GET | `/emotions` | `EmotionController@index` | Historique émotions |
| POST | `/emotions` | `EmotionController@store` | Enregistrer une émotion |
| GET | `/diagnostics/history` | `DiagnosticController@history` | Historique diagnostics |
| POST | `/diagnostics` | `DiagnosticController@store` | Soumettre un diagnostic |
| POST | `/relaxation/{id}/favorite` | `RelaxationController@toggleFavorite` | Ajouter/retirer un favori |

### 3.5 API REST

Préfixe : `/api` — Authentification : **Laravel Sanctum** (Bearer Token)

#### Routes publiques

| Méthode | URL | Description |
|---|---|---|
| POST | `/api/login` | Connexion — retourne un token Sanctum |
| POST | `/api/register` | Inscription d'un nouvel utilisateur |

#### Routes protégées (middleware `auth:sanctum`)

| Méthode | URL | Description |
|---|---|---|
| GET | `/api/profile` | Récupère le profil de l'utilisateur connecté |
| POST | `/api/update-profile` | Met à jour le profil |
| GET | `/api/stress-events` | Liste tous les événements de stress (Holmes & Rahe) |
| POST | `/api/stress-diagnostics` | Enregistre un diagnostic de stress |
| GET | `/api/emotions` | Historique émotionnel de l'utilisateur |
| POST | `/api/emotions` | Enregistre une émotion |
| GET | `/api/informations` | Liste des articles publiés |
| GET | `/api/informations/{id}` | Détail d'un article |

### 3.6 Administration Filament

Le panel d'administration est accessible à `/admin` uniquement pour les utilisateurs avec le rôle `Admin` et `is_active = true`.

**Ressource disponible :**
- **UserResource** : gestion complète des utilisateurs (CRUD, activation/désactivation, assignation de rôle)

### 3.7 Services

#### `StressCalculator`

Contient la logique métier du diagnostic de stress (échelle Holmes & Rahe).

```php
$calculator = new StressCalculator();
$score = $calculator->calculateScore($points); // somme des points des événements cochés
$level = $calculator->determineLevel($score);  // 'Faible', 'Modéré', ou 'Élevé'
```

Seuils :
- **< 150 points** → Niveau Faible
- **150–299 points** → Niveau Modéré
- **≥ 300 points** → Niveau Élevé

---

## 4. Application Mobile (Flutter)

### 4.1 Stack technique

| Élément | Technologie |
|---|---|
| Framework | Flutter 3 / Dart |
| State management | Provider |
| Navigation | go_router |
| Requêtes HTTP | Dio |
| Stockage sécurisé | flutter_secure_storage |
| Internationalisation | intl |

### 4.2 Architecture

L'application suit une architecture feature-first avec séparation claire des responsabilités :

```
mobile/lib/
├── core/
│   └── network/          ← Client HTTP Dio + intercepteurs (token)
├── features/
│   ├── auth/             ← Connexion / Inscription
│   │   ├── models/
│   │   ├── providers/    ← AuthProvider (gère le token Sanctum)
│   │   ├── screens/
│   │   └── services/     ← Appels API auth
│   ├── diagnostics/      ← Diagnostic de stress
│   │   ├── models/
│   │   ├── providers/
│   │   ├── screens/
│   │   └── services/
│   ├── exercises/        ← Activités de relaxation
│   │   ├── models/
│   │   ├── providers/
│   │   ├── screens/
│   │   └── services/
│   ├── informations/     ← Articles bien-être
│   │   ├── models/
│   │   ├── providers/
│   │   ├── screens/
│   │   └── services/
│   ├── relaxation/       ← Catalogue relaxation + favoris
│   │   ├── models/
│   │   ├── providers/
│   │   ├── screens/
│   │   └── services/
│   ├── tracker/          ← Tracker émotionnel (+ sync Wear OS)
│   │   ├── models/
│   │   ├── providers/
│   │   ├── screens/
│   │   └── services/
│   └── wear/             ← Communication Wearable Data Layer
│       ├── models/
│       ├── providers/
│       ├── screens/
│       └── services/
└── main.dart
```

### 4.3 Fonctionnalités

| Fonctionnalité | Description |
|---|---|
| **Authentification** | Connexion / inscription avec stockage sécurisé du token |
| **Diagnostic de stress** | Questionnaire Holmes & Rahe, calcul du score, historique |
| **Tracker émotionnel** | Enregistrement quotidien de l'humeur avec intensité et note |
| **Relaxation** | Catalogue d'activités filtrables, gestion des favoris |
| **Informations** | Lecture des articles bien-être publiés |
| **Sync Wear OS** | Transmission de l'humeur et du statut d'auth vers la montre |

**Flux d'authentification :**
1. L'utilisateur se connecte → le token Sanctum est stocké dans `flutter_secure_storage`
2. `AuthProvider` expose l'état de connexion à toute l'app via `Provider`
3. `go_router` redirige automatiquement selon l'état d'authentification

---

## 5. Application Wear OS

### 5.1 Stack technique

| Élément | Technologie |
|---|---|
| Langage | Kotlin |
| UI | Jetpack Compose for Wear OS |
| Communication | Wearable Data Layer API (Google) |
| Composants UI | `androidx.wear.compose.material3` |

### 5.2 Fonctionnement

L'application Wear OS est **dépendante de l'app Flutter** installée sur le téléphone couplé. Elle ne communique pas directement avec l'API Laravel.

**Architecture de communication :**

```
[Wear OS App] ←──── Wearable Data Layer (Bluetooth/Wi-Fi) ────→ [App Flutter]
                                                                       ↕
                                                              [API Laravel REST]
```

**Canal de communication :**
- Chemin `/wearable_communication` : messages envoyés de la montre vers le téléphone (commandes)
- Chemin `/auth_status` : données synchronisées téléphone → montre (nom d'utilisateur, statut)
- Chemin `/daily_mood` : données synchronisées téléphone → montre (humeur du jour)

**Commandes supportées :**

| Commande | Description |
|---|---|
| `get_sync_data` | Demande au téléphone de synchroniser les données (auth + humeur) |
| `save_mood` | Envoie l'humeur sélectionnée sur la montre pour enregistrement via l'API |

**Écran principal (`WearApp`) :**

- Si l'utilisateur **n'est pas connecté** sur le téléphone → affiche "Connexion requise"
- Si connecté et **aucune humeur du jour** → propose 5 choix d'humeur (Très bien, Bien, Neutre, Pas top, Stressé)
- Si une humeur est déjà enregistrée → affiche l'humeur du jour avec option de modification

**Connectivité :**
La montre utilise la priorité réseau suivante : Wi-Fi → Bluetooth (pont vers le téléphone).

---

## 6. Base de données

### Schéma simplifié

```
roles ─────────────────────────── users
  id, libelle                       id, name, email, password, id_role, is_active
                                    │
                    ┌───────────────┼───────────────────┐
                    │               │                   │
              emotion_records   resultat_diags      favorites
              user_id, emotion  user_id, score      id_user, id_activite
              intensity, note   level, events (JSON)
                                                        │
                                              relaxation_activities
                                              title, type, duration, url

stress_events                         information
  event_name, points                    title, content, category, image_url, is_published
```

### Migrations (ordre chronologique)

| Migration | Table créée |
|---|---|
| `000001` | `roles` |
| `000002` | `users` |
| `000003` | `stress_events` |
| `000004` | `relaxation_activities` |
| `000005` | `resultat_diags` |
| `000006` | `emotion_records` |
| `000007` | `personal_access_tokens` (Sanctum) |
| `103734` | `cache`, `sessions` |
| `111910/111917` | Colonne `is_active` sur `users` |
| `141553` | `information` |

---

## 7. Déploiement

### Environnement Docker (WEB)

Le projet Laravel embarque une configuration Docker prête à l'emploi :

```
WEB/
├── Dockerfile          ← Image PHP-FPM
├── docker-compose.yml  ← Services : app + nginx
└── nginx.conf          ← Configuration Nginx
```

**Démarrer l'environnement :**

```bash
cd WEB
docker-compose up -d
php artisan migrate --seed
```

### Application Mobile

```bash
cd mobile
flutter pub get
flutter run
```

Configurer l'URL de l'API dans le fichier de configuration réseau (`lib/core/network/`).

### Application Wear OS

Ouvrir le dossier `Wear/` dans **Android Studio**, puis lancer sur une montre Wear OS physique ou un émulateur.

> La montre doit être couplée à un téléphone Android ayant l'application Flutter installée.