# 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)