Planification/CLAUDE.md

# CLAUDE.md — Workflow de développement Planification

> **À lire avant toute modification.** Ce fichier décrit le processus complet
> que Claude doit suivre quand Quentin demande une modification de l'extension.

---

## Stack du projet

- **Type** : extension navigateur Manifest V3 (Chrome / Edge / Firefox 140+)
- **Fonction** : viewer du planning des techniciens DGNSI dans EasyVista
- **Cible utilisateurs** : techniciens DGNSI (Canton de Vaud)
- **Auteur** : Quentin Rouiller (email dans la mémoire Claude `user_role.md`)
- **Repo Gitea** : https://gitea.netaplaid.ch/FroSteel/Planification
- **Config runtime** : `chrome.storage.local["admin_config"]` (persiste entre updates)

## Structure du repo

```
src/                 # Sources de l'extension (chargées par le navigateur)
├── manifest.json    # Manifest V3 — version YYYY.M.PATCH
├── background.js    # Service worker
├── viewer.{html,js,css}
└── icons/

Autres/              # Méta + build
├── build.sh         # Génère dist/{chromium,firefox}/, .zip, .xpi, met à jour firefox-updates.json
├── CHANGELOG.md     # Synchronisé avec le CHANGELOG.md à la racine
├── README.md        # Synchronisé avec le README.md à la racine
└── LICENSE

Builds/              # Artefacts distribués (Chromium/, Firefox/, .zip, .xpi)
dist/                # Sortie de build (gitignoré)
firefox-updates.json # Manifest d'auto-update Firefox (servi via update_url)
CLAUDE.md            # Ce fichier
CHANGELOG.md         # Source de vérité du changelog (lu par AMO + GitHub-style)
README.md            # Source de vérité du README
```

> **NB** : le repo Gitea utilise un **layout flat à la racine** pour le code
> source historique (`build.sh`, `README.md`, `CHANGELOG.md`, `LICENSE`,
> `firefox-updates.json` à la racine, et `src/` pour le code). En local,
> le dossier `Autres/` contient une copie de ces fichiers — tu peux éditer
> l'un ou l'autre, mais quand tu pousses sur Gitea c'est la racine qui doit
> être mise à jour.

---

## Workflow standard d'une demande de modification

Quand Quentin demande une nouvelle fonctionnalité ou un bugfix :

### Phase 1 — Code + build local (toi seul, pas encore de push)

1. **Comprendre la demande**, poser des questions si nécessaire avant d'écrire du code.
2. **Coder les modifications** dans `src/` (jamais directement dans `dist/` ou `Builds/`).
3. **Bumper la version** : incrémenter le 3e chiffre dans `src/manifest.json`
   (ex: `2026.5.41` → `2026.5.42`). Bump majeur (2e chiffre) seulement pour
   les refontes ; année (1er chiffre) au passage à 2027.
4. **Mettre à jour le CHANGELOG** (`Autres/CHANGELOG.md` ET la copie racine
   `CHANGELOG.md`) en ajoutant une nouvelle entrée en haut.
5. **Mettre à jour le README** (`Autres/README.md` ET racine `README.md`)
   si la nouvelle version touche aux fonctionnalités principales.
6. **Builder** : `./Autres/build.sh` — ça produit `dist/chromium/`,
   `dist/firefox/`, le `.zip` et le `.xpi` avec la nouvelle version.
7. **Annoncer à Quentin** : "v2026.5.X buildée, recharge l'extension dans
   ton navigateur et teste". Décrire brièvement ce qui a changé visuellement.
8. **Attendre son retour**. Tant qu'il n'a pas dit "OK", ne pas pousser sur
   Gitea. Si correction demandée, retourner à l'étape 2.

### Phase 2 — Push sur Gitea (uniquement après validation explicite)

Quand Quentin dit "OK push" / "valide" / équivalent :

1. **Préparer un clone Gitea à jour** dans `/tmp/planif-push/` (clone si pas
   présent, sinon `git fetch origin && git reset --hard origin/main`).
2. **Synchroniser** :
   - `rsync -a --delete /Users/quentin/Documents/Planning/src/ /tmp/planif-push/src/`
   - Copier les versions racine de `CHANGELOG.md`, `README.md`, `LICENSE`,
     `build.sh` (les versions racine sur Gitea, pas celles de `Autres/`)
3. **Régénérer `firefox-updates.json`** à la racine du repo : ajouter
   l'entrée de la nouvelle version en haut de la liste `updates` (les
   anciennes entrées restent — Firefox prend la version la plus haute
   parmi celles listées). Le `update_link` pointe vers la release Gitea :
   `https://gitea.netaplaid.ch/FroSteel/Planification/releases/download/vYYYY.M.PATCH/planification-vYYYY.M.PATCH-firefox.xpi`.
   Le `update_hash` est calculé après signature AMO (cf. Phase 3).

   Le repo Gitea est **public**, donc l'URL fixe `update_url` =
   `https://gitea.netaplaid.ch/FroSteel/Planification/raw/branch/main/firefox-updates.json`
   est accessible sans auth → Firefox peut le fetcher directement.
   `build.sh` maintient automatiquement ce JSON à chaque build (ajoute /
   met à jour l'entrée de la version courante).
4. **Commit + push** :
   ```bash
   cd /tmp/planif-push
   git add -A
   git commit -m "vYYYY.M.PATCH — <description courte>"
   git push origin main
   git tag -a vYYYY.M.PATCH -m "vYYYY.M.PATCH"
   git push origin vYYYY.M.PATCH
   ```
5. **Créer la release Gitea** via l'API (POST
   `/repos/FroSteel/Planification/releases`) avec :
   - `tag_name`: `vYYYY.M.PATCH`
   - `name`: `vYYYY.M.PATCH`
   - `body`: extrait du CHANGELOG (la section de cette version)
6. **Uploader les binaires** comme assets de la release :
   - `dist/planification-vYYYY.M.PATCH-chromium.zip`
   - `dist/planification-vYYYY.M.PATCH-firefox.xpi` (NON signé pour le moment)
7. **Mettre à jour le wiki Gitea** :
   - Page **Versions** : ajouter une entrée détaillée en haut (dérivée du CHANGELOG)
   - Page **Utilisation** : si le changement modifie l'UX (ajout d'un bouton,
     d'une section admin, d'un comportement) → documenter
   - Page **Architecture** : si nouvelles fonctions clés / nouvelle config
     persistée → documenter

### Phase 3 — Signature Firefox (manuel, fait par Quentin)

L'addon `planification-dgnsi@netaplaid.ch` est **déjà enregistré** sur AMO en
mode "On your own" (Unlisted, self-distributed). Pour chaque nouvelle
version, la procédure est :

1. Quentin va sur https://addons.mozilla.org/developers/
2. Trouve l'addon `Planification` dans la liste → **"Téléverser une nouvelle
   version"** (pas "Submit a New Add-on" — l'addon existe déjà)
3. Upload le `.xpi` non signé qui se trouve sur la release Gitea (ou en local)
4. Mozilla valide + signe (généralement instantané pour une nouvelle version
   d'un addon existant) → Quentin télécharge le `.xpi` signé
5. Quentin revient vers Claude avec le chemin du `.xpi` signé
   (typiquement `/Users/quentin/Downloads/<hash>-<version>.xpi`)

Claude fait alors :
1. Vérifier que `META-INF/mozilla.rsa` + `META-INF/cose.sig` sont présents
2. Calculer le `sha256` du `.xpi` signé
3. Copier le `.xpi` signé dans `dist/` et `Builds/` (archive locale)
4. Remplacer l'asset `.xpi` de la release Gitea (delete + upload)
5. Mettre à jour `firefox-updates.json` : `"update_hash": "sha256:<hash>"`
   pour cette version
6. Commit + push le JSON mis à jour

À partir de ce moment, l'auto-update Firefox déclenche : tous les techs
DGNSI déjà installés en version précédente passent à la nouvelle dans les
24h via le mécanisme natif `update_url` de Firefox, sans aucune action de
leur part.

⚠️ **Chrome/Edge ne sont PAS concernés** par AMO. Les techs sur Chrome
restent sur la version installée jusqu'à ce qu'ils rechargent manuellement
le `.zip` (chrome://extensions → Recharger). Pas d'auto-update natif pour
les extensions chargées en "non empaquetées".

---

## Token Gitea

⚠️ **Le token API Gitea ne doit JAMAIS apparaître dans ce fichier ni dans le
repo Gitea**. Il est stocké uniquement dans la mémoire Claude locale
(`~/.claude/projects/-Users-quentin-Documents-Planning/memory/gitea_token.md`,
hors repo). Si Claude perd la mémoire (nouvelle session non héritée),
demander à Quentin de redonner le token.

Header API à utiliser : `Authorization: token <TOKEN>` + `User-Agent: curl/8.4.0`
(le User-Agent évite que Cloudflare bloque les requêtes Python urllib).

---

## Règles importantes

- **Ne jamais hardcoder** dans `src/` : groupe EV, équipe, domaines, absences
  récurrentes. Tout passe par `admin_config`. Les seuls hardcodes acceptables
  sont les **filets de sécurité** (DEFAULT_GROUP_ID, DEFAULT_EV_ORIGINS pour
  le 1er install). Cf. v2026.5.41 pour la migration complète.
- **Ne jamais pousser sur Gitea sans validation explicite** de Quentin.
- **Toujours bumper la version** avant un push qui modifie le code.
- **Toujours mettre à jour le CHANGELOG** avant un push.
- **Tags non touchés** sur Gitea : `v1.0.0`-`v3.3.0`, `v4.1.x`-`v4.3.0`,
  `v5.0.0`, `v2026.5.27`-`v2026.5.32` (ceux-là pointent vers du code
  reconstitué historique, ne jamais les bouger).
- **Force-push uniquement si Quentin le demande explicitement.**
- **L'email de l'auteur** ne doit apparaître nulle part dans `src/` ni dans
  les fichiers Markdown du repo (CLAUDE.md, README.md inclus). Il est stocké
  uniquement en mémoire Claude (`user_role.md` / `gitea_token.md`) et exposé
  obfusqué (entités HTML) sur la page wiki Contact.

---

## Pages wiki Gitea

| Page | Contenu | Quand mettre à jour |
|---|---|---|
| **Home** | Pitch, contexte, démarrage rapide | Rarement |
| **Utilisation** | Guide complet pour l'utilisateur | À chaque changement UX |
| **Versions** | Historique détaillé des versions | À chaque release |
| **Architecture** | Doc technique (fonctions, config, structure) | À chaque ajout d'helper / changement structurel |
| **Contact** | Email obfusqué + lien Issue Gitea | Rarement |

URL de base wiki : `https://gitea.netaplaid.ch/FroSteel/Planification/wiki/<NOM>`
Endpoint API : `/api/v1/repos/FroSteel/Planification/wiki/page/<NOM>` (PATCH avec
`content_base64`).

---

## Pour résumer ton rôle, Claude

Quentin demande une modif → tu codes → tu builds → il teste → il valide →
tu push tout (Gitea + wiki + firefox-updates.json). Plus tard il revient avec
le `.xpi` signé d'AMO → tu mets à jour la release et le `update_hash` du JSON.

Si tu hésites sur quoi faire à un moment, **demande**. Ne suppose pas.