Merge pull request 'docs(ops): add triple-source sync + troubleshooting + proposer spec' (#67) from docs/ops-missing2-20260201 into main

Reviewed-on: #67

docs/FEATURE-PROPOSER.md

@@ -0,0 +1,103 @@
+# FEATURE — “Proposer” (édition par paragraphe → issue Gitea)
+
+Dernière mise à jour : 2026-02-01
+
+Cette feature permet à un lecteur de proposer une correction/amélioration d’un paragraphe, en générant une issue pré-remplie dans Gitea.
+
+---
+
+## 0) Objectif fonctionnel
+Depuis une page chapitre :
+1) clic sur **Proposer** sur un paragraphe
+2) choix #1 (type)
+3) choix #2 (state/catégorie selon UI)
+4) ouverture d’un seul onglet vers Gitea : `/issues/new?...`
+5) issue pré-remplie avec :
+   - chemin / URL / ancre
+   - texte actuel (citation)
+   - champs “Proposition / Justification”
+6) l’utilisateur valide, et le runner/CI traite.
+
+---
+
+## 1) Dépendances de configuration (critique)
+
+Le lien Gitea est construit à partir de variables publiques injectées au build Astro :
+
+- `PUBLIC_GITEA_BASE` (ex: `https://gitea.archicratie.trans-hands.synology.me`)
+- `PUBLIC_GITEA_OWNER` (**casse sensible**, ex: `Archicratia`)
+- `PUBLIC_GITEA_REPO` (ex: `archicratie-edition`)
+
+### Symptômes si mauvais
+- mauvais repo → 404
+- redirect login inattendu
+- création d’issues impossible
+
+---
+
+## 2) Contrat “une seule ouverture d’onglet”
+Le flow ne doit jamais ouvrir deux onglets.
+
+### Contrat
+- pas de `window.open(...)`
+- un seul `a.target="_blank"` (ou équivalent) déclenché
+- sur click : handler doit neutraliser les propagations parasites
+
+### Vérification (NAS)
+en sh :
+curl -fsS http://127.0.0.1:8082/archicratie/archicrat-ia/chapitre-4/ > /tmp/page.html
+grep -n "window.open" /tmp/page.html | head
+
+Doit retourner 0 ligne.
+
+## 3) Diagnostic “trace ouverture onglet” (navigateur)
+
+Dans la console, tu peux surcharger temporairement les mécanismes d’ouverture pour tracer :
+
+si un window.open survient,
+
+ou si un a.click target _blank est appelé.
+
+But : prouver qu’il n’y a qu’un seul événement d’ouverture.
+
+## 4) URL attendue (forme)
+
+L’onglet doit ressembler à :
+
+{PUBLIC_GITEA_BASE}/{OWNER}/{REPO}/issues/new?title=...&body=...
+
+Important : owner et repo doivent être exactement ceux du repo canonique.
+
+## 5) Pré-requis d’accès
+
+L’utilisateur doit être loggé sur Gitea pour accéder à /issues/new
+
+Si non loggé : redirect vers /user/login (comportement normal)
+
+## 6) Tests fonctionnels (checklist)
+
+Ouvrir une page chapitre (ex chapitre 4)
+
+Clic Proposer (sur un paragraphe)
+
+Choix 1 puis choix 2
+
+Vérifier :
+
+1 seul onglet
+
+URL du repo correct
+
+formulaire new issue visible
+
+title/body pré-remplis (chemin + ancre + texte actuel)
+
+Créer l’issue → vérifier le traitement CI/runner
+
+## 7) Pannes typiques + causes
+
+404 sur issue/new : PUBLIC_GITEA_OWNER/REPO faux (souvent casse)
+
+2 onglets : double handler (bubbling + ouverture multiple)
+
+pas de favicon : cache ou absence dans public/ → rebuild

docs/OPS-SYNC-TRIPLE-SOURCE.md

@@ -0,0 +1,122 @@
+# OPS-SYNC-TRIPLE-SOURCE — Mac Studio / Gitea / NAS (prod)
+
+Dernière mise à jour : 2026-02-01
+
+Ce document décrit la synchronisation **sans ambiguïté** entre :
+- **Local (Mac Studio)** : édition / écriture / préparation PR
+- **Gitea** : **vérité canonique** (branche `main`)
+- **NAS Synology DS220+** : déploiement (blue/green) à partir de `main`
+
+---
+
+## 0) Invariants (à ne jamais violer)
+
+1) **Gitea `main` = source de vérité.**  
+2) Le NAS ne doit pas “inventer” du code : pas d’édition manuelle non versionnée en prod (sauf hotfix temporaire immédiatement reporté dans une PR).  
+3) Le bouton “Proposer” dépend de `PUBLIC_GITEA_*` : une valeur fausse → 404 / redirect login / mauvais repo.
+4) Les secrets (tokens) **ne doivent jamais** entrer dans le repo : `.env*` ignorés, token injecté uniquement via variable d’environnement locale/CI.
+
+---
+
+## 1) Topologie réelle (ce que nous avons)
+
+### 1.1 Local (Mac Studio)
+- Dev et documentation.
+- Git complet.
+- On fait : branches, commits, push, PR, merge.
+
+### 1.2 Gitea
+- Repo canonique : `Archicratia/archicratie-edition`.
+- `main` = défaut + protégée.
+- Toute modif arrive via PR.
+
+### 1.3 NAS (prod)
+- Chemin canonique :
+  - `/volume2/docker/archicratie-web/releases/<timestamp>/app`
+  - `/volume2/docker/archicratie-web/current` → symlink vers la release active
+- Blue/Green :
+  - `web_blue` sur `127.0.0.1:8081`
+  - `web_green` sur `127.0.0.1:8082`
+- Reverse proxy DSM : bascule 8081 ↔ 8082.
+
+---
+
+## 2) Règle d’or : qui écrit quoi, où ?
+
+### 2.1 Toute écriture “source” se fait sur Mac Studio
+- Code Astro
+- Scripts
+- Docs `docs/*.md`
+- `.gitignore`
+
+### 2.2 Gitea ne reçoit que via PR
+- Push sur branche feature/docs
+- PR → CI → merge
+
+### 2.3 NAS ne fait que :
+- `git reset --hard origin/main` (alignement)
+- build image + restart slot blue/green
+- smoke test
+- bascule reverse proxy DSM
+
+---
+
+## 3) Procédure standard (la seule à utiliser)
+
+### Étape A — Mac Studio → Gitea (PR)
+1) `git checkout -b feat/...` ou `docs/...`
+2) commits propres et atomiques
+3) `git push -u origin <branch>`
+4) PR dans Gitea → CI OK → merge dans `main`
+
+### Étape B — NAS : aligner `current` sur `origin/main`
+Sur NAS, git n’est pas forcément installé : on utilise un conteneur git.
+en sh :
+
+APP="/volume2/docker/archicratie-web/current"
+U_ID="$(id -u)"; G_ID="$(id -g)"
+
+sudo docker run --rm --network host \
+  -u "$U_ID:$G_ID" -e HOME=/tmp \
+  -v "$APP":/repo -w /repo \
+  --entrypoint sh alpine/git -lc '
+set -eu
+git config --global --add safe.directory /repo
+git config http.sslVerify false
+
+git fetch origin --prune
+git checkout -B main
+git reset --hard origin/main
+git status -sb
+'
+
+### Étape C — NAS : rebuild du slot inactif + smoke + bascule
+
+Rebuild de l’image (slot inactif recommandé).
+
+docker compose up -d --force-recreate --no-build web_green (ou blue)
+
+smoke test via script ou curl
+
+bascule DSM vers le port du slot actif
+
+## 4) Checkpoints rapides (sanity)
+### 4.1 Vérifier que NAS = origin/main
+
+git rev-parse --short HEAD sur NAS (via alpine/git)
+
+doit égaler origin/main.
+
+### 4.2 Vérifier “Proposer” (points minimum)
+
+PUBLIC_GITEA_OWNER=Archicratia (casse sensible)
+
+PUBLIC_GITEA_REPO=archicratie-edition
+
+Flow : Proposer → choix 1 → choix 2 → onglet Gitea /issues/new?... OK
+
+## 5) Rollback
+
+DSM reverse proxy : repasser sur l’autre port (8081/8082).
+
+En cas de code cassé : réaligner NAS sur origin/main précédent (tag/release) ou repointer /current vers une release précédente.

docs/TROUBLESHOOTING.md

@@ -0,0 +1,213 @@
+# TROUBLESHOOTING — Archicratie Web / NAS / Gitea
+
+Dernière mise à jour : 2026-02-01
+
+Ce document liste les symptômes rencontrés et les remèdes **concrets**.
+
+---
+
+## 0) Réflexe unique
+Toujours isoler : **Local**, **Gitea**, **NAS**, **Navigateur**.
+
+- Si ça marche sur `127.0.0.1:8082` mais pas sur le domaine → proxy/cache.
+- Si ça marche après login Gitea mais pas via “Proposer” → variables `PUBLIC_GITEA_*`.
+- Si push refusé → branch protection (normal).
+
+---
+
+## 1) “Proposer” ouvre Gitea mais retourne 404 / non autorisé
+
+### Symptôme
+Nouvel onglet :
+- 404 Not Found / “n’existe pas ou pas autorisé”
+- ou redirect `/user/login`
+
+### Cause la plus fréquente
+URL pointe vers **mauvais owner/repo** (casse sensible) :
+- `archicratia/archicratie-web` au lieu de `Archicratia/archicratie-edition`
+
+### Diagnostic
+Sur NAS (ou dans le HTML généré), vérifier l’URL ouverte :
+- doit contenir : `/Archicratia/archicratie-edition/issues/new`
+
+### Fix
+Dans `.env` de build prod (NAS) :
+- `PUBLIC_GITEA_OWNER=Archicratia`
+- `PUBLIC_GITEA_REPO=archicratie-edition`
+Puis rebuild + restart du container + smoke.
+
+---
+
+## 2) Double onglet à la validation du flow “Proposer”
+
+### Symptôme
+Deux onglets s’ouvrent au moment de valider (après choix 1 / choix 2).
+
+### Causes possibles
+- handler JS déclenché deux fois (bubbling)
+- présence d’un `window.open` + `a.click()` simultanément
+- bouton “Proposer” est un `<a target=_blank>` et un autre handler ouvre aussi.
+
+### Diagnostic rapide (devtools navigateur)
+Chercher `window.open` dans la page générée :
+- la commande doit retourner 0 lignes.
+
+Sur NAS :
+en sh :
+
+curl -fsS http://127.0.0.1:8082/archicratie/archicrat-ia/chapitre-4/ > /tmp/page.html
+grep -n "window.open" /tmp/page.html | head
+
+Fix
+
+garder un seul mécanisme d’ouverture
+
+sur click : preventDefault() + stopImmediatePropagation()
+
+## 3) Favicon 504 / erreurs console sur favicon
+# Symptôme
+
+Console navigateur : GET /favicon.ico 504
+
+# Cause fréquente
+
+Cache du navigateur (ancienne erreur conservée).
+
+# Diagnostic
+
+Comparer :
+
+curl -I http://127.0.0.1:8082/favicon.ico
+
+curl -kI https://<domaine>/favicon.ico
+
+Si curl = 200 et navigateur = 504 → cache.
+
+# Fix
+
+Désactiver cache dans l’onglet Réseau (devtools)
+
+hard refresh
+
+vérifier droits fichiers dans dist/
+
+## 4) Sur NAS : git: command not found
+# Symptôme
+
+git fetch impossible sur le NAS.
+
+# Cause
+
+Git non installé sur DSM shell.
+
+# Fix standard (recommandé)
+
+Utiliser un conteneur git :
+
+APP="/volume2/docker/archicratie-web/current"
+U_ID="$(id -u)"; G_ID="$(id -g)"
+
+sudo docker run --rm --network host \
+  -u "$U_ID:$G_ID" -e HOME=/tmp \
+  -v "$APP":/repo -w /repo \
+  --entrypoint sh alpine/git -lc '
+set -eu
+git config --global --add safe.directory /repo
+git config http.sslVerify false
+git fetch origin --prune
+git status -sb
+'
+
+## 5) Git : “dubious ownership in repository”
+# Symptôme
+
+fatal: detected dubious ownership
+
+# Fix
+
+Dans le conteneur git (ou machine locale) :
+git config --global --add safe.directory /repo
+
+## 6) Git : non-fast-forward au push
+# Symptôme
+
+rejected (non-fast-forward)
+
+# Cause
+
+Ta branche locale est en retard vs remote.
+
+# Fix
+
+En général :
+
+on fait une PR depuis une branche
+
+ou on rebase/merge origin/main avant push
+
+Sur une branche de travail :
+git fetch origin
+git rebase origin/main
+# ou
+git merge origin/main
+
+## 7) Gitea : “Not allowed to push to protected branch main”
+# Symptôme
+
+pre-receive hook declined
+
+# Cause
+
+Protection de branche (normal/attendu).
+
+# Fix
+
+Push sur une branche
+
+Ouvrir PR
+
+Merger via UI Gitea
+
+## 8) Docker build : BuildKit / buildx / API version
+# Symptômes typiques
+
+the --network option requires BuildKit
+
+BuildKit is enabled but the buildx component is missing
+
+client version ... too new. Maximum supported API version ...
+
+# Fix “robuste” (principe)
+
+installer buildx si nécessaire
+
+si DSM/docker API ancienne : définir DOCKER_API_VERSION=<compatible> (selon ton environnement)
+
+garder le build en --network host si nécessaire
+
+## 9) Container Manager / Docker : “database is locked” (logging driver db)
+# Symptôme
+
+failed to initialize logging driver : database is locked
+
+# Cause
+
+Le driver de logs Docker est db (Synology) et sa DB est verrouillée.
+
+# Fix rapide
+
+Redémarrer “Container Manager” depuis le centre de paquets DSM.
+
+Vérifier que le conteneur redémarre ensuite.
+
+## 10) Checklist “tout marche”
+
+curl -I http://127.0.0.1:8082/ => 200
+
+curl -kI https://<domaine>/ => 200
+
+PUBLIC_GITEA_* corrects
+
+“Proposer” : 1 onglet, pas de 404, issue pré-remplie
+
+CI passe sur PR merge