Skip to Content
Documentation

Catalogue des pages

Éditeur de pages basé sur Puck pour les canaux publics globaux et membres d'organisation.

Vue d'ensemble

Yayaw fournit la gestion des pages à :

  • /dashboard/content/pages

Le flux dashboard est divisé en :

  • la liste des pages, un écran du tableau de bord (dashboard.content.pages, voir Liste des pages)

  • une route dédiée d'édition de page (/dashboard/content/pages/[scope]/[slug])

Docs liées :

Les pages sont composées avec ces familles de noeuds :

  • stack : conteneurs de mise en page

  • component : références directes de composants pour la composition avancée

  • section : références de sections réutilisables du catalogue, résolues vers la dernière publication

  • generated_section : sections générées adossées à des recettes, y compris les sections de mise en page initialisées comme l'en-tête/pied de page public de l'accueil ; les sections de contenu générées par IA sont promues en références section réutilisables à la sauvegarde

Liste des pages

/dashboard/content/pages (permission de route page:list) est un écran du tableau de bord : une table pleine page sur la source system:pages (voir Tableau de bord). Une organisation qui personnalise ses écrans peut changer la vue par défaut de la table, mais la table reste toujours.

  • Qui voit quelles pages : les pages globales avec la permission globale page read, list ou manage, les pages de l'organisation active avec page read, list ou manage dans celle-ci, jamais celles d'une autre organisation. Qu'une personne puisse modifier une page dépend de page:manage dans sa portée (globale, ou l'organisation) ; chaque action le vérifie de nouveau sur le serveur.

  • Colonnes : nom, chemin, portée, canal, statut (une page en ligne avec des modifications non publiées affiche « Modifications · version publiée en ligne ») et dernière mise à jour ; le slug, le statut de publication, la date de création et le lien vers l'éditeur peuvent être affichés. Un clic sur une ligne ouvre la page dans son éditeur.

  • Vues : la vue de l'écran (toutes les pages, les dernières modifiées d'abord, 20 par page), puis les files de travail Brouillons à relire, Modifications à publier, Pages publiées et Pages archivées, puis les vues enregistrées. Chacune peut être la favorite d'une personne, et les vues enregistrées peuvent être partagées avec l'organisation.

  • Modes : table, liste, un kanban par statut (les cartes ne se déplacent pas) et graphiques.

  • Recherche et ordre : la recherche lit le nom, le slug et le chemin ; les noms se trient comme on les lit (« Page 2 » avant « Page 10 ») ; une page de la table contient au plus 100 lignes.

  • Actions : Créer une page (pour qui peut gérer les pages globalement ou dans l'organisation) demande un nom, une portée, la visibilité dans l'organisation (membres uniquement, ou l'un de ses domaines publics) et un chemin, puis ouvre l'éditeur. Pour une sélection : Publier la sélection fait relire les révisions exactes avant de les publier, Archiver la sélection archive après confirmation, l'édition groupée règle le référencement (noindex, nofollow) en nouveaux brouillons, et la suppression retire les pages que la personne peut supprimer et nomme les autres. Une ligne peut être supprimée là où la personne peut la modifier.

Rôle CMS

Les pages sont la couche finale de composition du CMS. Elles doivent agencer la mise en page, les métadonnées SEO, les références de sections, les références de composants, les bindings de données et les bindings média. Elles ne doivent pas devenir la source de vérité à long terme pour le contenu répété comme les menus de navigation, offres partagées, blocs de preuve réutilisables ou ressources d'organisation.

Utilisez les sections pour les unités de page réutilisables, les données CMS pour les valeurs structurées partagées, les médias pour les ressources binaires et les design tokens pour le thème visuel public.

Contrat de document

Les pages utilisent un contrat de document Puck natif :

  • PuckPageDocumentV1

  • emplacement : src/lib/shared/pages/puck-document.ts

La persistance des révisions reste dans les tables existantes, et ui_page_revisions.definition stocke le document Puck versionné comme source de vérité.

La conversion runtime émet PageSectionNodeV1 pour les sections réutilisables. Une page ordinaire stocke un id/slug stable et suit la dernière révision publiée. Un nœud de section peut aussi porter un pin sectionRevisionId, que la validation de publication contrôle contre cette révision de section exacte.

La racine du document stocke aussi les réglages de page localisés :

  • titleByLocale

  • seo.seoTitleByLocale

  • seo.metaDescriptionByLocale

  • seo.socialTitleByLocale

  • seo.socialDescriptionByLocale

  • seo.socialImageUrl

  • seo.canonicalUrl

  • seo.noIndex / seo.noFollow

Les métadonnées de registre restent utiles pour les résumés de catalogue, mais le runtime publié utilise la racine du document pour les métadonnées SEO publiques.

PageStack porte trois décisions explicites de layout :

  • container choisit la largeur contenue avec tokens ou la pleine largeur

  • gap définit le rythme entre sections

  • sectionFrame vaut "token" pour le cadre public partagé et "none" quand les sections art-directed maîtrisent leur espacement extérieur

yayaw_cms_page_draft exprime le même contrat via layout.bodyWidth, layout.sectionGap et layout.sectionFrame, sans forcer chaque page dans la même silhouette.

Les anciens brouillons contextuels peuvent encore stocker une designProof historique dans leur document de révision immuable. Aucune nouvelle preuve n'est émise, et les sauvegardes génériques retirent toute designProof fournie par l'appelant.

Les révisions de pages globales peuvent aussi porter un payload optionnel root.props.designTokens. yayaw_cms_page_draft expose la même couche via designTokens ; si elle est omise, la page hérite du thème public effectif. Un payload non nul est versionné, accepte des cartes clair/sombre (chaque couleur claire exige une valeur sombre) et uniquement des couleurs sémantiques et les piles approuvées font-sans et font-serif. Les tokens de layout, les ombres, la police mono, le CSS arbitraire, les URL et les familles non enregistrées sont rejetés. Les design tokens de page ne sont autorisés que sur les pages publiques globales. Modifier la couche crée une nouvelle révision immuable, et yayaw_pages_publish la revalide avant publication.

Les nouvelles révisions de brouillon d'une page existante passent par pageSlug avec expectedRevisionId sur yayaw_cms_page_draft, ou par yayaw_pages_save_draft avec expectedRevisionId. Les deux utilisent un verrouillage optimiste : une édition concurrente ou externe est refusée au lieu d'être écrasée silencieusement.

Canaux et scope

Les pages prennent en charge deux scopes/canaux :

  • global (global_public)

  • organization (org_members pour les pages réservées aux membres)

  • organization (org_public pour les pages publiques servies depuis des domaines personnalisés vérifiés)

Routes runtime :

  • page d'accueil publique globale : /[locale]

  • pages publiques globales : /[locale]/[...slug]

  • pages membres d'organisation : /[locale]/o/[orgSlug]/[[...slug]]

  • pages publiques d'organisation : domaine personnalisé vérifié + /[locale]/[[...slug]]

Le runtime des pages membres d'organisation exige une adhésion. Les pages publiques d'organisation n'exigent pas d'adhésion, mais ne sont rendues que lorsque l'hôte de la requête correspond à une ligne organization_public_domains vérifiée. Les hôtes personnalisés inconnus retournent 404 au lieu de retomber sur le site global Yayaw. Les pages publiques d'organisation peuvent cibler un seul domaine public d'organisation. Lorsqu'une cible est définie, la page ne se résout que sur cet hôte. Les pages publiques d'organisation non ciblées restent disponibles sur tous les domaines publics vérifiés de l'organisation. Les chemins de page sont des réglages de route explicites: une page publique d'organisation peut donc utiliser / pour la page d'accueil du domaine personnalisé au lieu d'hériter d'un chemin issu du nom de page.

Visibilité des sections :

  • pages globales : sections intégrées + globales

  • pages d'organisation : sections intégrées + globales + sections de la même organisation

UX d'édition dashboard

L'UX d'édition est Puck + shadcn direct :

  • édition locale temps réel dans Puck

  • sauvegarde automatique avec debounce

  • sauvegardes de brouillon sérialisées afin que les fins d'autosave obsolètes ne puissent pas écraser un état plus récent

  • sélecteur de locale basé sur src/config/i18n.config.ts

  • réglages de route pour mettre à jour après création le chemin de page, le canal de visibilité d'organisation et la cible de domaine public

  • champs SEO au niveau page dans l'inspecteur

  • contrôles de binding image/média qui sélectionnent des ressources média d'organisation existantes ou génèrent de nouvelles ressources WebP avec OpenAI

  • contrôles de binding de données globales qui lient un champ publié complet depuis /dashboard/content/data

  • cycle de vie publication/archivage explicite

  • mode lecture seule pour les utilisateurs sans permission de gestion

La palette d'insertion groupe les éléments de page ainsi :

  • Built-in / Intégrés : Header, Footer

  • Sections : sections globales publiées plus sections d'organisation pertinentes

  • Components : références directes de composants

  • Layout / Mise en page : PageStack

L'inspecteur PageStack expose la largeur contenue/pleine, l'espacement et le cadre de section partagé. Les documents existants se normalisent vers sectionFrame: "token" ; le désactiver reste une décision explicite.

Les instances de sections intégrées n'exposent aucune prop éditable dans l'inspecteur de page. Le contenu de section est édité depuis le catalogue de sections source, pas dupliqué par page.

Les recettes de sections générées prennent en charge les variantes header et footer en plus des sections de contenu. Les variantes de contenu actuelles sont hero, immersive_hero, legal, data_insights, value_grid, feature_split, system_map, mcp_console, proof, signal_wall et cta.

Les recettes d'en-tête et de pied de page utilisent itemsJson pour les liens de menu, groupes de sous-menu, bascules de thème, bascules de langue et menus utilisateur. Les sections de page Header/Footer initialisées lient ces props aux données CMS header-menu/main et footer-menu/main, avec le même contrat JSON comme fallback.

L'état de la barre d'outils expose le cycle d'autosave :

  • saving

  • saved

  • error

  • conflict

Autosave et concurrence

Les sauvegardes de brouillon utilisent le verrouillage optimiste :

  • saveDraftPageAction exige baseRevisionId

  • une révision de base obsolète retourne conflict

  • les sauvegardes réussies renvoient le document Puck canonique serveur afin que l'éditeur adopte les IDs de section normalisés et les bindings par défaut sans boucle d'état dirty

  • aucune opération serveur de rebase et aucune fusion automatique

Stratégie de résolution de conflit :

  • l'utilisateur recharge explicitement le dernier brouillon depuis la bannière de conflit

  • l'utilisateur réapplique les modifications souhaitées dans le contexte de la révision courante

Exécution et validation

Le runtime publié se résout directement depuis le document Puck stocké.

Chemin runtime serveur :

  • charge le document de révision publiée depuis ui_page_revisions.definition

  • normalise le document Puck

  • convertit vers la définition runtime validée

  • supprime PublicPageSectionFrame autour des sections seulement lorsque leur stack parent déclare sectionFrame: "none"

  • résout les références de sections publiées via ui_section_publications, en utilisant d'abord l'ID de section courant puis le repli scope/slug pour les anciennes révisions de page dont les IDs sont périmés

  • rend l'arbre d'aperçu runtime résolu

  • applique la couche de tokens de révision d'une page globale via le même wrapper scopé pour les aperçus immuables et le rendu publié

  • résout les métadonnées localisées pour generateMetadata

Le canvas Puck du dashboard conserve les tokens propres à la révision mais ne les applique pas dans cette version 1. Utilisez l'aperçu immuable, et non le canvas d'édition, pour la preuve visuelle et la revue d'une palette ou d'une direction typographique propre à la page.

Les routes publiques dynamiques exposent les métadonnées SEO via :

  • /[locale]/page.tsx

  • /[locale]/[...slug]/page.tsx

  • /[locale]/o/[orgSlug]/[[...slug]]/page.tsx

Les pages publiques globales alimentent aussi la découverte Google Search via :

  • /robots.txt, qui autorise le contenu public tout en excluant API, ingestion analytics, dashboard, auth, maintenance et chemins membres d'organisation

  • /sitemap.xml, qui liste chaque page globale publiée pour chaque locale configurée, inclut les alternatives hreflang et ignore les pages marquées noIndex

  • JSON-LD de niveau site pour l'organisation et le site web Yayaw

Les pages membres d'organisation sont protégées par des contrôles d'adhésion et émettent des métadonnées noindex même quand une page possède ses propres champs SEO. Pour la recherche IA générative, gardez un contenu utile aux personnes et évitez de vous appuyer sur des fichiers spéciaux réservés aux machines comme levier de classement ; llms.txt reste orienté documentation, ce n'est pas un chemin d'optimisation Google Search.

Les pages publiques d'organisation utilisent l'hôte de la requête pour les URL canoniques, alternatives hreflang, robots, entrées sitemap, URL Open Graph et JSON-LD. Les hôtes personnalisés sont publics uniquement : les surfaces dashboard, auth, API, docs, ingest et /o/* sont bloquées au niveau proxy. Les hôtes personnalisés vérifiés résolvent aussi le contenu localisé de page depuis le préfixe de locale de l'URL et appliquent le thème public et les overrides de design tokens de l'organisation propriétaire.

Domaines publics d'organisation

Les domaines personnalisés d'organisation sont stockés dans organization_public_domains et gérés depuis les paramètres d'organisation ou MCP. Un domaine appartient à exactement une organisation, peut être marqué primaire une fois vérifié, et stocke le statut fournisseur, les challenges de vérification TXT, les enregistrements CNAME/A recommandés et l'horodatage du dernier contrôle. Les anciennes colonnes vercel_* restent utilisées pour la compatibilité, mais le runtime traite la ligne comme un snapshot générique de vérification de domaine public.

Le registre de page stocke un public_domain_id optionnel pour les pages org_public. Les dialogues de création dashboard et de réglages de route de l'éditeur affichent les domaines publics non archivés de l'organisation active, avec par défaut le domaine primaire vérifié lorsqu'il existe. La résolution runtime par hôte filtre les pages ciblées par domaine avec la ligne de domaine personnalisé correspondante, tout en gardant les anciennes pages non ciblées visibles sur tous les domaines publics vérifiés de l'organisation.

PUBLIC_DOMAIN_PROVIDER=vercel utilise l'API de domaines projet Vercel pour ajouter et vérifier les domaines. PUBLIC_DOMAIN_PROVIDER=manual-dns génère un challenge TXT de propriété et affiche les indications CNAME/A depuis PUBLIC_DOMAIN_CNAME_TARGET et PUBLIC_DOMAIN_IPV4_TARGETS; les opérateurs configurent DNS et ingress hors de l'app, puis relancent le contrôle du domaine. La publication de contenu de page reste pilotée par la DB et ne redéploie pas le fournisseur d'hébergement.

La publication est bloquée quand les diagnostics contiennent une sévérité error.

Page d'accueil initialisée

bun run seed crée une page publique globale Home au chemin / lorsqu'aucune page d'accueil publiée n'existe encore. Le document initialisé est un PuckPageDocumentV1 normal avec :

  • sections générées header et footer adossées aux entrées singleton CMS header-menu/main et footer-menu/main

  • texte de page et métadonnées SEO localisés en anglais/français

  • pile de contenu composée de sections générées hero, value grid, feature split et CTA

Le seed est volontairement non destructeur. Une fois qu'une page d'accueil est déjà publiée, les exécutions ultérieures du seed gardent la révision publiée courante afin de ne pas écraser les éditions du Page Builder.

La route docs (/[locale]/docs) utilise les mêmes wrappers runtime d'en-tête et de pied de page que la mise en page publique. Ces wrappers lisent les slots CMS éditables pour la marque cliquable, la navigation centrale et les mini menus publics à droite, tout en laissant la mise en page Fumadocs gérer la sidebar et la table des matières des docs.

Pages marketing initialisées

bun run seed crée aussi les pages de lancement Yayaw via le même stockage de catalogue de pages. Leurs shells de page utilisent les variantes Header/Footer générées liées aux données de menu globales, tandis que le corps de page reste du contenu de sections générées :

  • / est la page d'accueil publique publiée pour la codebase SaaS en code source.

  • /codebase est la page commerciale publiée pour la possession du code et l'architecture.

  • /pricing est la page d'offre publiée pour l'accès lifetime au code source.

Le même seed publie les données globales utilisées par ces pages, dont sales-offer/main et billing-product-content/pro-lifetime, afin que le texte d'offre reste éditable pendant que noms produits, prix, IDs Stripe et état checkout restent résolus depuis le catalogue de facturation.

Le seed crée les pages manquantes et peut publier une révision plus récente quand une page appartient encore à la même clé de seed et que sa seedVersion change. Les pages Page Builder existantes qui n'appartiennent pas au seed conservent leur état de publication courant et leurs dernières révisions.

Page Builder IA

Les pages sont générées par la conception de site (src/lib/server/services/site-design) : un brief de site, trois directions artistiques, puis pour chaque page un plan, ses textes, la composition, une revue sur rendu et des variantes. Chaque étape est un appel de modèle séparé avec ses seuls outils, exécuté par l'orchestrateur sur la file que nomme PAGE_AI_QUEUE_DRIVER (direct en local, db-worker en production avec bun run worker:page-ai ; vercel-queue seulement s'il est réglé explicitement). Les tâches et leur avancement vivent dans site_design_tasks, les documents de conception dans site_design_documents.

Dans l'éditeur, le panneau IA est l'assistant (AiChatPanel, surface page) : il lit la page ouverte par les outils de l'éditeur et la modifie par les outils audités de la conception de site (yayaw_site_generate, yayaw_section_regenerate, yayaw_section_variants_propose, yayaw_page_review…). Le menu de section et la palette de commandes mènent aux mêmes actions. Une organisation qui n'a qu'une clé OpenAI suit le même pipeline par openai-turn.ts.

L'ancien générateur en un appel et ses routes /api/ai/pages/* sont supprimés. ui_page_ai_runs et ui_page_ai_run_events gardent ses exécutions passées pour l'historique des exécutions IA ; plus rien n'y écrit.

Modèle de données

Tables de persistance des pages :

  • ui_page_registry_items

  • ui_page_revisions

  • ui_page_publications

  • ui_page_ai_runs

  • ui_page_ai_run_events

Les sections réutilisables sont stockées séparément dans :

  • ui_section_registry_items

  • ui_section_revisions

  • ui_section_publications

Les contraintes de page restent inchangées :

  • unicité (scope, organization_id, slug)

  • unicité (scope, organization_id, path)

  • révisions immuables avec déduplication par hash

  • une ligne de publication par élément de registre

API serveur

Les actions de page vivent dans :

  • src/lib/server/actions/pages/pages-catalog-actions.ts

Actions actuelles :

  • getPagesCatalogWorkspaceAction (ce que la personne peut créer et modifier depuis la liste des pages, et les domaines publics de l'organisation pour la fenêtre de création)

  • openPageForEditingAction

  • createPageAction

  • updatePageDefinitionJsonAction

  • saveDraftPageAction

  • publishPageAction

  • archivePageAction

Les lignes de la liste des pages viennent de la source d'écran system:pages, paginées, triées et recherchées en SQL. Sa table (src/blocks/dashboard/screens/sources/pages-extension.tsx) utilise les actions groupées personnalisées Yayaw Table pour les raccourcis de cycle de vie des lignes sélectionnées :

  • publier les pages sélectionnées via publishPageAction, après relecture des révisions exactes

  • archiver les pages sélectionnées via archivePageAction

  • supprimer une page via deletePageByIdAction, une sélection via deletePagesBulkAction

  • enregistrer le référencement d'une sélection via saveDraftPageAction

La disponibilité des sections pour le page builder vient de :

  • listAvailableSectionsForPageAction

  • listAvailableSectionsForPage

La génération d'image pour les champs média de page est gérée par le service partagé de ressources image média, utilisé à la fois par le picker média et Page AI. Les images générées utilisent le modèle OpenAI configuré, avec gpt-image-1.5 par défaut, et suivent le même chemin de permissions d'organisation, quotas, téléversement vers le stockage objet et persistance media_assets que les téléversements manuels. Le picker média affiche les miniatures stockées quand elles sont disponibles, tandis que les bindings conservent le publicUrl original afin que les pages rendues utilisent toujours la ressource source.

Les champs de données globales publiées sont exposés à l'éditeur de page comme références de binding. Le rendu runtime des pages résout les bindings global_data_field et global_data_query depuis le cache de données globales publiées. Les bindings texte résolvent aussi les tokens de variables CMS namespacés comme {site.name}, {organization.name} et {data.global.header-menu.main.brand_label}. Les tokens manquants restent inchangés.

applyPageOperationsAction a été supprimé.

Validation

Vérifications utiles après des changements du catalogue de pages :

bun test src/lib/shared/pages/puck-document.test.ts
bun test src/lib/server/services/pages/page-definition-schema.test.ts
bun test src/lib/server/services/pages/page-definition-runtime.test.ts
bun test src/lib/server/services/site-design/orchestrator.test.ts
bun run check
bunx tsc --noEmit

Base ACL

Ressource : page

Politiques d'organisation recommandées :

  • member : page:list, page:read

  • manager/admin : page:manage

  • super admin : global page:manage

Le dashboard, les actions serveur des pages et les outils MCP de pages décident avec can() sur page seul, dans le scope de l'organisation pour les pages d'organisation et sans scope pour les pages globales. Une chaîne de rôle de membre Better Auth, owner compris, n'accorde jamais l'accès aux pages : un membre sans groupe portant une politique page est refusé. La liste des pages montre les pages globales aux détenteurs d'une politique globale page read, list ou manage, et seuls les gestionnaires les modifient.