Comment lire cette documentation

Cette page explique comment la documentation est organisée, quelles conventions elle suit, comment y chercher une information et comment signaler une erreur. Elle vaut aussi mode d'emploi pour qui veut la compléter : les règles d'écriture détaillées sont dans Écrire la documentation.

#Organisation en 16 parties

Le sommaire de gauche suit le fichier content/SUMMARY.md. Il commence par trois pages d'accueil, puis 16 parties numérotées. Chaque partie répond à une question précise.

Les parties 1 et 2 se lisent dans l'ordre. Les parties 3 à 13 sont des références : on y va pour une question précise. La partie 15 contient des recettes qui renvoient vers les références.

#Conventions

#Ce que la documentation garantit

Chaque affirmation a été vérifiée dans le code ou dans un fichier du dépôt au moment de la rédaction. Quand le code et une ancienne documentation divergent, c'est le code qui a raison, et l'écart est signalé. Les pages disent explicitement ce qui est réel, ce qui est simulé et ce qui n'est pas implémenté. Le récapitulatif est sur Réel, simulé ou à venir.

#Liens vers le code

Un lien dont le texte est un chemin en police fixe, par exemple backend/src/config/env.config.ts, ouvre le fichier sur GitHub, branche main. Le chemin part toujours de la racine du dépôt. La construction du site échoue si un fichier cité n'existe plus : un lien vers le code n'est donc jamais mort au moment de la publication.

Les liens ne portent pas de numéro de ligne, car les lignes bougent à chaque modification. Pour retrouver une fonction, chercher son nom dans le fichier.

#Pages générées depuis le code

Plusieurs tableaux ne sont pas écrits à la main. Le script scripts/build.mjs les reconstruit à chaque construction en lisant directement les sources. Ils sont donc toujours alignés sur le code publié.

Les descriptions qui accompagnent ces tableaux (rôle d'une variable, d'une table, d'un événement) viennent des fichiers JSON de documentation-officielle/content/_data/. Quand le code ajoute un élément sans description, la construction le signale. En mode strict (npm run check, exécuté par la CI), elle échoue.

#Encadrés

Cinq types d'encadrés signalent une information à ne pas manquer.

#Blocs de code et diagrammes

Les commandes sont données dans des blocs avec leur langage (bash, powershell, typescript...). Sauf mention contraire, une commande se lance depuis le dossier du projet concerné (backend/, frontend-web/...) et la racine du dépôt est le dossier BlockLucky/. Les commandes ont été vérifiées dans les scripts des package.json, les Dockerfile et la CI.

Les flux sont dessinés en Mermaid : diagrammes de séquence pour les échanges entre composants, diagrammes d'états pour le cycle d'un tour, schémas pour l'architecture.

#Vocabulaire

Quelques termes reviennent partout. Ils sont définis dans le glossaire.

#Chercher une information

#La recherche intégrée

Le champ de recherche en haut de page interroge toutes les pages. Il s'ouvre au clavier avec Ctrl K (ou Cmd K sur macOS), ou avec la touche / quand le curseur n'est pas dans un champ de saisie. Les flèches haut et bas parcourent les résultats, Entrée ouvre le résultat sélectionné et Échap ferme la liste.

L'index de recherche est construit avec le site : chaque section de niveau 2 ou 3 est une entrée, avec le titre de la page et de la section. Le texte des blocs de code n'est pas indexé. Pour retrouver une commande ou un nom de variable, chercher plutôt le terme en français qui l'accompagne, ou utiliser les pages générées (variables, scripts npm, API).

#Le sommaire de la page

La colonne de droite liste les titres de la page en cours. Chaque titre possède une ancre : l'identifiant est le texte du titre en minuscules, sans accents, chaque suite de caractères non alphanumériques remplacée par un tiret. « Cycle d'un tour » devient #cycle-d-un-tour. Ces ancres sont stables et peuvent être partagées.

#Chercher directement dans le code

Pour une question à laquelle la documentation ne répond pas, la page Index des fichiers clés indique où se trouve chaque responsabilité dans le dépôt.

#Signaler une erreur

Chaque page se termine par le lien « Modifier cette page sur GitHub ». Il ouvre la source Markdown de la page dans documentation-officielle/content/ sur le dépôt MarceauTDML/BlockLucky. Deux options :

1. proposer la correction directement par une pull request, en suivant le workflow Git ;
2. ouvrir un ticket sur le dépôt en citant la page, la phrase concernée et ce que dit le code (avec le chemin du fichier).

Avant de proposer une correction, construire le site localement pour vérifier les liens :

cd documentation-officielle
npm ci
npm run build
npm run check

npm run build régénère le dossier site/. npm run check reconstruit dans un dossier temporaire en mode strict, compare le résultat au dossier site/ versionné et vérifie chaque lien et chaque ancre. npm run serve sert ensuite site/ sur http://localhost:4040.

#Ce que la documentation ne remplace pas

• La documentation Swagger servie par le backend sur /api/docs reste la référence interactive pour tester un appel.
• Les livrables marketing et UX de l'équipe (proposition de valeur, recherche utilisateurs, stratégie de communication, budget) sont des documents PDF hors dépôt. Ils sont résumés et cités dans la partie 1, sans être recopiés.
• Les décisions d'architecture sont argumentées dans les ADR : la documentation de référence les applique sans les redémontrer.