fletchtime 0.2.2__tar.gz → 0.2.4__tar.gz

{fletchtime-0.2.2/src/fletchtime.egg-info → fletchtime-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fletchtime
-Version: 0.2.2
+Version: 0.2.4
 Summary: Chronométrage de compétitions d'archerie FFTL (Indoor, Flint) -- serveur + interfaces web incluses
 License: GPL-3.0-or-later
 Requires-Python: >=3.11
@@ -21,7 +21,7 @@ Dynamic: license-file
 
 <img src="https://mrfanghodev.github.io/fletchtime/_static/logo.svg" width="80" height="80" alt="FletchTime logo">
 
-[![Python](https://img.shields.io/badge/python-version-from-pep-621-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FMrFanghoDev%2Ffletchtime%2Fmaster%2Fpyproject.toml)](pyproject.toml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
 [![Licence](https://img.shields.io/github/license/MrFanghoDev/fletchtime)](LICENSE)
 [![Tests](https://github.com/MrFanghoDev/fletchtime/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/MrFanghoDev/fletchtime/actions/workflows/test.yml)
 [![PyPI](https://img.shields.io/pypi/v/fletchtime)](https://pypi.org/project/fletchtime/)
@@ -38,6 +38,13 @@ compris Pydroid 3. Ajoute `--headless` pour retrouver l'ancien mode
 terminal (aussi utilisé automatiquement si la fenêtre ne peut pas se
 charger, ex. `customtkinter` absent).
 
+En mode terminal, `fletchtime --headless --help` liste toutes les
+options -- notamment `-v`/`--verbose` et `-d`/`--debug` (plus de détail
+dans le journal), et `--http-port`/`--ws-port` pour remplacer les ports
+configurés le temps d'un seul lancement (ex. plusieurs salles de
+compétition sur un même PC via un script, sans dossier séparé par salle
+-- voir plus bas pour l'approche par copie de dossier).
+
 ## Installation
 
 Trois façons d'obtenir et faire tourner FletchTime, selon ton matériel --
@@ -105,12 +112,14 @@ Autoriser une application via le pare-feu* -- coche `FletchTime.exe` pour
 les réseaux privés.
 
 **Ports réseau utilisés** : **8000** en HTTP (pages web) et **8765** en
-WebSocket (synchronisation temps réel) -- deux ports séparés, tous deux
-nécessaires. Si le serveur tourne dans un conteneur/VM (Docker, WSL2...),
-les deux doivent être redirigés vers l'hôte, pas seulement le 8000 : sans
-le 8765, les pages se chargent normalement mais restent bloquées sur "en
-attente de connexion" indéfiniment (la synchronisation temps réel ne peut
-jamais s'établir).
+WebSocket (synchronisation temps réel) par défaut -- deux ports séparés,
+tous deux nécessaires, modifiables (fenêtre graphique, `config/gui.toml`,
+ou `--http-port`/`--ws-port` en ligne de commande). Si le serveur tourne
+dans un conteneur/VM (Docker, WSL2...), les deux doivent être redirigés
+vers l'hôte, pas seulement le port HTTP : sans le port WebSocket, les
+pages se chargent normalement mais restent bloquées sur "en attente de
+connexion" indéfiniment (la synchronisation temps réel ne peut jamais
+s'établir).
 
 Pour construire ces exécutables toi-même :
 voir `.github/workflows/build.yml` et `fletchtime.spec` (PyInstaller). Un
@@ -156,6 +165,9 @@ Envie de proposer un correctif, une idée, ou juste signaler un bug ? Voir
 [CONTRIBUTING.md](CONTRIBUTING.md) (français/anglais) -- processus
 volontairement simple, flux classique fork/branche/Pull Request.
 
+Merci aux membres du club qui ont testé l'outil et proposé des idées au
+fil du développement -- voir [REMERCIEMENTS.md](REMERCIEMENTS.md).
+
 ## Qualité continue
 
 Chaque push et pull request déclenche `.github/workflows/test.yml` :

{fletchtime-0.2.2 → fletchtime-0.2.4}/README.md

@@ -1,6 +1,6 @@
 <img src="https://mrfanghodev.github.io/fletchtime/_static/logo.svg" width="80" height="80" alt="FletchTime logo">
 
-[![Python](https://img.shields.io/badge/python-version-from-pep-621-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FMrFanghoDev%2Ffletchtime%2Fmaster%2Fpyproject.toml)](pyproject.toml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
 [![Licence](https://img.shields.io/github/license/MrFanghoDev/fletchtime)](LICENSE)
 [![Tests](https://github.com/MrFanghoDev/fletchtime/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/MrFanghoDev/fletchtime/actions/workflows/test.yml)
 [![PyPI](https://img.shields.io/pypi/v/fletchtime)](https://pypi.org/project/fletchtime/)
@@ -17,6 +17,13 @@ compris Pydroid 3. Ajoute `--headless` pour retrouver l'ancien mode
 terminal (aussi utilisé automatiquement si la fenêtre ne peut pas se
 charger, ex. `customtkinter` absent).
 
+En mode terminal, `fletchtime --headless --help` liste toutes les
+options -- notamment `-v`/`--verbose` et `-d`/`--debug` (plus de détail
+dans le journal), et `--http-port`/`--ws-port` pour remplacer les ports
+configurés le temps d'un seul lancement (ex. plusieurs salles de
+compétition sur un même PC via un script, sans dossier séparé par salle
+-- voir plus bas pour l'approche par copie de dossier).
+
 ## Installation
 
 Trois façons d'obtenir et faire tourner FletchTime, selon ton matériel --
@@ -84,12 +91,14 @@ Autoriser une application via le pare-feu* -- coche `FletchTime.exe` pour
 les réseaux privés.
 
 **Ports réseau utilisés** : **8000** en HTTP (pages web) et **8765** en
-WebSocket (synchronisation temps réel) -- deux ports séparés, tous deux
-nécessaires. Si le serveur tourne dans un conteneur/VM (Docker, WSL2...),
-les deux doivent être redirigés vers l'hôte, pas seulement le 8000 : sans
-le 8765, les pages se chargent normalement mais restent bloquées sur "en
-attente de connexion" indéfiniment (la synchronisation temps réel ne peut
-jamais s'établir).
+WebSocket (synchronisation temps réel) par défaut -- deux ports séparés,
+tous deux nécessaires, modifiables (fenêtre graphique, `config/gui.toml`,
+ou `--http-port`/`--ws-port` en ligne de commande). Si le serveur tourne
+dans un conteneur/VM (Docker, WSL2...), les deux doivent être redirigés
+vers l'hôte, pas seulement le port HTTP : sans le port WebSocket, les
+pages se chargent normalement mais restent bloquées sur "en attente de
+connexion" indéfiniment (la synchronisation temps réel ne peut jamais
+s'établir).
 
 Pour construire ces exécutables toi-même :
 voir `.github/workflows/build.yml` et `fletchtime.spec` (PyInstaller). Un
@@ -135,6 +144,9 @@ Envie de proposer un correctif, une idée, ou juste signaler un bug ? Voir
 [CONTRIBUTING.md](CONTRIBUTING.md) (français/anglais) -- processus
 volontairement simple, flux classique fork/branche/Pull Request.
 
+Merci aux membres du club qui ont testé l'outil et proposé des idées au
+fil du développement -- voir [REMERCIEMENTS.md](REMERCIEMENTS.md).
+
 ## Qualité continue
 
 Chaque push et pull request déclenche `.github/workflows/test.yml` :

fletchtime-0.2.4/REMERCIEMENTS.md

@@ -0,0 +1,30 @@
+# Remerciements
+
+<!-- sphinx-include-start -->
+
+FletchTime doit beaucoup aux membres du club (Les Archers
+Libres de Fontaine le Port) qui ont testé l'outil en conditions réelles,
+remonté des bugs, et proposé des idées qui ont façonné le projet au fil
+de son développement.
+
+Un grand merci à :
+
+- **Fangho** -- Intention initiale
+- **Xavier** -- Primo testeur
+- **Fabrice** -- Concours multi-serveurs
+- **Caro** -- Ne pas oublier les Remerciements!
+
+<!--
+Modèle à remplir : une ligne par personne, avec ce qu'elle a apporté si
+tu veux être précis·e (pas obligatoire -- juste le nom suffit aussi).
+Pas d'ordre particulier attendu (alphabétique, chronologique, ou
+simplement dans l'ordre où ça te vient -- comme tu préfères).
+-->
+
+---
+
+*Tu as testé FletchTime ou proposé une idée et tu ne te retrouves pas
+dans cette liste ? Fais-le savoir pour qu'on corrige ça.*
+
+*Envie de contribuer plus directement (code, documentation) ? Voir
+[CONTRIBUTING.md](CONTRIBUTING.md).*

{fletchtime-0.2.2 → fletchtime-0.2.4}/docs/architecture.md

@@ -28,7 +28,7 @@ installation logicielle sur les tablettes d'affichage.
 | Composant | Choix | Justification |
 |---|---|---|
 | Backend WebSocket | Paquet `websockets` (asyncio) | Pas de FastAPI/Pydantic (dépendance Rust `pydantic-core` à risque sur Android/Pydroid) ni d'uvicorn `[standard]` (extensions C `uvloop`/`httptools`) ; `websockets` a un fallback pur Python si son extension C optionnelle ne compile pas — installable de façon fiable sur Pydroid 3. |
-| Serveur HTTP statique | `http.server` (stdlib), port **8000** | Sert les pages et assets sur un port séparé du WebSocket (port **8765**) -- évite l'API instable de combinaison HTTP+WS selon les versions de `websockets` ; utilisé aussi pour la découverte de fichiers (bannières, packs de sons) via le listing de répertoire natif. **Les deux ports doivent être accessibles** depuis les écrans/postes clients (pare-feu, redirection de port si le serveur tourne dans un conteneur/VM -- ex. Docker, WSL2) : rediriger seulement le 8000 charge les pages mais laisse la synchronisation temps réel bloquée ("en attente de connexion" indéfiniment). |
+| Serveur HTTP statique | `http.server` (stdlib), port **8000** par défaut | Sert les pages et assets sur un port séparé du WebSocket (port **8765** par défaut) -- évite l'API instable de combinaison HTTP+WS selon les versions de `websockets` ; utilisé aussi pour la découverte de fichiers (bannières, packs de sons) via le listing de répertoire natif. Les deux ports sont modifiables (fenêtre graphique, `config/gui.toml`, ou `--http-port`/`--ws-port` en ligne de commande -- voir {doc}`dev-guide/index`), notamment pour plusieurs salles de compétition sur un même PC. **Les deux ports doivent être accessibles** depuis les écrans/postes clients (pare-feu, redirection de port si le serveur tourne dans un conteneur/VM -- ex. Docker, WSL2) : rediriger seulement le port HTTP charge les pages mais laisse la synchronisation temps réel bloquée ("en attente de connexion" indéfiniment). |
 | Communication temps réel | WebSocket | Évite la dérive du polling, tous les écrans restent synchronisés à la seconde près. |
 | Frontend | HTML/CSS/JS vanilla | Pas de build, une tablette ouvre juste une URL. |
 | Config des modes (Indoor/Flint) | Fichiers **TOML** (`config/*.toml`) | Lu via `tomllib`, stdlib depuis Python 3.11 (donc Pydroid) -- zéro dépendance. Écriture via un petit sérialiseur maison (pas de support d'écriture en stdlib). |
@@ -502,6 +502,52 @@ Le poste de contrôle, à l'inverse, affiche une bannière large et alarmante
 (pas discrète) en cas de coupure -- c'est le responsable du chronométrage
 qui doit être alerté clairement, pas les archers.
 
+## Synchronisation du diaporama de l'écran neutre
+
+L'écran neutre (hors concours, ou après sa fin) alterne logo/horloge et
+bannières sponsors -- voir `display.html`, `showSlideshowStep`. Aucune
+coordination serveur pour ça : chaque écran calcule sa slide actuelle en
+divisant l'horloge murale (`Date.now()`) par la durée d'une slide, plutôt
+que d'incrémenter un compteur local à partir de 0 à son propre démarrage.
+
+```{important}
+Une première version utilisait un compteur local (`slideshowStep`,
+incrémenté par `setInterval`) -- deux écrans qui chargeaient ou se
+reconnectaient à des instants différents affichaient alors des slides
+différentes au même moment, chacun étant reparti de 0 à son propre
+démarrage. Corrigé en dérivant la slide actuelle de l'horloge murale
+(`Math.floor(Date.now() / SLIDE_DURATION_MS) % totalSlides`) : deux
+écrans avec des horloges système raisonnablement synchronisées (le cas
+normal sur un même réseau local) calculent alors la même slide,
+indépendamment de quand chacun a démarré. Vérifié avec un vrai navigateur
+(Chromium via Playwright) : deux pages chargées à 3 secondes d'écart
+affichent bien la même slide.
+```
+
+## Découverte du port WebSocket côté client
+
+`display.html` et `control.html` ne connaissent pas à l'avance le port
+WebSocket à utiliser : depuis que les ports sont devenus modifiables
+(voir la fenêtre graphique et `config/gui.toml`, pensé pour plusieurs
+salles de compétition sur un même PC), le coder en dur côté client
+casserait silencieusement toute page si le port avait été changé.
+
+Chaque page interroge `/api/version` (servi par le même serveur HTTP qui
+vient de la servir, donc forcément sur le bon port) avant d'ouvrir sa
+connexion WebSocket -- la réponse inclut `ws_port`, le port réellement
+configuré (`ServerRuntime.ws_port`, plombé jusqu'à
+`http_static.start_http_server`). Un échec de cette requête (réseau,
+serveur non démarré) se rabat silencieusement sur `8765` -- l'ancien
+port fixe, qui reste une valeur par défaut raisonnable, jamais une
+erreur bloquante pour l'utilisateur.
+
+```{note}
+Vérifié avec un vrai navigateur (Chromium via Playwright), pas seulement
+en théorie : les deux pages utilisent bien le port récupéré
+dynamiquement, et se rabattent proprement sur 8765 sans planter quand
+`/api/version` échoue.
+```
+
 ## Multi-écrans et ciblage
 
 Chaque écran se connecte au WebSocket et s'enregistre avec son numéro de lane

{fletchtime-0.2.2 → fletchtime-0.2.4}/docs/dev-guide/index.md

@@ -133,6 +133,40 @@ dernier commit de `main`, seulement la dernière version taguée -- voir
 la note correspondante sur {doc}`../index`.
 ```
 
+## Options de la ligne de commande (mode terminal)
+
+`fletchtime --headless --help` (ou `python -m fletchtime --headless
+--help`) affiche la liste complète, mais résumé ici pour référence
+rapide -- voir `fletchtime/__main__.py`, `_build_arg_parser`.
+
+| Option | Effet |
+|---|---|
+| `-h`, `--help` | Affiche l'aide et quitte. |
+| `-V`, `--version` | Affiche la version et quitte. |
+| `--headless`, `--no-gui` | Mode terminal, sans fenêtre graphique. |
+| `-v`, `--verbose` | Affiche les journaux applicatifs (commandes reçues, (dé)connexions...) dans le terminal, pas seulement dans le fichier. |
+| `-d`, `--debug` | Journalisation la plus détaillée possible, fichier compris -- implique `--verbose`. |
+| `--http-port PORT` | Remplace le port HTTP configuré, pour cette exécution seulement. |
+| `--ws-port PORT` | Remplace le port WebSocket configuré, pour cette exécution seulement. |
+
+```{note}
+`--http-port`/`--ws-port` **ne modifient jamais** `config/gui.toml` --
+un remplacement ponctuel (utile pour un lancement scripté/CI, ou
+plusieurs salles de compétition sur un même PC sans dossier séparé par
+salle), pas un changement persistant. Pour un réglage durable, voir la
+fenêtre graphique (section Ports) ou éditer `config/gui.toml`
+directement.
+```
+
+**Niveaux de journalisation, fichier et terminal indépendants l'un de
+l'autre** (voir `fletchtime.logging_setup.configure_logging`) : le
+fichier de journal (`logs/fletchtime.log`) reste toujours à INFO par
+défaut, quelle que soit la commande utilisée pour lancer FletchTime --
+le diagnostic après-coup d'un concours ne doit pas dépendre de si
+quelqu'un a pensé à ajouter `-v`. Seul le terminal respecte
+`-v`/`--verbose` (silencieux par défaut, WARNING). `--debug` élève les
+deux au niveau DEBUG.
+
 ## Architecture générale
 
 Voir {doc}`../architecture` pour le détail complet. En résumé :

{fletchtime-0.2.2 → fletchtime-0.2.4}/docs/index.md

@@ -4,7 +4,7 @@
 :align: center
 ```
 
-[![Python](https://img.shields.io/badge/python-version-from-pep-621-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FMrFanghoDev%2Ffletchtime%2Fmaster%2Fpyproject.toml)](https://github.com/MrFanghoDev/fletchtime/blob/master/pyproject.toml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/MrFanghoDev/fletchtime/blob/master/pyproject.toml)
 [![Licence](https://img.shields.io/github/license/MrFanghoDev/fletchtime)](https://github.com/MrFanghoDev/fletchtime/blob/master/LICENSE)
 [![Tests](https://github.com/MrFanghoDev/fletchtime/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/MrFanghoDev/fletchtime/actions/workflows/test.yml)
 [![PyPI](https://img.shields.io/pypi/v/fletchtime)](https://pypi.org/project/fletchtime/)
@@ -27,9 +27,11 @@ page d'accueil, pas ici) -- voir {doc}`user-guide/index`.
 :maxdepth: 2
 :caption: Contenu
 
+premier-club
 specifications
 architecture
 roadmap
+remerciements
 user-guide/index
 dev-guide/index
 api-reference

fletchtime-0.2.4/docs/premier-club.md

@@ -0,0 +1,113 @@
+# Découvrir FletchTime pour son club
+
+Cette page s'adresse à quelqu'un qui découvre FletchTime pour la première
+fois -- un⋅e archer⋅ère, un⋅e responsable de club. Pas besoin de
+connaître quoi que ce soit du projet au préalable.
+
+## C'est quoi
+
+FletchTime est un logiciel de chronométrage pour les compétitions
+d'archerie FFTL (Indoor et Flint) : il gère le décompte du temps de tir,
+les phases de préparation et de repos, les sons qui rythment le
+concours, sur autant d'écrans que nécessaire. Gratuit, open source, né
+de l'usage réel d'un club.
+
+## Pourquoi s'en servir
+
+::::{grid} 2
+:gutter: 3
+
+:::{grid-item-card} 📺 Un écran par pas de tir
+Pas juste un chrono près du starter -- chaque archer voit le temps
+restant sans avoir à se retourner.
+:::
+
+:::{grid-item-card} 🔊 Les sons rythment le concours tout seuls
+Début de préparation, passage à l'orange, fin de volée... plus besoin
+qu'une personne déclenche chaque signal à la main.
+:::
+
+:::{grid-item-card} 💻 Du matériel qu'un club a probablement déjà
+Un vieux PC, des tablettes ou téléphones pour les écrans -- pas de
+matériel spécialisé à acheter.
+:::
+
+:::{grid-item-card} 🔌 Résiste aux coupures et aux plantages
+Le chrono ne perd pas le fil, la reprise se fait sans intervention
+manuelle -- voir {doc}`architecture` pour le détail technique.
+:::
+
+::::
+
+## Ce qu'il faut avant de commencer
+
+- Un appareil pour héberger le serveur (PC ou téléphone selon la méthode
+  d'installation choisie) -- pas besoin d'être puissant.
+- Un réseau WiFi local reliant cet appareil et les écrans.
+- Des écrans pour l'affichage : tablettes, téléphones, ou même un vieux
+  moniteur relié à un PC secondaire.
+- Aucune compétence technique nécessaire pour l'usage courant -- voir
+  plus bas si l'installation elle-même te semble intimidante.
+
+## Premiers pas
+
+1. **Installer** : plusieurs façons possibles selon le matériel -- voir le
+   [README](https://github.com/MrFanghoDev/fletchtime#installation)
+   pour le détail de chacune.
+2. **Premier lancement** : une fenêtre s'ouvre avec les adresses à
+   utiliser depuis les autres appareils du réseau.
+3. **Ouvrir la page de contrôle** depuis l'appareil hôte ou n'importe
+   quel appareil du réseau, choisir le mode (Indoor ou Flint), ajuster
+   les réglages si besoin (temps de tir, nombre de volées...).
+4. **Ouvrir la page d'affichage** sur chaque écran destiné aux archers.
+5. **Faire un match d'essai** avant le premier vrai concours -- le
+   temps de se familiariser avec les boutons (démarrer, pause, urgence)
+   sans pression.
+
+Une fois ces cinq étapes passées une fois, le pilotage d'un vrai
+concours se résume à quelques clics : voir le manuel utilisateur
+intégré à l'application (accessible depuis sa page d'accueil) pour le
+détail de chaque réglage et bouton.
+
+## Peut-on lui faire confiance
+
+Question légitime avant de l'utiliser en compétition officielle :
+
+- **Open source** : le code est public, inspectable par qui veut --
+  rien de caché.
+- **Testé en conditions réelles de concours**, pas seulement "ça
+  compile" -- voir {doc}`roadmap` pour l'historique des versions et ce
+  qui a été vérifié en pratique.
+- **Récupère après un plantage ou un redémarrage du serveur** sans
+  perdre la progression du match en cours.
+- Reste un projet de club, sans obligation de résultat ni support
+  garanti -- voir la
+  [licence](https://github.com/MrFanghoDev/fletchtime/blob/master/LICENSE)
+  et le ton du
+  [guide de contribution](https://github.com/MrFanghoDev/fletchtime/blob/master/CONTRIBUTING.md)
+  pour ce que ça implique concrètement.
+
+## Où chercher de l'aide
+
+::::{grid} 2
+:gutter: 3
+
+:::{grid-item-card} 📖 Usage au quotidien
+Réglages, pilotage d'un match : le manuel utilisateur intégré à
+l'application, accessible depuis sa page d'accueil une fois installée.
+:::
+
+:::{grid-item-card} 🐛 Un bug, une question
+Les [Issues GitHub](https://github.com/MrFanghoDev/fletchtime/issues).
+:::
+
+:::{grid-item-card} 🤝 Envie de contribuer
+Code, documentation, idée -- voir
+[CONTRIBUTING.md](https://github.com/MrFanghoDev/fletchtime/blob/master/CONTRIBUTING.md).
+:::
+
+:::{grid-item-card} 🔧 Fonctionnement technique
+Le reste de cette documentation : {doc}`specifications`, {doc}`architecture`.
+:::
+
+::::

fletchtime-0.2.4/docs/remerciements.md

@@ -0,0 +1,5 @@
+# Remerciements
+
+```{include} ../REMERCIEMENTS.md
+:start-after: sphinx-include-start
+```

{fletchtime-0.2.2 → fletchtime-0.2.4}/docs/roadmap.md

@@ -56,23 +56,33 @@ dépendent d'extensions compilées (Rust/C) peu fiables sur Pydroid 3, voir
   (`pip install fletchtime` + commande `fletchtime`), exécutables
   autoporteurs Windows/Linux, CI (lint + tests à chaque push).
 
-## ⬜ Étape 7 — Partage FFTL
+## ✅ Étape 7 — Partage FFTL (hors contact fédération, démarche humaine)
 
 - ~~Licence open source claire~~ -- déjà en place : `LICENSE`
   (GPL-3.0-or-later), cohérent avec `pyproject.toml`.
 - ~~Guide de contribution~~ -- fait : `CONTRIBUTING.md` (français/anglais),
   flux classique fork/branche/Pull Request, volontairement simple.
-- Nettoyage : vérifier qu'aucun contenu spécifique au club (nom, logo,
-  détails propres à Les Aigles 77) ne traîne en dur dans le code ou la
-  doc, en dehors de `web/assets/` où c'est normal et attendu.
-- Un vrai guide "premier club" : point d'entrée pour quelqu'un qui
-  découvre l'outil sans le contexte déjà connu (c'est quoi, pourquoi
-  l'utiliser, comment démarrer).
+- ~~Nettoyage~~ -- fait : balayage complet du dépôt, aucun contenu
+  spécifique au club trouvé en dehors de `web/assets/` (normal et
+  attendu là). Un vrai souci trouvé au passage, mais côté livraison
+  plutôt que dans le dépôt lui-même : un logo de club réel se
+  retrouvait dans les archives livrées malgré son exclusion de git --
+  corrigé.
+- ~~Guide "premier club"~~ -- fait : {doc}`premier-club`, point d'entrée
+  pour quelqu'un qui découvre l'outil sans contexte préalable (c'est
+  quoi, pourquoi s'en servir, prérequis, premiers pas, peut-on lui faire
+  confiance, où chercher de l'aide).
 - Contact fédération pour retour d'expérience / adoption éventuelle par
   d'autres clubs -- démarche humaine, hors du champ du dépôt lui-même.
 
 ## Backlog — à discuter / non encore programmé dans une étape précise
 
+- ~~**Remerciements**~~ -- structure prête, à compléter : `REMERCIEMENTS.md`
+  (modèle à remplir avec les noms), lié depuis le README et intégré à la
+  doc Sphinx ({doc}`remerciements` -- même contenu, pas dupliqué, via une
+  inclusion). Les membres du club ont aidé à tester et proposé des idées
+  au fil du développement -- reste à toi d'ajouter les noms.
+
 - ~~**Journal applicatif persistant**~~ -- fait : `MatchServer` journalise
   désormais chaque commande reçue, (dé)connexion, perte de connexion
   réseau et message malformé dans un fichier avec rotation

{fletchtime-0.2.2 → fletchtime-0.2.4}/src/fletchtime/__main__.py

@@ -19,6 +19,8 @@ Deux notions de dossier bien distinctes ici, à ne pas confondre :
 
 from __future__ import annotations
 
+import argparse
+import logging
 import shutil
 import signal
 import socket
@@ -150,7 +152,85 @@ def _print_banner(ip: str, data_root: Path, http_port: int) -> None:
         print("=" * 60)
 
 
-def _run_headless() -> None:
+def _build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="fletchtime",
+        description=(
+            "Serveur de chronométrage pour compétitions d'archerie FFTL " "(Indoor et Flint)."
+        ),
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"FletchTime {__version__}",
+    )
+    parser.add_argument(
+        "--headless",
+        "--no-gui",
+        dest="headless",
+        action="store_true",
+        help="Mode terminal, sans fenêtre graphique.",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Affiche les journaux applicatifs (commandes reçues, "
+        "(dé)connexions...) dans le terminal, pas seulement dans le "
+        "fichier de journal.",
+    )
+    parser.add_argument(
+        "-d",
+        "--debug",
+        action="store_true",
+        help="Journalisation la plus détaillée possible, fichier compris " "-- implique --verbose.",
+    )
+    parser.add_argument(
+        "--http-port",
+        type=int,
+        metavar="PORT",
+        help="Port HTTP -- remplace la valeur de config/gui.toml pour "
+        "cette exécution seulement, sans la modifier (voir aussi la "
+        "fenêtre graphique pour un réglage persistant).",
+    )
+    parser.add_argument(
+        "--ws-port",
+        type=int,
+        metavar="PORT",
+        help="Port WebSocket -- remplace la valeur de config/gui.toml "
+        "pour cette exécution seulement, sans la modifier.",
+    )
+    return parser
+
+
+def _resolve_console_log_level(args: argparse.Namespace) -> int:
+    if args.debug:
+        return logging.DEBUG
+    if args.verbose:
+        return logging.INFO
+    return logging.WARNING
+
+
+def _resolve_ports(args: argparse.Namespace, parser: argparse.ArgumentParser) -> tuple[int, int]:
+    """Priorité aux options de la ligne de commande sur config/gui.toml,
+    sans jamais modifier ce fichier -- une exécution scriptée/CI ne doit
+    pas laisser de trace persistante par accident. Revalide les deux
+    ports ensemble (même règle que config_store.save_gui_config) même
+    si un seul des deux vient de la ligne de commande, pour ne jamais se
+    retrouver avec une combinaison invalide (identiques, hors bornes)."""
+    gui_config = config_store.load_gui_config()
+    http_port = args.http_port if args.http_port is not None else gui_config["http_port"]
+    ws_port = args.ws_port if args.ws_port is not None else gui_config["ws_port"]
+    for name, port in (("--http-port", http_port), ("--ws-port", ws_port)):
+        if not (1 <= port <= 65535):
+            parser.error(f"{name} : le port doit être entre 1 et 65535 (reçu {port}).")
+    if http_port == ws_port:
+        parser.error("--http-port et --ws-port doivent être différents.")
+    return http_port, ws_port
+
+
+def _run_headless(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
     """Mode terminal classique -- utilisé si l'interface graphique n'a pas
     pu être chargée (ex. `customtkinter` absent), ou explicitement demandé
     via `--headless`/`--no-gui`."""
@@ -159,18 +239,18 @@ def _run_headless() -> None:
     ensure_directories(data_root, app_web_dir)
     assets_dir = data_root / "web" / "assets"
 
-    log_file = configure_logging(data_root / "logs")
+    console_level = _resolve_console_log_level(args)
+    file_level = logging.DEBUG if args.debug else logging.INFO
+    log_file = configure_logging(data_root / "logs", console_level, file_level)
     print(f"Journal détaillé / Detailed log: {log_file}")
 
-    # Ports lus depuis config/gui.toml (mêmes préférences que la fenêtre
-    # graphique, voir config_store.load_gui_config) -- permet de faire
-    # tourner plusieurs salles de compétition sur le même PC : une copie
-    # de dossier par salle, chacune avec son propre gui.toml donnant des
-    # ports différents. "gui.toml" malgré le nom concerne aussi ce mode
-    # terminal, pour que les deux se comportent de façon cohérente.
-    gui_config = config_store.load_gui_config()
-    http_port = gui_config["http_port"]
-    ws_port = gui_config["ws_port"]
+    # Ports lus depuis config/gui.toml par défaut (mêmes préférences que
+    # la fenêtre graphique, voir config_store.load_gui_config), sauf
+    # remplacement explicite via --http-port/--ws-port pour cette seule
+    # exécution -- permet de faire tourner plusieurs salles de
+    # compétition sur un même PC sans dossier séparé par salle, utile
+    # pour un lancement scripté/CI par exemple.
+    http_port, ws_port = _resolve_ports(args, parser)
 
     _print_banner(local_ip(), data_root, http_port)
 
@@ -193,8 +273,11 @@ def _run_headless() -> None:
 
 
 def main() -> None:
-    if "--headless" in sys.argv or "--no-gui" in sys.argv:
-        _run_headless()
+    parser = _build_arg_parser()
+    args = parser.parse_args()
+
+    if args.headless:
+        _run_headless(args, parser)
         return
 
     try:
@@ -212,7 +295,7 @@ def main() -> None:
         # repli ne risque pas un conflit de port avec _run_headless().
         print(f"Interface graphique indisponible ({exc}) -- mode terminal.")
         print(f"Graphical interface unavailable ({exc}) -- terminal mode.")
-        _run_headless()
+        _run_headless(args, parser)
 
 
 if __name__ == "__main__":

{fletchtime-0.2.2 → fletchtime-0.2.4}/src/fletchtime/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.2'
-__version_tuple__ = version_tuple = (0, 2, 2)
+__version__ = version = '0.2.4'
+__version_tuple__ = version_tuple = (0, 2, 4)
 
-__commit_id__ = commit_id = 'gceb71f360'
+__commit_id__ = commit_id = 'g5efc3a10b'

{fletchtime-0.2.2 → fletchtime-0.2.4}/src/fletchtime/engine/models.py

@@ -14,15 +14,15 @@ from enum import StrEnum
 class Phase(StrEnum):
     """Visual/safety phase of the current step.
 
-    WAIT      -- before the match starts, or between matches. No countdown.
-    RED       -- preparation time (archers approach / take position).
-    GREEN     -- main shooting time.
-    ORANGE    -- warning period near the end of shooting time.
-    PAUSE     -- end of a volée: archers retrieve arrows, no countdown.
-                 The engine waits here indefinitely until the DOS manually
-                 starts the next volée (``MatchEngine.next()``).
-    EMERGENCY -- danger signal, clock frozen, must be explicitly resumed.
-    FINISHED  -- sequence exhausted, nothing left to shoot.
+    - ``WAIT`` -- before the match starts, or between matches. No countdown.
+    - ``RED`` -- preparation time (archers approach / take position).
+    - ``GREEN`` -- main shooting time.
+    - ``ORANGE`` -- warning period near the end of shooting time.
+    - ``PAUSE`` -- end of a volée: archers retrieve arrows, no countdown.
+      The engine waits here indefinitely until the DOS manually starts
+      the next volée (``MatchEngine.next()``).
+    - ``EMERGENCY`` -- danger signal, clock frozen, must be explicitly resumed.
+    - ``FINISHED`` -- sequence exhausted, nothing left to shoot.
     """
 
     WAIT = "wait"

{fletchtime-0.2.2 → fletchtime-0.2.4}/src/fletchtime/engine/sequence.py

@@ -1,7 +1,8 @@
 """A ``Step`` is one timed segment of a competition (e.g. "red light, 10s,
 end 3 of 12, turn A-B, distance 18m"). A shooting mode's job is only to
-produce an ordered list of ``Step``s up front; the engine then plays that
-list back, handling ticking, manual advance and emergency stop.
+produce an ordered list of ``Step`` objects up front; the engine then
+plays that list back, handling ticking, manual advance and emergency
+stop.
 
 This keeps modes simple, declarative, and trivial to unit test: you can
 assert on the exact list of steps a config produces without running any