fletchtime 0.2.3__tar.gz → 0.2.5__tar.gz

{fletchtime-0.2.3/src/fletchtime.egg-info → fletchtime-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fletchtime
-Version: 0.2.3
+Version: 0.2.5
 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
@@ -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

{fletchtime-0.2.3 → fletchtime-0.2.5}/README.md

@@ -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

{fletchtime-0.2.3 → fletchtime-0.2.5}/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). |
@@ -343,6 +343,60 @@ confirmer le rendu et l'ergonomie tactile -- voir aussi le piège
 PyInstaller/`customtkinter` documenté dans {doc}`dev-guide/index`.
 ```
 
+## Résilience de la boucle de décompte
+
+`MatchServer.tick_loop()` capture désormais toute exception imprévue en
+son sein (journalisée avec la trace complète) plutôt que de laisser
+mourir la boucle silencieusement -- filet de sécurité ajouté suite à un
+symptôme signalé en pratique : le chrono se figeait indéfiniment, sans
+aucune erreur visible, le reste du serveur (connexions, réponse aux
+commandes) continuant de fonctionner normalement à côté.
+
+```{important}
+**Cause la plus probable identifiée** : sous Windows, remplacer un
+fichier (`Path.replace`) peut échouer avec une "violation de partage"
+si un autre processus a le fichier cible ouvert au même instant
+(antivirus, surveillance de fichiers d'un IDE, Git Bash...) -- une
+différence fondamentale avec la sémantique POSIX (Linux/macOS), où ceci
+n'arrive jamais. Observé une fois en pratique, précisément sur
+`config/match_state.json` -- écrit à chaque tick depuis la persistance
+après plantage (voir plus bas). Sans gestion d'erreur, cette exception
+tuait silencieusement `tick_loop` pour de bon : exactement le symptôme
+rapporté (gel permanent, aucune déconnexion, se produisant aussi bien
+en fenêtre graphique qu'en mode terminal -- sans lien réel avec le
+focus d'une fenêtre, malgré la corrélation observée au départ).
+
+Deux correctifs complémentaires : ce filet dans `tick_loop` (n'importe
+quelle exception, pas seulement celle-ci), et
+`config_store.save_match_snapshot` qui retente quelques fois avant
+d'abandonner proprement (jamais d'exception qui remonterait perturber
+la diffusion de l'état aux écrans pour ce tick). Testé concrètement :
+un échec transitoire (une fois puis réussite) est absorbé et le
+contenu final reste correct ; un échec permanent (toutes les tentatives
+échouent) est abandonné proprement, sans jamais lever d'exception.
+```
+
+## Statut technique exposé via HTTP (`/api/status`)
+
+Les mêmes données déjà affichées dans `control.html` (écrans connectés,
+mode actif, phase en cours, pack de sons, mot de passe configuré ou non)
+sont aussi exposées via un simple GET HTTP, lues directement depuis
+l'instance `MatchServer` partagée avec le serveur WebSocket (voir
+`ServerRuntime`, qui construit maintenant ce `MatchServer` une seule fois
+et le fait circuler vers les deux serveurs plutôt que de le laisser
+`run_ws_server` en créer un nouveau à chaque démarrage).
+
+Utilisé par la fenêtre graphique pour afficher ce même statut sans
+dupliquer la logique de rendu HTML -- interrogé par sondage périodique
+(toutes les 2s) depuis un thread séparé plutôt qu'en temps réel via une
+vraie connexion WebSocket, volontairement : pas besoin de la précision
+temps réel d'une vraie connexion juste pour un affichage de statut, et
+ça évite de dupliquer toute la logique de reconnexion/état déjà présente
+côté web. La requête HTTP elle-même tourne toujours dans un thread à
+part, jamais directement depuis le thread principal de la fenêtre (une
+requête bloquante, même locale, gèlerait sinon l'interface le temps de
+sa réponse).
+
 ## Journal applicatif persistant
 
 En plus du journal affiché dans la fenêtre graphique (en mémoire,
@@ -370,6 +424,21 @@ volatile de la fenêtre.
   dernières secondes de chaque volée -- noierait le journal sans valeur
   diagnostique ajoutée).
 
+```{important}
+`configure_logging` prend un `console_level` séparé du niveau du fichier
+(toujours INFO par défaut, lui) -- la fenêtre graphique doit l'appeler
+avec `console_level=logging.INFO` explicitement, **pas** le défaut
+(`WARNING`, pensé pour un terminal silencieux par défaut, voir
+`fletchtime.__main__`, `-v`/`--verbose`). Un oubli de ce paramètre a
+laissé le widget de journal de la fenêtre silencieux en usage normal
+pendant un temps -- tous les journaux applicatifs ci-dessus sont à
+INFO, donc filtrés par le `WARNING` par défaut, exactement l'inverse de
+ce que ce widget est censé montrer. Confirmé par comparaison directe
+avant/après correctif : file d'attente vide avant, message présent
+après, avec un appel par ailleurs identique.
+```
+
+
 ```{important}
 Le mot de passe (action `authenticate`) n'est **jamais** journalisé -- le
 code ne journalise jamais `data` tel quel, seulement le nom de l'action
@@ -502,6 +571,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
@@ -519,3 +634,15 @@ La miniature d'aperçu de `control.html` est un vrai `display.html` chargé
 dans une `<iframe>` (mise à l'échelle en CSS) plutôt qu'une logique de rendu
 dupliquée -- elle s'enregistre avec la lane spéciale `"apercu"`, exclue du
 comptage des écrans connectés.
+
+```{note}
+**Cette même lane `"apercu"` ne joue jamais de son** (voir `display.html`,
+`soundEnabled`) : sans ça, ouvrir la page de contrôle et un vrai écran
+d'affichage sur le même PC faisait entendre chaque son deux fois --
+l'aperçu est une simple vue visuelle pour le responsable du
+chronométrage, pas un écran destiné aux archers. Un paramètre d'URL
+`?mute=1` permet en plus de couper le son sur n'importe quel autre onglet
+ouvert en trop sur la même machine (ex. pour surveiller une autre lane
+sans dupliquer le son de l'écran qui joue réellement pour les archers).
+```
+

{fletchtime-0.2.3 → fletchtime-0.2.5}/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.3 → fletchtime-0.2.5}/docs/index.md

@@ -27,6 +27,7 @@ page d'accueil, pas ici) -- voir {doc}`user-guide/index`.
 :maxdepth: 2
 :caption: Contenu
 
+premier-club
 specifications
 architecture
 roadmap

fletchtime-0.2.5/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.3 → fletchtime-0.2.5}/docs/roadmap.md

@@ -56,23 +56,69 @@ 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
 
+- ~~**Icône de l'exécutable**~~ -- fait : `web/logo.ico` (multi-résolution,
+  16 à 256px, généré depuis `web/logo.svg`), utilisé par `fletchtime.spec`
+  pour l'exécutable Windows. Sans effet sous Linux, qui n'a pas ce
+  concept de métadonnées d'icône pour un simple binaire (vérifié). Le
+  favicon des pages web était en fait déjà en place, rien à faire là.
+- ~~**Son dupliqué sur plusieurs onglets**~~ -- fait : l'aperçu de
+  `control.html` (une vraie instance de `display.html` en iframe) ne
+  joue plus jamais de son -- c'est une simple vue visuelle, pas un écran
+  destiné aux archers. `?mute=1` permet en plus de couper le son sur
+  n'importe quel autre onglet ouvert en trop sur le même PC.
+- ~~**Chrono figé (sous Windows, pas lié au focus en réalité)**~~ --
+  cause la plus probable identifiée : sous Windows, remplacer un fichier
+  peut échouer avec une "violation de partage" si un autre processus l'a
+  ouvert au même instant (antivirus, surveillance de fichiers d'un
+  IDE...) -- observé une fois en pratique, précisément sur
+  `config/match_state.json`, écrit à chaque tick depuis la persistance
+  après plantage. Sans gestion d'erreur, ça tuait silencieusement
+  `tick_loop` pour de bon -- exactement le symptôme rapporté (gel
+  permanent, pas de déconnexion, se produisant aussi bien en GUI qu'en
+  headless, sans lien réel avec le focus). Deux correctifs : `tick_loop`
+  capture désormais toute exception imprévue en son sein (journalisée
+  avec sa trace complète, ne meurt plus silencieusement) et
+  `save_match_snapshot` retente quelques fois avant d'abandonner
+  proprement (jamais d'exception qui remonterait perturber la diffusion
+  de l'état aux écrans). Testé concrètement : échec transitoire récupéré,
+  échec permanent absorbé sans lever.
+- ~~**Journal absent du widget de la fenêtre**~~ -- vrai bug trouvé en
+  creusant le point précédent : `configure_logging` était appelé sans
+  préciser `console_level`, retombant sur le défaut `WARNING` (pensé
+  pour un terminal silencieux) -- qui filtrait justement tout ce que ce
+  widget est censé montrer (commandes, connexions, transitions, toutes
+  en `INFO`). Corrigé avec `console_level=INFO` explicite pour la
+  fenêtre. Confirmé par comparaison directe avant/après : file vide
+  avant, message présent après.
+- ~~**Données techniques dans la fenêtre**~~ -- fait : nouvel endpoint
+  `/api/status` (les mêmes données déjà affichées dans `control.html`),
+  affiché dans la fenêtre via sondage périodique. `ServerRuntime`
+  construit maintenant le `MatchServer` une seule fois et le partage
+  entre les deux serveurs, plutôt que d'en laisser `run_ws_server` créer
+  un nouveau à chaque démarrage.
+
+
 - ~~**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

{fletchtime-0.2.3 → fletchtime-0.2.5}/fletchtime.spec

@@ -71,6 +71,13 @@ exe = EXE(
     # assets/ du bootstrap), d'où un serveur qui tourne mais ne sert rien
     # d'utile. "." restaure explicitement l'ancien comportement.
     contents_directory=".",
+    # Icône de l'exécutable (barre des tâches, explorateur de fichiers,
+    # raccourci) -- fichier .ico multi-résolution (16 à 256px), généré à
+    # partir de web/logo.svg. PyInstaller ignore ce paramètre sous Linux
+    # (les .ico n'y ont pas de sens -- l'icône affichée dépend du
+    # gestionnaire de fichiers/bureau, hors du contrôle de l'exécutable
+    # lui-même), donc rien à prévoir de spécial pour cette plateforme.
+    icon=str(project_root / "src" / "fletchtime" / "web" / "logo.ico"),
 )
 
 coll = COLLECT(

{fletchtime-0.2.3 → fletchtime-0.2.5}/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.3 → fletchtime-0.2.5}/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.3'
-__version_tuple__ = version_tuple = (0, 2, 3)
+__version__ = version = '0.2.5'
+__version_tuple__ = version_tuple = (0, 2, 5)
 
-__commit_id__ = commit_id = 'gd2257b057'
+__commit_id__ = commit_id = 'ga6e6ad564'