## Objectif

Nous evaluons une nouvelle facon de fournir les donnees de programmation et de contenus aux sites web TFO, IDELLO, ONFR et lineaire.

L'objectif est de savoir si une publication sous forme de fichiers JSON versionnes peut bien repondre a vos besoins techniques et operationnels.

Ce document ne presente pas une decision finale. Il sert a recueillir vos commentaires avant de figer le format.

## Idee generale

Aujourd'hui, les donnees sont disponibles via Directus ou via des mecanismes de synchronisation propres a chaque site.

La proposition est de publier des fichiers JSON prets a consommer, organises par plateforme, par version et par publication.

Exemple:

```text
/tfo/v1/manifest.json
/tfo/v1/runs/20260730-0900/today.json
/tfo/v1/runs/20260730-0900/latest.json
/tfo/v1/runs/20260730-0900/schedule/2026-07-30.json
/tfo/v1/runs/20260730-0900/schedule/2026-08-08.json
/tfo/v1/runs/20260730-0900/products/GP123456.json
/tfo/v1/runs/20260730-0900/collections/0123456/full.json
/tfo/v1/runs/20260730-0900/search/index.json
```

Les sites ne devraient pas coder un chemin de run en dur. Ils liraient d'abord:

```text
/tfo/v1/manifest.json
```

Puis utiliseraient le `base_path` retourne par le manifest pour charger les fichiers du run actif.

## Exemple de manifest

```json
{
  "schema_version": "1.0",
  "platform": "tfo",
  "published_at": "2026-07-30T09:50:00-04:00",
  "run_id": "20260730-0900",
  "base_path": "/tfo/v1/runs/20260730-0900"
}
```

Le `manifest.json` permet de changer de publication de facon atomique. Si une nouvelle generation echoue, le manifest continue de pointer vers le dernier run valide.

## Types de fichiers proposes

### today.json

Contient les contenus ou programmations pertinents pour la journee courante.

```json
{
  "schema_version": "1.0",
  "platform": "tfo",
  "run_id": "20260730-0900",
  "date": "2026-07-30",
  "programs": []
}
```

### latest.json

Contient les contenus ajoutes, modifies ou retires depuis la derniere publication.

```json
{
  "schema_version": "1.0",
  "platform": "tfo",
  "run_id": "20260730-0900",
  "added": [],
  "updated": [],
  "removed": []
}
```

### schedule/YYYY-MM-DD.json

Contient la programmation pour une date precise.

```json
{
  "schema_version": "1.0",
  "platform": "tfo",
  "run_id": "20260730-0900",
  "date": "2026-08-08",
  "programs": [
    {
      "program_key": "123",
      "product_key": "GP123456",
      "begin": "2026-08-08T06:00:00-04:00",
      "end": "2026-08-08T06:24:00-04:00",
      "title": "Titre de l'episode"
    }
  ]
}
```

La premiere version viserait une fenetre future jusqu'a J+10.

### products/{product_key}.json

Contient le detail d'un produit ou episode.

```json
{
  "schema_version": "1.0",
  "platform": "tfo",
  "run_id": "20260730-0900",
  "product": {
    "product_key": "GP123456",
    "biznumber": "0123456",
    "title": "Titre de l'episode",
    "description": "..."
  },
  "programmations": {
    "current": [],
    "upcoming": [],
    "next": {
      "date": "2026-08-08",
      "begin": "2026-08-08T06:00:00-04:00"
    }
  },
  "media": {},
  "images": []
}
```

### collections/{biznumber}/full.json

Contient une vue complete d'une collection, dans le sens attendu par les sites:

```text
collection -> saisons -> episodes
```

Exemple:

```json
{
  "schema_version": "1.0",
  "platform": "tfo",
  "run_id": "20260730-0900",
  "collection": {
    "biznumber": "0123456",
    "title": "Titre de la collection",
    "description": "...",
    "programmation": {
      "start": "2026-08-08T06:00:00-04:00",
      "end": "2026-08-08T06:24:00-04:00"
    },
    "next_programmation": {
      "date": "2026-08-08",
      "begin": "2026-08-08T06:00:00-04:00"
    }
  },
  "seasons": [
    {
      "serie": {
        "serie_key": "S123",
        "title": "Saison 1"
      },
      "episodes": [
        {
          "product": {
            "product_key": "GP123456",
            "title": "Episode 1"
          },
          "programmations": [],
          "media": {},
          "images": []
        }
      ]
    }
  ]
}
```

### search/index.json

Fichier optionnel pouvant servir a alimenter un moteur de recherche comme Algolia, Meilisearch, Typesense ou un index interne.

```json
[
  {
    "objectID": "GP123456",
    "type": "product",
    "title": "Titre de l'episode",
    "slug": "titre-de-lepisode",
    "image": "https://...",
    "collection_biznumber": "0123456"
  }
]
```

## Cache propose

Le manifest aurait un cache court:

```text
/tfo/v1/manifest.json
Cache-Control: public, max-age=60, stale-while-revalidate=120
```

Les fichiers d'un run seraient immuables et pourraient etre caches longtemps:

```text
/tfo/v1/runs/20260730-0900/*
Cache-Control: public, max-age=31536000, immutable
```

Logique:

- le site consulte regulierement `manifest.json`;
- si `run_id` change, le site charge les fichiers du nouveau run;
- les fichiers des runs ne changent jamais;
- un rollback peut etre fait en repointant le manifest vers un run precedent.

## Points importants pour les sites

- Les JSON seraient versionnes dans le chemin: `/v1/`, puis eventuellement `/v2/`.
- Les changements cassants seraient publies dans une nouvelle version.
- Les dates seraient fournies avec timezone explicite.
- Les fichiers seraient separes pour eviter de telecharger un enorme JSON unique.
- Les sites pourraient consommer seulement les fichiers utiles a leurs pages.
- Les fournisseurs pourraient avoir acces uniquement a leur plateforme ou prefixe.

## Questions pour vous

Merci de nous dire si cette approche fonctionnerait pour votre site, et de commenter les points suivants.

### Consommation

- Est-ce que votre site peut consommer des fichiers JSON statiques via HTTP/CDN?
- Est-ce que votre site peut lire un `manifest.json` avant de charger les donnees?
- Avez-vous besoin d'une API dynamique, ou des fichiers JSON suffisent?
- Avez-vous des contraintes sur le nombre de fichiers charges?

### Structure des donnees

- Le modele `collection -> seasons -> episodes` convient-il a vos pages?
- Le fichier `products/{product_key}.json` contient-il le bon niveau de detail?
- Le fichier `collections/{biznumber}/full.json` est-il trop gros, trop petit ou correct?
- Avez-vous besoin d'autres regroupements?
- Quels champs sont obligatoires pour vos pages?

### Programmation

- La fenetre future J+10 est-elle suffisante?
- Avez-vous besoin de programmation passee?
- Avez-vous besoin d'un fichier par date, par semaine ou par mois?
- Comment affichez-vous "prochain episode" aujourd'hui?

### Media et images

- Quels champs media sont requis pour votre lecteur video?
- Avez-vous besoin de plusieurs formats d'image?
- Avez-vous besoin de sous-titres, transcriptions, audio ou autres assets dans le JSON?

### Recherche

- Utilisez-vous Algolia, Meilisearch, Typesense ou un autre moteur?
- Un fichier `search/index.json` vous serait-il utile?
- Quels champs devraient etre inclus dans l'index?

### Cache et mise a jour

- Un cache court sur `manifest.json` vous convient-il?
- Quelle frequence de verification du manifest serait acceptable?
- Avez-vous besoin d'un webhook ou signal pour savoir qu'un nouveau run est disponible?
- Comment votre site ferait-il un rollback si necessaire?

### Migration

- Pouvez-vous tester cette approche en parallele de votre integration actuelle?
- Quel serait le meilleur pilote pour vous: une page, une plateforme, une collection, une section?
- Quels risques voyez-vous dans une migration vers ce modele?

## Commentaires attendus

Pour nous aider a valider l'approche, merci de repondre avec:

- les fichiers que vous utiliseriez;
- les champs manquants;
- les champs inutiles;
- les contraintes de performance ou cache;
- les impacts sur votre architecture;
- les risques de migration;
- une estimation du travail cote site.

## Decision recherchee

Nous voulons confirmer si cette approche JSON peut devenir un contrat stable entre notre systeme de publication et les sites.

La decision attendue n'est pas encore "on migre tout". La decision attendue est plutot:

```text
Est-ce que ce modele JSON est techniquement viable pour les sites?
Si oui, quels ajustements sont necessaires avant un pilote?
```