From 8b7cfdfd481f58fa39c6129e417ce9116f50cec3 Mon Sep 17 00:00:00 2001 From: Archicratia Date: Sun, 1 Feb 2026 14:30:18 +0100 Subject: [PATCH] docs(ops): add triple-source sync + troubleshooting + proposer spec --- docs/FEATURE-PROPOSER.md | 103 +++++++++++++++++++++++++++++++++ docs/OPS-SYNC-TRIPLE-SOURCE.md | 91 +++++++++++++++++++++++++++++ docs/TROUBLESHOOTING.md | 58 +++++++++++++++++++ 3 files changed, 252 insertions(+) create mode 100644 docs/FEATURE-PROPOSER.md create mode 100644 docs/OPS-SYNC-TRIPLE-SOURCE.md create mode 100644 docs/TROUBLESHOOTING.md diff --git a/docs/FEATURE-PROPOSER.md b/docs/FEATURE-PROPOSER.md new file mode 100644 index 0000000..8f99d45 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/OPS-SYNC-TRIPLE-SOURCE.md b/docs/OPS-SYNC-TRIPLE-SOURCE.md new file mode 100644 index 0000000..a42c6f8 --- /dev/null +++ b/docs/OPS-SYNC-TRIPLE-SOURCE.md @@ -0,0 +1,91 @@ +# 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//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 ` +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. + +```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 +' diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..082e4d5 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,58 @@ +# 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 `` 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 : +```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 \ No newline at end of file