[FIX] Uge session of debugging and code coverage.

NAMING.md

@@ -0,0 +1,125 @@
+# NAMING.md - Convention des noms de partitions
+
+Référence du format de fichiers/répertoires des partitions (`legacy/Scores/`).
+Cette convention a été normalisée une fois par `scripts/convert_final_v2.js`
+(6388 fichiers convertis). **Ne pas renommer à la main** : le backend
+(`api/lib/ScoreScanner.php`) et le frontend en dépendent.
+
+## Arborescence
+
+```
+legacy/Scores/<NUM>/<PIECE>/<INSTRUMENT>/<VERSION>/<FICHIER>
+legacy/Scores/<NUM>/score.ini
+```
+
+| Segment | Rôle | Exemples |
+|---|---|---|
+| `NUM` | identifiant du morceau, **zéro-paddé sur 3 chiffres** | `102`, `390`, `072`, `098` |
+| `PIECE` | numéro de pièce (mouvement) | `1` (morceau simple), `1`..`5` (medley type `390`) |
+| `INSTRUMENT` | trigramme de l'instrument | `cla`, `sax`, `sup`… (voir table) |
+| `VERSION` | répertoire de version | `1` = version principale, `2`, `3`… = alternatives |
+| `FICHIER` | nom du PDF (grammaire ci-dessous) | `clarinette-sib-1.pdf` |
+
+> `VERSION` est un **répertoire**, pas un token du nom de fichier. Le dossier `1/`
+> est la version principale ; `2/`+ sont des versions alternatives du même morceau
+> (ex. score `210` : `cla/1/` et `cla/2/`).
+
+## Grammaire du nom de fichier
+
+```
+{instrument}[-{tonalité}][-{variante}]-{partie}[_{partie_combinée}][_{clef}][_alt{N}].pdf
+```
+
+- Séparateur de champs : **`-`**
+- Séparateur interne aux noms composés et aux suffixes : **`_`**
+- Multi-instrument (deux instruments sur la même partition) : **`+`**
+
+### Exemples réels
+
+| Fichier | Sens |
+|---|---|
+| `clarinette-sib-1.pdf` | clarinette en Si♭, partie 1 |
+| `clarinette_alto-mib-1.pdf` | clarinette alto en Mi♭, partie 1 (`_` = nom composé) |
+| `sax_alto-mib-2.pdf` | sax alto en Mi♭, partie 2 |
+| `cor-fa-1_2.pdf` | cor en Fa, parties **1 et 2 combinées** |
+| `baryton-clefa-1.pdf` | baryton, clé de fa, partie 1 (pas de tonalité) |
+| `euphonium-sib-clesol-1.pdf` | euphonium Si♭, clé de sol, partie 1 |
+| `cornet-sib-solo-1.pdf` | variante `solo` |
+| `baryton-sib-default_cor-2.pdf` | substitution `default_cor` |
+| `conducteur-1_alt1.pdf` | version alternative `alt1` |
+| `basse-sib-1+contrebasse-sib-1.pdf` | **deux instruments** sur la même partition |
+| `saxophone-mib-1+baryton-mib-1.pdf` | idem (sax + baryton) |
+| `glockenspiel-1+xylophone-1.pdf` | percussion multiple |
+| `percussion-1+gong-1+cymbale-1+triangle-1.pdf` | 3 `+` possibles |
+
+### Tonalités
+
+`sib` (Si♭), `mib` (Mi♭), `fa` (Fa), `ut` (Do — **`do` s'écrit `ut` dans les
+fichiers**), `sol`, `re`, `mi`, `si`, `reb`, `dob`, `solb`, `lab`.
+
+### Clefs
+
+`clesol` (clé de sol), `clefa` (clé de fa).
+
+### Variantes / suffixes
+
+- `solo` : partie solo.
+- `default_<instr>` : instrument de substitution (ex. `default_cor`).
+- `_altN` : version alternative dans un même dossier (ex. `_alt1`, `_alt2`).
+
+## Codes instruments
+
+| Code | Instrument | Code | Instrument |
+|---|---|---|---|
+| `dir` | Direction | `trp` | Trompette |
+| `pic` | Piccolo | `trb` | Trombone |
+| `flu` | Flûte | `tub` | Tuba |
+| `cla` | Clarinette | `htb` | Hautbois |
+| `clb` | Clarinette basse | `bas` | Basson |
+| `sax` | Saxophone alto | `per` | Percussions |
+| `sat` | Saxophone ténor | `crn` | Cornet |
+| `sab` | Saxophone baryton | `eup` | Euphonium |
+| `coa` | Cor anglais | `har` | Harpe |
+| `cba` | Contrebasse | `pia` | Piano |
+| `cor` | Cor | `sup` / `par` | Parties combinées |
+
+## `score.ini`
+
+```ini
+[info]
+name = La part d'Euterpe
+compositor = Michaël CUVILLON
+ressource = https://...        ; optionnel (lien externe)
+
+[pieces]
+count = 1
+; pour un medley (count = N) :
+; 1 = La Part d Euterpe
+; 2 = Calliope s Songs
+```
+
+- `[pieces] count` = nombre de pièces. Les clés `1`..`N` donnent leur nom.
+- `ressource` : lien externe optionnel (YouTube, éditeur…).
+
+## Points d'attention (code)
+
+- **`+` dans les chemins** : un `+` littéral dans une URL est valide en *path*,
+  mais PHP `urldecode()` le transforme en espace. Le download doit donc :
+  - encoder chaque segment côté frontend (`encodePath` dans `partitions/src/lib/api.ts`) ;
+  - utiliser `rawurldecode()` (jamais `urldecode()`) côté `api/index.php`.
+  Sinon les 167 fichiers multi-instruments (`a+b.pdf`) renvoient 403.
+- **Parsing** : `ScoreScanner::parseFilename()` détecte tonalité, clef, variante
+  et partie. Les motifs doivent être ancrés (`_sib(?:_|$)`) et du plus long au plus
+  court (`sibemol` avant `sib`) pour ne pas mal découper les noms.
+- Le matcher multi-instruments utilise `+` (et non `_et_`, supprimé par la
+  conversion).
+
+## Conversion (one-off)
+
+`scripts/convert_final_v2.js` est le convertisseur historique utilisé pour
+normaliser l'ensemble du catalogue. Il ne doit plus être nécessaire pour de
+nouveaux fichiers (uploader via l'admin respecte la convention).
+
+```bash
+node scripts/convert_final_v2.js /chemin/vers/Scores confirm
+```