Indicateurs de fonctionnalité

Pourquoi utiliser des indicateurs de fonctionnalité ici

Utilisez des indicateurs de fonctionnalité lorsque vous avez besoin d'un contrôle à l'exécution sans redéploiement:

• déploiement progressif de comportement
• interrupteurs de désactivation d'urgence
• comportement propre à un environnement sans forks de configuration
• expériences de courte durée avec ownership explicite

Gardez la configuration statique pour les constantes qui ne sont pas du comportement produit (timeouts, valeurs de sécurité strictes, réglages de niveau protocole).

Indicateurs actuels à l'exécution

Les indicateurs gérés sont déclarés dans src/config/flags.config.ts, créés par le seed dans feature_flags et exposés dans Admin → Site Settings lorsqu'ils sont raccordés au comportement applicatif.

• theme-management
• enable-passkey-auth
• enable-magic-link
• auth-multi-session-enabled
• require-2fa
• auth-signup-enabled
• auth-api-keys-enabled
• org-self-serve-creation-enabled
• org-invitations-enabled
• enable-scim-plugin
• billing-enabled
• billing-enforcement-enabled
• toast-duration-seconds
• toast-stack-limit
• toast-gap-px
• toast-expand
• toast-position
• settings-layout-max-width
• actions-as-icons
• dashboard-breadcrumbs-enabled
• dashboard-section-navigation-enabled
• ai-components-enabled
• media-image-generation-enabled
• control-plane-mcp-enabled

settings-layout-max-width contrôle la largeur des surfaces de style réglages du tableau de bord, y compris les cartes Better Auth, Products & services, Authorization et d'autres panneaux de configuration admin qui utilisent le wrapper de réglages. Les surfaces de catalogue et de bibliothèque de contenu lisent aussi cette valeur afin que les pages de travail denses puissent utiliser la même politique de largeur. Les racines de section du tableau de bord, notamment /dashboard, /dashboard/admin, /dashboard/content, /dashboard/organization, /dashboard/settings et /dashboard/test, héritent aussi de cette politique via le wrapper partagé de page dashboard. La valeur supporte l'échelle standard Tailwind de largeur maximale, la largeur dashboard container et full.

actions-as-icons bascule les groupes d'actions de tableau de bord pris en charge entre boutons texte complets et boutons compacts à icône avec infobulle, y compris les actions de catalogue de contenu et les barres d'outils Yayaw Table raccordées à l'indicateur à l'exécution.

dashboard-breadcrumbs-enabled et dashboard-section-navigation-enabled contrôlent le chrome de navigation du shell de tableau de bord. Ce sont deux indicateurs d'expérience côté serveur, activés par défaut par le seed, et ils peuvent être désactivés indépendamment depuis Admin → Site Settings lors de l'évaluation d'autres patterns de navigation du tableau de bord.

control-plane-mcp-enabled est le coupe-circuit côté serveur pour les outils MCP de plan de contrôle (control plane) destinés à Codex. Il est créé désactivé par défaut et devrait être vérifié par les points d'entrée MCP/API avant d'autoriser des opérations Yayaw via le plan de contrôle.

Modèle d'accès à l'exécution

Le Flags SDK est le contrat canonique de déclaration et de découverte. Yayaw garde feature_flags comme fournisseur interne de réglages de site, expose les métadonnées via l'endpoint de découverte Vercel Flags et peut évaluer des clés adossées à PostHog via l'adaptateur PostHog lorsque le slug est listé dans POSTHOG_FLAG_KEYS.

Utilisez getManagedFlagValues([...]) ou getManagedBooleanFlagValues([...]) dans les layouts serveur, providers, navigation de tableau de bord, configuration auth à l'exécution et tout autre chemin chaud qui a besoin de plusieurs indicateurs. Les helpers à indicateur unique restent disponibles pour les chemins de compatibilité étroits, mais il ne faut pas ajouter de lectures unitaires répétées dans du code critique de requête.

Les composants client ne peuvent consommer que des indicateurs dont la définition gérée a exposeClient: true. Ces valeurs sont chargées côté serveur avec loadClientRuntimeFlags(), hydratées dans RuntimeFlagsProvider et revalidées avec TanStack Query. Les décisions de sécurité, auth, authz, enforcement de facturation et MCP doivent rester des sources de vérité côté serveur.

Indicateurs personnalisés

Les indicateurs présents dans feature_flags mais non déclarés dans MANAGED_FEATURE_FLAGS sont traités comme des indicateurs personnalisés. La page admin génère automatiquement leurs contrôles depuis la valeur stockée en base:

• les booléens s'affichent comme des interrupteurs
• les nombres s'affichent comme des champs numériques
• les chaînes s'affichent comme des champs texte
• les objets, tableaux et valeurs null s'affichent comme des zones de texte JSON

Les indicateurs personnalisés sont des valeurs libres à l'exécution. Ils ne sont utilisés par l'application que lorsque le code appelle explicitement getFlag("custom-slug") ou l'un des helpers typés de fallback DB avec ce slug.

Les indicateurs de déploiement progressif dépréciés comme blocks-ai-plan-v1, blocks-ai-plan-persistence-v1, blocks-ai-plan-trigger-worker-v1, page-ai-deep-refinement-enabled et pages-wysiwyg-v1 sont masqués de l'UI admin et supprimés par le seed parce qu'ils ne représentent plus des réglages de site utiles.

Contrat non négociable: logique + UI

Tout indicateur qui contrôle une fonctionnalité doit garder à la fois:

• le comportement backend/plugin
• les points d'entrée UI visibles par l'utilisateur

Exemple: les indicateurs auth contrôlent maintenant les plugins Better Auth et les cartes/vues UI visibles. Si un plugin est désactivé mais que l'UI rend encore des contrôles, les utilisateurs peuvent atteindre des chemins morts.

Indicateurs auth/org prioritaires

Priorités de rollout actuelles:

1. auth-signup-enabled

• Contrôle la disponibilité de l'inscription dans l'UI auth et les options du serveur auth.
• Remplace le basculement statique de la configuration auth pendant les périodes sur invitation uniquement.

2. auth-api-keys-enabled

• Contrôle le plugin de clés API et les écrans de clés API.
• Utile lors du rollout progressif de l'accès API par tier client.

3. auth-multi-session-enabled

• Contrôle le plugin multi-session Better Auth, la carte des sessions de sécurité et la carte de changement de compte dans les réglages de compte.
• Utile lorsque vous voulez un modèle à session active unique pour des environnements plus stricts.

4. org-self-serve-creation-enabled

• Contrôle si les utilisateurs peuvent créer eux-mêmes des organisations.
• Utile pour les setups enterprise où les organisations sont provisionnées de façon centralisée.

5. org-invitations-enabled

• Contrôle les flux d'invitation pour l'ajout de membres.
• Permet de geler temporairement la croissance tout en gardant les organisations existantes utilisables.

Ce qui doit rester config/env, pas indicateur

• crypto/secrets et credentials fournisseurs
• connexion DB et réglages d'infrastructure runtime
• invariants protocole/sécurité qui ne doivent pas dériver au runtime
• routes statiques, contrats de locales, configuration de build et configuration de l'optimiseur d'images
• données du catalogue de facturation, ids de prix Stripe et limites de plans
• vrai interrupteur dur de maintenance d'urgence (MAINTENANCE_MODE)

Le mode maintenance dans Yayaw est intentionnellement basé sur l'environnement et piloté par middleware:

• MAINTENANCE_MODE
• MAINTENANCE_MODE_END_DATE

Modèle d'implémentation

1. Ajoutez la définition gérée dans src/config/flags.config.ts avec:

• slug stable
• catégorie
• valeur par défaut explicite
• description claire

2. Lisez via un accesseur côté serveur:

• getFlag(key) pour une recherche unifiée PostHog-first avec fallback DB
• getManagedBooleanFlagValue(slug) pour les gates booléens typés

3. Appliquez le double gating:

• comportement serveur
• visibilité UI

4. Ajoutez les docs:

• inclure l'indicateur dans cette page et les notes d'architecture
• expliquer s'il apparaît dans les réglages à l'exécution ou les indicateurs personnalisés

5. Validez:

• états activé et désactivé
• limites de permissions
• absence de liens/routes morts dans l'UI

Contrat de seed

Le seed crée les indicateurs gérés manquants et répare les métadonnées nom, description et catégorie. Il n'écrase pas enabled ni value pour les lignes existantes; les choix admin faits dans Site Settings survivent donc aux déploiements et reseeds.

Définition de terminé pour les nouveaux indicateurs

• slug et description ajoutés au seed
• comportement serveur gardé
• surface UI gardée
• aucune route cassée lorsque désactivé
• docs mises à jour
• content/llm/llm-source.md mis à jour lorsque les consignes assistant changent
• docs assistant générées rafraîchies avec bun run docs:llm:generate
• checks CI passent (check, tsc, build, intégrité docs)