# Pointage et imputation des prestations — maquettes d'écrans

Dix-neuf écrans haute fidélité du module de pointage Merlin, à l'identité Merlin,
sur le jeu de données du workshop Constructa Luxembourg du 2 septembre 2026.

**Ouvrir `index.html`.** Pas de build, pas d'installation, pas de dépendance externe.

---

## Ce que c'est

Une **maquette fonctionnelle** : les compteurs comptent, les filtres filtrent, les
validations valident, le glisser-déposer déplace. Elle sert trois publics :

- **le client**, pour valider le flux avant qu'une ligne de code soit écrite ;
- **l'équipe de développement**, qui y trouve le comportement attendu écran par écran,
  les règles de gestion et le contrat de données ;
- **l'intégration Merlin**, à qui elle donne le vocabulaire, les états et les mailles
  de consolidation à reprendre tels quels.

L'état vit en mémoire et repart de zéro à chaque rechargement. Aucun stockage local,
aucun appel réseau.

---

## Organisation

```
index.html                sommaire, vignettes, jeu de données
merlin-tokens.css         jetons de la charte — livrés tels quels, non modifiés
merlin-ui.css             couche de composants : une classe = un composant React attendu
merlin-data.js            référentiels, règles de calcul, chrome (barre, flux, rail)
ecrans/                   les dix-neuf écrans, un fichier autonome par écran
assets/                   les deux wordmarks
reference/                le brief et les deux spécifications d'origine
audit.html                harnais de vérification : rendu et débordement à 1440 et 1024 px
verifier.sh               contrôle de syntaxe des scripts, sans navigateur
NOTES.md                  écarts par rapport au brief, avec leur raison
```

### Les dix-neuf écrans

| | Écran | Rôle |
|---|---|---|
| **A1** | Grille de planification hebdomadaire | Planification |
| **A2** | Constitution des équipes | Planification |
| **A3** | Planification en masse | Planification |
| **B1** | Mes chantiers du jour | Chef d'équipe — mobile |
| **B2** | Saisie de l'équipe | Chef d'équipe — mobile |
| **B3** | Deuxième activité et mode expert | Chef d'équipe — mobile |
| **B4** | Déclaration d'absence | Chef d'équipe — mobile |
| **C1** | Journée reçue, tous chantiers | Conducteur |
| **C2** | Correction et scission | Conducteur |
| **C3** | Saisie déléguée et manquants | Conducteur |
| **D1** | Consolidé par jour | Bureau |
| **D2** | Détail par pointage | Bureau |
| **D3** | Alertes | Bureau |
| **D4** | Exports générés — Kostor et Salaris | Bureau |
| **E1** | Tableau de bord chantier | Contrôle de gestion |
| **E2** | Matrice ouvriers × jours | Contrôle de gestion |
| **F1** | Collecte externe | Intégration |
| **F2** | Tables de correspondance | Paramétrage |
| **F3** | Contrôles et seuils | Paramétrage |

---

## Pour l'équipe de développement

### Les quatre fonctions à reprendre telles quelles

Elles sont dans `merlin-data.js` et portent l'essentiel du modèle :

| Fonction | Ce qu'elle décide |
|---|---|
| `cible(p)` | La ligne de budget d'un pointage — déduite de l'activité, ou choisie en mode expert |
| `controles(S, p)` | Les alertes d'un pointage, **avec leur portée** : `date`, `ressource+date`, `pointage` |
| `journees(S)` | La consolidation par `(ressource, date)`, tous chantiers confondus — la maille de la paie |
| `reel(S)` | La consommation du budget, sur les seules heures validées par le bureau |

### Les six règles qui structurent tout

1. La clé d'un pointage est **`(ressource, date, chantier, séquence)`** — jamais `(ressource, date)`.
   Plusieurs pointages par personne et par jour sont le cas nominal.
2. **Le terrain ne voit jamais le métré.** Il confirme une activité proposée par son métier ;
   la ligne de budget s'en déduit, dans le budget du chantier du pointage.
3. Les contrôles s'évaluent sur **la personne et la date, tous chantiers confondus**.
   Un cumul filtré par chantier ne verrait rien.
4. Une **absence** est un objet distinct — `{ ressource, date, motif, posePar }` — jamais un
   pointage à zéro heure, jamais un manquant.
5. Une heure n'entre dans le réel **qu'après validation bureau**. Avant, elle est « en attente ».
6. Les **seuils sont du paramétrage**, pas des constantes : voir F3.

Les vingt-et-une règles complètes sont dans `reference/maquette.html`, écran « Règles & états ».

### Correspondance composants

Les classes de `merlin-ui.css` sont nommées pour être reprises directement :

| Classe | Composant attendu |
|---|---|
| `.top`, `.flux`, `.rail`, `.stage` | `AppBar`, `FluxSteps`, `NavRail`, `Stage` |
| `.panel` + `.actions` | `Panel` avec sa barre d'actions |
| `.tag` (`.ok` `.wait` `.flag` `.calm` `.brand` `.alt`) | `Tag` — fond teinté clair, texte foncé, jamais l'inverse |
| `.chtabs` / `.chtab` | `ChantierTabs` |
| `.segmented` / `.seg` | `SegmentedControl` |
| `.kpis` / `.kpi` | `KpiRow`, `KpiCard` |
| `.device`, `.crew`, `.step`, `.sheet` | Cadre mobile, carte d'ouvrier, compteur, feuille modale |
| `.pgrid`, `.mx` | Grille de planification, matrice ouvriers × jours |
| `.bar` | `ProgressBar` |

### Densité et responsive

Les tableaux de pointage se lisent à **vingt lignes à l'écran** : cellule `9px 12px`, corps 14 px,
chiffres en `tabular-nums`. Les écrans desktop se lisent à 1440 px et restent utilisables à 1024 ;
un tableau large défile dans son propre conteneur `.scrollx`, la page ne défile jamais
horizontalement. Les écrans mobiles sont rendus dans un cadre de 390 × 844.

### Vérifier après modification

```bash
./verifier.sh
```

Puis ouvrir `audit.html` dans un navigateur : il charge les dix-neuf écrans à 1440 et 1024 px
et signale tout écran vide ou tout débordement horizontal.

---

## Vocabulaire

Vocabulaire chantier, pas vocabulaire logiciel. On écrit **pointage**, **chantier**, **métré**,
**conducteur**, **imputation**, **valorisation**, **ligne de budget**, **activité**, **mode expert** —
jamais *timesheet*, *resource* ou *task*.

Les cinq états d'un pointage, dans cet ordre strict et sans saut :
`saisie` → `envoye` → `conducteur` → `bureau` → `exporte`.