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
| Surface | Route | Objectif |
|---|---|---|
| Tableau de bord CMS | /dashboard/content | Écran du contenu : chiffres clés, pages vues et ce qui demande votre attention |
| Pages | /dashboard/content/pages | Composition de pages publiques et d'organisation |
| Documentation | /dashboard/content/documentation | Contenus Fumadocs bilingues versionnés et navigation |
| Sections | /dashboard/content/sections | Sections de page réutilisables, recettes générées et sections formulaire |
| Modèles de données | /dashboard/content/data-models | Définitions typées de modèles CMS |
| Entrées de données | /dashboard/content/data | Contenu publié singleton et collection |
| Médias | /dashboard/content/media | Ressources binaires scopées par organisation et images générées |
| Composants | /dashboard/content/components | Registre de composants UI, aperçus et imports |
| Design tokens | /dashboard/content/design-tokens | Surcharges de tokens de thème publics au runtime |
| Modèles d'e-mails | /dashboard/content/email-templates | Modèles transactionnels React Email |
Pile de contenu
Le CMS est volontairement organisé en couches :
Les modèles de données définissent les champs typés, les règles de localisation et la cardinalité.
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.
Les ressources média fournissent des URL publiques durables pour les fichiers sélectionnés ou générés.
Les composants définissent l'inventaire UI réutilisable et les moteurs de rendu de recettes.
Les sections lient des littéraux, des données CMS ou des médias dans des unités de page réutilisables.
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.
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.
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 :
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.
Construire une section réutilisable quand le contenu doit apparaître sur plus d'une page.
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.
Publier la page ou la section une fois les diagnostics de validation propres.
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 :
yayaw_cms_context_get(lecture) renvoie, pour lescopedemandé (organizationpar 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,formSectionetcatalogProductSection;includeVocabulary: falsel'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.yayaw_cms_page_draft(écriture) crée le brouillon de page en un seul appel :name, puis en optionpath,slug,channel,locales,defaultLocale,titleByLocale,seo,layout,designTokens(pages publiques globales uniquement) et 1 à 24sections. Chaque section crée une nouvelle section de composition (kind: "create"avec unedefinition) ou réutilise une section publiée du scope (kind: "reuse"avecsectionSlug; 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. AvecpageSlugetexpectedRevisionId, l'appel ajoute plutôt une nouvelle révision de brouillon à une page existante.dryRun: truevalide 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 deyayaw_pages_publish.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_publicationset rendent lePuckPageDocumentV1publiéles références de sections se résolvent via
ui_section_publicationsles bindings littéraux de composants et sections acceptent directement des valeurs JSON bornées, y compris tableaux, objets imbriqués et
null; les contratsvalueShaperécursifs valident les champs imbriqués tout en gardant les anciennes chaînes JSON lisiblesles 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_assetsles 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 :
pagesectionsglobal-datamediacomponentsglobal-variablesemail-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 --noEmitExé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.
Intentions
Permettre aux agents IA et à votre propre app de demander à une ressource de votre produit qui tourne, un appareil par exemple, d'exécuter une action que votre produit a déclarée.
Modèles de données CMS
Modèles de données typés, localisés et publiables, et variables inline pour le contenu CMS.