vault backup: 2026-07-30 17:41:49

20 Work/Ideas/Proposition d'architecture Sync Mogador v2.md

@@ -1,5 +1,4 @@
 
-
 ## Objectif
 
 Ce document resume une proposition de refonte de la synchronisation Mogador afin de rendre le systeme plus fiable, plus simple a maintenir et plus rapide a publier vers les sites TFO, IDELLO, ONFR et Linear.
@@ -185,6 +184,29 @@ Si Directus est retire, il faut remplacer son role d'edition d'urgence.
 
 La proposition est de creer un mini CMS interne dans Laravel, non expose a Internet.
 
+Ce mini CMS doit etre protege par authentification. Les edimestres qui ont aujourd'hui acces a Directus devront avoir acces a cet outil interne selon leurs roles.
+
+Acces proposes:
+
+```text
+Admin sync:
+- peut configurer et publier
+- peut gerer les utilisateurs
+- peut faire rollback
+
+Edimestre:
+- peut rechercher et consulter
+- peut creer une correction d'urgence
+- peut voir les overrides actifs
+- ne peut pas changer la configuration systeme
+
+Read-only interne:
+- peut consulter les donnees, rapports et JSON publies
+- ne peut pas modifier
+```
+
+Le mini CMS doit rester disponible uniquement sur le reseau interne ou via VPN/SSO interne. Il ne doit pas devenir une API publique.
+
 Fonctions minimales:
 
 - rechercher un produit, programme, collection ou serie;
@@ -231,6 +253,17 @@ Exemple d'override:
 
 Important: il ne faut pas modifier les JSON publies directement a la main. Les overrides doivent etre appliques dans le pipeline de generation, sinon ils seront perdus ou impossibles a auditer.
 
+Chaque override devrait inclure:
+
+- l'utilisateur;
+- le role;
+- la raison;
+- la date d'expiration;
+- l'entite touchee;
+- l'ancien contenu;
+- le nouveau contenu;
+- le run dans lequel la correction a ete publiee.
+
 ## Fabrication d'un incremental a partir d'un full export
 
 Louise ne fournit pas d'incremental. Chaque export est complet.
@@ -310,33 +343,75 @@ Au lieu d'un seul gros JSON, il faut publier plusieurs fichiers specialises.
 Exemple pour TFO:
 
 ```text
-/tfo/manifest.json
+/tfo/v1/manifest.json
-/tfo/today.json
+/tfo/v1/runs/20260730-0900/today.json
-/tfo/latest.json
+/tfo/v1/runs/20260730-0900/latest.json
-/tfo/schedule/index.json
+/tfo/v1/runs/20260730-0900/schedule/index.json
-/tfo/schedule/2026-07-30.json
+/tfo/v1/runs/20260730-0900/schedule/2026-07-30.json
-/tfo/schedule/2026-07-31.json
+/tfo/v1/runs/20260730-0900/schedule/2026-07-31.json
-/tfo/collections/index.json
+/tfo/v1/runs/20260730-0900/collections/index.json
-/tfo/collections/0123456/full.json
+/tfo/v1/runs/20260730-0900/collections/0123456/full.json
-/tfo/products/GP123456.json
+/tfo/v1/runs/20260730-0900/products/GP123456.json
-/tfo/search/index.json
+/tfo/v1/runs/20260730-0900/search/index.json
 ```
 
 Pour 8 000 produits TFO et 22 000 produits IDELLO, ce volume de fichiers JSON n'est pas un probleme pour un bucket S3/CDN. C'est meme preferable a un gros fichier unique.
 
+Le site ne devrait pas coder un chemin de run en dur. Il lit toujours le manifest:
+
+```text
+/tfo/v1/manifest.json
+```
+
+Puis il utilise le `base_path` retourne:
+
+```text
+/tfo/v1/runs/20260730-0900
+```
+
 ### manifest.json
 
 Le manifest indique quelle version est publiee.
 
 ```json
 {
+  "schema_version": "1.0",
   "platform": "tfo",
   "published_at": "2026-07-30T09:50:00",
   "run_id": "20260730-0900",
-  "base_path": "/tfo/runs/20260730-0900"
+  "base_path": "/tfo/v1/runs/20260730-0900"
 }
 ```
 
+Le manifest est le seul fichier qui doit avoir un cache court.
+
+Cache recommande:
+
+```text
+/tfo/v1/manifest.json
+Cache-Control: public, max-age=60, stale-while-revalidate=120
+
+/tfo/v1/runs/20260730-0900/*
+Cache-Control: public, max-age=31536000, immutable
+```
+
+Meme si Louise exporte seulement toutes les 3 heures, le manifest ne devrait pas etre cache 3 heures. Il doit pouvoir changer rapidement pour:
+
+- correction d'urgence via mini CMS;
+- rollback;
+- republication apres erreur;
+- correction d'un mapping;
+- correction d'une video/image;
+- publication manuelle.
+
+Compromis acceptable si Infra veut reduire les appels:
+
+```text
+manifest.json: max-age=300
+```
+
+Donc 5 minutes. Mais 3 heures est trop long pour les corrections d'urgence.
+
 ### today.json
 
 Contient ce qui doit etre en ligne aujourd'hui.
@@ -438,11 +513,11 @@ Pour afficher des messages comme "prochain episode le 8 aout", il faut extraire
 Proposition configurable:
 
 ```env
-TFO_SCHEDULE_DAYS_AHEAD=14
+TFO_SCHEDULE_DAYS_AHEAD=10
-IDELLO_SCHEDULE_DAYS_AHEAD=30
+IDELLO_SCHEDULE_DAYS_AHEAD=10
-ONFR_SCHEDULE_DAYS_AHEAD=14
+ONFR_SCHEDULE_DAYS_AHEAD=10
 LINEAR_SCHEDULE_DAYS_BEHIND=7
-LINEAR_SCHEDULE_DAYS_AHEAD=15
+LINEAR_SCHEDULE_DAYS_AHEAD=10
 ```
 
 Les programmations futures sont publiees dans:
@@ -464,6 +539,10 @@ Et resumees dans les JSON produit/collection:
 
 Cela evite aux sites de parcourir toute la grille future pour afficher une information simple.
 
+Le maximum propose pour la v1 est J+10. Cette limite garde les JSON raisonnables et evite que la generation future ralentisse inutilement la synchronisation.
+
+Le site peut ensuite appliquer sa logique d'affichage selon l'heure. Par exemple, si un programme est prevu a 6h, le JSON contient deja `begin: 06:00`, et le site decide quand l'afficher ou le mettre en evidence.
+
 ## Search et Algolia
 
 Un fichier comme:
@@ -498,9 +577,9 @@ Il faut eviter qu'un site lise une publication incomplete.
 Principe:
 
 ```text
-/tfo/runs/20260730-0900/...
+/tfo/v1/runs/20260730-0900/...
-/tfo/runs/20260730-1200/...
+/tfo/v1/runs/20260730-1200/...
-/tfo/manifest.json
+/tfo/v1/manifest.json
 ```
 
 Le site lit d'abord:
@@ -515,6 +594,107 @@ Si la generation du run `20260730-1200` echoue, `manifest.json` continue de poin
 
 Ainsi, une sync ratee ne casse pas le site.
 
+Exemple simplifie:
+
+```text
+/tfo/v1/runs/1/collections/...
+/tfo/v1/runs/1/products/...
+
+/tfo/v1/runs/2/collections/...
+/tfo/v1/runs/2/products/...
+
+/tfo/v1/manifest.json -> pointe vers /tfo/v1/runs/2
+```
+
+### Retention des runs
+
+Il faut supprimer les anciens runs pour eviter une croissance infinie du bucket.
+
+Politique proposee:
+
+```text
+JSON publies:
+- garder les runs des 10 derniers jours
+- garder au minimum les 3 derniers runs valides
+- supprimer les runs incomplets jamais publies
+
+Rapports:
+- garder 90 jours
+
+Anomalies importantes / audit:
+- garder 1 an ou selon politique interne
+```
+
+Pourquoi garder au moins 3 runs valides:
+
+- rollback rapide;
+- comparaison entre publications;
+- diagnostic si un site signale un probleme.
+
+### Versioning du contrat JSON
+
+Les JSON deviennent un contrat avec les sites. Il faut donc versionner le format.
+
+Version dans le chemin:
+
+```text
+/tfo/v1/manifest.json
+/tfo/v1/runs/20260730-0900/products/GP123456.json
+/tfo/v1/runs/20260730-0900/collections/0123456/full.json
+```
+
+Version dans chaque fichier:
+
+```json
+{
+  "schema_version": "1.0",
+  "platform": "tfo",
+  "run_id": "20260730-0900"
+}
+```
+
+Si un changement cassant est necessaire:
+
+```text
+/tfo/v2/manifest.json
+```
+
+La v1 et la v2 peuvent coexister pendant une periode de transition.
+
+### Documentation et validation
+
+Swagger/OpenAPI est surtout utile pour des API dynamiques. Pour des JSON statiques, la documentation devrait plutot etre:
+
+```text
+docs/
+  publication-contract.md
+  files.md
+  cache-strategy.md
+  versioning.md
+  examples/
+    manifest.json
+    product.json
+    collection-full.json
+    schedule-day.json
+  schemas/
+    manifest.schema.json
+    product.schema.json
+    collection-full.schema.json
+    schedule-day.schema.json
+```
+
+Les JSON Schema sont importants parce qu'ils permettent de valider automatiquement les fichiers avant publication.
+
+Avant de publier un run:
+
+```text
+1. generer tous les JSON
+2. valider chaque type de fichier contre son JSON Schema
+3. produire le rapport
+4. publier seulement si les erreurs critiques sont absentes
+5. mettre a jour manifest.json
+```
+
 ## Rapport et alertes
 
 Le rapport est une piece centrale de la v2.