Skip to Content
Documentation

Vue d'ensemble du CMS

Comment les surfaces de contenu, modèles de données, médias, sections, pages, design tokens et modèles d'e-mails de Yayaw s'articulent.

Vue d'ensemble

Le CMS de Yayaw est la couche d'exploitation de contenu dans le dashboard. Il combine données structurées, sections réutilisables, pages, ressources média, design tokens publics, modèles d'e-mails transactionnels et recettes de composants sous un même modèle d'autorisation.

Le point d'entrée principal est :

  • /dashboard/content

Ce dashboard est un écran : un filtre Période, les chiffres clés (pages publiées, pages en attente de publication, pages vues comparées à la période précédente, stockage des médias), les pages vues par jour et les pages les plus vues, les pages modifiées récemment, une liste À traiter de ce qui demande votre attention, et les graphiques des médias par type et des pages créées par mois. Chaque chiffre est lu derrière can() pour la personne qui le consulte, et les admins d'organisation peuvent personnaliser l'écran (voir Tableau de bord). La navigation de section mène à chaque surface de contenu disponible pour l'utilisateur courant.

Carte des surfaces

SurfaceRouteObjectif
Tableau de bord CMS/dashboard/contentÉcran du contenu : chiffres clés, pages vues et ce qui demande votre attention
Pages/dashboard/content/pagesComposition de pages publiques et d'organisation
Documentation/dashboard/content/documentationContenus Fumadocs bilingues versionnés et navigation
Sections/dashboard/content/sectionsSections de page réutilisables, recettes générées et sections formulaire
Modèles de données/dashboard/content/data-modelsDéfinitions typées de modèles CMS
Entrées de données/dashboard/content/dataContenu publié singleton et collection
Médias/dashboard/content/mediaRessources binaires scopées par organisation et images générées
Composants/dashboard/content/componentsRegistre de composants UI, aperçus et imports
Design tokens/dashboard/content/design-tokensSurcharges de tokens de thème publics au runtime
Modèles d'e-mails/dashboard/content/email-templatesModèles transactionnels React Email

Pile de contenu

Le CMS est volontairement organisé en couches :

  1. Les modèles de données définissent les champs typés, les règles de localisation et la cardinalité.

  2. Les entrées de données publient des valeurs partagées, comme les menus d'en-tête, les menus de pied de page et les variables de site.

  3. Les ressources média fournissent des URL publiques durables pour les fichiers sélectionnés ou générés.

  4. Les composants définissent l'inventaire UI réutilisable et les moteurs de rendu de recettes.

  5. Les sections lient des littéraux, des données CMS ou des médias dans des unités de page réutilisables.

  6. Les pages composent des noeuds de mise en page, des références de composants et des références de sections publiées dans des routes publiques ou réservées aux membres d'organisation.

  7. Les design tokens modifient la présentation publique via les couches globales et organisation. Une page globale peut aussi porter une couche bornée de couleurs sémantiques et de rôles sans/serif dans sa révision.

  8. Les modèles d'e-mails transactionnels réutilisent les variables CMS quand cela convient, mais sont envoyés par le runtime e-mail, pas par le moteur de rendu des pages publiques.

La documentation est une surface CMS headless dédiée, et non un canal de pages Puck. Chaque document logique stocke les contenus anglais et français dans une seule révision immuable afin que la publication bascule les deux langues ensemble. Le CMS conserve le chemin partagé, le parent, l'ordre de navigation, la source Markdown validée, l'arbre de rendu sûr, la table des matières et la structure de recherche. Fumadocs reste le système de layout et de rendu public pour /[locale]/docs/* ; seule sa source de contenu est résolue depuis les entrées publiées en base.

L’éditeur de documentation partage la barre compacte, la zone centrale et le panneau de propriétés repliable de l’éditeur de pages. La langue se choisit séparément des modes Visuel, Markdown et Aperçu. Le mode visuel utilise Tiptap, comme l’éditeur d’e-mails, pour les titres, le texte, les liens, les images, les listes, les blocs de code et les tableaux GFM. La source stockée reste du Markdown. Les widgets MDX spécialisés et la syntaxe non prise en charge restent des blocs source ou des éléments de texte inertes : modifiez-les en Markdown et vérifiez leur rendu public dans Aperçu. Changer de mode ne réécrit pas la source. Chaque enregistrement crée une révision bilingue avec un motif ; la publication conserve la validation serveur et les contrôles de conflit.

Le dialecte Markdown de la documentation accepte le Markdown standard, les tables GFM et les blocs de code, ainsi que la petite liste autorisée de widgets d'installation utilisée dans les guides Yayaw Table. Les imports, exports, expressions, MDX exécutable brut et composants inconnus sont refusés avant publication d'un brouillon. La documentation utilise le contrat d'autorisation dédié documentation:list, documentation:read, documentation:manage et documentation:publish. Ces permissions du dashboard sont seedées uniquement pour le rôle Super Admin; aucun rôle d'organisation ne reçoit l'accès d'édition de la documentation.

Cette séparation garde le contenu réutilisable au même endroit. Les pages doivent référencer des sections et des entrées de données publiées au lieu de copier le JSON de menu, les promesses partagées, les images ou le contenu répété dans chaque document.

Flux d'édition

Une modification CMS typique suit ce parcours :

  1. Créer ou mettre à jour la source structurée dans les modèles de données, les entrées de données ou la médiathèque.

  2. Construire une section réutilisable quand le contenu doit apparaître sur plus d'une page.

  3. Composer la page dans l'éditeur Puck avec des noeuds de mise en page intégrés, des références de sections et des références directes de composants seulement si nécessaire.

  4. Publier la page ou la section une fois les diagnostics de validation propres.

  5. Vérifier la route publique ou réservée aux membres d'organisation.

La largeur de page et le rythme des sections appartiennent au layout sérialisé. Un brouillon de page définit page.layout.bodyWidth, page.layout.sectionGap et page.layout.sectionFrame. Ces valeurs pilotent le container, l'espacement et le cadre partagé du PageStack racine. sectionFrame: "token" conserve le wrapper public standard ; "none" laisse les sections art-directed maîtriser leurs limites sans second cadre uniforme.

Une page publique globale peut définir page.designTokens sans modifier le registre global. Le payload versionné accepte les couleurs sémantiques clair/sombre (chaque couleur claire exige une valeur sombre) et les rôles sans/serif chargés et approuvés. Si le champ est omis, la page hérite des couches globale et d'organisation. Les tokens de layout ou d'effet, les polices mono, le CSS arbitraire, les URL et les familles non enregistrées sont rejetés. La couche normalisée est stockée dans la révision de page et utilise le même wrapper dans l'aperçu immuable et le runtime publié.

Les flux assistés par IA suivent le même modèle de persistance. Page AI promeut le contenu généré en sections réutilisables, la génération d'images Page AI persiste les médias via la médiathèque, et l'absence de publication d'une section produit un échec explicite au lieu d'un fallback inline.

Le design de page assisté par MCP suit le même modèle, mais le client Codex ou ChatGPT connecté porte le raisonnement créatif et la génération d'images. Yayaw n'appelle pas un second modèle texte côté serveur pour ce workflow. Le MCP fournit le vocabulaire de direction artistique, l'inventaire du CMS, l'ingestion durable des médias, la validation, la persistance des brouillons et les aperçus.

Rédaction de pages via MCP

Une nouvelle page se crée en trois appels :

  1. yayaw_cms_context_get (lecture) renvoie, pour le scope demandé (organization par défaut) et l'orgId, le vocabulaire de direction artistique (tokens de composition créative, options de layout de page, design tokens de page, recettes d'exemple, formSection et catalogProductSection ; includeVocabulary: false l'omet), les sections publiées que la page peut réutiliser avec leurs entrées et emplacements média, le catalogue de composants visible et jusqu'à 50 images récentes de l'organisation.

  2. yayaw_cms_page_draft (écriture) crée le brouillon de page en un seul appel : name, puis en option path, slug, channel, locales, defaultLocale, titleByLocale, seo, layout, designTokens (pages publiques globales uniquement) et 1 à 24 sections. Chaque section crée une nouvelle section de composition (kind: "create" avec une definition) ou réutilise une section publiée du scope (kind: "reuse" avec sectionSlug ; la section propre à une organisation l'emporte sur une section partagée de même slug). Les bindings d'entrées et de médias sont validés contre les entrées et emplacements média déclarés par la section. Les nouvelles sections sont créées et publiées dans la bibliothèque de sections dans le même appel ; une section publiée n'est qu'une brique réutilisable, et rien n'est public tant qu'une page qui l'affiche n'est pas publiée. Avec pageSlug et expectedRevisionId, l'appel ajoute plutôt une nouvelle révision de brouillon à une page existante. dryRun: true valide sans écrire. Le résultat renvoie la page (id, path, slug, revisionId, validationStatus), des URLs d'aperçu signées de courte durée par locale et les arguments de yayaw_pages_publish.

  3. yayaw_pages_publish (publication) valide la révision de tête exacte, son statut de validation, son ensemble borné de dépendances et les design tokens de page. Montrez d'abord les aperçus à l'utilisateur et obtenez son accord. Une page contenant une section de formulaire est refusée : un membre la publie depuis le dashboard.

yayaw_pages_save_draft enregistre un document de page complet comme nouvelle révision de brouillon, avec verrouillage optimiste sur expectedRevisionId. Un acteur scopé à une organisation étend le catalogue de composants de sa propre organisation avec yayaw_component_recipe_import (recettes déclaratives uniquement), puis yayaw_component_publish avec le revisionId exact renvoyé.

Les uploads de médias privés utilisent un STORAGE_MEDIA_STAGING_BUCKET privé distinct lorsque CMS_MEDIA_STAGED_UPLOADS_ENABLED=true. Par défaut, les grants opaques passent par le proxy applicatif same-origin et gardent S3_ENDPOINT interne. Ne configurez S3_SIGNED_PUBLIC_ENDPOINT que si l'hébergeur applicatif ne peut pas streamer le contrat média de 250 Mo ; ce doit être une origine d'API S3 HTTPS publique sûre et seuls les uploads basculent en direct. Les deux transports utilisent des PUT conditionnels sans écrasement. L'objet de staging vérifié reste privé pendant l'expiration du grant et une stabilisation de 24 heures pour bloquer les rejeux inter-instances. Le reaper répète la suppression pendant cette fenêtre et ne marque le nettoyage terminé qu'après le DELETE final.

La présentation des recettes utilise les rôles sémantiques de design tokens Yayaw/shadcn. Ajustez les couleurs de marque via la couche de design tokens du CMS plutôt que de coder en dur des couleurs propres à une page dans des composants runtime réutilisables.

Les URLs d'aperçu sont des identifiants bearer. Elles expirent rapidement, résolvent une révision immuable, contournent les caches publics et l'analytics, utilisent noindex/nofollow et sont bloquées sur les domaines personnalisés d'organisation. En production, configurer CMS_PREVIEW_SIGNING_SECRET avec un secret serveur dédié à forte entropie ; BETTER_AUTH_SECRET sert de repli.

Résolution au runtime

Le contenu publié se résout depuis des révisions immuables et des lignes de publication :

  • les pages chargent ui_page_publications et rendent le PuckPageDocumentV1 publié

  • les références de sections se résolvent via ui_section_publications

  • les bindings littéraux de composants et sections acceptent directement des valeurs JSON bornées, y compris tableaux, objets imbriqués et null; les contrats valueShape récursifs valident les champs imbriqués tout en gardant les anciennes chaînes JSON lisibles

  • les bindings de données résolvent les entrées de données CMS globales ou d'organisation publiées

  • les bindings média utilisent l'URL publique stockée dans media_assets

  • les design tokens publics se résolvent depuis les payloads globaux/organisation, puis une couche de révision optionnelle s'applique dans le wrapper d'une page globale

  • les e-mails transactionnels chargent le modèle actif en base pour la locale demandée avant de retomber sur les valeurs par défaut des composants

Les pages publiques globales alimentent /sitemap.xml et les métadonnées SEO publiques. Les pages membres d'organisation exigent une adhésion et émettent des métadonnées noindex même quand des champs SEO existent au niveau de la page.

Localisation

Les documents CMS utilisent les locales applicatives configurées dans src/config/i18n.config.ts. Les locales actuelles sont l'anglais et le français.

Le contenu localisé apparaît dans :

  • le texte des pages et les champs SEO

  • les valeurs d'entrées de données globales et d'organisation

  • les entrées de menus d'en-tête et de pied de page

  • les valeurs de recettes de sections générées

  • les objets, textes d'aperçu, HTML de corps et exports texte des e-mails transactionnels

Les bindings de sections de page générées sont stockés comme texte d'objet JSON dans le document Puck (propsBindingsJson, apiBindingsJson, harnessBindingsJson et champs de binding associés). Les valeurs contenues dans ces objets sont de vraies valeurs JSON et ne doivent pas être stringifiées individuellement. La validation applique des limites récursives, bloque les clés d'objet dangereuses, vérifie les valueShape imbriqués et refuse les sections générées sans binding variant valide.

Les docs anglaises sont canoniques. Du contenu français peut exister dans le produit, mais la nouvelle documentation technique doit d'abord mettre à jour l'anglais.

Autorisation

Le CMS utilise le modèle d'autorisation par groupes et rôles de Yayaw. La navigation du dashboard n'est qu'un indice ; les loaders serveur, actions, services et opérations MCP doivent encore autoriser chaque lecture ou mutation.

Ressources CMS courantes :

  • page

  • sections

  • global-data

  • media

  • components

  • global-variables

  • email-template

Les membres d'organisation reçoivent normalement l'accès list/read au contenu scopé par organisation. Les managers, admins, owners et superadmins reçoivent l'accès de gestion selon leurs bindings de rôles de groupe.

Plan de contrôle (control plane)

Les workflows CMS opérationnels doivent partager la logique de service entre le dashboard, MCP, les scripts CLI et les tests quand ils sont exposés hors de l'interface.

La couverture actuelle du plan de contrôle (control plane) inclut :

  • opérations de pages

  • opérations de données CMS

  • opérations de modèles d'e-mails transactionnels

  • opérations de catalogue de facturation utilisées par les variables CMS

Quand vous ajoutez une fonctionnalité CMS, décidez si les clients MCP de confiance doivent pouvoir l'opérer. Si oui, ajoutez des schémas typés, un reason pour les écritures, des enregistrements d'audit, des contrôles d'autorisation et des mises à jour de documentation. Si non, documentez pourquoi la fonctionnalité est volontairement limitée au dashboard.

Règles opérationnelles

  • Stocker le contenu réutilisable comme données, médias, sections ou modèles publiés.

  • Garder les documents de page comme documents de composition, pas comme stores de contenu dupliqué.

  • Ne pas exécuter de code de composant stocké en base.

  • Ne pas stocker les binaires média dans Postgres.

  • Garder les design tokens publics scopés hors des routes dashboard et auth.

  • Scoper explicitement les données CMS globales et les données CMS d'organisation.

  • Revalider les chemins dashboard et runtime publics affectés après publication/archivage.

  • Traiter les fichiers assistants générés comme des artefacts dérivés ; mettre d'abord à jour content/llm/llm-source.md, puis les régénérer.

Validation

Vérifications utiles après des changements de documentation ou de comportement CMS :

bun run docs:generate
bun run docs:check-links
bun run docs:check-translations
bun run docs:llm:generate
bun run docs:llm:check
bun run check
bunx tsc --noEmit

Exécuter les tests de domaine au besoin quand des changements d'implémentation touchent les pages, sections, modèles de données, médias, composants, tokens ou modèles d'e-mails.

Docs liées

Aperçus signés et optimisation des médias

Les routes d’aperçu de brouillon passent par le proxy de requête, même si leur jeton contient un point. Ce ne sont pas des fichiers statiques : le proxy transmet la langue et le chemin à la mise en page et applique les règles d’accès du domaine personnalisé de l’organisation.

Les sections générées et les compositions créatives utilisent la même liste de sources d’images autorisées que Next.js : STORAGE_PUBLIC_BASE_URL et le bucket public historique exact encore référencé par les révisions existantes et le contenu initial relu. Cette compatibilité ne réécrit pas les URL, ne migre pas les médias et n’autorise aucun autre projet Supabase, bucket privé ou URL signée. Les images existantes bénéficient des variantes responsives sans republication ; les sources externes inconnues restent des images directes. Seule l’image principale explicitement choisie est chargée en priorité, les autres restent chargées à la demande.