Wiki/_byan-output/fast-app/formation-hub/SESSION-RESUME.md

# SESSION RESUME — formation-hub Acadenice (last update 2026-05-07 nuit Bloc 7)

## CHANGELOG depuis derniere update (Bloc 7 — webhooks)

- **Bloc 7a livre (Baserow webhooks complet)** + **Bloc 7b stub (Docmost)** :
  - Nouveau module `src/webhooks/` : `signature.ts` (HMAC-SHA256 hex constant-time + format `sha256=` accepte), `types.ts` (zod payloads Baserow + Docmost), `baserow-handler.ts` (mapping table_id -> entite + invalidation cache + cascade rollups parents), `docmost-handler.ts` (stub log-only avec TODO Bloc 8).
  - Route `POST /api/webhooks/baserow` (HMAC `X-Baserow-Signature`, idempotence Redis 24h, dispatch invalidation par event_type, table inconnue -> 200 ignored).
  - Route `POST /api/webhooks/docmost` stub (HMAC `X-Docmost-Signature`, idempotence si event_id present, log + 200).
  - Body brut via `c.req.text()` puis `JSON.parse` manuel (stream consomme une seule fois).
  - Config zod : `docmostWebhookSecret` ajoute (optional, min 16 chars).
  - 40 tests Vitest ajoutes (220 -> 260) : signature 13 / handler baserow 10 / handler docmost 2 / routes 15.
  - Coverage `src/webhooks/**` = **100% lines/branches/funcs**, `src/routes/webhooks.ts` = **97.77% lines / 96.42% branches**.
  - vitest.config.ts thresholds : ajout `src/webhooks/**` a 80%.

# SESSION RESUME — formation-hub Acadenice (Bloc 6, conserve pour reference)

> Document de reference pour reprendre le travail apres restart Claude Code OU /compact.
> Lis-moi avant de commencer la prochaine session.

## CHANGELOG depuis derniere update (session 2026-05-07 nuit — Bloc 6)

5 commits ajoutes (`5b2abbc`, `2c5665b`, `c8e9b4d`, `7a3fbe4`, `1528017`) — bridge passe de "scaffold + 4 agents recrutes" a "service utilisable end-to-end + adapters couverts a 97-100%" :

- **Bloc 1 cloture** (`5b2abbc`) : adapters propres (TS errors fixed, biome format), 679 LOC.
- **Bloc 2 livre** (`2c5665b`) : domain models 12 fichiers (Personne, Module, Attribution, Tache, etc.) + 111 tests Vitest, coverage **97.86%** lines sur `src/domain/`. Decimal.js partout pour heures, schemas zod, RG-01 implementee dans Module.creerAttribution.
- **Bloc 3 livre** (`c8e9b4d`) : routes REST Tier 1 + auth middleware + repos Baserow + tests integration mockes. **10/10 endpoints livres** : GET personnes/:id/dashboard, GET formations/:id, GET projets/:id, POST modules/:id/attribuer, POST interventions, PATCH attributions/:id/heures-realisees, etc. Tests : **163/163 verts**, coverage globale `src/` : **70.77%**.
- **Smoke test fixes** (`7a3fbe4`) : 2 bugs decouverts via test live contre Baserow + Docmost reels :
  - `BaserowClient.resolveTableIds` requiert un JWT user (Baserow API distingue DB tokens / JWT). Workaround : env var `BASEROW_TABLE_IDS` JSON override.
  - `BaseRepo.list` cassait sur row malformee (Personne avec splits null != 100 → throw). Fix : try/catch toDomain par row, skip + log warn + `meta.skipped` exposed.
- **Bloc 6 livre** (`1528017`) : tests integration des 3 adapters via bridge-tester. **59 nouveaux tests** (220/220 verts au total) :
  - `redis-cache.test.ts` : 16 tests via testcontainers redis:7-alpine, **100% lines / 95.2% branches**.
  - `baserow-client.test.ts` : 18 tests via faux serveur node:http local, **99% lines / 96.9% branches**.
  - `docmost-client.test.ts` : 25 tests via faux serveur node:http (login + cookie + envelope `{data}`), **97.7% lines / 93.7% branches**.
  - Choix technique : faux serveur HTTP plutot que container Baserow/Docmost (boot 60-120s incompatible CI rapide). Le code adapter tape un vrai socket TCP via ofetch/fetch — boundary integration rigoureux. Helper reutilisable `tests/helpers/http-server.ts`.
  - vitest.config.ts : threshold 70% lines+branches ajoute sur `src/adapters/**`.
  - Note design : `RedisCache.checkRateLimit` utilise `${Date.now()}` comme membre ZSET → collision si plusieurs appels dans la meme ms. Workaround dans tests (delay 2ms). Pas critique en prod (charge plus diffuse) mais a noter.

## Smoke test live — etat actuel

Stack live + bridge testes :
- Baserow : `http://localhost:8080` (workspace 112 "Acadenice", database 133 "formation-hub", 9 tables au singulier 609-617)
- Docmost : `http://localhost:3000`
- Redis bridge dedie : container `bridge-redis` sur `127.0.0.1:6379` (separe du `docmost-redis` interne)
- Bridge : `http://localhost:4000` via `npm run dev` dans `bridge/`

`.env` du bridge cree (gitignore confirme). Token Baserow DB cree : `vyabYuYW7E5BLTTV7RGbl2Y0Mkk4hvHP` (workspace 112, CRUD complet). Token bridge admin de test : `brg_smoketest_admin` avec scope `admin:*`.

7/8 endpoints OK au smoke test (le 8e bug est fix dans `7a3fbe4`). Tableau detaille :

| Endpoint | Resultat |
|----------|----------|
| GET /api/health | 200 |
| GET /api/ready | 200 (baserow:true, redis:true) |
| GET /personnes (no auth) | 401 AUTH_REQUIRED |
| GET /personnes (bad token) | 401 AUTH_INVALID |
| GET /personnes (good, 2 rows malformees) | 200 data:[] meta.skipped:2 (apres fix) |
| GET /personnes/9999 | 404 NOT_FOUND |
| GET /formations | 200 (2 rows) |
| GET /projets | 200 (2 rows) |

## Etat des blocs Phase 2 (a jour)

| Bloc | Status | Detail |
|------|--------|--------|
| 1 — Adapters | DONE | `5b2abbc`, coverage adapters 97-100% via Bloc 6 |
| 2 — Domain models | DONE | `2c5665b`, 97.86% coverage |
| 3 — Routes Tier 1 + auth + repos | DONE | `c8e9b4d`, 10/10 endpoints, 86-96% coverage middleware/routes |
| 3.2 — Refactor erreurs domain typees + routes /blocs /clients /taches | TODO | DomainError sub-classes (RGViolationError, ConflictError) pour remplacer mapping par texte |
| 4 — Auth middleware | DONE (en partie) | inclus dans Bloc 3 (Bearer brg_*, scopes JSON-encoded, admin:* wildcard) |
| 5 — Rate limit + cache invalidation | TODO | RedisCache.checkRateLimit existe deja, faut middleware Hono qui l'appelle |
| 6 — Tests integration adapters | DONE | `1528017`, 59 tests, redis-cache 100% / baserow 99% / docmost 97.7% lines |
| 7a — Webhook Baserow (HMAC + idempotence + invalidation cache) | DONE | webhooks/* + routes/webhooks.ts, 100% coverage |
| 7b — Webhook Docmost (stub) | STUB | log-only, handlers metier en Bloc 8 |
| 7 — Sync bidirec (write-back Baserow apres event Docmost) | TODO | depend de Bloc 8 (parser node-views) |
| 8 — Tiptap node-views Docmost | TODO | docmost-fork-dev, Phase 2.3+ — PROCHAIN |
| 9 — Bidirec backlinks | TODO | docmost-fork-dev, Phase 3 |
| 10 — Doc utilisateur + release v0.1.0 | TODO | tech-writer + acadenice-devops |

## Coverage globale (post-Bloc 7)

- **All files** : 86.91% lines / 86.48% branches
- **adapters/** : 98.73% lines / 95.04% branches
- **domain/** : 97.86% lines / 98.16% branches
- **routes/** : 96.58% lines / 76.19% branches (incluant webhooks.ts 97.77%)
- **webhooks/** : **100% lines / 100% branches** (signature, baserow-handler, docmost-handler, types)
- **middleware/** : 86.41% lines / 88.88% branches
- **lib/** : 49.18% lines (config.ts/container.ts non couverts — bootstrap)
- **repos/** : 59.53% lines (BaseRepo abstract — couvert via repos concrets)

## Vote pour la prochaine session

Recommandation pour la reprise :

- **Option A (recommandee)** : Bloc 8 — Tiptap node-views Docmost (docmost-fork-dev). Forke Docmost AGPL, ajoute les nodes custom `baserow-row` / `baserow-list` qui font des reads via le bridge `/api/v1/*` et des writes via webhooks Docmost (handler stub deja en place — il restera a parser le payload reel et appeler les repos Baserow). Cest la piece UI manquante qui rend le bridge visible cote utilisateur.
- **Option B** : Bloc 9 — tests E2E Playwright contre la stack live (bridge-tester) pour figer le comportement actuel des routes + webhooks avant que le fork Docmost ne bouge.
- **Option C** : Bloc 5 — rate limit + cache invalidation middleware. Court (~1h). RedisCache.checkRateLimit existe deja, faut le wire dans Hono. Pas bloquant pour Bloc 8.
- **Option D** : Bloc 3.2 — refactor erreurs domain typees + routes restantes (/blocs, /clients, /taches). Pas urgent.

## Vision projet en 3 lignes

Notion-like self-host pour Acadenice (CFA + Agence dev) en Stack composite :
- **Docmost** (wiki AGPL, illimite users) + **Baserow** (DBs MIT, illimite users) + **bridge service** custom Node TS (Phase 2)
- Suivi heures formateurs/devs unifie via entite **PERSONNE** pivot multi-roles, scope etendu CFA + Agence approuve.
- Cible 90-100 users total. Production-like des le jour 1.

## User & equipe

- **Corentin JOGUET** (corentin@acadenice.fr) — AdminSys/DevOps solo, bras droit de Yan (resp tech). Decisionnaire technique.
- Yan (resp tech), Ludo (fondateur), Sophie (co-fondatrice) — validation business. Pas a confondre avec Corentin.

## Localisation des artefacts

| Resource | Chemin / URL |
|----------|--------------|
| Repo source of truth | https://git.acadenice.com/AcadeNice/Wiki (Forgejo selfhost, public) |
| Repo mirror GitHub | https://github.com/AcadeNice/wiki (private, plan free) |
| Local dev | `/home/imugiii/Documents/jsap/formation-hub/` |
| Wiki conception (19 docs) | https://wiki.acadenice.com/collection/agence-rd-notion-like-v9nvBLodst |
| BYAN web project | id `4e72108b-dc05-4938-a1a9-530e1551ed52` |
| Stack locale | http://localhost:3000 (Docmost) + http://localhost:8080 (Baserow) |

## Phase 0 — Conception (DONE — 19 docs)

Localises dans `docs/` du repo + miroir Outline collection R&D Notion-Like :

| # | Doc | Status |
|---|-----|--------|
| 01 | Discovery Recap | OK |
| 02 | Scope etendu CFA + Agence (APPROVED 2026-05-07) | OK |
| 03 | Decision Records (5 ADR) | OK |
| 04 | CDC Technique (stack + NFR + roadmap + couts) | OK |
| 05 | Data Dictionary | OK |
| 06 | Merise MCD (5 vues splittees) | OK |
| 07 | Merise MLD (5 vues splittees) | OK |
| 08 | Merise MCT | OK |
| 09 | Merise MOT | OK |
| 10 | State Diagrams | OK |
| 11 | UML Use Cases (4 vues splittees) | OK |
| 12 | UML Class Diagram (5 vues splittees) | OK |
| 13 | UML Activity Diagrams | OK |
| 14 | Repo Structure & GitOps | OK |
| 15 | Baserow MPD | OK |
| 16 | Plan de tests | OK |
| 17 | Plan de deployment | OK |
| 18 | Plan d'operations | OK |
| 19 | Bridge API design (incl. MCP server Phase 3+) | OK |
| 99 | DRAWIO Architecture infra (XML) | OK |

## Phase 1 — Build local (en cours — local seul, prod-like)

### OK et teste live

| Iteration | Detail |
|-----------|--------|
| **I1 — Baserow tables + liens** | 9 tables (PERSONNE + CFA + Agence) + 10 link FK avec related fields renommes |
| **I2 — Baserow formulas** | 17 formulas (rollups + heures_restantes) |
| **I3 — Docmost setup** | Workspace `Acadenice` + 3 spaces (CFA, Agence, Interne) + page Welcome + share link |
| **I5a — Healthcheck etendu** | UI + API Docmost/Baserow + container status — 4/4 OK |

### Partiellement OK

| Item | Probleme | Fix prevu |
|------|----------|-----------|
| **I4a — Forms publics Baserow** | Form cree mais endpoint `/api/database/views/form/{id}/field-options/` retourne 404 sur Baserow 1.30 | A investiguer (URL exacte selon version) — bridge-dev |
| **I4b — Space etudiant Docmost** | Slug fix applique (`re.sub`), limit fix (200→100). Pas re-teste. | Re-run pour confirmer — quick |
| **I5b — Cron install** | Script ecrit non-execute (sudo requis) | A run sur la prod quand VPS sera up — acadenice-devops |
| **I5c — Backup test E2E** | Script `scripts/backup.sh` existant, pas teste end-to-end avec restore | Test mensuel selon plan ops — acadenice-devops |

### TODO Phase 1 finale

| Item | Pour qui |
|------|----------|
| Test rollups Baserow live (1 personne + 1 formation + 1 attribution) | Corentin |
| Migration data initiale (formations/clients existants) | Corentin + Yan + Sophie |
| Onboarding 5-10 testeurs (Yan, Ludo, Sophie + 2-3 formateurs + 2 devs) | Corentin |
| Setup VPS staging (Hetzner CPX21) | acadenice-devops |
| Configurer Forgejo Actions runner (`infra/forgejo-runner/`) | acadenice-devops |

## Phase 2 — Bridge service (en cours, Blocs 1-3 + fix smoke test livres)

Code Phase 2 = MAIN focus de la session 2026-05-07 soir + suite. Brief complet dans `docs/19-bridge-api-design.md`. Architecture :
- 5 missions : expose Baserow, webhooks Baserow, sert Tiptap nodes Docmost, orchestre workflows metier, **sync bidirec Docmost ↔ Baserow**
- Stack fixee : Node 22 + Hono + zod + ofetch + ioredis + pino + decimal.js + Vitest + Biome
- Endpoints REST `/api/v1/*` versionnes (10 livres Tier 1)
- Webhooks anti-loop via header `X-Bridge-Origin`
- MCP server (Phase 3+) co-located dans le meme service

Cf section "Etat des blocs Phase 2 (a jour)" en haut du document pour le status detaille de chaque bloc.

## Agents BYAN crees pour le projet

Dans `.claude/agents/` du repo :

| Agent | Mission | Quand l'invoquer |
|-------|---------|------------------|
| **bridge-dev** | Code TS du bridge service (adapters, domain, routes, webhooks) | Toute tache code metier dans `bridge/` |
| **bridge-tester** | Tests Vitest + testcontainers + E2E Playwright + coverage | Toute tache test bridge ou validation AC |
| **acadenice-devops** | Infra (Docker, Traefik, Forgejo, backups, monitoring, CI/CD) | Toute tache ops/deploy/infra |
| **docmost-fork-dev** | Fork Docmost + Tiptap node-views React + bidirec backlinks | Phase 2.3+ et Phase 3 (UI custom) |

**Invocation** : Agent tool avec `subagent_type='bridge-dev'` (ou autre nom) apres restart Claude Code.

Chaque agent a un brief detaille (~150-200 lignes) avec :
- Mission + contexte projet
- Stack technique fixee
- Specialisations
- Conventions code & commits
- Limites (ce qu'il ne fait PAS)
- Resources & references

## Workflows BYAN proposes (a creer plus tard)

Pas encore crees. A faire via BYAN web ou skill `byan-bmb-workflow-builder` :

| Workflow | Phases |
|----------|--------|
| **WF formation-hub BUILD** | story → bridge-dev code → bridge-tester tests → user review → push → deploy staging → smoke tests. Boucle si fail. |
| **WF formation-hub SYNC** | webhook Baserow → bridge handler → cache invalidation → notif → log audit. Idempotence event_id. |
| **WF formation-hub RELEASE** | tests E2E staging → CHANGELOG update → tag semver → approval review → deploy prod → 30 min watch period → rollback si fail. |

## Decisions structurelles (a respecter)

| Decision | Reference |
|----------|-----------|
| Stack Docmost + Baserow + bridge custom | ADR-001 doc 03 |
| Path B : UX quasi-unified via Tiptap nodes | ADR-002 doc 03 |
| Monorepo trunk-based development | ADR-003 doc 03 |
| Postgres separe par service | ADR-004 doc 03 |
| Bridge stack Node 22 + Hono | ADR-005 doc 03 |
| Scope etendu CFA + Agence via PERSONNE pivot | ADR-006 doc 02 |
| Etudiants pas modelises en Baserow, juste users Docmost | doc 02 |
| API Docmost = Enterprise paye → on utilise endpoints internes (AGPL legal) | doc 19 |
| Repo source of truth = Forgejo selfhost (git.acadenice.com), GitHub mirror optionnel | doc 14 |
| **Pas de mirror auto** decide pour l'instant | session 2026-05-07 |
| **Local seul** pour le moment (pas de staging deploy) | session 2026-05-07 |
| Pas de modification des docs conception sans ADR | session 2026-05-07 |

## Credentials utilises (dans `.env` gitignore — a regenerer si compromis)

Racine `.env` :
```
DOCMOST_ADMIN_EMAIL=corentin@acadenice.fr
DOCMOST_ADMIN_PASSWORD=ton-pwd123456
BASEROW_EMAIL=admin@acadenice.fr
BASEROW_PASSWORD=ton-pwd123456
GITHUB_TOKEN=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  (a revoke apres session)
FORGEJO_TOKEN=cc21fee2913b6043fb68f93d8b6c184fac4671f4  (admin AcadeNice)
OUTLINE_TOKEN=ol_api_s2EqjDW5SPlXzM4vqiZaMd8UD00jsnespK4rRs
```

`bridge/.env` (cree session 2026-05-07 soir) :
```
NODE_ENV=development
PORT=4000
LOG_LEVEL=debug
BASEROW_API_URL=http://localhost:8080
BASEROW_API_TOKEN=vyabYuYW7E5BLTTV7RGbl2Y0Mkk4hvHP
DOCMOST_API_URL=http://localhost:3000
REDIS_URL=redis://127.0.0.1:6379
BASEROW_WEBHOOK_SECRET=smoke-test-webhook-secret-32chars-min
BRIDGE_API_TOKENS=[{"token":"brg_smoketest_admin","name":"smoketest","scopes":["admin:*"]}]
BASEROW_DATABASE_ID=133
BASEROW_TABLE_IDS={"personne":609,"formation":610,"bloc":611,"module":612,"attribution":613,"client":614,"projet":615,"tache":616,"intervention":617}
```

Container Redis dedie pour bridge (separe du docmost-redis interne) :
```bash
docker run -d --name bridge-redis -p 127.0.0.1:6379:6379 redis:7-alpine
```

## Commits Forgejo selfhost (cumulés)

Session 2026-05-07 jour :
```
668576c chore: initial commit (55 files, 7986 insertions, conception complete)
d510bdd ops: fix CI run + bump testcontainers + doc 19 sync bidirec
991d172 ops(ci): trigger CI on main + disable auto deploy-staging Phase 0
66ff909 ops(ci): add vitest config + sanity tests
d8e8bde ops(ci): fix docker-build .env before compose
ecb7a44 ops(infra): add Forgejo Actions Runner skeleton
6724be6 feat(baserow): add seed script + Fast-App iteration 1 artifacts
a0266b8 feat(baserow): add formulas pass + related field naming
5d02977 feat(docmost): manual setup guide for iteration 3
8a676d2 feat(docmost): add seed.py via internal endpoints
d5558ca fix(docmost-seed): handle data envelope + add format field
1d71364 feat(seed): add I4 forms publics + space etudiant + I5 healthcheck
7d4d2cd feat(agents): create bridge-dev specialized agent (1st BYAN INT)
b37220d feat(agents): complete BYAN INT for 3 more agents + session resume MD
460f7ef feat(workflows): create 5 BYAN workflows for agent collaboration
```

Session 2026-05-07 soir :
```
5b2abbc feat(bridge/adapters): bloc 1 propre — BaserowClient + DocmostClient + RedisCache
2c5665b feat(bridge/domain): bloc 2 — domain models + tests Vitest (coverage 97.86%)
c8e9b4d feat(bridge): bloc 3 — routes REST Tier 1 + auth + repos Baserow (10 endpoints)
7a3fbe4 fix(bridge): smoke test fixes — skip rows malformees + BASEROW_TABLE_IDS override
[NEXT]  docs(session): update SESSION-RESUME apres Bloc 1+2+3 + smoke test
```

## Memoire BYAN persistee

`/home/imugiii/.claude/projects/-home-imugiii-Documents-jsap/memory/` :
- `user_role.md` : Corentin JOGUET profil + role chez Acadenice
- `project_notion_like.md` : projet detaille, scope, stack, decisions, IDs externes
- `reference_outline.md` : Outline wiki Acadenice config + endpoints

## Pour la prochaine session — checklist demarrage

```
[ ] Lire ce SESSION-RESUME.md (ce CHANGELOG en haut + section "Etat des blocs Phase 2")
[ ] Verifier stack locale up : docker compose ps + docker ps | grep bridge-redis
    (si bridge-redis absent : docker run -d --name bridge-redis -p 127.0.0.1:6379:6379 redis:7-alpine)
[ ] Verifier git pull a jour : cd formation-hub && git pull
[ ] Verifier bridge boot : cd bridge && npm run dev (logs dans /tmp/bridge-smoke.log si en background)
[ ] Smoke quick : curl http://localhost:4000/api/ready
[ ] Decider quoi attaquer en premier (cf section "Vote pour la prochaine session" en haut) :
    - Option A : Bloc 7 — webhooks Baserow + sync bidirec (gros, recommande)
    - Option B : Bloc 5 — rate limit + cache invalidation (court, prerequis)
    - Option C : Bloc 6 — tests integration adapters via bridge-tester
    - Option D : Bloc 3.2 — refactor erreurs domain typees + routes restantes
```

## Fast-App workflow local (artefacts dans `_byan-output/fast-app/formation-hub/`)

| Fichier | Contenu |
|---------|---------|
| pitch.json | Validated 2026-05-07 |
| backlog.json | 15 features MoSCoW + 5 WONT validated |
| cdcf-stories.json | 10 stories Connextra+Gherkin pour Phase 1 |
| plan.json | 7 iterations BUILD |
| dispatch.json | Repartition Claude/Corentin/equipe |
| build-state.json | current_iteration: 1, completed phases 1-6 (workflow Fast-App) |

---

**Tao Acadenice respecte tout au long** : direct, structures avec tirets, zero emoji, orientation solution.

Pret pour la suite. Bonne session.