dd-timer/docs/algorithmes.md

# Algorithmes de calcul — Obsidienne

Ce document décrit tous les algorithmes utilisés dans l'application, expliqués simplement.

---

## 1. Système de tiers des jauges

Chaque jauge (baffeur, caresseur, foudroyeur, abreuvoir, dragofesse, mangeoire) a un **niveau** entre 0 et 100 000.
Ce niveau détermine un **tier** qui fixe la vitesse de conversion :

| Niveau de jauge | Tier | Taux (pts / 10 sec) |
|-----------------|------|---------------------|
| 0 – 40 000      | 1    | 10                  |
| 40 001 – 70 000  | 2    | 20                  |
| 70 001 – 90 000  | 3    | 30                  |
| 90 001 – 100 000 | 4    | 40                  |

**Principe** : La jauge se **vide** en donnant des points à la DD. Plus la jauge est haute, plus elle se vide vite (tier élevé = plus de points par tick).

Un "tick" = 10 secondes de timer.

---

## 2. Calcul des points gagnés dans le temps — `gainedIn(lvl, sec)`

**Question** : "Si ma jauge démarre au niveau `lvl` et tourne pendant `sec` secondes, combien de points ma DD gagne-t-elle ?"

**Algorithme** :
1. On part du haut (tier 4) et on descend
2. Pour chaque palier, on calcule combien de ticks on peut consommer avant de passer au palier en-dessous
3. On additionne les points de chaque palier traversé

**Exemple** : Jauge à 95 000, timer 60 sec (= 6 ticks)
- Tier 4 (90k–100k) : 5 000 pts dispo ÷ 40/tick = 125 ticks possibles → on en utilise 6 → gain = 6 × 40 = **240 pts**
- Jauge restante : 95 000 - 240 = 94 760

La jauge descend au fur et à mesure qu'elle donne des points. Quand elle passe sous un seuil de tier, le taux ralentit.

---

## 3. Temps pour gagner X points — `timeToGain(lvl, pts)`

**Question** : "Combien de temps faut-il pour gagner `pts` points depuis une jauge au niveau `lvl` ?"

C'est l'inverse de `gainedIn`. On parcourt les paliers du haut vers le bas :
1. Pour chaque tier, combien de points peut-on donner avant de descendre au palier suivant ?
2. On prend le minimum entre les points disponibles et les points restants à donner
3. On calcule le temps correspondant : `ceil(points / taux) × 10 sec`

Si la jauge se vide complètement avant d'atteindre l'objectif → retourne `Infinity` (impossible).

**Cas "vidange complète"** : `timeToGain(lvl, lvl)` donne le temps pour vider entièrement la jauge. C'est cette formule qu'utilisent à la fois l'affichage "Vide en" et le timer XP quand la cible est hors de portée d'une seule charge.

---

## 4. Niveau de jauge après X secondes — `gaugeAfter(lvl, sec)`

**Question** : "Si ma jauge démarre à `lvl` et tourne `sec` secondes, à quel niveau sera-t-elle ?"

Même logique que `gainedIn`, mais au lieu de compter les points donnés, on soustrait directement du niveau de la jauge.

---

## 5. Temps écoulé — `elapsed` et `elapsedLive`

### `elapsed(timer)` — temps figé pour l'affichage

Calcule les secondes écoulées depuis le démarrage du timer d'un enclos, en excluant les pauses. **Se fige** quand le timer est en pause ou terminé :

```
Si en cours     : (maintenant - démarrage - temps_en_pause) / 1000
Si en pause     : (moment_pause - démarrage - temps_en_pause) / 1000
Si non démarré  : 0
```

Utilisé pour : l'affichage "Temps écoulé", le dashboard.

### `elapsedLive(enc)` — temps réel après complétion automatique

Retourne un temps qui **continue de progresser en temps réel** même après que la session s'est terminée automatiquement. Cela permet aux jauges de continuer à se vider en arrière-plan après l'alarme.

```
Si enc.alerted['__done__'] est positionné :
    → (Date.now() - startTime - pausedMs) / 1000  (jamais figé)
Sinon :
    → elapsed(enc.timer)  (comportement normal, fige sur pause)
```

**`enc.alerted['__done__']`** est posé par la commande `complete-timer` quand toutes les cibles sont atteintes. Ce flag distingue une "fin naturelle de session" (jauges continuent) d'une "pause manuelle" (jauges figées).

Utilisé pour : tous les calculs de jauges dans `computeGaugeLive`, `enclosGaugeCurGl`, `calcSerenEtaLive`, `calcLevelEtaLive`.

---

## 6. Gel de jauge au cap absolu des stats et calcul par segments — `computeGaugeState`

### 6.1 Gel au cap absolu

Quand une **stat** atteint sa **limite absolue** (sérénité ±5000, endurance/maturité/amour 20 000), la jauge correspondante **s'arrête de se vider** — il n'y a plus rien à donner à la DD.

**Points jusqu'au cap** (`ptsToAbsCap`) :
- Stat normale : `dir>0 ? (statMax - startSt) : (startSt - statMin)` — la jauge continue **même après la cible**, jusqu'au cap absolu de la stat
- XP / mangeoire : `xpForLevel(200) - xpForLevel(niveauDépart)` — la jauge gèle uniquement au niveau 200, **jamais à la cible XP**

**Comportement après la cible** : les jauges ne s'arrêtent PAS quand la cible d'une DD est atteinte. Elles continuent de se vider jusqu'à ce que la stat atteigne son cap absolu (ex: sérénité à -5000, même si la cible était -60). Cela garantit que l'affichage reste cohérent et que les DDs continuent de progresser en fond.

**Affichage global de la jauge de stat (enclos)** : la jauge de stat se fige quand la **dernière** DD atteint son cap absolu. La mangeoire continue de se vider jusqu'au niveau 200.

### 6.2 Calcul par segments avec recharges — `computeGaugeState(startGl, recharges, ptsAllowed, el)`

Quand le joueur recharge une jauge en cours de session, le calcul se découpe en **segments** :

```
Segment 1 : startGl → recharge[0].atSec  (ou fin du timer si pas de recharge)
Segment 2 : recharge[0].level → recharge[1].atSec
...
Segment N : recharge[N-1].level → el
```

Pour chaque segment :
1. Calculer la durée du segment
2. Calculer les points gagnés dans ce segment avec `gainedIn`
3. Vérifier si le cap (`ptsAllowed`) est atteint → si oui, calculer le moment exact du gel et stopper
4. Si non, passer au segment suivant avec le nouveau niveau de jauge après recharge

**Retourne** : `{ gained, curGl, effectiveEl }`
- `gained` : points totaux accumulés sur tous les segments
- `curGl` : niveau de jauge au moment du gel (ou à `el` si pas de gel)
- `effectiveEl` : temps réel de fonctionnement (≤ el, limité par le gel)

---

## 7. Calcul unifié d'une jauge — `computeGaugeLive(enc, dd, gid, el, started)`

C'est le **cœur du système**. Pour chaque DD et chaque jauge active, il calcule en temps réel :
- La stat estimée actuelle
- Si la cible est atteinte
- Le % de progression
- Le countdown restant

> **Note sur le paramètre `el`** : bien que la signature accepte un paramètre `el` (elapsed), il est **ignoré en interne**. La fonction appelle systématiquement `elapsedLive(enc)` pour ses calculs, ce qui garantit que les jauges continuent de progresser après la fin de session. Le paramètre `el` est conservé dans la signature pour la compatibilité des appels depuis `enclosGlobalState`.

### Pour les jauges normales (sérénité, endurance, maturité, amour) :

1. On récupère le **snapshot** de la jauge et de la stat au moment du démarrage du timer
2. On appelle `computeGaugeState(startGl, recharges, ptsToAbsCap, elLive)` pour obtenir les points gagnés en tenant compte des recharges et du gel
3. On applique la direction (`dir`) :
   - `dir = +1` (caresseur, foudroyeur, abreuvoir, dragofesse) : stat monte
   - `dir = -1` (baffeur) : stat descend
4. On clamp la stat dans ses bornes (ex: sérénité entre -5000 et +5000)
5. On calcule le temps total et le countdown via `timeToGain`

### Pour la mangeoire (XP) — même modèle que les autres jauges :

La mangeoire se vide exactement comme les autres jauges (même tiers, même dégression). L'XP suit le même algorithme :

1. XP gagnée = via `computeGaugeState` (tient compte des recharges et du gel à niveau 200)
2. XP nécessaire = `xpForLevel(cible) - xpForLevel(départ)`
3. Niveau estimé = `levelFromXp(xpDépart + xpGagnée)`
4. Countdown = `timeToGain(curGl, Math.min(xpRestante, curGl))` — si la cible dépasse la capacité de la jauge, on affiche le temps de vidange complète

**Cible XP par défaut** : si `dd.levelTarget === null`, on cible le niveau 200.

**Exemple** : mangeoire à 85 000 (tier 3) pendant 7 000 sec (700 ticks) :
- 500 ticks à 30 XP/tick (tier 3, 70k→85k) = 15 000 XP, jauge → 70 000
- 200 ticks à 20 XP/tick (tier 2) = 4 000 XP, jauge → 66 000
- Total = **19 000 XP** (contre 21 000 XP avec un taux fixe erroné)

---

## 8. Table d'XP et niveaux

### Table XP_RAW

Dictionnaire de 200 entrées : `niveau → XP cumulatif total`.

Exemples :
- Niveau 1 → 0 XP
- Niveau 10 → 809 XP
- Niveau 50 → 34 365 XP
- Niveau 100 → 172 668 XP
- Niveau 200 → 867 582 XP

Les valeurs sont **cumulatives** (pas incrémentales).

### `xpForLevel(lvl)` : Retourne l'XP cumulatif pour atteindre le niveau `lvl`.

### `levelFromXp(xp)` : Retourne le plus haut niveau atteint avec `xp` points d'XP cumulatifs. Parcourt la table de 200 à 1 pour trouver le seuil.

---

## 9. ETA Sérénité — `calcSerenEta` / `calcSerenEtaLive`

### Version statique (`calcSerenEta`)
1. Calcule `diff = cible - sérénité actuelle`
2. Si `diff > 0` → besoin du caresseur (monte la sérénité)
3. Si `diff < 0` → besoin du baffeur (baisse la sérénité)
4. Temps = `timeToGain(niveauJauge, |diff|)`

### Version live (`calcSerenEtaLive`)
1. Utilise `computeGaugeState` pour obtenir la sérénité estimée en temps réel (avec recharges et gel)
2. Recalcule le diff depuis cette estimation
3. Calcule le temps restant avec les points encore à parcourir

---

## 10. ETA Niveau — `calcLevelEta` / `calcLevelEtaLive`

### Version statique (`calcLevelEta`)
1. XP nécessaire = `xpForLevel(cible) - xpForLevel(niveauActuel)`
2. Cible = `dd.levelTarget ?? 200`
3. Temps = `timeToGain(niveauMangeoire, Math.min(xpNécessaire, niveauMangeoire))`

### Version live (`calcLevelEtaLive`)
1. Cible = `dd.levelTarget ?? 200`
2. XP gagnée via `computeGaugeState` (avec recharges et gel)
3. Niveau estimé = `levelFromXp(xpDépart + xpGagnée)`
4. XP restante = `xpForLevel(cible) - xpForLevel(départ) - xpGagnée`
5. Countdown = `timeToGain(curGl, Math.min(xpRestante, curGl))`
   - Si XP restante ≤ capacité de la jauge : temps pour atteindre la cible
   - Sinon : temps de vidange complète (cohérent avec "Vide en")

---

## 11. Countdown global d'un enclos — `enclosGlobalState(enc)`

**Question** : "Dans combien de temps TOUTES les DD de cet enclos auront atteint TOUTES leurs cibles ?"

1. Pour chaque DD × chaque jauge active → appeler `computeGaugeLive`
2. Prendre le **maximum** de tous les countdowns = le plus long à terminer
3. Compter combien de DD ont TOUTES leurs cibles atteintes (`ddDone`)
4. `allDone = true` si **toutes les jauges actives** de **toutes les DDs** ont atteint leur cible

**Règle d'alarme unique** : la session se termine (`complete-timer`) une seule fois, au timer le plus long. Si un enclos a baffeur + mangeoire, l'alarme ne sonne que quand les DEUX cibles (sérenité ET niveau XP) sont atteintes pour toutes les DDs. Il n'y a pas d'alarme intermédiaire quand une seule cible est atteinte.

**Prévisualisation avant démarrage** : la fonction calcule même quand le timer n'est pas démarré (`started = false`, `el = 0`). L'"Alarme dans" et les timers DD se mettent à jour en temps réel dès que le joueur saisit une valeur de jauge ou une cible — sans avoir à démarrer le timer.

## 11 bis. Vérification globale de complétion — `checkAllEnclosCompletion()` dans `App`

La vérification de complétion ne dépend pas de la vue active ni du focus de la fenêtre.

**Pourquoi pas dans la boucle rAF ?** `requestAnimationFrame` se **suspend** quand l'application Electron perd le focus OS (ex : l'utilisateur alt-tab vers une autre application). Si la détection était dans la boucle rAF, la notification ne sonnerait jamais quand l'utilisateur est hors de l'app.

**Solution** : `checkAllEnclosCompletion()` tourne dans un `window.setInterval(..., 1000)` indépendant, démarré dans `App.render()` et nettoyé dans `App.destroy()`. `setInterval` continue de s'exécuter même quand la fenêtre est en arrière-plan.

**Algorithme** :
1. Parcourt **tous** les enclos en cours (`summary.running = true`)
2. Pour chacun, récupère l'état complet et appelle `enclosGlobalState`
3. Si `allDone = true`, exécute `complete-timer` → alarme + notification immédiate

**Double protection** : `EnclosView.update()` appelle aussi `complete-timer` quand `allDone && running` (quand l'utilisateur est sur l'enclos). Le handler `complete-timer` possède un guard `if (!enc.timer.running || enc.alerted['__done__']) return` pour éviter un double déclenchement.

---

## 12. Recharge de jauge en cours de session

Le joueur peut **recharger une jauge pendant que le timer tourne** (ex : remplir la mangeoire à mi-session).

### Enregistrement (`recharge-gauge`)

- Stocke `{ atSec: elapsed(), level: newLevel }` dans `timer.gaugeRecharges[gid]`
- Plusieurs recharges s'accumulent dans un tableau
- Le `reset-timer` vide tous les tableaux de recharge

### Impact sur le calcul

`computeGaugeState` segmente automatiquement le calcul entre chaque recharge :
- Segment 1 depuis `startGl` jusqu'à la première recharge
- Segment 2 depuis le nouveau niveau jusqu'à la recharge suivante (ou la fin)
- etc.

Le gel au cap absolu est vérifié dans chaque segment : si la stat atteint son cap avant la prochaine recharge, le gel est précis à la seconde près.

### Affichage

Les inputs de jauge affichent une bordure verte (classe `.gauge-inp-recharge`) pendant que le timer tourne, indiquant que toute nouvelle saisie sera interprétée comme une recharge.

---

## 13. Mises à jour en temps réel des inputs

Tous les champs de saisie (niveaux de jauges, stats des DD, cibles) déclenchent une mise à jour de l'état à **chaque frappe** via un listener `input`, en plus du `blur` final. Cela permet :

- L'"Alarme dans" de se recalculer instantanément pendant la saisie
- Les timers DD (XP, sérénité, etc.) de se mettre à jour à la volée
- Une expérience cohérente avant ET pendant le timer

Exception : les recharges de jauge ne sont déclenchées que sur `blur`/`Enter` (pas sur chaque frappe) pour éviter d'enregistrer des recharges partielles.

---

## 14. Arbre de réapprovisionnement — `calcAppro()`

**Question** : "Pour produire Q exemplaires de la race X, de quelles races et en quelles quantités ai-je besoin ?"

### Principe : décomposition récursive par génération

Chaque race de génération ≥ 2 est produite par le croisement de 2 races parentes (table `BREEDING_RECIPES`).

**Algorithme** :
1. On part de la race cible et de la quantité voulue
2. Pour chaque génération (de la plus haute à gen 2) :
   - Pour chaque race nécessaire à cette génération :
     - Calculer le nombre de couples nécessaires (voir §14.1)
     - Ajouter les parents nécessaires (chacun × nombre de couples) dans le pool
3. Les races gen 1 restantes = matières premières

### 14.1 Mécanisme du reproducteur

Un reproducteur est une DD réutilisable : elle peut faire plusieurs bébés.

```
Si 2×R ≥ Q  →  couples = ceil(Q / 2)
Sinon       →  couples = Q - R
```

Où `R` = nombre de reproducteurs, `Q` = quantité nécessaire.

---

## 15. Calcul d'inventaire avec contraintes ♂/♀ — `calcInventaire()`

**Question** : "Avec mon stock actuel de DD (mâles et femelles), quels croisements puis-je réaliser ?"

### Modèle de données
Chaque race dans l'inventaire : `{ m: mâles, f: femelles, n: neutres }`

### Algorithme : round-robin par génération

Pour chaque génération (2 → 10) :
1. Lister tous les croisements possibles à cette génération
2. **Boucle round-robin** : tant qu'au moins un croisement est possible :
   - Vérifier qu'on a 1 mâle-capable chez A ET 1 femelle-capable chez B (ou l'inverse)
   - Consommer les parents (priorité au stock réel m/f, puis les neutres n)
   - Ajouter 1 neutre (`n++`) à la race du bébé produit

### Priorité de consommation
```
takeMale   : si m > 0 → m--, sinon n--
takeFemale : si f > 0 → f--, sinon n--
```

---

## 16. Constantes des stats

| Stat      | Min    | Max    | Jauge(s) associée(s) |
|-----------|--------|--------|----------------------|
| Sérénité  | -5 000 | 5 000  | Baffeur (↓), Caresseur (↑) |
| Endurance | 0      | 20 000 | Foudroyeur (↑) |
| Maturité  | 0      | 20 000 | Abreuvoir (↑) |
| Amour     | 0      | 20 000 | Dragofesse (↑) |
| Niveau/XP | 1      | 200    | Mangeoire (↑) |

---

## 17. Système de snapshots

Quand le timer démarre (démarrage initial uniquement, pas lors d'une reprise de pause) :
- `snapGauges` : niveaux de toutes les jauges actives au moment du démarrage
- `snapStats[dd.id]` : stats de chaque DD au moment du démarrage
- `gaugeRecharges` : réinitialisé à `{}`

Tous les calculs utilisent ces snapshots comme point de départ. Une **reprise de pause** accumule uniquement `pausedMs` sans toucher aux snapshots.

---

## 18. Flux de session — enchaînement des sessions

### Session unique (sans jauges supplémentaires)
1. Timer démarré → `start-timer` prend les snapshots
2. Toutes les cibles atteintes → `complete-timer` déclenché
3. Session terminée : timer figé, bannière "Session terminée" visible, jauges continuent en fond
4. Clic "🔄 Nouvelle fournée" → `nouvelle-fournee` : reset complet + 1 DD neuve

### Session enchaînée (nouvelles stats à monter)
1. Session terminée (`alerted['__done__'] = true`)
2. Les **boutons de jauges sont déverrouillés** → l'utilisateur sélectionne de nouvelles jauges
3. L'utilisateur configure les niveaux de jauges pour la nouvelle session
4. Clic "▶ Démarrer" → `start-timer` détecte `alerted['__done__']` → **démarrage initial** (pas reprise de pause) → nouveaux snapshots pris avec les stats actuelles des DD
5. Nouvelle session démarre : les stats des DD reflètent les gains de la session précédente

**Règle de déverrouillage des jauges** : `locked = started && !enc.alerted['__done__']`
Les jauges sont verrouillées uniquement pendant une session active (running ou en pause manuelle). Elles sont déverrouillées une fois la session terminée automatiquement.

**Bouton timer** : affiche "▶ Reprendre" uniquement en cas de pause manuelle (`pausedAt` et `!alerted['__done__']`). Après complétion automatique, affiche "▶ Démarrer" (nouvelle session).

---

## 19 bis. Commande `nouvelle-fournee`

Remet l'enclos dans un état "vierge" pour une nouvelle fournée complète :
- Reset timer (efface startTime, snapshots, alerted, recharges)
- Remet tous les niveaux de jauges à 0
- Supprime toutes les DDs
- Ajoute 1 nouvelle DD avec les stats de base (`serenite: 0, endurance: 0, maturite: 0, amour: 0, xp: 1`)

Distinct de `reset-timer` (qui remet seulement le timer à zéro, conserve les DDs et les jauges) et de `clear-enclos` (qui remet tout à zéro incluant les jauges actives et le nom).

---

## 18. Cycle de vie de `complete-timer`

La commande `complete-timer` représente la **fin naturelle d'une session** (toutes les cibles atteintes). Elle est distincte d'un simple `stop-timer` (pause manuelle).

### Ce que fait `complete-timer`
1. **Guard** : si `enc.timer.running = false` ou si `enc.alerted['__done__']` est déjà posé → retourne immédiatement (idempotent, pas de double alarme)
2. Pose `enc.timer.running = false`
3. Pose `enc.timer.pausedAt = Date.now()` — gèle `elapsed()` à l'instant de complétion
4. Pose `enc.alerted['__done__'] = true` — active le mode "continuation en fond" dans `elapsedLive`
5. Persiste l'état via `repo.save()`
6. Émet l'événement `timer-completed` → déclenche alarme audio + notification Windows/mobile

### Différence avec `stop-timer` (pause manuelle)
- `stop-timer` : pose `running = false` et `pausedAt` mais **ne pose pas** `alerted['__done__']`
- Conséquence : `elapsedLive` retourne `elapsed()` figé → toutes les jauges se figent sur la pause
- `complete-timer` : `alerted['__done__'] = true` → `elapsedLive` continue en temps réel → jauges continuent de se vider en fond

### Après `complete-timer`
| Élément | Comportement |
|---------|-------------|
| Affichage "Temps écoulé" (enclos + dashboard) | **Figé** — utilise `elapsed(timer)` = `(pausedAt - startTime - pausedMs) / 1000` |
| Jauges (niveau, barre) | **Continuent** — `enclosGaugeCurGl` utilise `elapsedLive` |
| Stats estimées des DD | **Continuent** — `computeGaugeLive` utilise `elapsedLive` |
| Countdown "Alarme dans" | Affiche `✅` |
| Bannière "Session terminée" | Visible dans la vue enclos |

---

## 19. Animations et détection de tick — `DragodindeCard`

### Détection de tick

Un "tick" survient toutes les 10 secondes. La carte DD détecte un nouveau tick en comparant `Math.floor(elapsedLive(enc) / 10)` avec la valeur précédente.

Utiliser `elapsedLive(enc)` (et non `elapsed`) garantit que les animations de tick **continuent** après la fin de session, le temps que toutes les jauges se vident en arrière-plan.

### `deltaActive` — quand afficher l'animation de delta

L'animation de delta ("+20 xp", "-10 sérenité"…) s'affiche à chaque tick **uniquement si la jauge est encore active**. Une jauge est considérée inactive quand la stat atteint son **cap absolu** (pas sa cible) :

```
Pour les jauges de stats : atAbsCap = (estStat >= statMax)  ou  (estStat <= statMin)
Pour la mangeoire (XP)  : atAbsCap = (estLevel >= 200)
```

Cela signifie que l'animation continue après la cible de l'utilisateur (ex: sérénité cible -60 → animation continue jusqu'à -5000).

### Badge "✓ TERMINÉ"

Affiché sur la carte DD quand **toutes les jauges actives** ont `done = true` pour cette DD. Les jauges de stats et la mangeoire comptent toutes de la même façon — pas de distinction.

---

## 20. Événements domaine actifs

| Événement | Déclencheur | Effet |
|-----------|-------------|-------|
| `timer-completed` | `complete-timer` (toutes cibles atteintes) | Alarme audio + notification Windows + notification mobile ntfy |
| `gauge-threshold-reached` | Franchissement d'un palier de jauge | (usage interne) |
| `accouplement-registered` | Enregistrement d'un accouplement | Mise à jour des stats globales |
| `enclos-deleted` | Suppression d'un enclos | Nettoyage de l'état |

**Événements supprimés** (ancienne implémentation, ne plus utiliser) :
- `target-reached` — ancienne alarme intermédiaire quand une cible de stat était atteinte avant les autres
- `xp-target-reached` — ancienne alarme séparée pour la cible XP

Ces événements ont été remplacés par la règle d'alarme unique : **une seule alarme au timer le plus long**, déclenchée par `timer-completed` uniquement.