# Horaires ITA ITO

Panneau d'administration des horaires d'ouverture de la boutique **ITA ITO**, et
serveur d'affichage pour un écran e-ink **TRMNL 7,5" (kit DIY Seeed)** posé en
vitrine.

Changer un horaire depuis un téléphone, debout dans la boutique, en deux clics —
et que l'écran suive tout seul, jours fériés genevois et message bilingue
compris.

```
  Écran e-ink (ESP32, Wi-Fi boutique)
        │  GET /api/setup · GET /api/display · POST /api/log
        │  GET /api/device/image/<hash>.bmp
        ▼
  ┌──────────────────────────────────────────────┐
  │  Next.js 16 + PostgreSQL 16                  │
  │  horaires.ita-ito.com                        │
  └──────────────────────────────────────────────┘
        ▲                          │
        │ OIDC                     ├─► api.loxi.ch          (traduction FR→EN)
   Navigateur admin                └─► openholidaysapi.org  (jours fériés CH-GE)
     auth.loxi.ch
```

## Ce qu'il faut savoir avant tout

**L'écran ne reçoit rien.** Il dort sur batterie, se réveille, demande quoi
afficher, et se rendort. On ne peut pas lui pousser une mise à jour : le seul
levier est la durée de son sommeil, réglable dans *Paramètres → Écran*. Une
modification apparaît donc au réveil suivant, pas immédiatement. C'est la nature
du BYOS, pas une limitation de cette application.

**Le nom du fichier image est le hash de son contenu.** Si rien n'a changé,
l'écran reconnaît le nom, ne redessine pas, et économise sa batterie. C'est
pourquoi le rendu doit rester reproductible à l'octet près — d'où les polices
et le logo versionnés dans `public/`.

## Prérequis

- Docker et Docker Compose
- Node.js ≥ 20.9 (seulement pour le développement hors conteneur)
- Une application OIDC dans Authentik (voir plus bas)
- Un écran TRMNL 7,5" dont le portail captif accepte un serveur personnalisé

## Installation locale

```bash
cp .env.example .env
sed -i "s|^AUTH_SECRET=.*|AUTH_SECRET=$(openssl rand -base64 33)|" .env
# Renseignez ensuite POSTGRES_PASSWORD, AUTH_AUTHENTIK_*, TRANSLATION_API_KEY.

docker compose up -d db --wait      # PostgreSQL seul
npm install
npx prisma migrate deploy
npm run seed                        # horaires de démonstration, idempotent
npm run dev                         # http://localhost:3010
```

Le port 3010 n'est pas un caprice : 3000 est déjà pris par une autre pile sur la
machine de développement.

Pour faire tourner l'application elle aussi en conteneur :

```bash
docker compose up -d --build --wait
```

### Commandes utiles

| Commande | Effet |
|---|---|
| `npm run dev` | serveur de développement sur 3010 |
| `npm test` | toute la suite (unitaire + intégration) |
| `npm run coverage` | idem, avec les seuils de couverture |
| `npm run lint` / `npm run typecheck` | ESLint / TypeScript strict |
| `npm run screen:preview` | rend l'écran dans `.preview/`, sans appareil |
| `npm run brand` | régénère le logo depuis le CDN de la boutique |
| `npm run holidays:sync` | synchronise les jours fériés maintenant |
| `npm run translate:test "texte"` | vérifie le service de traduction |

Les tests d'intégration ont besoin d'une base à eux — `TEST_DATABASE_URL`. Ils
la vident entièrement, donc elle ne doit jamais désigner une base qui contient
quoi que ce soit d'utile. Sans cette variable, ils se désactivent plutôt que de
détruire quelque chose.

```bash
docker compose exec db psql -U horaires -d postgres -c "create database horaires_test owner horaires;"
DATABASE_URL="$TEST_DATABASE_URL" npx prisma migrate deploy
```

## Configuration d'Authentik

1. **Groupe** — créez `horaires-admins` et ajoutez-y les personnes qui peuvent
   modifier les horaires. **Ne liez pas ce groupe à l'application** : seuls les
   administrateurs pourraient alors se connecter, et le rôle lecture seule
   deviendrait inatteignable. Pour restreindre l'accès, créez un groupe plus
   large et liez celui-là.

2. **Provider** — *OAuth2/OpenID Provider* :

   | Champ | Valeur |
   |---|---|
   | Client type | Confidential |
   | Signing Key | n'importe quel certificat — **obligatoire** |
   | Redirect URIs (Strict) | `https://horaires.ita-ito.com/api/auth/callback/authentik`<br>`http://localhost:3010/api/auth/callback/authentik` |
   | Scopes | `openid`, `email`, `profile` (les valeurs par défaut) |
   | Subject mode | Based on the User's Email |
   | Include claims in id_token | activé |

   Le claim `groups` arrive via le scope `profile` : aucun mapping à créer. Rien
   à activer pour le PKCE, Authentik annonce `S256` et Auth.js l'utilise seul.

3. **Application** — slug `horaires-ita-ito`, liée au provider. Le slug
   détermine l'issuer, qui doit correspondre **au caractère près, barre oblique
   finale comprise**.

4. **Vérification**, avant même de lancer l'application :

   ```bash
   curl -s https://auth.loxi.ch/application/o/horaires-ita-ito/.well-known/openid-configuration | jq .issuer
   ```

   La valeur doit être identique à `AUTH_AUTHENTIK_ISSUER`. C'est la première
   cause d'échec de connexion, et elle se diagnostique mal depuis l'application.

**Le rôle est fixé à la connexion.** Retirer quelqu'un du groupe ne coupe pas sa
session en cours : l'effet arrive à la reconnexion, ou au bout de huit heures.
Si un compte apparaît en lecture seule alors qu'il ne devrait pas, le tableau de
bord affiche les groupes réellement reçus et celui qui était attendu.

## Appairage de l'écran

Aucun reflashage. Le firmware d'origine suffit.

1. Maintenez le bouton au dos de l'écran **5 secondes** : il ouvre un réseau
   Wi-Fi nommé `TRMNL`.
2. Connectez-vous-y depuis un téléphone ; le portail s'ouvre tout seul.
3. Donnez le Wi-Fi de la boutique, puis **Advanced → Custom Server → Yes**.
4. Saisissez `https://horaires.ita-ito.com` — **sans barre oblique finale**.
   L'URL exacte est rappelée dans *Paramètres → Appareils*.
5. Validez. L'écran s'enregistre seul au premier appel et affiche les horaires.

Il apparaît ensuite dans *Paramètres → Appareils* avec son identifiant, sa
dernière visite, son firmware et sa batterie.

> **Si *Custom Server* n'apparaît pas** dans le portail, le firmware livré avec
> le kit est une version qui ne l'expose pas. Il faut alors flasher le firmware
> TRMNL officiel — ce qui sort du cadre de ce dépôt. Vérifiez ce point avant de
> déployer quoi que ce soit.

## Mise en production

Voir **[DEPLOY.md](DEPLOY.md)** : première installation, mises à jour,
sauvegardes, restauration et retour arrière.

## Dépannage

| Symptôme | Cause la plus probable |
|---|---|
| Connexion refusée en boucle | `AUTH_AUTHENTIK_ISSUER` ne correspond pas exactement à l'issuer annoncé |
| « Compte en lecture seule » | le compte n'est pas dans `AUTHENTIK_ADMIN_GROUP` ; le tableau de bord affiche les groupes reçus |
| L'écran reste blanc | il n'a pas encore atteint le serveur : vérifiez l'URL du portail captif, sans barre oblique finale |
| L'écran n'a pas suivi une modification | normal jusqu'à son prochain réveil ; le tableau de bord indique quand il est attendu |
| « La traduction a échoué » | `TRANSLATION_API_KEY` absente ou révoquée — `npm run translate:test` le dit précisément |
| Jours fériés absents | lancez `npm run holidays:sync` ; la page Fériés affiche la dernière synchro réussie |
| Aperçu d'écran en erreur | le rendu a besoin de `public/fonts` et `public/brand` ; ils sont versionnés, vérifiez qu'ils sont présents |

## Licence

Propriétaire. Voir [LICENSE](LICENSE).