AMN

Type de ressource : Schéma Sanity (Document)
Fichier source : apps/studio/schemaTypes/amn.ts
Statut : Actif
Slice : 1 (Page d’accueil)
Version : 1.0

---

1. Vue d’ensemble (DOC)

1.1. Description

Schéma singleton pour la page d’accueil/welcome. Contient un message personnalisé et un statut d’activation. Utilisé pour afficher un message contextuel sur la page d’accueil.

1.2. Objectif

• Modéliser un message singleton pour la page d’accueil
• Permettre l’activation/désactivation du message sans le supprimer
• Faciliter la communication contextuelle avec les visiteurs
• Supporter les avertissements ou annonces temporaires

1.3. Cas d’usage

• Affichage d’un message de bienvenue personnalisé sur la page d’accueil
• Gestion de l’activation/désactivation du message
• Communication contextuelle avec les visiteurs
• Avertissements ou annonces temporaires

1.4. Relations avec d’autres schémas

Relation	Schéma	Type	Description
Dépend de	Aucun	-	Schéma singleton indépendant
Utilisé par	Aucun	-	Schéma singleton non référencé

---

2. Structure des données (DOC)

2.1. Champs principaux

Nom du champ	Type	Obligatoire	Description	Validation
message	string	✅	Message à afficher sur la page welcome	Rule.required()
status	string	✅	Statut d’activation du message	Options: active, inactive

2.2. Champs SEO

Aucun champ SEO spécifique n’est implémenté dans ce schéma.

2.3. Champs de contenu riche

Aucun champ de contenu riche n’est implémenté dans ce schéma.

---

3. Contrats d’Entrée/Sortie (SPEC)

3.1. Inputs (création/modification)

Champ	Type	Validation	Description
message	string	Rule.required()	Message à afficher
status	string	Options: active, inactive	Statut d’activation

3.2. Outputs (structure du document)

Champ	Type	Description
_id	string	ID unique du document
_type	string	Type du document (amn)
_createdAt	string	Date de création (généré par Sanity)
_updatedAt	string	Date de dernière modification (généré par Sanity)
message	string	Message à afficher
status	string	Statut d’activation (active ou inactive)

3.3. États du document

État	Description	Transition
active	Message activé et affiché	→ inactive
inactive	Message désactivé et masqué	→ active

---

4. Implémentation (CODE)

4.1. Code du schéma

apps/studio/schemaTypes/amn.ts

import { defineType, defineField } from 'sanity'

export default defineType({
  name: 'amn',
  title: 'AMN',
  type: 'document',
  fields: [
    defineField({
      name: 'message',
      title: 'Message',
      type: 'string',
      description: 'Le message à afficher sur la page welcome',
      validation: (Rule) => Rule.required(),
    }),
    defineField({
      name: 'status',
      title: 'Status',
      type: 'string',
      options: {
        list: [
          { title: 'Active', value: 'active' },
          { title: 'Inactive', value: 'inactive' },
        ],
        layout: 'radio',
      },
      initialValue: 'active',
    }),
  ],
  preview: {
    select: {
      title: 'message',
      subtitle: 'status',
    },
  },
})

4.2. Requêtes GROQ associées

Requête principale (message actif)

*[_type == "amn" && status == "active"][0] {
  _id,
  message,
  status
}

Requête détaillée (page unitaire)

*[_type == "amn" && _id == $id][0] {
  _id,
  message,
  status
}

4.3. Types TypeScript (génération automatique)

Non implémenté - sanity-typegen n’est pas configuré dans le projet actuel.

// Types à implémenter manuellement si nécessaire
export type Amn = {
  _id: string;
  _type: 'amn';
  message: string;
  status: 'active' | 'inactive';
};

---

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario	Description	Résultat attendu
Validation du message	Créer un document sans message	Erreur de validation
Validation du status	Créer un document sans status	Valeur par défaut active appliquée
Changement de status	Passer de active à inactive	Status changé avec succès
Message vide	Créer un document avec message vide	Erreur de validation (required)

5.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Consommation Astro	Route Astro + Sanity API	Récupération du message via getAmn()	Message récupéré si status == active
Preview Sanity	Sanity Studio + Preview API	Mode preview pour le schéma amn	Preview fonctionne avec le secret
Affichage index	Route index.astro	Afficher le message sur la page d’accueil	Message affiché si actif

5.3. Tests E2E

Scénario	Parcours utilisateur	Description	Résultat attendu
Création → Affichage	Studio → Build → Site	Créer un message avec status active	Message visible sur la page d’accueil
Désactivation → Masquage	Studio → Build → Site	Passer le status à inactive	Message masqué sur la page d’accueil
Preview → Vérification	Studio → Preview	Vérifier le preview du message	Preview affiche le message correctement

---

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Fonction getAmn()	L2	Récupération du message	Requête GROQ avec filtre status == active
Route index.astro	L2	Affichage du message	Appel de getAmn() et rendu conditionnel
Route welcome.astro	L2	Affichage du message	Appel de getAmn() et rendu conditionnel
Preview Sanity	L1	Génération URL preview	productionUrl configuré pour type amn

6.2. Points d’attention

• Ce schéma est conçu comme un singleton (un seul document actif)
• La requête filtre sur status == "active" pour n’afficher que le message actif
• Utilisé dans la fonction getAmn() du fichier lib/sanity.ts
• Le preview Sanity est configuré pour rediriger vers /welcome pour ce type
• Supporte le mode preview avec isPreview parameter dans getAmn()
• Le preview affiche le message comme titre et le statut comme sous-titre

6.3. Vérification de cohérence

• Le schéma ne casse aucun schéma existant
• Les requêtes GROQ retournent les données attendues
• Les types TypeScript sont générés correctement (à implémenter)
• Le preview fonctionne correctement

---

7. Sécurité

7.1. Mécanismes de sécurité

• ✅ Le preview est protégé par un secret (SANITY_PREVIEW_SECRET)
• ✅ Les permissions Sanity sont configurées par rôle
• ✅ Le champ message est validé (required)

7.2. Validation des entrées

• ✅ Le champ message est obligatoire (Rule.required())
• ✅ Le champ status est limité aux options active et inactive
• ✅ Le status a une valeur par défaut active

---

8. Performance et limites

8.1. Limites Sanity

Limite	Valeur	Stratégie d’optimisation
Taille du document	16 MB	Éviter les messages trop volumineux
Profondeur des références	10 niveaux	Pas applicable (pas de références)

8.2. Optimisations appliquées

• ✅ Utilisation de projections GROQ pour réduire la taille des réponses
• ✅ Mise en cache CDN pour les requêtes en production
• ✅ Filtre sur status pour éviter de récupérer les messages inactifs

---

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme	Cause probable	Solution
Message non affiché	Status != active	Vérifier le statut du document
Preview ne fonctionne pas	Secret non configuré	Vérifier SANITY_PREVIEW_SECRET
Requête vide	Aucun document avec status active	Créer un document avec status active

9.2. Commandes de debug

# Extraire le schéma depuis Sanity
npx sanity schema extract

# Générer les types TypeScript (à implémenter)
npx sanity typegen generate

---

10. Bonnes pratiques

10.1. Architecture

• ✅ Toujours utiliser des types générés par sanity-typegen (à implémenter)
• ✅ Centraliser les requêtes GROQ dans src/lib/queries.ts (à implémenter)
• ✅ Documenter les champs et leurs validations

10.2. Code

• ✅ Utiliser defineField pour chaque champ
• ✅ Configurer le preview pour une meilleure UX dans Studio
• ✅ Utiliser des validations appropriées

10.3. Maintenance

• ✅ Mettre à jour ce fichier lors de toute modification du schéma
• ✅ Régénérer les types après modification (à implémenter)
• ✅ Tester les requêtes GROQ après modification

---

11. Évolutions et roadmap

11.1. Améliorations planifiées

• Implémentation de sanity-typegen pour la génération de types
• Ajout de champs SEO pour le message
• Support de plusieurs messages actifs (array au lieu de singleton)
• Centralisation des requêtes GROQ dans un fichier dédié

11.2. Limitations connues

• ❌ Singleton (un seul document actif)
• ❌ Pas de champs SEO spécifiques
• ❌ Types TypeScript non générés automatiquement
• ❌ Pas d’historique des messages précédents

---

12. Ressources liées

• Documentation Sanity : Schema Types
• DAT L1 : §4 - Modélisation et Schémas des Données
• Schémas dépendants : Aucun (schéma indépendant)
• Pages Astro consommatrices : apps/web/src/pages/index.astro, apps/web/src/pages/welcome.astro
• Utilitaires : apps/web/src/lib/sanity.ts (fonction getAmn)
• Configuration Preview : apps/studio/sanity.config.ts (productionUrl pour type ‘amn’)

---

13. Historique des modifications

Date	Version	Description	Auteur
2026-09-15	1.0	Création initiale	Devin