gestion_table_tournante_libre/spec.md

# Gestion de tables tournantes — spécification

## 1. Objet

Un logiciel qui place les personnes d'un événement autour de tables et les
fait tourner sur plusieurs tours, de sorte que chacune rencontre le plus de
monde possible. Il propose **plusieurs placements comparables** plutôt qu'une
réponse unique, mesure chacun par les mêmes indicateurs, et dit à l'opérateur
ce qu'une configuration rend inévitable avant qu'il ne cherche en vain.

Il fonctionne **hors ligne, sans serveur**, et se livre comme un exécutable.

## 2. Contexte d'usage

L'opérateur est l'organisateur d'un souper, d'un colloque ou d'un banquet. Il
travaille sur un portable, dans une salle, souvent sans réseau fiable. Il
prépare son plan la veille et le retouche sur place quand des gens manquent
ou s'ajoutent.

Les conséquences de ce contexte sont des exigences :

- **Aucune connexion n'est requise**, à aucun moment, pas même au premier
  démarrage.
- **Aucune installation de serveur, ni de base de données.** L'exécutable se
  copie et se lance.
- **Rien ne sort de la machine.** Pas de télémétrie, pas de service distant.
- Les données d'un événement se copient, se sauvegardent et se transmettent
  comme des fichiers ordinaires.

## 3. Périmètre

**Dans le périmètre.** Saisir les participants, décrire la salle, générer et
comparer des placements, retoucher à la main, imprimer ce qu'il faut pour
tenir la soirée.

**Hors périmètre, explicitement.** Les inscriptions en ligne, la billetterie,
le paiement, l'envoi de courriels, le travail à plusieurs sur un même plan,
la synchronisation entre postes, les comptes et les droits d'accès.

Un seul opérateur, une seule machine, un seul plan à la fois.

## 4. Les objets manipulés

**Événement** — un nom, une date, et tout le reste ci-dessous.

**Participant** — un nom, éventuellement un courriel et une **appartenance**
(entreprise, équipe, famille, école : l'étiquette qui sert à séparer les gens
qui se connaissent déjà). Un participant peut être **exclu** sans être
supprimé : il reste dans la liste, il n'est plus placé.

**Table** — un numéro à partir de 1, un nombre de sièges, une forme (ronde ou
carrée), et une position sur le plan. **Le nombre de sièges d'une table ne
change pas d'un tour à l'autre** : c'est une propriété du mobilier, pas du
tour.

**Tour** — une des R rondes de la soirée. À chaque tour, chaque participant
non exclu est assis à exactement une table.

**Placement** — l'affectation complète : pour chaque tour, qui est à quelle
table, et à quel siège si les sièges sont attribués.

**Réservation** — une place retenue à la main par l'opérateur avant la
génération. Elle contraint ce que la machine produira et lui survit.

## 5. Le cœur : le placement

### 5.1 Le problème

Étant donné N participants, T tables de capacités fixées et R tours, répartir
les gens à chaque tour de façon à **maximiser le nombre de personnes
distinctes que chacun rencontre**, sous les contraintes que l'opérateur active.

### 5.2 Les contraintes, activables une à une

| contrainte | ce qu'elle exige |
|---|---|
| **Séparer les appartenances** | deux personnes de la même appartenance ne partagent pas une table |
| **Nouveaux voisins à chaque tour** | deux personnes ne se retrouvent pas deux fois à la même table |
| **Nouvelle table à chaque tour** | personne ne revient à une table déjà occupée |
| **Attribuer les sièges** | chacun reçoit un numéro de siège, pas seulement une table |

Elles sont des **objectifs**, pas des interdits absolus : quand la
configuration les rend impossibles à toutes satisfaire, le logiciel produit le
meilleur compromis **et dit lequel**, plutôt que de refuser.

### 5.3 Les indicateurs, mesurés pour chaque placement

Tout placement proposé porte les mêmes chiffres, afin que la comparaison soit
une lecture et non un jugement :

- paires de même appartenance assises ensemble ;
- rencontres répétées (deux personnes réunies plus d'une fois) ;
- nombre maximal de rencontres d'une même paire ;
- retours à une table déjà occupée ;
- personnes rencontrées : **minimum** sur l'ensemble des participants, et
  moyenne.

Le minimum compte plus que la moyenne : il décrit le sort de la personne la
plus mal servie, qui est celle qui se plaindra.

### 5.4 La borne prouvée

Pour certaines configurations — tables de taille égale, nombres bien choisis —
il existe une construction mathématique qui atteint l'optimum, et l'on peut
**prouver** qu'aucun placement ne fera mieux.

Le logiciel doit :

1. calculer cette borne quand elle existe ;
2. afficher, à côté de chaque proposition, l'écart qui l'en sépare ;
3. dire explicitement **« minimum atteint »** quand la proposition l'égale.

Sans cela, l'opérateur ne sait jamais s'il doit relancer la recherche ou
s'arrêter. C'est la différence entre un outil qui propose et un outil en
qui l'on a confiance.

### 5.5 Le diagnostic, avant la recherche

Certaines configurations rendent un conflit **inévitable**, quel que soit
l'algorithme. Par exemple : plus de personnes d'une même appartenance que de
tables — deux d'entre elles se retrouveront forcément ensemble.

Le logiciel détecte ces cas **avant** de chercher, et énonce :

- ce qui est inévitable, et **combien** (« au moins 8 paires de collègues ») ;
- ce qui le rendrait évitable (« avec 7 tables, un plan parfait existe »).

Un opérateur à qui l'on dit « c'est impossible, voici pourquoi, voici le
remède » cesse de relancer la génération en espérant mieux.

### 5.6 Plusieurs propositions, pas une

Une génération produit **plusieurs placements distincts et comparables** — le
nombre est réglable. L'opérateur les compare par leurs indicateurs, en examine
un sur le plan de salle, puis en **retient** un.

Les générations **s'accumulent** : relancer avec d'autres réglages ajoute des
candidats à la liste plutôt que d'effacer les précédents, et un classement
unique les ordonne tous. Une commande efface la liste en épargnant celui qui
est retenu.

### 5.7 Le placement à la main

L'opérateur peut asseoir des gens **avant toute génération** : ces places sont
des **réservations**. La génération suivante les honore et place les autres
autour. Une commande transforme un placement manuel partiel en placement
complet, le générateur comblant les vides.

Une fois un placement retenu, le même geste déplace une personne réelle au
lieu de réserver une place. **Le geste est identique ; ce qui change est
l'état des données**, et l'interface doit le dire pour que l'opérateur sache
lequel des deux il est en train de faire.

## 6. Le plan de salle

C'est la surface de travail principale, du début à la fin.

**Ce qu'il dessine.** Chaque table à l'échelle de son nombre de sièges, ronde
ou carrée, avec ses chaises en couronne. À côté de chaque table, la **liste
numérotée** des personnes qui y sont assises, reliée à la table par un trait.
Les noms ne sont pas écrits autour de la table : au-delà de quelques convives
ils se chevauchent et deviennent illisibles.

**Les gestes.**

- Glisser une personne sur un siège libre la déplace.
- Glisser une personne sur une autre les échange.
- Glisser une personne hors des tables la retire du tour ; elle attend dans
  une **réserve** visible.
- Un menu par personne offre les mêmes actions sans glisser, pour le tactile
  et le clavier.

**Les aides à la lecture.**

- Un sélecteur de tour.
- La mise en évidence d'une personne, **visible à chaque tour**, pour suivre
  son parcours.
- Afficher ou masquer les listes de noms.
- Zoom, ajustement à la fenêtre, plein écran.
- Une commande qui **réorganise les tables** sur une grille assez large pour
  les listes de noms, sans jamais déplacer quelqu'un.

**Les signaux.** Une table où une contrainte est violée le signale sur le
plan, avec le détail au survol. Un bandeau compare en permanence le nombre de
participants au nombre de sièges.

## 7. Les états d'un plan

Quatre états, dont un seul restreint quoi que ce soit.

| état | ce qu'il signifie |
|---|---|
| **Brouillon** | on prépare |
| **Proposé** | des placements existent, aucun n'est retenu |
| **Retenu** | un placement est en vigueur |
| **Bloqué** | rien ne peut plus changer |

**Brouillon, proposé et retenu n'interdisent rien.** Ils ordonnent le travail
et se posent en cliquant l'état ; passer de l'un à l'autre **ne détruit
jamais** de données.

**Bloqué refuse toute modification** — tours, options, tables, participants,
et jusqu'à la position d'une table à l'écran. La lecture et l'impression
restent ouvertes : on bloque un plan précisément pour le distribuer. Seules
deux commandes explicites y entrent et en sortent.

**La dérive avertit, elle ne bloque pas.** Si les participants changent après
qu'un placement a été retenu, le logiciel le signale et laisse l'opérateur
décider : lui seul sait si la personne arrivée en retard doit être placée ou
non.

## 8. Les sorties

- **Une fiche par participant** : son nom, et pour chaque tour sa table et
  son siège.
- **Une feuille par table** : pour chaque tour, qui y est assis.
- **Export du plan** en fichier, pour archive ou transmission.

Tout s'imprime depuis le logiciel, sans service externe.

## 9. Architecture

### 9.1 Forme du projet

Une application **Cordova**, dont le code vit dans `www/` et ne dépend
d'aucun service.

| plateforme | rôle |
|---|---|
| `electron` | la livraison : un exécutable Windows |
| `browser` | le développement et les tests sous Linux |
| `android` | ouvert, non requis pour la première livraison |

Le code applicatif ignore sur quelle plateforme il tourne, sauf aux deux
frontières nommées ci-dessous.

### 9.2 Une seule langue, et c'est une exigence

Tout — le moteur de placement, la géométrie du plan, l'interface — est écrit
en **JavaScript**. Aucune partie du calcul n'est dupliquée dans un second
langage.

Cette propriété doit être **préservée délibérément**. Dès que la même
arithmétique existe en deux endroits, une suite de tests peut prouver qu'ils
s'accordent sans jamais prouver qu'ils ont raison : les deux dérivent
ensemble et les tests restent verts. Une seule implémentation rend ce mode de
défaillance impossible.

### 9.3 Les couches

```
  interface          le plan de salle, les listes, les formulaires
      │
  application        les états, les commandes, l'historique
      │
  moteur             le placement : pur, sans DOM, sans API de plateforme
      │
  stockage           lecture et écriture de fichiers
```

**Le moteur ne connaît ni le DOM ni Cordova.** Il reçoit des nombres et des
listes, il rend des placements. C'est ce qui le rend testable sous `node`, en
quelques secondes, sans navigateur ni émulateur — et c'est la condition pour
qu'il soit éprouvé sérieusement.

**La géométrie du plan** — taille d'une table selon son nombre de sièges,
position des chaises, place réservée à une liste de noms — est elle aussi un
module **de fonctions pures**, séparé du rendu, et testé de la même façon.

### 9.4 Stockage

Un **fichier par événement**, en JSON, dans le répertoire de données de
l'application. Lisible, copiable, sauvegardable, transmissible.

Un plan complet — une centaine de personnes, une douzaine de tables, cinq
tours — pèse quelques centaines de kilooctets. Une base de données
n'apporterait rien et ajouterait une dépendance native à empaqueter par
plateforme.

L'accès au système de fichiers est la **première des deux frontières de
plateforme** : une interface unique, deux implémentations, l'une pour
`electron`, l'autre pour `browser`.

La seconde frontière est l'**impression**.

## 10. Exigences de développement

Elles ne sont pas des préférences de style : chacune répond à une façon connue
de se tromper.

### 10.1 Les constantes de géométrie se mesurent

Toute dimension qui dépend du rendu du texte — hauteur d'une ligne, largeur
d'une colonne, nombre de caractères tenant sur une ligne — se **mesure dans un
navigateur**, sur la police réellement rendue. Jamais déduite d'une autre
constante, jamais posée de tête.

Un seuil en nombre de caractères se cale sur le **glyphe le plus large** de
l'alphabet visé, pas sur une moyenne. Un seuil moyen laisse déborder les noms
écrits en lettres larges, silencieusement, par-dessus la ligne suivante.

Chaque constante mesurée porte en commentaire **ce qu'elle mesure et
pourquoi**, afin que personne ne la « corrige » plus tard par le calcul.

### 10.2 Un test qui ne peut pas échouer ne prouve rien

Tout test ajouté doit être **montré en train d'échouer** sur le code
d'avant. Un test qui passe du premier coup n'a rien démontré tant qu'on n'a
pas vu ce qu'il refuse.

Un test de rendu lit le **style calculé**, pas la présence d'une classe : une
classe peut se poser sur un élément qui ne peint rien.

Un test qui parcourt un ensemble refuse de passer quand cet ensemble est
vide : « zéro fichier examiné » n'est pas « zéro problème ».

### 10.3 Les règles se gardent, pas seulement les cas

Quand un défaut est corrigé, le test qui l'accompagne épingle la **règle**
plutôt que le cas. Une valeur remise à la main sera défaite par la main
suivante ; une règle qui fait échouer la construction tient.

### 10.4 Les trois niveaux d'épreuve

| niveau | ce qu'il couvre | quand |
|---|---|---|
| `node` | moteur et géométrie, sans navigateur | à chaque modification, quelques secondes |
| navigateur | ce que l'interface dessine et ce que les gestes produisent | avant chaque livraison |
| manuel | une soirée complète, de la saisie à l'impression | avant chaque livraison au client |

### 10.5 Accessibilité et thèmes

Le texte tient **4,5:1** de contraste sur son fond. Chaque couleur choisie est
accompagnée du ratio mesuré. L'application fonctionne en thème clair comme en
thème sombre ; les deux sont éprouvés par rendu, jamais seulement par calcul.

## 11. Livraison

L'exécutable Windows se construit depuis Linux par la plateforme `electron`
de Cordova. **Cette capacité est à vérifier dès la première semaine**, sur un
squelette vide : découvrir en fin de projet qu'une étape exige une machine
Windows coûte beaucoup plus cher que de le découvrir tout de suite.

Ce qui est livré au client : un exécutable, et rien d'autre à installer.

## 12. Ce que ce document ne tranche pas

À décider avant de coder :

1. **La bibliothèque d'interface** — Cordova n'en impose aucune.
2. **Le rendu du plan de salle** — SVG, canvas, ou éléments positionnés. Le
   premier se teste et s'inspecte le plus facilement.
3. **La langue de l'interface** et le mécanisme de traduction, à poser dès le
   départ plutôt que d'avoir à retrouver les chaînes plus tard.
4. **Le nom du produit** et l'identité de l'exécutable.