From b28a37d411847991bee50fdd0b6df2d5c031b27d Mon Sep 17 00:00:00 2001 From: Pierre MARTIN Date: Tue, 3 Nov 2026 10:25:50 +0100 Subject: [PATCH] ADR 0013 : position dans l'adresse ; plan 0e.4 Co-Authored-By: Claude Opus 5.5 --- docs/adr/0013-position-dans-l-adresse.md | 49 +++++++++++++++++++ docs/adr/README.md | 1 + docs/feuille-de-route.md | 2 +- .../2026-11-03-position-dans-l-adresse.md | 39 +++++++++++++++ 4 files changed, 90 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0013-position-dans-l-adresse.md create mode 100644 docs/plans/2026-11-03-position-dans-l-adresse.md diff --git a/docs/adr/0013-position-dans-l-adresse.md b/docs/adr/0013-position-dans-l-adresse.md new file mode 100644 index 0000000..c06ddc1 --- /dev/null +++ b/docs/adr/0013-position-dans-l-adresse.md @@ -0,0 +1,49 @@ +# 0013. Une position du plateau dans l'adresse de la page + +- **Statut** : accepté +- **Date** : 2026-11-03 +- **Décideurs** : Pierre (besoin), Claude Code (format) + +## Contexte + +Pierre a demandé, au premier test sur le téléphone (2026-11-03), qu'avec la +seule adresse on arrive à une position du plateau : chaque position devient un +lien direct, à partager, à mettre dans une leçon ou dans un prompt pour une IA. +GNU Backgammon décrit déjà toute position par deux identifiants publics et +documentés : le Position ID (14 caractères, les pions) et le Match ID +(12 caractères : videau, score, longueur du match, joueur au trait, dés). Le +moteur sait les lire et les écrire (`engine.h`). + +## Décision + +- L'adresse porte la position dans le fragment (après `#`) : + `https://ustagammon.sans.pub/#position=&match=`, + chaque identifiant encodé avec `encodeURIComponent` (le base64 de gnubg + contient `+` et `/`). `match` est facultatif : sans lui, partie libre, videau + au centre, joueur du bas au trait, sans dés. +- Ouvrir un tel lien affiche la position, non jouable, avec deux actions : + « Jouer à partir d'ici » (nouvelle partie contre l'ordinateur depuis cette + position, sans toucher à la partie en cours) et « Retour à ma partie ». +- Toute position affichée (partie, coup de l'ordinateur, analyse, leçon) peut + être copiée en lien (« Copier le lien de la position »). +- Un identifiant illisible pour le moteur donne un message clair et le retour + à la partie, jamais une page cassée. + +## Alternatives écartées + +- **Paramètres de requête (`?position=`)** : ils changent l'adresse demandée + au serveur et au service worker ; hors ligne, la page en cache ne + correspondrait plus. Le fragment ne quitte jamais le navigateur. +- **XGID (format d'eXtreme Gammon)** : répandu, mais un seul identifiant de + plus à décoder ; gnubg l'importe, son import pourra s'ajouter plus tard + (outil « import d'un identifiant GNU ou XGID » du cadrage). +- **Format maison plus lisible** : il faudrait le décoder sans le moteur, donc + réimplémenter une règle de représentation (ADR 0007). + +## Conséquences + +- Le fragment est lu au chargement et à chaque changement (`hashchange`) ; le + domaine reçoit une position et un Match ID, le moteur les valide. +- Les liens restent valables tant que GNU Backgammon garde ces formats, stables + depuis des années. +- Les liens contiennent la position, rien d'autre : pas de donnée personnelle. diff --git a/docs/adr/README.md b/docs/adr/README.md index ef00008..e79216f 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -19,3 +19,4 @@ l'ancien passe au statut « remplacé par NNNN ». Voir l'ADR 0001. | [0010](0010-identite-visuelle.md) | Identité visuelle : symbole, logotype, palette | accepté | | [0011](0011-lecons-conseil-et-bilan.md) | Leçons numérotées, conseil du maître après le coup, bilan de fin de partie | accepté | | [0012](0012-mode-immersif.md) | Mode immersif : le plateau en paysage, sur demande | accepté | +| [0013](0013-position-dans-l-adresse.md) | Une position du plateau dans l'adresse de la page | accepté | diff --git a/docs/feuille-de-route.md b/docs/feuille-de-route.md index 502af9f..88a9530 100644 --- a/docs/feuille-de-route.md +++ b/docs/feuille-de-route.md @@ -24,7 +24,7 @@ Demandes de Pierre du 2026-11-03, traitées avant d'ouvrir l'étape 1. | Sous-étape | Contenu | État | Plan | | --- | --- | --- | --- | | 0e.3 | Révision UX arbitrée (session « identité », sur délégation de Pierre) : portrait stable, bandeaux de compte de points, menu en feuille et nouvelle partie annulable, vibrations, écran allumé, paysage « plateau = écran » dès la rotation (ADR 0012 amendé) | ⏳ | `plans/2026-11-03-revision-ux.md` | -| 0e.4 | Position dans l'adresse : chaque position du plateau a un lien direct (nouvel ADR pour le format) | ⏳ | | +| 0e.4 | Position dans l'adresse : chaque position du plateau a un lien direct (ADR 0013) | ⏳ | `plans/2026-11-03-position-dans-l-adresse.md` | | 0e.5 | Page d'accueil, installation en un toucher (« Ajouter à l'écran d'accueil », proposée par l'app), tutoriel des règles très didactique avec plateaux illustrés, aide réécrite sur un ton plus humain ; textes à valider par Pierre | ⏳ | | ## Étapes suivantes diff --git a/docs/plans/2026-11-03-position-dans-l-adresse.md b/docs/plans/2026-11-03-position-dans-l-adresse.md new file mode 100644 index 0000000..a1f3b5d --- /dev/null +++ b/docs/plans/2026-11-03-position-dans-l-adresse.md @@ -0,0 +1,39 @@ +# Position dans l'adresse (0e.4) + +- **Date** : 2026-11-03 +- **Étape** : 0e.4 (feuille de route) +- **Statut** : prévu (après la fusion de la révision UX, qui touche les mêmes fichiers) +- **Exécutant** : sous-agent general-purpose, dans un worktree + +## Objectif + +Appliquer l'ADR 0013 : chaque position du plateau a un lien direct. + +## Consignes + +ADR 0007, 0008 et 0013. Aucune nouvelle dépendance. + +1. Lecture du fragment `#position=…&match=…` au chargement et sur + `hashchange` ; validation par le moteur ; message clair si illisible. +2. Vue de la position, non jouable, avec « Jouer à partir d'ici » (nouvelle + partie depuis la position, la partie en cours restant reprenable) et + « Retour à ma partie ». +3. Domaine : démarrer une partie depuis une position et un Match ID donnés + (événement GameStarted étendu de façon rétrocompatible, ou équivalent + justifié), sans règle réimplémentée. +4. « Copier le lien de la position » depuis le menu de la partie et depuis la + vue du coup de l'ordinateur ; le lien copié rouvre exactement la même + position (test aller-retour). +5. Scénarios Gherkin (« Ouvrir un lien vers une position », « Partager la + position »), fiches du glossaire (Position ID, Match ID si absentes). +6. `make lint`, `make test`, `make test-browser` (ouvrir un lien, jouer à + partir d'ici, revenir, lien invalide). + +## Critères de réussite + +Un lien copié depuis l'app, ouvert dans un nouvel onglet, montre la même +position ; les trois commandes passent. + +## Résultat + +À remplir à la clôture.