# Spécifications Fonctionnelles
## Application "Livre dont vous êtes le héros" - IA Interactive

**Version:** 1.0  
**Date:** 31 Décembre 2025  
**Statut:** Spécifications initiales

---

## 1. Vue d'ensemble du projet

### 1.1 Objectif
Créer une plateforme web interactive permettant aux joueurs de vivre des histoires narratives générées et guidées par une intelligence artificielle. L'utilisateur devient le héros de sa propre aventure à travers deux modes de jeu : choix multiples ou dialogue libre.

### 1.2 Public cible
- Amateurs de fiction interactive
- Passionnés de jeux de rôle narratifs
- Lecteurs créatifs souhaitant personnaliser leurs histoires
- Créateurs de contenu (mode joueur/éditeur)

### 1.3 Proposition de valeur
- Histoires uniques générées par IA adaptées aux préférences du joueur
- Liberté totale de personnalisation (genre, époque, réalisme)
- Expérience immersive avec interface sobre type bibliothèque ancienne
- Sauvegarde intelligente via système LoreBook

---

## 2. Fonctionnalités principales

### 2.1 Gestion des utilisateurs

#### 2.1.1 Inscription / Connexion
**Inscription simple :**
- Email
- Mot de passe (avec confirmation)
- Pseudo/nom d'utilisateur
- Validation par email

**Connexion :**
- Email + mot de passe
- Option "Se souvenir de moi"
- Récupération de mot de passe

**Profil utilisateur :**
- Informations personnelles basiques
- Liste des histoires créées
- Statistiques (histoires terminées, en cours, publiées)

#### 2.1.2 Gestion multi-histoires
- Un joueur peut créer et gérer plusieurs histoires simultanément
- Chaque histoire est indépendante avec :
  - Son propre contexte
  - Son LoreBook dédié
  - Ses paramètres de jeu
  - Son statut (privée ou publiée)

### 2.2 Système de publication

#### 2.2.1 Modes de visibilité
**Mode privé (par défaut) :**
- Visible uniquement par le créateur
- Modifications possibles à tout moment

**Mode publié (publication progressive) :**
- Activé par le joueur/éditeur volontaire
- **L'histoire peut être publiée même si elle n'est pas terminée**
- Publication type "série à épisodes" : l'auteur continue d'écrire et publie chapitre après chapitre
- **Le passé déjà publié est figé** (chapitres publiés ne peuvent plus être modifiés)
- **L'auteur peut continuer à écrire** : les nouveaux chapitres s'ajoutent progressivement
- Les lecteurs peuvent **suivre l'histoire en cours d'écriture**
- Métadonnées visibles : titre, genre, époque, description, statut (en cours / terminée)

**Version lecteur (nettoyée) :**
Les lecteurs voient une **version purement narrative** :
- Uniquement les passages narratifs de l'IA et les actions du personnage
- **Masquage complet des échanges techniques** (messages OFF, instructions à l'IA)
- **Masquage des choix non sélectionnés** (seul le choix retenu est visible en tant qu'action du héros)
- Format fluide type roman, sans interface de jeu
- Impression de lire une histoire cohérente écrite d'un seul jet

**Exemple de transformation :**
```
Version auteur (privée) :
[Passage IA] : "Tu te tiens devant la porte..."
[Choix A] : Entrer prudemment
[Choix B] : Contourner
[Choix C] : Examiner les gargouilles
[Choix D] : Utiliser le médaillon ← sélectionné
[Message OFF de l'auteur] : "Fais en sorte que le médaillon révèle quelque chose"
[Passage IA suivant] : "Le médaillon émet une lueur dorée..."

Version lecteur (publique) :
"Tu te tiens devant la porte... Tu décides d'utiliser le médaillon. 
Le médaillon émet une lueur dorée..."
```

#### 2.2.2 Galerie publique
- Page de découverte des histoires publiées
- Filtres : genre, époque, popularité, date, **statut (terminée/en cours)**
- Système de favoris/likes
- Lecture intégrale en mode spectateur
- **Suivi des histoires en cours** : notification quand un nouveau chapitre est publié (futur)
- Badge "En cours d'écriture" pour les histoires actives
- Affichage du dernier chapitre disponible

---

## 3. Création et configuration d'une histoire

### 3.1 Flux de création

**Étape 1 : Paramètres initiaux**
Le joueur définit :
- **Genre** : entrée libre (fantasy, science-fiction, policier, historique, romance, horreur, aventure, etc.)
- **Époque** : entrée libre (médiéval, Renaissance, années 1920, contemporain, futur proche, dystopique 2150, etc.)
- **Niveau de réalité** : curseur ou choix gradué
  - 100% fiction (mondes imaginaires, magie, créatures fantastiques)
  - Fiction inspirée du réel (événements historiques romancés)
  - Réalisme historique/factuel
- **Perspective narrative** : choix entre deux options
  - **"Tu" (2ème personne)** : Style classique "livre dont vous êtes le héros"
    - Exemple : "Tu te tiens devant le château..."
  - **"Il/Elle" (3ème personne)** : Style "livre dont vous contrôlez le héros"
    - Si sélectionné : champs supplémentaires
      - Nom du protagoniste (optionnel) : "Aria", "Marcus", etc.
      - Genre : "Il" ou "Elle"
    - Exemple : "Aria se tient devant le château..." ou "Elle se tient devant le château..."

**Étape 2 : Questions de contextualisation**
L'IA pose 3-5 questions pour affiner l'histoire :
- Type de protagoniste souhaité ?
- Ambiance générale (sombre, légère, épique, intimiste) ?
- Thèmes préférés (amitié, vengeance, découverte, survie) ?
- Éléments spécifiques à intégrer (un lieu, un objet, un type de personnage) ?

**Étape 3 : Génération du squelette narratif**
L'IA génère un plan d'histoire structuré :
- **Acte I** : Situation initiale, déclencheur de l'aventure
- **Acte II** : Développement, obstacles, révélations
- **Acte III** : Climax, résolution

Le squelette inclut :
- 3-5 points de passage clés (événements importants)
- 2-3 retournements potentiels
- Direction générale de l'arc narratif
- Flexibilité pour adaptation selon les choix du joueur

**Étape 4 : Génération de la couverture**
- Génération automatique d'une image type couverture de livre via DALL-E
- Basée sur : genre + époque + ambiance + éléments clés
- Style visuel : artistique, évocateur, adapté au thème
- Le joueur peut régénérer s'il n'est pas satisfait

**Étape 5 : Choix du mode de jeu**
- **Mode Choix Multiples** : l'IA propose 3-4 options à chaque étape
- **Mode Dialogue Libre** : le joueur écrit ce qu'il souhaite faire

### 3.2 Titre de l'histoire
- Proposé automatiquement par l'IA après la configuration
- Modifiable par le joueur à tout moment
- Exemple : "Les Chroniques de Sylvandre" / "1942 : L'Ombre de Berlin"

---

## 4. Modes de jeu

### 4.1 Mode Choix Multiples

**Fonctionnement :**
1. L'IA génère un passage narratif (150-300 mots)
2. Présentation de 3-4 choix d'action :
   - **A)** Option pragmatique
   - **B)** Option audacieuse
   - **C)** Option réfléchie
   - **D)** Option alternative/créative
   - **E)** "Autre action..." → **Ouvre un champ de texte libre**
3. Le joueur sélectionne un choix prédéfini OU écrit une action personnalisée
4. L'IA continue la narration en fonction du choix

**Avantages :**
- Progression guidée et structurée
- Idéal pour les nouveaux joueurs
- Rythme narratif maîtrisé
- **Flexibilité** : possibilité d'action personnalisée à tout moment

### 4.2 Mode Dialogue Libre

**Fonctionnement :**
1. L'IA génère un passage narratif (150-300 mots)
2. Le joueur écrit librement son action/réponse dans une zone de texte
   - **Action narrative** : "Je m'approche prudemment de la porte et écoute"
   - **Instruction technique (mode "off")** : "Je voudrais que l'ambiance devienne plus sombre" ou "Introduis un personnage mystérieux"
3. L'IA interprète l'intention et génère la suite

**Type de messages :**
- **Messages narratifs** : actions du personnage, dialogues (mode par défaut)
- **Messages "off" / instructions techniques** : directives à l'IA pour orienter l'histoire
  - Préfixe suggéré : "[OFF]" ou toggle "Mode instruction"
  - Exemples : "[OFF] Fais en sorte que ce personnage devienne un allié", "[OFF] Je veux un retournement inattendu"
  - Ces messages ne sont **pas visibles dans la version publique** de l'histoire

**Contraintes :**
- Limite de caractères par action (500-1000 caractères)
- Modération du contenu utilisateur

**Avantages :**
- Liberté créative totale
- Immersion maximale
- Possibilités infinies
- **Contrôle narratif** : le joueur peut guider l'IA comme un co-auteur

### 4.3 Messages "hors narratif" (mode OFF)

**Concept :**
Les joueurs/éditeurs peuvent envoyer des **instructions techniques à l'IA** qui ne font pas partie de la narration, mais servent à diriger l'histoire.

**Utilisation :**
- **En mode Choix Multiples** : via l'option "Autre action..." (champ libre)
- **En mode Dialogue Libre** : via un toggle ou préfixe [OFF]

**Exemples de messages OFF :**
- "Introduis un personnage secondaire qui sera important plus tard"
- "Je veux que l'ambiance devienne plus oppressante"
- "Fais en sorte que le prochain événement soit un retournement majeur"
- "Je souhaite que mon personnage développe une relation amicale avec ce PNJ"

**Traitement par l'IA :**
- L'IA intègre la directive dans sa génération suivante
- Pas de réponse narrative directe au message OFF
- La directive influence subtilement (ou explicitement) la suite de l'histoire

**Visibilité :**
- Ces messages sont **enregistrés en base de données** avec un flag `is_technical`
- Ils **ne sont PAS affichés** dans la version publique de l'histoire
- Seul l'auteur peut les voir dans son historique privé
- Permet de garder une version "nettoyée" pour les lecteurs

### 4.4 Changement de mode
- Le joueur peut basculer d'un mode à l'autre à tout moment
- L'historique est conservé quel que soit le mode
- Les messages OFF restent accessibles à l'auteur, invisibles pour les lecteurs

---

## 5. Système LoreBook

### 5.1 Concept
Le LoreBook est une base de connaissances dynamique qui résume les éléments importants de l'histoire en cours. Il permet de :
- Maintenir la cohérence narrative
- Éviter les prompts trop longs à l'API
- Préserver la mémoire des événements clés

### 5.2 Contenu du LoreBook

**Catégories trackées :**
- **Personnages** : nom, traits descriptifs, rôle, relation avec le protagoniste
- **Lieux** : descriptions, importance narrative
- **Objets clés** : artefacts, indices, possessions importantes
- **Événements majeurs** : tournants de l'histoire, révélations
- **Relations** : alliances, conflits, dynamiques entre personnages
- **État du protagoniste** : traits actuels, évolution, blessures, acquisitions

**Exemple de structure :**
```json
{
  "personnages": [
    {
      "nom": "Elara",
      "description": "Magicienne âgée, sage mais mystérieuse",
      "traits": ["sagesse", "méfiance", "connaissance des anciens"],
      "relation": "Mentor potentiel, cache des secrets"
    }
  ],
  "evenements_cles": [
    "Découverte du médaillon dans les ruines",
    "Trahison du compagnon Marcus",
    "Vision prophétique dans le temple"
  ],
  "etat_protagoniste": {
    "traits": ["courageux", "impulsif", "loyal"],
    "possessions": ["médaillon ancien", "carte cryptée"],
    "blessures": ["égratignure à l'épaule"]
  }
}
```

### 5.3 Mise à jour automatique
**Déclencheurs de mise à jour :**
- Rencontre d'un nouveau personnage important
- Découverte d'un lieu significatif
- Obtention/perte d'un objet clé
- Événement majeur affectant l'intrigue
- Évolution importante du protagoniste

**Processus :**
1. À chaque interaction, l'IA évalue si l'action est "importante"
2. Si oui → ajout/modification du LoreBook en arrière-plan
3. Le joueur n'est jamais interrompu
4. Le LoreBook est inclus dans le contexte des prochains prompts

### 5.4 Consultation (optionnelle)
- Le joueur peut consulter son LoreBook via un menu
- Présentation organisée et lisible
- Utile pour se remémorer l'histoire après une pause

---

## 6. Système de traits descriptifs

### 6.1 Principe
Pas de statistiques numériques (pas de "Force: 15" ou "HP: 100").  
Tout est descriptif et narratif.

### 6.2 Traits de personnage
**Exemples de traits :**
- Physiques : "robuste", "agile", "frêle", "imposant"
- Mentaux : "rusé", "impulsif", "réfléchi", "charismatique"
- Compétences : "expert en navigation", "formé au combat", "connaissances en herboristerie"
- Faiblesses : "peur du noir", "naïf", "têtu"

### 6.3 Utilisation par l'IA
L'IA utilise ces traits pour :
- Proposer des choix cohérents avec le personnage
- Déterminer le succès/échec d'actions
- Créer des défis adaptés
- Faire évoluer le personnage

**Exemple :**
- Joueur "agile" → a plus de chances de réussir une acrobatie
- Joueur "impulsif" → l'IA peut proposer des choix risqués tentants
- Joueur "charismatique" → les PNJ réagissent plus favorablement

### 6.4 Évolution
Les traits peuvent évoluer durant l'histoire :
- Acquisition de nouvelles compétences
- Développement de forces
- Apparition de blessures/faiblesses temporaires

---

## 7. Modération du contenu

### 7.1 Modération de l'IA
**Filtres appliqués aux générations :**
- Éviter la violence graphique excessive
- Bloquer le contenu sexuel explicite
- Pas de promotion de comportements dangereux
- Respect des contenus sensibles (racisme, discrimination, etc.)

**Paramètres OpenAI :**
- Utilisation des guardrails de modération d'OpenAI
- Prompts système incluant des directives de modération
- Ton adapté : aventure, suspense, mais toujours approprié

### 7.2 Modération du contenu utilisateur
**En mode Dialogue Libre :**
- Filtrage des inputs utilisateur avant envoi à l'API
- Rejet des tentatives de jailbreak ou contenu inapproprié
- Message d'avertissement si contenu bloqué

### 7.3 Signalement
- Possibilité de signaler une histoire publiée problématique
- Revue manuelle par modération

---

## 8. Sauvegarde et persistance

### 8.1 Sauvegarde automatique
- Chaque action/tour est automatiquement sauvegardé
- Aucun risque de perte de progression
- Synchronisation immédiate avec la base de données

### 8.2 Historique complet
Chaque histoire conserve :
- Tous les passages narratifs générés
- Tous les choix/actions du joueur (narratifs ET techniques)
- **Flag `is_technical`** : distingue les messages narratifs des instructions OFF
- **Choix non sélectionnés** (en mode choix multiples) pour historique auteur
- Horodatage de chaque interaction
- État du LoreBook à chaque étape (versioning)

**Deux vues de l'historique :**
- **Vue auteur (privée)** : historique complet avec tous les échanges, choix, et messages OFF
- **Vue publique (lecteurs)** : historique nettoyé, uniquement la narration fluide

### 8.3 Reprise de partie
- Le joueur peut reprendre exactement où il s'est arrêté
- Affichage des derniers passages pour se remémorer le contexte
- Accès au LoreBook pour rafraîchir la mémoire

---

## 9. Interface et expérience utilisateur

### 9.1 Ambiance générale
**Thème : Bibliothèque ancienne**
- Tons chauds et automnaux (ocre, brun, beige, bordeaux)
- Textures parchemin, papier vieilli
- Typographies serif élégantes (style livre ancien)
- Ambiance cosy et immersive

### 9.2 Navigation
**Pages principales :**
1. **Accueil/Landing** : présentation du concept, appel à l'action
2. **Dashboard** : liste des histoires du joueur (en cours, terminées)
3. **Galerie publique** : histoires partagées par la communauté
4. **Création d'histoire** : wizard de configuration
5. **Page de jeu** : interface de narration immersive
6. **Profil utilisateur** : paramètres et statistiques

### 9.3 Page de jeu
**Disposition :**
- Zone centrale : texte narratif (style livre)
- Couverture de l'histoire en haut ou en sidebar
- Choix/zone de texte en bas
- Menu discret (pause, LoreBook, options)
- Indicateurs subtils : chapitres/progression

---

## 10. Limites et contraintes techniques

### 10.1 Gestion des tokens
- Utilisation de LoreBook pour optimiser les prompts
- Résumé périodique des anciens passages si l'histoire devient très longue
- Monitoring des coûts API

### 10.2 Rate limiting
- Limite raisonnable d'actions par minute (éviter le spam)
- Quota de génération d'images par jour/utilisateur

### 10.3 Pas de limite de longueur
- Les histoires peuvent durer indéfiniment
- Système de chapitrage automatique (tous les X passages) pour organisation

---

## 11. Évolutions futures (hors MVP)

### 11.1 Fonctionnalités envisagées
- Illustrations générées durant l'histoire (pas que couverture)
- Mode multijoueur (2 joueurs, 1 histoire partagée)
- Système de succès/achievements narratifs
- Export de l'histoire en PDF/ebook
- IA vocale (narration audio)
- Communauté : commentaires, recommandations
- Abonnement premium (accès illimité, modèles IA avancés)

### 11.2 Intégrations
- OAuth (Google, Discord) pour connexion
- Partage sur réseaux sociaux
- Webhooks Discord/Slack pour notifications

---

## 12. Règles métier

### 12.1 Squelette d'histoire
- **Obligatoire** : généré avant de débuter la narration
- **Flexible** : peut être modifié par l'IA si les choix divergent
- **Invisible au joueur** : ne doit pas briser l'immersion
- **Objectif** : donner cohérence, direction, et rythme narratif

### 12.2 Cohérence narrative
- L'IA doit respecter les événements passés (via LoreBook)
- Les personnages conservent leur personnalité
- Les lieux restent cohérents
- Les objets ne disparaissent pas sans raison

### 12.3 Longueur des passages
- **Narration IA** : 150-300 mots par passage (ajustable)
- **Action joueur (mode libre)** : 500-1000 caractères max
- **Choix (mode multiples)** : 4 options maximum

### 12.4 Fréquence des événements clés
- Points de passage du squelette : tous les 5-10 tours
- Retournements : 1-2 par acte
- Cliffhangers : en fin de session suggérée (optionnel)

---

## 13. Glossaire

- **LoreBook** : Base de connaissances résumant les éléments clés d'une histoire
- **Squelette narratif** : Plan structuré de l'histoire générée avant de commencer
- **Traits descriptifs** : Qualificatifs narratifs décrivant un personnage (pas de stats numériques)
- **Mode Choix Multiples** : Gameplay avec options A/B/C/D proposées par l'IA + option texte libre
- **Mode Dialogue Libre** : Gameplay où le joueur écrit librement ses actions
- **Message OFF / Instruction technique** : Message hors narratif envoyé à l'IA pour diriger l'histoire (invisible en version publique)
- **Version nettoyée** : Version publique d'une histoire masquant les échanges techniques et choix non retenus
- **Publication progressive** : Publication chapitre par chapitre d'une histoire en cours d'écriture (type série)
- **Joueur/Éditeur** : Utilisateur qui accepte de publier son histoire (terminée ou en cours)
- **Perspective narrative** : Point de vue de la narration (2ème personne "Tu" ou 3ème personne "Il/Elle")
- **Livre dont vous êtes le héros** : Narration en 2ème personne ("Tu")
- **Livre dont vous contrôlez le héros** : Narration en 3ème personne ("Il/Elle" + nom optionnel)

---

**Document vivant** : Ces spécifications seront affinées durant le développement en fonction des retours et tests utilisateurs.