veza/fixtures/README.md

# 🎵 Veza Fixtures System

[![CI Status](https://github.com/your-org/veza-platform/workflows/Fixtures%20Validation/badge.svg)](https://github.com/your-org/veza-platform/actions)
[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](./coverage)
[![Version](https://img.shields.io/badge/version-1.0.0-blue)](./package.json)

> **Système de fixtures complet et robuste pour Veza Platform**

Le système de fixtures Veza est une solution complète pour générer, gérer et valider des données de test réalistes pour tous les services de la plateforme Veza. Il offre une approche cohérente et scalable pour les tests, le développement et les démonstrations.

## 🚀 Fonctionnalités Principales

### ✨ **Génération de Données Avancée**
- 🎯 **Données réalistes** avec relations cohérentes
- 🌍 **Multi-environnements** (development, testing, staging, demo)
- 🎲 **Reproductible** avec système de seeds
- 📊 **Scalable** de 10 à 10,000+ entités

### 🔗 **Intégration Multi-Services**
- 🌐 **Web Service** - MSW handlers et localStorage
- 💬 **Chat Server** - Base de données PostgreSQL et cache Redis
- 🎵 **Stream Server** - Sessions de streaming et métriques
- 🔧 **Backend API** - Données utilisateur et métadonnées

### 🎬 **Scénarios de Test Complets**
- 👤 **User Journey** - Parcours utilisateur réalistes
- ⚡ **Performance** - Tests de charge et stress
- 🔗 **Integration** - Communication inter-services
- 🎯 **Edge Cases** - Cas limites et erreurs

### 🛠️ **Outils CLI Puissants**
- 📊 **Generate** - Création de datasets
- 🌱 **Seed** - Population des services
- 🔍 **Validate** - Vérification d'intégrité
- 🧹 **Clean** - Nettoyage des données

## 📦 Installation

### Prérequis
- Node.js 18+ 
- PostgreSQL 13+
- Redis 6+
- npm ou yarn

### Installation Rapide

```bash
# Cloner et installer
git clone https://github.com/your-org/veza-platform.git
cd veza-platform/fixtures

# Installation automatique
./tools/scripts/install.sh

# Ou installation manuelle
npm install
npm run build
```

### Configuration

```bash
# Copier et configurer l'environnement
cp ../env.example .env

# Éditer les variables de connexion
nano .env
```

## 🎯 Démarrage Rapide

### Génération de Base

```bash
# Générer un dataset de développement
npm run generate -- --env development

# Alimenter tous les services
npm run seed -- --service all

# Vérifier l'intégrité
npm run validate
```

### Utilisation CLI

```bash
# Voir l'état du système
veza-fixtures status

# Générer des données personnalisées
veza-fixtures generate --env staging --users 200 --tracks 500

# Lancer un scénario de test
veza-fixtures scenario --run onboarding

# Nettoyer les données
veza-fixtures clean --service web --force
```

### Utilisation Programmatique

```typescript
import { VezaFixtures, WebFixtures } from '@veza/fixtures'

// Initialisation rapide
const result = await quickStart({
  environment: 'development',
  services: ['web', 'chat'],
  scenario: 'onboarding'
})

// Utilisation avancée
await VezaFixtures.initialize('testing')
const dataset = VezaFixtures.generateCompleteDataset()
await WebFixtures.initialize()
```

## 🏗️ Architecture

### Structure du Projet

```
fixtures/
├── core/                     # Système central
│   ├── generators/          # Générateurs de données
│   │   ├── users.ts        # Utilisateurs réalistes
│   │   ├── audio.ts        # Contenu audio
│   │   └── conversations.ts # Messages et conversations
│   ├── schemas/            # Schémas de validation
│   ├── utils/              # Utilitaires partagés
│   └── config.ts           # Configuration centrale
├── services/               # Intégrations par service
│   ├── web/               # Frontend fixtures
│   ├── chat-server/       # Backend chat
│   └── stream-server/     # Backend streaming
├── scenarios/             # Scénarios de test
│   ├── user-journey/      # Parcours utilisateur
│   ├── performance/       # Tests de performance
│   └── integration/       # Tests d'intégration
├── environments/          # Configurations d'environnement
├── tools/                # Outils CLI et scripts
└── test/                 # Tests du système
```

### Flux de Données

```mermaid
graph TD
    A[Configuration] --> B[Générateurs]
    B --> C[Relations Manager]
    C --> D[Service Fixtures]
    D --> E[Validation]
    E --> F[Export/Seed]
    
    G[CLI Tools] --> B
    H[Scenarios] --> B
    I[CI/CD] --> G
```

## 📊 Générateurs de Données

### Générateur d'Utilisateurs

```typescript
import { UserGenerator } from '@veza/fixtures'

// Utilisateur basique
const user = UserGenerator.generate()

// Utilisateur spécialisé
const artist = UserGenerator.generateArtist({
  isVerified: true,
  withAvatar: true
})

// Batch avec distribution
const users = UserGenerator.generateWithDistribution()
```

**Fonctionnalités:**
- ✅ Rôles réalistes (admin, artist, producer, user)
- ✅ Profils complets avec préférences
- ✅ Relations sociales (followers, following)
- ✅ Statistiques d'activité cohérentes

### Générateur Audio

```typescript
import { AudioGenerator } from '@veza/fixtures'

// Track individuelle
const track = AudioGenerator.generate({
  genre: 'electronic',
  isPopular: true
})

// Album complet
const album = AudioGenerator.generateAlbum(10)

// Playlist thématique
const playlist = AudioGenerator.generatePlaylist({
  theme: 'workout',
  trackCount: 20
})
```

**Fonctionnalités:**
- ✅ Métadonnées audio réalistes
- ✅ Waveform data généré
- ✅ Relations album/track cohérentes
- ✅ Statistiques d'écoute

### Générateur de Conversations

```typescript
import { ConversationGenerator } from '@veza/fixtures'

// Conversation directe
const directChat = ConversationGenerator.generateConversation({
  type: 'direct',
  participantIds: [user1.id, user2.id]
})

// Scénario complexe
const scenario = ConversationGenerator.generateScenario(
  ConversationGenerator.SCENARIOS[0], // Studio Collaboration
  userIds
)
```

**Fonctionnalités:**
- ✅ Types variés (direct, group, channel)
- ✅ Messages avec réactions et mentions
- ✅ Scénarios pré-définis réalistes
- ✅ Patterns de conversation naturels

## 🎬 Scénarios de Test

### Onboarding Utilisateur

```bash
# Lancer le scénario d'onboarding
veza-fixtures scenario --run onboarding
```

**Couvre:**
- ✅ Inscription et vérification email
- ✅ Complétion du profil
- ✅ Première écoute et playlist
- ✅ Participation au chat communautaire

### Tests de Performance

```bash
# Test de charge haute
veza-fixtures scenario --run high-load
```

**Simule:**
- ✅ 1000+ utilisateurs concurrent
- ✅ Streaming audio simultané
- ✅ Flood de messages chat
- ✅ Métriques de performance

### Intégration Cross-Service

```bash
# Test d'intégration complète
veza-fixtures scenario --run integration
```

**Valide:**
- ✅ Communication inter-services
- ✅ Cohérence des données
- ✅ Gestion des erreurs
- ✅ Performance sous charge

## 🔧 Configuration Avancée

### Environnements

```typescript
// fixtures/environments/staging.ts
export const stagingConfig = {
  generation: {
    users: { count: 500 },
    audio: { trackCount: 2000 },
    conversations: { directCount: 200 }
  },
  database: {
    host: 'staging-db.example.com'
  }
}
```

### Personnalisation des Générateurs

```typescript
// Configuration Faker personnalisée
import { vezaFaker } from '@veza/fixtures'

vezaFaker.music.songTitle = () => {
  return 'Mon Titre Personnalisé'
}
```

### Hooks et Middleware

```typescript
// Hooks de génération
DataRelationManager.onUserGenerated((user) => {
  console.log(`Utilisateur créé: ${user.username}`)
})
```

## 🧪 Tests et Validation

### Tests Unitaires

```bash
# Lancer les tests
npm test

# Coverage
npm run test:coverage
```

### Validation des Données

```bash
# Validation complète
npm run validate -- --check-relations --check-performance

# Validation spécifique
npm run validate -- --service chat-server
```

### CI/CD Integration

Le système s'intègre automatiquement avec GitHub Actions :

- ✅ **Validation PR** - Vérification des fixtures modifiées
- ✅ **Tests nightly** - Tests complets quotidiens
- ✅ **Performance regression** - Détection de régressions

## 📈 Monitoring et Métriques

### Métriques de Génération

```bash
# Statistiques détaillées
veza-fixtures status --verbose
```

**Affiche:**
- 📊 Nombre d'entités par type
- ⏱️ Temps de génération
- 🔗 Cohérence des relations
- 💾 Utilisation mémoire

### Health Checks

```typescript
// Vérification de santé des services
const health = await ChatServerFixtures.healthCheck()
console.log(health) // { database: true, redis: true, dataConsistency: true }
```

## 🚀 Cas d'Usage

### Développement Local

```bash
# Setup rapide pour développement
npm run dev:with-fixtures
```

### Tests Automatisés

```bash
# Tests avec données fraîches
npm run test:with-fixtures
```

### Démonstrations Client

```bash
# Dataset de démo professionnel
veza-fixtures generate --env demo --format json
```

### Tests de Performance

```bash
# Stress test complet
veza-fixtures scenario --run high-load
```

## 🔍 Dépannage

### Problèmes Courants

**Erreur de connexion base de données:**
```bash
# Vérifier la configuration
veza-fixtures status
# Diagnostics complets
./tools/scripts/install.sh doctor
```

**Données incohérentes:**
```bash
# Validation et correction
veza-fixtures validate --check-relations
veza-fixtures clean --force
veza-fixtures seed --validate
```

**Performance lente:**
```bash
# Réduire la taille du dataset
veza-fixtures generate --users 50 --tracks 100
```

### Logs et Debug

```bash
# Mode verbose
DEBUG=veza:fixtures npm run generate

# Logs détaillés
veza-fixtures generate --verbose
```

## 🤝 Contribution

### Développement

```bash
# Setup développement
git clone https://github.com/your-org/veza-platform.git
cd fixtures
npm install
npm run build

# Tests
npm test
npm run lint
```

### Ajout de Générateurs

```typescript
// fixtures/core/generators/my-generator.ts
export class MyGenerator {
  static generate() {
    // Implémentation
  }
}
```

### Nouveaux Scénarios

```typescript
// fixtures/scenarios/my-scenario/index.ts
export class MyScenario {
  static async setup() {
    // Configuration du scénario
  }
}
```

## 📚 Documentation API

### Classes Principales

- **`VezaFixtures`** - Point d'entrée principal
- **`DataRelationManager`** - Gestion des relations
- **`UserGenerator`** - Génération d'utilisateurs
- **`AudioGenerator`** - Génération de contenu audio
- **`ConversationGenerator`** - Génération de conversations

### Interfaces

- **`FixtureConfig`** - Configuration système
- **`User`**, **`Audio`**, **`Conversation`** - Types de données
- **`ScenarioContext`** - Contexte de scénario

## 📝 Changelog

### Version 1.0.0
- ✅ Système de fixtures complet
- ✅ Générateurs avancés
- ✅ Intégration multi-services
- ✅ Scénarios de test
- ✅ CLI tools
- ✅ CI/CD integration

## 📄 Licence

MIT License - voir [LICENSE](./LICENSE) pour les détails.

## 🆘 Support

- 📧 **Email**: fixtures-support@veza-platform.com
- 💬 **Discord**: [Veza Platform Community](https://discord.gg/veza)
- 🐛 **Issues**: [GitHub Issues](https://github.com/your-org/veza-platform/issues)
- 📖 **Docs**: [Documentation complète](https://docs.veza-platform.com/fixtures)

---

**Fait avec ❤️ par l'équipe Veza Platform**