Wiki/docs/04-cahier-des-charges-techniques.md

# Cahier des Charges Techniques (CDC)

> Specification technique complete : stack, choix, contraintes, NFR, architecture, roadmap.
> Version : 1.0 — Date : 2026-05-07.
> Statut : draft, a valider Yan/Ludo avant industrialisation.

## 1. Identification

| Champ | Valeur |
|-------|--------|
| Nom du projet | formation-hub |
| Owner technique | Corentin JOGUET (DevOps/AdminSys, bras droit Yan) |
| Validateurs | Yan (resp tech), Ludo (direction) |
| Sponsor metier | Direction Acadenice |
| Type | Outil interne — Notion-like self-host pour CFA + Agence dev |
| Date debut | 2026-05-07 |
| Date cible MVP | T+1 mois (Phase 1 — stack vanilla + setup metier) |
| Date cible v1.0 | T+3 mois (Phase 2 — bridge UX unifie) |

## 2. Contexte metier

Acadenice = double activite **CFA + Agence dev** (cf doc fondateur "Vision Acadenice"). Les formateurs sont aussi developpeurs sur projets clients : leur capacite annuelle se split entre les deux activites.

Le projet formation-hub fournit l'outil interne pour :
- Wiki collaboratif (SOPs, supports, doc technique)
- Suivi heures formation (CFA)
- Suivi projets et taches Agence
- Vue 360 capacite par personne (formation + agence)
- Acces guests clients (lien partage)
- Spaces personnels etudiants (libres, non modelises)

## 3. Objectifs

| Objectif | Mesure |
|----------|--------|
| Centraliser la documentation | 100% des SOPs et supports formation dans l'outil |
| Tracer les heures formateurs | Saisie reguliere par 100% des formateurs |
| Tracer les heures projets clients | Saisie reguliere par 100% des devs |
| Calcul automatique heures restantes | Tableau de bord temps reel par formation, par formateur, par projet |
| Reduire le couplage outils externes | Remplacer 0 a 3 outils actuels (Excel, Trello legers ?) |
| Self-host illimite users | Aucun cout de licence par seat, juste l'infra |
| Ouvert aux etudiants | Spaces personnels libres, beneficient des templates |

## 4. Perimetre fonctionnel

Couvert :
- Wiki Docmost avec mermaid/drawio/excalidraw natifs
- Bases de donnees Baserow (CFA + Agence)
- Permissions hierarchiques (workspace, space, page)
- Share links avec password / expiration
- Acces guests clients

Non couvert (out of scope v1) :
- Modelisation formelle des etudiants (inscriptions, suivi pedagogique)
- Generation factures clients
- ATS / recrutement
- Messagerie integree
- Application mobile native (UI mobile-friendly via responsive web)

## 5. Stack technique

### 5.1 Diagramme architecture cible

```mermaid
flowchart TB
    User([Utilisateur final<br/>Admin/Formateur/Dev/Etudiant/Client])

    subgraph "Edge / Reverse Proxy"
        Traefik[Traefik<br/>TLS Let's Encrypt<br/>routing par sous-domaine]
    end

    User -->|HTTPS| Traefik
    Traefik -->|wiki.acadenice.fr| Docmost
    Traefik -->|baserow.acadenice.fr| Baserow
    Traefik -->|bridge.acadenice.fr| Bridge

    subgraph "Application services"
        Docmost[Docmost<br/>NestJS + React + Tiptap]
        Baserow[Baserow<br/>Django + Caddy interne]
        Bridge[Bridge service<br/>Node 22 + Hono<br/>Phase 2]
    end

    subgraph "Storage"
        DocmostDB[(Postgres<br/>docmost)]
        DocmostRedis[(Redis<br/>docmost)]
        BaserowDB[(Postgres<br/>baserow embedded)]
        BaserowRedis[(Redis<br/>baserow embedded)]
        FS[Local FS / MinIO<br/>docmost files]
    end

    Docmost --> DocmostDB
    Docmost --> DocmostRedis
    Docmost --> FS
    Baserow --> BaserowDB
    Baserow --> BaserowRedis
    Bridge -->|API REST| Baserow
    Bridge --> DocmostRedis
    Bridge -->|API REST| Docmost

    subgraph "Infra ops"
        CronBackup[Cron host<br/>backups quotidiens]
        Monitoring[Uptime monitoring<br/>a definir]
    end

    CronBackup -->|pg_dump + tar| DocmostDB
    CronBackup -->|pg_dump + tar| BaserowDB
    CronBackup -->|tar| FS
```

### 5.2 Composants

| Composant | Role | Techno | Version cible | License |
|-----------|------|--------|--------------|---------|
| **Docmost** | Wiki + collab + share + diagrammes natifs | NestJS, React, Tiptap, Postgres | latest stable (>= v0.8.2 mai 2026) | AGPL-3.0 |
| **Baserow** | DBs structurees + multi-vues + rollups + formules | Django, Postgres, Redis, Celery, Caddy | 1.30.x pinned | MIT (core) |
| **Bridge** (Phase 2) | API entre Docmost (Tiptap nodes custom) et Baserow | Node 22, Hono, zod, ofetch | 1.0 (a developper) | MIT (interne) |
| **PostgreSQL** | DB pour Docmost + DB pour Baserow (containers separes) | Postgres 16 alpine | 16.x | PostgreSQL License |
| **Redis** | Cache et queues (Docmost + Bridge) | Redis 7 alpine | 7.x | RSAL (free pour notre usage) |
| **MinIO** ou **local FS** | Storage attachments Docmost | MinIO | latest stable | AGPL-3.0 |
| **Traefik** | Reverse proxy, TLS auto | Traefik 3.x (deja deploye) | latest | MIT |
| **Docker / Compose** | Containerisation, orchestration | Docker 25+, compose v2 | latest | Apache 2.0 |
| **GitHub Actions** | CI/CD | GitHub Actions | — | — |

### 5.3 Versions pinning

- Docmost : `docmost/docmost:latest` initialement, **pinned** sur version mineure stable apres tests (ex: v0.8.2)
- Baserow : `baserow/baserow:1.30.1` (deja pinne)
- Postgres : `postgres:16-alpine`
- Redis : `redis:7-alpine`
- Node Bridge : `node:22-alpine`
- Bumps version : decision manuelle apres test staging

## 6. Choix de stack — justifications

| Choix | Alternatives ecartees | Raison |
|-------|-----------------------|--------|
| **Docmost** comme wiki | AFFiNE (10-seat limit), AppFlowy (1-user limit), Outline (BSL + pas de bidirec), SiYuan/Trilium (single-user), HedgeDoc (pas de DB ni bidirec) | Seul wiki AGPL avec users illimites, team workspaces, share links et diagrammes natifs (Mermaid + Draw.io + Excalidraw) integres |
| **Baserow** comme moteur DB | NocoDB (license non-OSI Sustainable Use), Teable (jeune, pas mature), Airtable (cloud paye), construire un moteur DB dans Docmost (4-6 mois) | MIT, mature, real-time collab, rollups+formules natifs, multi-vues completes, users illimites |
| **Stack composite** vs unifie | AFFiNE Team paid (~2200€/an) ou tout custom | Zero recurrent + Stack mainstream + decouple = remplaceable |
| **Bridge custom Node TS** | Embed iframe Baserow ou reecrire UI complete | UX unifie sans Tiptap reverse engineering Docmost. Effort 2-3 mois acceptable. |
| **Postgres separe** par service | Postgres partage avec 2 databases | Isolation versions, migrations independantes, dump/restore propres |
| **Hono** pour le bridge | Express, Fastify, NestJS, Bun | Leger, TypeScript-first, performance Edge-ready, simple a deployer |
| **Path B** (UX quasi-unified) vs Path A (deux mondes) | Cross-link URL externe entre Docmost et Baserow | UX unifie evite jonglage 2 onglets pour les utilisateurs |

(Voir `02-decision-record.md` pour les ADR detailles.)

## 7. Specifications non-fonctionnelles (NFR)

### 7.1 Performance

| Metrique | Cible | Mesure |
|----------|-------|--------|
| Latence saisie heures (UC-13, UCA-07) | < 2s p95 | Bridge endpoint timing |
| Latence chargement page wiki | < 1s p95 | Lighthouse |
| Recalcul rollups Baserow | < 5s | Baserow-side timing |
| Recherche full-text Docmost | < 500ms p95 | Docmost search timing |

### 7.2 Securite

| Aspect | Specification |
|--------|---------------|
| Auth Docmost | Email + password, SSO OIDC en option (Phase 3) |
| Auth Baserow | Email + password, JWT |
| Auth Bridge | API tokens longue duree pour service-to-service |
| TLS | Let's Encrypt via Traefik, renouvellement auto |
| Backup encryption | AES-256 sur backups distants (MinIO/S3 distant) |
| Secrets | Variables d'environnement docker-compose, fichier `.env` exclu de git |
| Audit log | Log toutes operations sensibles (suppression, archivage, partage externe) |
| RGPD | Suppression de donnees personnelles sur demande, retention etudiants/clients selon loi |

### 7.3 Disponibilite

| Aspect | Cible | Justification |
|--------|-------|---------------|
| Disponibilite stack | 99% (= 3.65j down/an) | Outil interne, pas critique |
| RPO (Recovery Point Objective) | 24h max | Backup quotidien |
| RTO (Recovery Time Objective) | 4h max | Restauration manuelle assistee |
| MTTR | < 1h pour bugs critiques, < 24h pour bugs mineurs | Bug critique = bloquant pour une activite |

### 7.4 Scalabilite

Cible v1 : ~30 users simultanes peak, 100 users total — **hors-perf** sur un VPS 4 vCPU/8 Go.

Croissance an 5 prevue : ~150 users total, ~50 simultanes peak. **Pas de refactor stack prevu** — juste un upsizing VPS si besoin.

### 7.5 Backup / Disaster recovery

| Aspect | Strategie |
|--------|-----------|
| Frequence | Quotidienne, 03:00 UTC |
| Targets | Postgres docmost (pg_dump.gz), Postgres baserow embedded (pg_dump.gz), Docmost FS (tar.gz), Baserow data (tar.gz) |
| Retention | 30 jours sur disque local, 90 jours sur stockage distant (S3 / Backblaze) |
| Test restauration | Mensuel, sur un environnement test isole |
| RPO | 24h |
| RTO | 4h |

## 8. Contraintes

| Contrainte | Justification |
|-----------|---------------|
| Self-host obligatoire | Souverainete des donnees, pas de SaaS payant |
| Stack OSS (AGPL/MIT/Apache acceptable) | Eviter lock-in vendor |
| Docker + Compose | Stack ops existante d'Acadenice |
| Traefik reverse proxy | Stack ops existante (labels TOML) |
| GitHub pour le code | Workflow standard equipe |
| Budget recurrent : 0 (hors infra ~30€/mois) | Decision direction |
| Equipe dev : Corentin solo + freelance ponctuel pour Tiptap | Pas d'embauche dediee |

## 9. Hypotheses / dependances

- Le hardware serveur (VPS Hetzner ou equivalent) est commande / disponible avant deploiement staging
- Un nom de domaine `acadenice.com` ou `acadenice.fr` est disponible pour les sous-domaines wiki/baserow/bridge
- Traefik tourne deja en prod chez Acadenice — on s'integre dans le reseau Docker existant
- L'API Outline reste accessible pendant la phase de validation (push docs depuis local pour relecture)
- Docmost et Baserow continuent d'etre maintenus activement par leur upstream pendant la duree du projet

## 10. Risques et mitigations

| Risque | Probabilite | Impact | Mitigation |
|--------|-------------|--------|-----------|
| Docmost upstream change ses API publiques | Faible | Moyen | Pinning de versions, tests staging avant bump |
| Baserow change son data model en breaking | Moyenne | Eleve | Backups frequents, migration test avant bump |
| Tiptap node-views complexe pour AdminSys solo | **Eleve** | Moyen | Freelance senior fullstack TS pour 2-3 jours pair-programming |
| AGPL conformite (publication code source si SaaS public) | Faible | Eleve | Outil reste interne — pas SaaS public, AGPL OK |
| Charge depasse capacite VPS 4 vCPU | Faible | Moyen | Upsizing simple, cloud-native |
| Perte de cle API Outline ou Baserow | Faible | Faible | Rotation manuelle simple, secrets dans .env |
| Manque adoption metier (saisie heures non faite) | Moyenne | Eleve | Onboarding etalonne + UX simple + relances admin |

## 11. Roadmap technique

### Phase 0 — Conception (en cours, fini fin mai)

- [x] Discovery + decisions
- [x] Data dictionary, MCD, MLD, UML use cases, state diagrams, MCT, MOT, class diagram, activity diagrams
- [x] CDC technique (ce doc)
- [ ] MPD Baserow (table-par-table)
- [ ] Validation metier (Yan + Ludo + admin pedagogique)

### Phase 1 — MVP vanilla (T+1 mois)

- [ ] Setup stack Docker compose locale → staging
- [ ] Configuration Docmost (workspace, spaces, share links)
- [ ] Configuration Baserow (4 BDDs CFA + 4 BDDs Agence)
- [ ] Migration data initiale (formations existantes, formateurs, clients, projets en cours)
- [ ] Onboarding 5-10 power users
- [ ] Backup + monitoring de base

### Phase 2 — Bridge UX unifie (T+3 mois)

- [ ] Bridge service skeleton + premier Tiptap node-view custom (mention `@formateur`, `@projet`)
- [ ] Routes /personne/:id, /projet/:id, /formation/:id en page Docmost-style
- [ ] Saisie heures formateur + intervention dev en bridge UI mobile-friendly
- [ ] Webhook Baserow → bridge → cache Redis pour mentions
- [ ] Migration progressive utilisateurs (formateurs + devs ouvrent le bridge plutot que Baserow direct)

### Phase 3 — Maturite (T+6 mois)

- [ ] Bidirec backlinks dans Docmost (custom)
- [ ] Workflow approbation heures realisees (review admin)
- [ ] Notifications avancees (Slack/Teams)
- [ ] Rapports PDF (formation + formateur + projet)
- [ ] SSO OIDC pour gros volume users

### Phase 4 — Optimisation & extensions (T+9 mois)

- [ ] Modelisation etudiants si besoin metier
- [ ] Integration calendrier (iCal export)
- [ ] API publique limitee pour clients (auto-service projets)
- [ ] Multi-langue UI (EN en plus de FR)

## 12. Estimations couts

### Infra (recurrent)

| Element | Cout |
|---------|------|
| VPS Hetzner CPX31 ou CCX23 (4 vCPU/8 Go) | 13-30€/mois |
| Stockage backup distant (Backblaze B2 / OVH Object Storage) | 5-10€/mois |
| Domaine + sous-domaines | 15€/an |
| **Total recurrent** | **~30€/mois = ~360€/an** |

### Dev (one-shot)

| Phase | Effort | Cout estime |
|-------|--------|-------------|
| Phase 0 — Conception | ~10h Corentin | Inclus salaire |
| Phase 1 — MVP vanilla | ~80h Corentin | Inclus salaire |
| Phase 2 — Bridge | ~200-300h Corentin + 2-3j freelance Tiptap | Salaire + ~2k€ freelance |
| Phase 3 — Maturite | ~150h Corentin | Inclus salaire |
| **Total externe** | | **~2-3k€** (freelance ponctuel) |

## 13. Glossaire

| Terme | Definition |
|-------|------------|
| CFA | Centre de Formation des Apprentis |
| RNCP | Repertoire National des Certifications Professionnelles (les blocs de competences) |
| Bloc de competences | Ensemble homogene et coherent de competences validees ensemble |
| Module | Lecon individuelle au sein d'un bloc |
| Attribution | Affectation d'un module a un formateur avec heures |
| Intervention | Travail d'un developpeur sur une tache projet client (avec heures) |
| Formation pedagogique | Cas ou un projet client sert de support de formation pour des etudiants |
| Bridge | Service intermediaire qu'on construit entre Docmost et Baserow |
| Tiptap | Editor framework utilise par Docmost (extension de ProseMirror) |
| Node-view | Composant React custom integre dans un editeur Tiptap |
| Rollup | Calcul d'agregation Baserow (sum, count, avg) sur une relation |
| Path A / Path B | Strategies d'integration Docmost-Baserow (cf ADR-002) |

## 14. References

- Doc fondateur Vision Acadenice : [KxvipVcxNV](https://wiki.acadenice.com/doc/vision-acadenice-document-fondateur-KxvipVcxNV)
- Discovery recap : `01-discovery-recap.md`
- Decision records : `02-decision-record.md`
- Data dictionary : `05-data-dictionary.md`
- MCD : `06-merise-mcd.md`
- MLD : `07-merise-mld.md`
- Sources externes verifiees :
  - [Docmost AGPL pricing](https://docmost.com/pricing)
  - [Docmost v0.3.0 release Mermaid+Drawio+Excalidraw](https://github.com/docmost/docmost/releases/tag/v0.3.0)
  - [AFFiNE 10-seat limit](https://docs.affine.pro/self-host-affine/features/basic-user-quota)
  - [AppFlowy 1-user limit](https://github.com/AppFlowy-IO/AppFlowy-Cloud/issues/1570)
  - [Baserow vs NocoDB comparison](https://www.softr.io/blog/baserow-vs-nocodb)