# Livre stratégique de référence

Document de référence du projet pour les **ouvertures et plans classiques**
utilisés par le moteur heuristique et l’apprentissage.

Ce n’est **pas** un extrait FIDE (les Lois du jeu ne cataloguent pas les ouvertures).
La classification suit l’**Encyclopaedia of Chess Openings (ECO)** et la théorie
classique reconnue.

---

## Rôle dans le système

| Couche | Tables / fichiers | Rôle |
|--------|-------------------|------|
| **Référence** | `strategy_ref_meta`, `strategy_ref_lines`, `strategy_ref_moves` | Catalogue officiel, synchro depuis `chess/strategy_book.py` |
| **Doc** | ce fichier + codes ECO | Traçabilité humaine |
| **Apprentissage** | `experience_moves`, `experience_lines` | Stats des parties ; **boost** si le coup est dans la réf |

Flux :

1. Au démarrage SQLite → `sync_strategy_reference` (idempotent par version).
2. Moteur → priorité + bonus cp depuis `strategy_ref_moves`.
3. Fin de partie → `learn_game` multiplie le crédit si le coup suit la réf.

API : `GET /api/strategy-book` (catalogue + notes pour la modale UI), `POST /api/experience/seed-strategy` (`force`).

UI : panneau Expérience → **Explications** (ou clic sur une ouverture) ouvre la fenêtre **Référence ECO — ouvertures officielles**.

---

## Catalogue (version 4)

~70 lignes ECO robustes (amorces + suites principales), indexées en DB.
Source code : `chess/strategy_book.py` (`STRATEGY_BOOK_VERSION = 4`).

### e4 e5
| ECO | Nom | Id |
|-----|-----|-----|
| C50 | Partie italienne / Giuoco / roque / hongroise | `italian`, `giuoco`, `italian_castle`, `hungarian` |
| C51 | Gambit Evans | `italian_evans` |
| C55 | Deux cavaliers | `two_knights` |
| C60–C99 | Espagnole Morphy / Berlin / échange | `ruy_lopez`, `ruy_morphy`, `berlin`, `ruy_exchange` |
| C45 | Écossaise | `scotch` |
| C47 | Quatre cavaliers | `four_knights` |
| C42 | Petrov (+ classique) | `petrov`, `petrov_classical` |
| C41 | Philidor | `philidor` |
| C25 | Viennoise | `vienna` |
| C23 | Ouverture du fou | `bishops` |
| C30 | Gambit du roi refusé | `kings_gambit_declined` |

### Sicilienne & semi-ouvertes
| ECO | Nom | Id |
|-----|-----|-----|
| B20–B99 | Open / Najdorf / Dragon / Kan | `sicilian`, `najdorf`, `dragon`, `sicilian_kan`, `sicilian_svesh` |
| B22 | Alapin | `alapin` |
| B23 | Fermée | `closed_sicilian` |
| C00–C19 | Française (+ échange, avancée, Winawer, Tarrasch) | `french`, `french_*` |
| B10–B19 | Caro-Kann (+ avancée, classique) | `caro_*` |
| B01 | Scandinave (+ moderne) | `scandinavian`, `scandi_modern` |
| B07 / B06 / B03 | Pirc / Moderne / Alekhine | `pirc`, `modern`, `alekhine` |

### d4 / indiennes / QG
| ECO | Nom | Id |
|-----|-----|-----|
| D30–D69 | Gambit dame (+ échange, accepté) | `qg_*`, `qgd_exchange`, `qga_main` |
| D10–D49 | Slave / semi-slave | `slav`, `slav_main`, `semi_slav` |
| D02 / D05 / A45 | Londres / Colle / Trompowsky | `london`, `colle`, `trompowsky` |
| E60–E99 | Indienne du roi (+ classique) | `kings_indian`, `kid_classical` |
| D80 | Grünfeld | `grunfeld` |
| E20–E59 | Nimzo (+ Dc2) | `nimzo`, `nimzo_classical` |
| E12–E19 | Ouest-indienne | `queens_indian`, `qid_main` |
| E00–E09 | Catalane | `catalan`, `catalan_main` |
| A43 / A57 | Benoni / Benko | `benoni`, `benko` |
| A80–A99 | Hollandaise (+ stonewall) | `dutch`, `dutch_stonewall` |

### Flanc
| ECO | Nom | Id |
|-----|-----|-----|
| A20–A39 | Anglaise (+ 4 cavaliers, symétrique) | `english*` |
| A09 / A07 | Réti / KIA | `reti`, `kia` |
| A02 | Bird | `bird` |

---

## Critères d’inclusion

Une ligne entre dans la réf seulement si :

1. elle est **légale** coup par coup depuis la position initiale ;
2. elle correspond à une **ouverture ECO** (ou plan clairement rattaché) ;
3. elle est une **amorce / suite principale**, pas une sideline douteuse ;
4. elle a un `weight` et une `source` traçable.

Pour enrichir : éditer `STRATEGIC_LINES`, incrémenter `STRATEGY_BOOK_VERSION`,
mettre à jour ce document, puis `POST /api/experience/seed-strategy` avec `{"force": true}`.

---

## Séparation d’avec l’expérience

- **Référence** = vérité théorique **déjà cataloguée** (pas besoin de N parties).
- **Expérience** = ce que les parties enseignent ; la réf **amplifie** le crédit
  quand la théorie est suivie (`REF_LEARN_BOOST`).