the-tip-top-frontend/README.md

# 🍵 Thé Tip Top - Jeu Concours Frontend

Application web moderne pour le jeu-concours "Thé Tip Top" avec Next.js 14 et Tailwind CSS.

## 📋 Description

Site web complet permettant aux utilisateurs de :
- Se connecter via Google/Facebook OAuth ou formulaire classique
- Participer au jeu-concours en entrant un code de ticket (10 caractères)
- Consulter leurs gains et historiques
- Permettre aux employés de vérifier les gains et marquer comme "remis"
- Permettre aux administrateurs de visualiser les statistiques globales du jeu

## 🚀 Technologies utilisées

- **Framework:** Next.js 14 (App Router)
- **Styling:** Tailwind CSS
- **Gestion d'état:** React Context API (AuthContext)
- **Formulaires:** React Hook Form + Zod
- **Notifications:** React Hot Toast
- **Appels API:** Axios
- **Language:** TypeScript

## 📁 Structure du projet

```
the-tip-top-frontend/
├── app/                          # Pages Next.js 14 (App Router)
│   ├── page.tsx                  # Page d'accueil
│   ├── login/page.tsx            # Connexion
│   ├── register/page.tsx         # Inscription
│   ├── jeux/page.tsx             # Page de jeu
│   ├── client/page.tsx           # Dashboard client
│   ├── employe/page.tsx          # Dashboard employé
│   ├── admin/page.tsx            # Dashboard admin
│   ├── historique/page.tsx       # Historique
│   ├── profile/page.tsx          # Profil
│   ├── layout.tsx                # Layout principal
│   └── globals.css               # Styles globaux
│
├── components/                   # Composants réutilisables
│   ├── Header.tsx                # Header avec navigation
│   ├── Footer.tsx                # Footer complet
│   ├── Button.tsx                # Bouton personnalisé
│   └── ui/                       # Composants UI
│       ├── Card.tsx
│       ├── Input.tsx
│       ├── Badge.tsx
│       ├── Modal.tsx
│       ├── Loading.tsx
│       └── Table.tsx
│
├── contexts/                     # Contextes React
│   └── AuthContext.tsx           # Authentification
│
├── services/                     # Services API
│   ├── api.ts                    # Configuration Axios
│   ├── auth.service.ts           # Auth
│   ├── user.service.ts           # Utilisateur
│   ├── game.service.ts           # Jeu
│   ├── employee.service.ts       # Employé
│   └── admin.service.ts          # Admin
│
├── hooks/                        # Hooks personnalisés
│   └── useGame.ts
│
├── lib/                          # Librairies
│   └── validations.ts            # Schémas Zod
│
├── types/                        # Types TypeScript
│   └── index.ts
│
└── utils/                        # Utilitaires
    ├── constants.ts              # Constantes
    └── helpers.ts                # Helpers
```

## 🎨 Fonctionnalités

### Pages publiques
- ✅ **Page d'accueil** : Présentation du jeu-concours
- ✅ **Connexion/Inscription** : Authentification complète avec OAuth
- ✅ **Navigation responsive** : Header et Footer professionnels

### Espace Client (`/client`)
- ✅ Statistiques personnelles (participations, gains, en attente)
- ✅ Historique des tickets joués
- ✅ Accès rapide au jeu

### Page de jeu (`/jeux`)
- ✅ Saisie de code ticket avec validation
- ✅ Résultat instantané avec modal
- ✅ Protection : utilisateurs connectés uniquement

### Espace Employé (`/employe`)
- ✅ Recherche de ticket par code
- ✅ Liste des tickets en attente
- ✅ Validation des gains
- ✅ Protection : rôle "employee" requis

### Espace Admin (`/admin`)
- ✅ Statistiques globales du jeu
- ✅ Distribution des lots
- ✅ Aperçu des statuts
- ✅ Derniers utilisateurs et tickets
- ✅ Protection : rôle "admin" requis

## ⚙️ Installation

1. **Cloner le projet**
```bash
git clone <repo-url>
cd the-tip-top-frontend
```

2. **Installer les dépendances**
```bash
npm install
```

3. **Configurer les variables d'environnement**
Créer un fichier `.env.local` :
```env
# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:4000/api
NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000

# NextAuth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key

# OAuth Providers (Optionnel - voir section OAuth ci-dessous)
NEXT_PUBLIC_GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
NEXT_PUBLIC_FACEBOOK_APP_ID=your-facebook-app-id
FACEBOOK_CLIENT_SECRET=your-facebook-client-secret
```

4. **Lancer le serveur de développement**
```bash
npm run dev
```

Le site sera accessible sur **http://localhost:3000**

## 🔐 Configuration OAuth (Optionnel)

L'application supporte l'authentification via Google et Facebook OAuth. Ces fonctionnalités sont **optionnelles** - l'application fonctionne sans OAuth configuré.

### Google OAuth

1. **Créer un projet Google Cloud**
   - Aller sur [Google Cloud Console](https://console.cloud.google.com/)
   - Créer un nouveau projet ou sélectionner un existant

2. **Activer l'API Google+**
   - APIs & Services → Library
   - Rechercher "Google+ API" → Enable

3. **Créer des identifiants OAuth 2.0**
   - APIs & Services → Credentials
   - Create Credentials → OAuth client ID
   - Type d'application: **Application Web**

4. **Configurer les origines autorisées**
   - **Origines JavaScript autorisées:**
     - `https://dev.dsp5-archi-o24a-15m-g3.fr` (production DEV)
     - `http://localhost:3000` (développement local)
   - **URI de redirection autorisés:**
     - `https://dev.dsp5-archi-o24a-15m-g3.fr`
     - `http://localhost:3000`

5. **Copier le Client ID** et l'ajouter à vos variables d'environnement

### Facebook OAuth

1. **Créer une application Facebook**
   - Aller sur [Facebook Developers](https://developers.facebook.com/)
   - Mes Apps → Créer une app → Type: **Consommateur**

2. **Configurer Facebook Login**
   - Ajouter un produit → Facebook Login → Configurer
   - Paramètres → Facebook Login

3. **Configurer les URI de redirection**
   - **URI de redirection OAuth valides:**
     - `https://dev.dsp5-archi-o24a-15m-g3.fr`
     - `http://localhost:3000`

4. **Paramètres de base**
   - Domaines de l'app: `dev.dsp5-archi-o24a-15m-g3.fr`
   - URL de la politique de confidentialité: (requis pour mise en production)
   - URL des conditions de service: (requis pour mise en production)

5. **Copier l'ID de l'app** et l'ajouter à vos variables d'environnement

6. **Rendre l'app publique**
   - Mode développement: seuls les testeurs peuvent se connecter
   - Mode production: tout le monde peut se connecter (nécessite validation Facebook)

### Variables d'environnement pour OAuth

```env
# Google OAuth
NEXT_PUBLIC_GOOGLE_CLIENT_ID=votre-client-id-google.apps.googleusercontent.com

# Facebook OAuth
NEXT_PUBLIC_FACEBOOK_APP_ID=votre-facebook-app-id
```

### Déploiement avec OAuth

Pour le déploiement via Jenkins, les variables d'environnement doivent être passées lors du build Docker:

```bash
docker build \
  --build-arg NEXT_PUBLIC_API_URL=https://api.dev.dsp5-archi-o24a-15m-g3.fr/api \
  --build-arg NEXT_PUBLIC_FRONTEND_URL=https://dev.dsp5-archi-o24a-15m-g3.fr \
  --build-arg NEXT_PUBLIC_GOOGLE_CLIENT_ID=votre-client-id \
  --build-arg NEXT_PUBLIC_FACEBOOK_APP_ID=votre-app-id \
  -t the-tip-top-frontend .
```

**Note:** Si OAuth n'est pas configuré, les boutons de connexion Google/Facebook ne s'afficheront pas sur la page de login.

## 🔗 Routes principales

| Route | Description | Protection |
|-------|-------------|-----------|
| `/` | Page d'accueil | Publique |
| `/login` | Connexion | Publique |
| `/register` | Inscription | Publique |
| `/jeux` | Participer au jeu | Authentifié |
| `/client` | Dashboard client | Client |
| `/employe` | Dashboard employé | Employé |
| `/admin` | Dashboard admin | Admin |
| `/historique` | Historique | Authentifié |
| `/profile` | Profil utilisateur | Authentifié |

## 🎯 Backend requis

Le frontend se connecte à un backend Express sur `http://localhost:5000` (configurable).

### Endpoints attendus :

**Authentification**
- `POST /api/auth/login`
- `POST /api/auth/register`
- `POST /api/auth/google`
- `POST /api/auth/facebook`
- `GET /api/auth/me`
- `POST /api/auth/logout`

**Jeu**
- `POST /api/game/play`

**Utilisateur**
- `GET /api/user/tickets`
- `GET /api/user/profile`

**Employé**
- `GET /api/employee/pending-tickets`
- `POST /api/employee/validate/:id`

**Admin**
- `GET /api/admin/statistics`
- `GET /api/admin/users`
- `GET /api/admin/tickets`

## 🏗️ Build de production

```bash
# Créer le build
npm run build

# Démarrer en production
npm start
```

## 🎨 Thème et design

Le projet utilise un thème personnalisé avec Tailwind CSS :
- **Couleur primaire** : Vert (thème du thé)
- **Couleur secondaire** : Jaune/Or
- **Design** : Moderne, responsive, accessible
- **Composants** : Réutilisables et modulaires

## 📱 Responsive

L'application est entièrement responsive :
- 📱 Mobile : < 768px
- 💻 Tablet : 768px - 1024px
- 🖥️ Desktop : > 1024px

## ♿ Accessibilité

- Labels ARIA sur tous les éléments interactifs
- Navigation au clavier
- Contrastes de couleurs respectés
- Messages d'erreur descriptifs

## 🧪 Scripts disponibles

```bash
npm run dev      # Développement
npm run build    # Build production
npm start        # Démarrer en production
npm run lint     # Linter
```

## 📄 License

Ce projet est sous licence privée - Thé Tip Top © 2024

## 👥 Auteur

Développé pour Thé Tip Top - Jeu Concours 2024

---

**Note:** Assurez-vous que le backend est démarré avant de lancer le frontend.