SRD — transport unique et deux façades

Publié sur le site VitePress sous /srd/architecture. Les diagrammes Mermaid sont rendus via le plugin VitePress.

Objectif

Une couche transport partagée dans @franksauvag/rpg-commons/srd et deux façades consommant la même donnée JSON exposée par l’API PHP :

1. Façade bundles — createSrdClient + build*Bundle : adaptateurs TypeScript côté client.
2. Façade entrées — createSrdEntryListClient : bulk par typeId, overlay /api/locales/{lang}/srd/{typeId}, merge dans editor, lignes triées par index.

Transport partagé

• fetchJsonWithRetry (src/srd/http/fetch.ts) : GET JSON, timeout, retry sur 429/502/503, backoff, corps parsé en unknown.
• SrdHttpError : erreur réseau / HTTP homogène.
• URLs (src/srd/http/config.ts) : buildSrdDatasetUrl, buildSrdMetaUrl, buildLocaleSrdUrl — uniquement à partir de apiBaseUrl injecté (pas d’import.meta.env dans la lib).

createSrdClient et createSrdEntryListClient utilisent ce transport en interne (dédup « en vol » par dataset / par couple locale+dataset pour les overlays).

Façade entrées (détail)

• mergeLocaleOverlayRows (src/srd/i18n/mergeLocaleOverlays.ts) : fusion des champs d’overlay (hors index) dans editor pour chaque ligne source.
• SrdEntryRow / SrdEditorOverlay (src/srd/types/entry.ts) : contrat minimal pour les listes type Candlekeep.
• createSrdEntryListClient(config) (src/srd/client/entryListClient.ts) : loadTypeEntries(typeId, lang) — si lang === "en", pas d’appel locale ; sinon fetch overlay puis merge.

Consommateur (character-creator-studio)

Depuis 2.0 : srdRuntime (src/srd/runtime.ts) encapsule createSrdRuntime — bundles, loadTypeEntries, stats, preload. Candlekeep : src/library/registry/. Types SrdEntryRow / overlays depuis @franksauvag/rpg-commons/srd.

Chaîne de responsabilité (résumé)

Couche	Rôle
Serveur	JSON (bulk, meta, stats, locales).
fetchJsonWithRetry	Fetch + retry + parse.
Façade bundles	adapters / bundleBuilders.
Façade entrées	createSrdEntryListClient + mergeLocaleOverlayRows.
Apps	UI ; instance runtime dans la lib (cache + preload) — pas de second cache SRD côté app. CCS (2.0) : src/srd/runtime.ts (srdRuntime).

Cible : runtime SRD (cache + preload, cadrage 2026)

Statut : implémenté en 2.0.0 — createSrdRuntime dans @franksauvag/rpg-commons/srd. Voir SRD overview et le CHANGELOG.
Implémentation : livrée en 2.0.0 — voir overview, migration, CHANGELOG. Reliquats et audits : audit-2026-05.md (interne).

Objectif

• Offrir une seule couche de mémoïsation valeur + promesse pour tout le périmètre SRD lecture géré par la lib, en s’appuyant sur les deux façades existantes (bundles + index / entrées).
• Permettre un preload à l’initialisation sans charger par défaut tout le catalogue : l’app déclare ce dont elle a besoin (bundles lourds et/ou listes typeId + lang pour la façade entrées).

Principes

1. Framework-agnostic : pas de import.meta.env ; pas de @tanstack/react-query dans le cœur du runtime (l’app peut utiliser Query pour le hors-SRD ou en queryFn qui délègue au runtime sans conserver une seconde copie des données SRD).
2. Preload déclaratif : à l’init, config explicite — par exemple listes preloadBundles, preloadTypeEntries: { typeId, lang }[], et éventuellement profils nommés (character-editor, candlekeep-library, …) documentés dans la lib. Défaut : sobre (vide ou minimal) pour éviter le sur-coût réseau.
3. Pas de double cache : l’app ne combine pas loadResource / autre Map / useQuery avec mémo concurrente pour les mêmes clés SRD ; migration CCS = supprimer ces chemins au profit du runtime.
4. Un seul chemin HTTP interne : le runtime réutilise ou encapsule createSrdClient / createSrdEntryListClient (ou une couche unique) pour éviter deux dédup inflight sur le même GET.
5. Changement de langue : l’API du runtime expose une stratégie documentée (setLocale, invalidation des clés dépendantes, etc.) — détail d’implémentation à livrer avec le code.

Documentation obligatoire (lib)

• Ce fichier (docs/srd-facades.md) : section cible + lien depuis le backlog unifié.
• À la livraison : overview, CHANGELOG.md, page /srd/architecture si les diagrammes évoluent.

Politique des clés de cache (consommateurs)

Référence actuelle : character-creator-studio (src/data/srd/cache.ts + appelants). Cible : ces clés migrent dans le runtime de la lib (section Cible : runtime SRD ci-dessous) ; le CCS ne conserve pas un second magasin pour le même périmètre.

Principe

• Un seul magasin : toute mémoïsation « promesse + valeur » des chargements SRD côté app passe par loadResource / peekResource (une Map unique). Ne pas ajouter un second cache parallèle (autre Map, WeakMap globale, singleton ad hoc) pour le même périmètre HTTP sans mettre à jour ce document.

Préfixes documentés (CCS)

Préfixe / motif	Usage
{dataset}:v2	Bundles éditeur lourds (classes, spells, …) — voir src/data/srd/lazy/index.ts.
srd:type:{typeId}:{lang}	Lignes entrées Candlekeep — loadSrdTypeEntriesCached ; loadType dans src/srd/loader.ts délègue directement à cette clé (plus de couche srd:bundle).
srd:translation-stats:{lang}	Réponse translation-stats par langue.
srd:meta:locales	Liste des locales issues de /api/srd/meta.

Rôle de la lib (complémentaire, pas redondant)

createSrdClient et createSrdEntryListClient dédupliquent les requêtes en vol par dataset / couple (locale, dataset) à l’intérieur du client : ce n’est pas un second cache applicatif ; les apps gardent loadResource pour la durée de vie session / onglet — jusqu’à adoption du runtime unifié, qui remplace ce rôle pour le SRD.

Diagrammes (Mermaid)

Modèles côté serveur (HTTP)

Façade bundles (createSrdClient)

Façade entrées (createSrdEntryListClient)

Chaîne complète (acteurs)

Maintenir les diagrammes (DOC7)

1. Source unique : éditer uniquement docs/srd-facades.md (section « Diagrammes (Mermaid) ») — pas de copie divergente ailleurs.
2. Quand mettre à jour : changement d’URL ou de flux dans src/srd/ (transport, entryList, client, adaptateurs, runtime une fois livré) ; évolution du contrat OpenAPI / PHP qui change le sens des flèches.
3. Valider la syntaxe : aperçu sur GitHub, ou mermaid.live en collant le bloc ; respecter la règle IDs de nœuds sans espaces (voir section « Diagrammes » ci-dessus).
4. Mini-site : après modification, cd website && pnpm build (ou pnpm run build:website à la racine du dépôt si Storybook + site). Vérifier /docs/srd-facades en pnpm dev.
5. Implémentation : le rendu Mermaid est géré par le plugin VitePress (vitepress-plugin-mermaid) ; conserver les blocs ```mermaid dans ce fichier.

Liens

• audit-2026-05.md — reliquats post-2.0 (données, composants, normalizers).
• CCS backlog post-commons (repo séparé) — suite CCS.
• overview — usage createSrdRuntime et clients bas niveau.
• CHANGELOG.md — livraisons Phase 1 (lots D, DOC, etc.).