archicratie-edition/docs/START-HERE.md

START-HERE — Archicratie / Édition Web (v2)

Onboarding + exploitation “nickel chrome” (DEV → Gitea → CI → Release → Blue/Green → Edge/SSO)

0) TL;DR (la règle d’or)

• Gitea = source canonique.
• main est protégé : toute modification passe par branche → PR → CI → merge.
• Le NAS n’est pas la source : si un hotfix est fait sur NAS, on backporte via PR immédiatement.
• Le site est statique Astro : la prod sert du HTML (nginx), l’accès est contrôlé au niveau reverse-proxy (Traefik + Authelia).

1) Architecture mentale (ultra simple)

• DEV (Mac Studio) : édition + tests + commit + push
• Gitea : dépôt canon + PR + CI (CI.yaml)
• NAS (DS220+) : déploiement “blue/green”
  • web_blue (staging upstream) → 127.0.0.1:8081
  • web_green (live upstream) → 127.0.0.1:8082
• Edge (Traefik) : route les hosts
  • staging.archicratie... → 8081
  • archicratie... → 8082
  • Authelia devant, via middleware chain-auth@file

2) Répertoires & conventions (repo)

2.1 Contenu canon (édition)

• src/content/** : contenu MD / MDX canon (Astro content collections)
• src/pages/** : routes Astro (index, [...slug], etc.)
• src/components/** : composants UI (SiteNav, TOC, SidePanel, etc.)
• src/layouts/** : layouts (EditionLayout, SiteLayout)
• src/styles/** : CSS global

2.2 Annotations (pré-Édition “tickets”)

• src/annotations/<workKey>/<slug>.yml
  • Exemple : src/annotations/archicrat-ia/prologue.yml
• Objectif : stocker “Références / Médias / Commentaires” par page et par paragraphe (p-...).

2.3 Scripts (tooling / build)

• scripts/inject-anchor-aliases.mjs : injection aliases dans dist
• scripts/dedupe-ids-dist.mjs : retire IDs dupliqués dans dist
• scripts/build-para-index.mjs : index paragraphes (postbuild / predev)
• scripts/build-annotations-index.mjs : index annotations (postbuild / predev)
• scripts/check-anchors.mjs : contrat stabilité d’ancres (CI)
• scripts/check-annotations*.mjs : sanity YAML + médias

Important : les scripts sont partie intégrante de la stabilité (IDs/ancres/indexation).
On évite “la magie” : tout est scripté + vérifié.

3) Workflow Git “pro” (main protégé)

3.1 Cycle standard (toute modif)

en bash :

git checkout main git pull --ff-only

BR="chore/xxx-$(date +%Y%m%d)" git checkout -b "$BR"

dev…

npm i npm run build npm run test:anchors

git add -A git commit -m "xxx: description claire" git push -u origin "$BR"

3.2 PR vers main

Ouvrir PR dans Gitea

CI doit être verte

Merge PR → main

3.3 Cas spécial : hotfix prod (NAS)

On peut faire un hotfix “urgence” en prod/staging si nécessaire…

MAIS : l’état final doit revenir dans Gitea : branche → PR → CI → merge.

4) Déploiement (NAS) — principe

4.1 Release pack

On génère un pack “reproductible” (source + config + scripts) puis on déploie.

4.2 Blue/Green

web_blue = staging upstream (8081)

web_green = live upstream (8082)

Edge Traefik sélectionne quel host pointe vers quel upstream.

5) Check-list “≤ 10 commandes” (happy path complet)

5.1 DEV (Mac)

git checkout main && git pull --ff-only git checkout -b chore/my-change-$(date +%Y%m%d)

npm i rm -rf .astro node_modules/.vite dist npm run build npm run test:anchors npm run dev

5.2 Push + PR

git add -A git commit -m "chore: my change" git push -u origin chore/my-change-YYYYMMDD

ouvrir PR dans Gitea

5.3 Déploiement NAS (résumé)

Voir docs/runbooks/DEPLOY-BLUE-GREEN.md.

6) Problèmes “classiques” + diagnostic rapide

6.1 “Le staging ne ressemble pas au local”

Comparer upstream direct 8081 vs 8082 :

curl -sS http://127.0.0.1:8081/ | head -n 2 curl -sS http://127.0.0.1:8082/ | head -n 2

Vérifier quel routeur edge répond (header diag) :

curl -sSI -H 'Host: staging.archicratie.trans-hands.synology.me' http://127.0.0.1:18080/
| grep -iE 'HTTP/|location:|x-archi-router'

Lire docs/runbooks/EDGE-TRAEFIK.md.

6.2 Canonical incorrect (localhost en prod)

Cause racine : site dans Astro = PUBLIC_SITE non injecté au build.

Fix canonique : voir docs/runbooks/ENV-PUBLIC_SITE.md.

Test :

curl -sS http://127.0.0.1:8082/ | grep -oE 'rel="canonical" href="[^"]+"' | head -1

6.3 Contrat “anchors” en échec après migration d’URL

Quand on déplace des routes (ex: /archicratie/archicrat-ia/* → /archicrat-ia/*), le test d’ancres peut échouer même si les IDs n’ont pas changé, car les pages ont changé de chemin.

Procédure safe :

Backup baseline :

cp -a tests/anchors-baseline.json /tmp/anchors-baseline.json.bak.$(date +%F-%H%M%S)

Mettre à jour les clés (chemins) sans toucher aux IDs :

node - <<'NODE' import fs from 'fs'; const p='tests/anchors-baseline.json'; const j=JSON.parse(fs.readFileSync(p,'utf8')); const out={}; for (const [k,v] of Object.entries(j)) { const nk = k.replace(/^archicratie/archicrat-ia//, 'archicrat-ia/'); out[nk]=v; } fs.writeFileSync(p, JSON.stringify(out,null,2)+'\n'); console.log('updated keys:', Object.keys(j).length, '->', Object.keys(out).length); NODE

Re-run :

npm run test:anchors

7) Ce que l’étape 9 doit faire (orientation)

Stabiliser le pipeline “tickets → YAML annotations”

Formaliser la spec YAML + merge + anti-doublon (voir docs/EDITORIAL-ANNOTATIONS-SPEC.md)

Durcir l’onboarding (ce START-HERE + runbooks)

Éviter les régressions par tests (anchors / annotations / smoke)